次世代 ユーザー インターフェース デザイン
nsDialogs は、インストーラーに カスタム ページを作る事を可能にします。ビルトイン ページに加えて、nsDialogs は 順序やアレンジに関係なく どんなタイプのコントロールでも持つページを作る事ができます。ラベル１つのシンプルなページから ユーザーのアクションに反応するフォームまで、何でも作る事ができます。Modern UI 2 は、例えば、"ようこそ"と"完了"ページを作る為に nsDialogs を使用しています。
nsDialogs は、バージョン 2.29 で InstallOptions の代わりとして導入された 新しい NSIS プラグインです。nsDialogs は INI ファイルを使わないので、InstallOptions よりも 高速な方法です。スクリプトとの統合は より緊密で より自然です - コントロールは プラグイン ファンクションを用いて作成され、通知は スクリプト中で直接ファンクションを呼ぶ事により 行われています。InstallOptions とは違って、利用可能なコントロールタイプは あらかじめ決められては居らず、Windows API への低レベル アクセスを提供する事によって、どんなタイプのコントロールも作る事ができ、ページを よりカスタマイズする事ができます。
nsDialogs を よりフレキシブルにする事は同じく、Win32 API の知識なしでは ユーザーをより複雑にさせ得るものでもあります。これは、スクリプト中で定義される、コントロールの作成や取り扱いを可能にする あらかじめ決められたファンクションのライブラリーを作成する事により、解決されています。この方法は、初心者が フレキシビリティへの容易なアクセスを得るのに、上級ユーザーは、ライブラリーを改良する事や 単に使用を避る事によって まだコア ファンクショナリティーへのアクセスを得ています。
nsDialogs を使用する前に、まず、スケルトンとしてベーシック スクリプトを作成しましょう。
Name nsDialogs OutFile nsDialogs.exe XPStyle on Page instfiles Section DetailPrint "hello world" SectionEnd
次に、nsDialogs を使用できるところで カスタムページを追加します。nsDialogs は、セクション中や どんなファンクション中でも 使用できず、カスタムページ ファンクションでだけ使用できます。
Name nsDialogs OutFile nsDialogs.exe XPStyle on Page custom nsDialogsPage Page instfiles Function nsDialogsPage FunctionEnd Section DetailPrint "hello world" SectionEnd
準備が整ったので、nsDialogs を使う時です。最初は必ず nsDialogs::Create へのコール (関数呼び出し) でなければなりません。ページで新しいダイアログを作成し、スタック中にそのハンドル HWND を返します。処理結果は、スタックでの「対象変数のズレ」とならないように スタックから pop されなければなりません。もし処理結果が error ならば、ダイアログは作成されていません。
nsDialogs::Create は、nsDialogs::Show を除くすぺての nsDialogs ファンクションのように、常に /NOUNLOAD 付きでコールされなければなりません。
nsDialogs::Create は、パラメーターを１つ受け取ります。とても独特なファンクションを持っていますが、このチュートリアルでは解かり易くする為に、常に 1018 にしましょう。
HWND はダイアログを一意に識別する数字で、SendMessage、SetCtlColors、Win32 API で使用する事ができます。
!include LogicLib.nsh
Name nsDialogs
OutFile nsDialogs.exe
XPStyle on
Var Dialog
Page custom nsDialogsPage
Page instfiles
Function nsDialogsPage
nsDialogs::Create /NOUNLOAD 1018
Pop $Dialog
${If} $Dialog == error
Abort
${EndIf}
FunctionEnd
Section
DetailPrint "hello world"
SectionEndページが作成されました。それを表示する時です。これは nsDialogs::Show で行われます。このファクションは、ユーザーが Next か Back か Cancel をクリックするまで戻りません。
!include LogicLib.nsh
Name nsDialogs
OutFile nsDialogs.exe
XPStyle on
Var Dialog
Page custom nsDialogsPage
Page instfiles
Function nsDialogsPage
nsDialogs::Create /NOUNLOAD 1018
Pop $Dialog
${If} $Dialog == error
Abort
${EndIf}
nsDialogs::Show
FunctionEnd
Section
DetailPrint "hello world"
SectionEndこれまでのスクリプトをコンパイルして実行した結果は、空っぽのページで 全く役に立ちません。それで、コントロールをいくつか追加します。そのため、nsDialogs.nsh から ${NSD_Create*} マクロを使用します。これらのマクロは各々、５つのパラメーター - x、y、幅, 高さ、そして text - を取ります。各々のマクロはまた、スタック上に１つの値、新しいコントロールのハンドル HWND を返します。ダイアログのハンドル HWND の様に、スタックから pop されて保存されなければなりません。
マクロが取る各々の寸法は、３つの単位様式 - ピクセル、ダイアログユニット、ダイアログサイズのパーセント - の内の１つを使う事ができます。端からきちんと測られた位置を示すために、負である事もできます。ダイアログユニットを使うには、寸法に 文字 u が接尾辞として添えられなければなりません。パーセントを使うには、寸法に パーセント記号 - % - が接尾辞として添えられなければなりません。他のどんなサフィックスや サフィックス無しは、ピクセルを意味します。
ダイアログユニットは、異なったフォントや DPI が使われている時に 上手く拡大縮小してダイアログを作成する事ができます。そのピクセルでのサイズは、フォントと DPI に基づいて実行時に決定されています。例えば、クラシック NSIS ユーザー インターフェースでのスタンダードなページは、266 ダイアログユニット幅で 130 ダイアログユニット高です。Modern UI でのページは、300 ダイアログユニット幅で 140 ダイアログユニット高です。違う解像度では、違ったフォントと DPI 設定を使っていて、ダイアログは、ダイアログユニットでは常に同じサイズを持っていますが ピクセルでは異なったサイズです。
!include nsDialogs.nsh
!include LogicLib.nsh
Name nsDialogs
OutFile nsDialogs.exe
XPStyle on
Var Dialog
Var Label
Var Text
Page custom nsDialogsPage
Page instfiles
Function nsDialogsPage
nsDialogs::Create /NOUNLOAD 1018
Pop $Dialog
${If} $Dialog == error
Abort
${EndIf}
${NSD_CreateLabel} 0 0 100% 12u "Hello, welcome to nsDialogs!"
Pop $Label
${NSD_CreateText} 0 13u 100% -13u "Type something here..."
Pop $Text
nsDialogs::Show
FunctionEnd
Section
DetailPrint "hello world"
SectionEnd${NSD_Create*} で作る事のできるコントロールのタイプ：
これで、ユーザーが対話する事のできるコントロールがいくつかあります。ユーザーがそれで実際に何をするかを見る時です。そのため、まず ページに leave callback ファンクションを追加します。そのファンクションでは、作成してユーザーに表示した テキストコントロールの状態を問い合わせます。そのために、${NSD_GetText} マクロを使用します。RadioButton と CheckBox コントロールについては ${NSD_GetState} マクロを使って下さい。
すべてのコントロールが ${NSD_GetText} をサポートしている訳ではなく、幾つかのものは WinMessages.nsh で定義されている特定メッセージでの 特別な取り扱いを要求することに注意して下さい。例えば、ListBox コントロールは LB_GETCURSEL と LB_GETTEXT の使用を要求します。時間と共に、nsDialogs.nsh 内のマクロのライブラリーは、より多くをこの様に扱うケースの もっともっと多くのマクロで埋まるでしょう。
!include nsDialogs.nsh
!include LogicLib.nsh
Name nsDialogs
OutFile nsDialogs.exe
XPStyle on
Var Dialog
Var Label
Var Text
Page custom nsDialogsPage nsDialogsPageLeave
Page instfiles
Function nsDialogsPage
nsDialogs::Create /NOUNLOAD 1018
Pop $Dialog
${If} $Dialog == error
Abort
${EndIf}
${NSD_CreateLabel} 0 0 100% 12u "Hello, welcome to nsDialogs!"
Pop $Label
${NSD_CreateText} 0 13u 100% -13u "Type something here..."
Pop $Text
nsDialogs::Show
FunctionEnd
Function nsDialogsPageLeave
${NSD_GetText} $Text $0
MessageBox MB_OK "You typed:$\n$\n$0"
FunctionEnd
Section
DetailPrint "hello world"
SectionEndnsDialogs のよりエキサイティングな新しい特徴の一つは、ダイアログに対する変更のコールバック ファンクション通知です。nsDialogs は、テキストフィールドの変更やボタンのクリックといったユーザーアクションに応じて、スクリプト中で定義されたファンクションを呼ぶ事ができます。nsDialogs がイベントを知らせる為に、${NSD_OnClick} と ${NSD_OnChange}を使用します。すべてのコントロールが 両方のイベントをサポートする訳ではありません。例えば、ラベルの変更について通知する事は何も無く、クリックだけです。
コールバック ファンクションが呼ばれると、そのコントロールのハンドル HWND はスタック上で待っていて、スタック破壊を避けるために pop されなければなりません。このシンプルな例では、あまり役に立ちません。しかし、複数のコントロールが同じコールバック ファンクションに関連した もっと大きなスクリプトの場合、ハンドル HWND は コントロールがイベントを生じる所で いくらかの光を放ちます。
新しい例は、ユーザーがテキストボックスにタイプした hello に応答します。
!include nsDialogs.nsh
!include LogicLib.nsh
Name nsDialogs
OutFile nsDialogs.exe
XPStyle on
Var Dialog
Var Label
Var Text
Page custom nsDialogsPage nsDialogsPageLeave
Page instfiles
Function nsDialogsPage
nsDialogs::Create /NOUNLOAD 1018
Pop $Dialog
${If} $Dialog == error
Abort
${EndIf}
${NSD_CreateLabel} 0 0 100% 12u "Hello, welcome to nsDialogs!"
Pop $Label
${NSD_CreateText} 0 13u 100% -13u "Type something here..."
Pop $Text
${NSD_OnChange} $Text nsDialogsPageTextChange
nsDialogs::Show
FunctionEnd
Function nsDialogsPageLeave
${NSD_GetText} $Text $0
MessageBox MB_OK "You typed:$\n$\n$0"
FunctionEnd
Function nsDialogsPageTextChange
Pop $1 # $1 == $ Text
${NSD_GetText} $Text $0
${If} $0 == "hello"
MessageBox MB_OK "right back at ya!"
${EndIf}
FunctionEnd
Section
DetailPrint "hello world"
SectionEnd今までで、幾つかのベーシックな入力コントロールを持つページがあります。しかし、ユーザーが次のページへ行って戻って来た時に 何が起こるでしょうか？今のコードでは、ユーザーの入力は記憶されていません。記憶するには、ユーザーの選択を変数に保存し 次回コントロールを作成する時に渡す為に、既に存在する leave callback ファンクションを使います。より良い例として、ページに checkbox も追加して、その状態を取得・設定するのに ${NSD_GetState} と ${NSD_SetState} を使います。
明快さの為、通知の幾つかを 前の段階から削除します。
!include nsDialogs.nsh
!include LogicLib.nsh
Name nsDialogs
OutFile nsDialogs.exe
XPStyle on
Var Dialog
Var Label
Var Text
Var Text_State
Var Checkbox
Var Checkbox_State
Page custom nsDialogsPage nsDialogsPageLeave
Page license
Page instfiles
Function .onInit
StrCpy $Text_State "Type something here..."
FunctionEnd
Function nsDialogsPage
nsDialogs::Create /NOUNLOAD 1018
Pop $Dialog
${If} $Dialog == error
Abort
${EndIf}
${NSD_CreateLabel} 0 0 100% 12u "Hello, welcome to nsDialogs!"
Pop $Label
${NSD_CreateText} 0 13u 100% 12u $Text_State
Pop $Text
${NSD_CreateCheckbox} 0 30u 100% 10u "&Something"
Pop $Checkbox
${If} $Checkbox_State == ${BST_CHECKED}
${NSD_Check} $Checkbox
${EndIf}
# alternative for the above ${If}:
#${NSD_SetState} $Checkbox_State
nsDialogs::Show
FunctionEnd
Function nsDialogsPageLeave
${NSD_GetText} $Text $Text_State
${NSD_GetState} $Checkbox $Checkbox_State
FunctionEnd
Section
DetailPrint "hello world"
SectionEndnsDialogs::Create /NOUNLOAD rect
新しいダイアログを作成する。rectは具体的に、位置が真似られるコントロールの識別子。これは通常1018であるはずで、それはビルトインページの作成について真似るコントロールです。Modern UIはwelcomeとfinishページのためのコントロール1040も持っています。
(訳注：mimicedをmimickedのタイプミスとして訳しました。)
スタック上に新しいダイアログのHWNDかerrorを返す。
nsDialogs::CreateControl /NOUNLOAD class style extended_style x y width height text
現在のダイアログにおいて新しいコントロールを作成する。これが働くためにダイアログが存在しなければなりません。従って、nsDialogs::Createがこの関数に先んじて呼ばれなければなりません。
スタック上に新しいダイアログのHWNDかerrorを返す。
nsDialogs::Show
ページを表示する。nsDialogs::Create、nsDialogs::CreateControl、その他が終わったら、これを一度呼んでください。
何も返さない。
nsDialogs::SelectFileDialog /NOUNLOAD mode initial_selection filter
ユーザーにファイル選択ダイアログを表示する。もしmodeがsaveに設定されると、ファイル保存ダイアログを表示する。もしmodeがopenに設定されると、ファイルオープンダイアログを表示する。filterは、パイプで分けられた 利用可能なファイルフィルタのリストです。もし空の文字列が渡されると、デフォルト - すべてファイル|*.* - が使われます。
initial_selectionはユーザーに、捜すためのデフォルトファイル と／あるいは 捜すためのデフォルトフォルダを提供するために使用できます。もしinitial_selectionが空なら、デフォルトファイル名はユーザーに提供されず、ダイアログは現在の作業用ディレクトリでスタートします。もしinitial_selectionがファイル名だけを指定するなら、例えば "test.exe"、ダイアログは現在の作業用ディレクトリでtest.exeと呼ばれるファイルを捜すようにセットアップされます。もしinitial_selectionがディレクトリだけを指定するなら、例えば "C:\Program Files"、ダイアログは与えられたファイル名なしで与えられたディレクトリでスタートします。もしinitial_selectionがディレクトリとファイル名を指定するなら、例えば "C:\Windows\System32\calc.exe"、ダイアログはディレクトリC:\Windows\System32でcalc.exeと呼ばれるファイルを捜すようにセットアップされます。
スタック上に選択されたファイル、あるいは もしユーザーが操作をキャンセルしたら空の文字列を返す。
nsDialogs::SelectFolderDialog /NOUNLOAD title initial_selection
ディレクトリ選択ダイアログをユーザーに表示する。
スタック上に選択されたディレクトリ、あるいは ユーザーが操作をキャンセルしたりエラーが発生した場合には "error" を返す。
nsDialogs::SetRTL /NOUNLOAD rtl_setting
右から左モードを on か off にセットする。もしrtl_setting が0なら、off にセットされる。もしrtl_setting が1なら、on にセットされる。この関数は、nsDialogs::CreateControlへのどのコールよりも前に呼ばれなければなりません。
何も返さない。
nsDialogs::GetUserData /NOUNLOAD control_HWND
スタック上にコントロールと結びつけられたユーザーデータを返す。このデータを設定するにはnsDialogs::SetUserDataを使ってください。
nsDialogs::SetUserData /NOUNLOAD control_HWND data
dataをコントロールに結びつける。このデータを得るにはnsDialogs::GetUserDataを使ってください。
何も返さない。
nsDialogs::OnBack /NOUNLOAD function_address
Backボタンのためのコールバック関数をセットする。 この関数はユーザーがBackボタンをクリックした時に呼ばれます。ユーザーが最後のページに戻ることを防止するには、この関数でAbortを呼んでください。
望んだコールバック関数のアドレスを得るには、GetFunctionAddressを使ってください。
何も返さない。
nsDialogs::OnChange /NOUNLOAD control_HWND function_address
与えられたコントロールのための変更通知コールバック関数をセットする。コントロールが変化する時はいつでも、関数が呼ばれて、コントロールのHWNDがそのスタック上で待たされています。
望んだコールバック機能のアドレスを得るには、GetFunctionAddressを使ってください。
何も返さない。
nsDialogs::OnClick /NOUNLOAD control_HWND function_address
与えられたコントロールのためのクリック通知コールバック関数をセットする。コントロールがクリックされた時はいつでも、関数が呼ばれて、コントロールのHWNDがそのスタック上で待たされています。
望んだコールバック機能のアドレスを得るには、GetFunctionAddressを使ってください。
何も返さない。
nsDialogs::OnNotify /NOUNLOAD control_HWND function_address
与えられたコントロールのための通知コールバック関数をセットする。コントロールがWM_NOTIFYメッセージを受け取った時はいつでも、関数が呼ばれて、コントロールのHWND、通知コード、MNHDR構造体へのポインタがそのスタック上で待たされています。
望んだコールバック機能のアドレスを得るには、GetFunctionAddressを使ってください。
何も返さない。
nsDialogs::CreateTimer function_address timer_interval
一定の間隔ごとに与えられたコントロールのためのコールバック関数を呼ぶタイマーをセットする。インターバル時間は ミリ秒で指定されます。
望んだコールバック機能のアドレスを得るには、GetFunctionAddressを使ってください。
何も返さない。
nsDialogs::KillTimer /NOUNLOAD function_address
以前にセットされたタイマーを止める。
望んだコールバック機能のアドレスを得るには、GetFunctionAddressを使ってください。
何も返さない。
nsDialogs.nsh は、nsDialogs の使用をずっと容易にする事のできる たくさんのマクロを含んでいます。下が、そのマクロ各々の、目的、シンタックス、入力と出力を含めた 説明です。
${NSD_Create*} x y width height text
現在のダイアログにおいて新しいコントロールを作成する。これが働くためにダイアログが存在しなければなりません。従って、nsDialogs::Createがこの関数に先んじて呼ばれなければなりません。
Available variants:
スタック上に新しいダイアログのHWNDかerrorを返す。
${NSD_OnBack} function_address
See OnBack for more details.
${NSD_OnChange} control_HWND function_address
See OnChange for more details.
See Real-time Notification for usage example.
${NSD_OnClick} control_HWND function_address
See OnClick for more details.
${NSD_OnNotify} control_HWND function_address
See OnNotify for more details.
${NSD_CreateTimer} function_address timer_interval
See CreateTimer for more details.
${NSD_KillTimer} function_address
See KillTimer for more details.
${NSD_AddStyle} control_HWND style
1つ以上のウィンドウスタイルをコントロールに追加します。複数のスタイルはパイプ `|' で分離されるべきです。
See MSDN for style description.
${NSD_AddExStyle} control_HWND style
1つ以上の拡張ウィンドウスタイルをコントロールに追加します。複数のスタイルはパイプ `|' で分離されるべきです。
See MSDN for style description.
${NSD_GetText} control_HWND output_variable
コントロールのテキストを取り出し、それをoutput_variableに保存します。特に、テキストのコントロールに役立ちます。
See Control State for usage example.
${NSD_SetText} control_HWND text
Sets the text of a control.
${NSD_SetTextLimit} control_HWND limit
Sets input size limit for a text control.
${NSD_GetState} control_HWND output_variable
チェックボックスまたはラジオボタンコントロールの状態を取り出します。可能なアウトプットは${BST_CHECKED}と${BST_UNCHECKED}です。
See Memory for usage example.
${NSD_SetState} control_HWND state
チェックボックスまたはラジオボタンコントロールの状態をセットします。stateについて可能な値は${BST_CHECKED}と${BST_UNCHECKED}です。
See Memory for usage example.
${NSD_Check} control_HWND
チェックボックスまたはラジオボタンコントロールにチェックを付けます。${BST_CHECKED}で${NSD_SetState}を呼ぶ事と同じです。
${NSD_Uncheck} control_HWND
チェックボックスまたはラジオボタンコントロールのチェックを外します。${BST_UNCHECKED}で${NSD_SetState}を呼ぶ事と同じです。
See Memory for usage example.
${NSD_CB_AddString} combo_HWND string
Adds a string to a combo box.
${NSD_CB_SelectString} combo_HWND string
Selects a string in a combo box.
${NSD_LB_AddString} listbox_HWND string
Adds a string to a list box.
${NSD_LB_DelString} listbox_HWND string
Deletes a string from a list box.
${NSD_LB_Clear} listbox_HWND
Deletes all strings from a list box.
${NSD_LB_GetCount} listbox_HWND output_variable
Retrieves the number of strings from a list box.
${NSD_LB_SelectString} listbox_HWND string
Selects a string in a list box.
${NSD_LB_GetSelection} listbox_HWND output_variable
リストボックスから選択された文字列を取り出します。もし文字列が選択されていなければ空の文字列を返します。
${NSD_SetFocus} control_HWND
Sets focus to a control.
${NSD_SetImage} control_HWND image_path output_variable
image_path からビットマップをロードして、それを${NSD_CreateBitmap}により作成されたcontrol_HWND 上に表示します。イメージハンドルはoutput_variable に保存されて、もう必要でなくなれば${NSD_FreeImage}を使って解放されるべきです。
イメージは、このマクロを呼ぶことに先んじて、ユーザーのコンピュータに展開されなければなりません。イメージを展開するのに良い場所は$PLUGINSDIRです。
!include nsDialogs.nsh
Name nsDialogs
OutFile nsDialogs.exe
XPStyle on
Page custom nsDialogsImage
Page instfiles
Var Dialog
Var Image
Var ImageHandle
Function .onInit
InitPluginsDir
File /oname=$PLUGINSDIR\image.bmp "${NSISDIR}\Contrib\Graphics\Header\nsis-r.bmp"
FunctionEnd
Function nsDialogsImage
nsDialogs::Create /NOUNLOAD 1018
Pop $Dialog
${If} $Dialog == error
Abort
${EndIf}
${NSD_CreateBitmap} 0 0 100% 100% ""
Pop $Image
${NSD_SetImage} $Image $PLUGINSDIR\image.bmp $ImageHandle
nsDialogs::Show
${NSD_FreeImage} $ImageHandle
FunctionEnd
Section
SectionEnd${NSD_SetStretchedImage} control_HWND image_path output_variable
ちょうど${NSD_SetImage}のようにビットマップをロードして表示しますが、コントロールにフィットするようにイメージを伸ばします。
${NSD_SetIcon} control_HWND image_path output_variable
${NSD_SetImage}と同じですが、${NSD_CreateIcon}により作成されたコントロール中でアイコンをロードし設定するために使われます。イメージハンドルはoutput_variable に保存されて、もう必要でなくなれば${NSD_FreeIcon}を使って解放されるべきです。
${NSD_SetIconFromInstaller} control_HWND output_variable
インストーラー中で使用されるアイコンをロードし、${NSD_CreateIcon}により作成されたcontrol_HWND 上でそれを表示します。イメージハンドルはoutput_variable に保存されて、もう必要でなくなれば${NSD_FreeIcon}を使って解放されるべきです。
${NSD_ClearImage} control_HWND
Clears an image from a control.
${NSD_ClearIcon} control_HWND
Clears an icon from a control.
${NSD_FreeImage} image_handle
${NSD_SetImage}や${NSD_SetStretchedImage}で以前にロードされたイメージハンドルを開放します。
${NSD_FreeIcon} icon_handle
${NSD_SetIcon}や${NSD_SetIconFromInstaller}で以前にロードされたイメージハンドルを開放します。
A: nsDialogs.nsh は、INI ファイルから nsDialogs のダイアログを作成する事ができる CreateDialogFromINI と呼ばれるファンクションを含んでいます。それは InstallOptions がサポートする あらゆるタイプのコントロールを扱う事ができますが、フラグや通知は まだ扱う事ができません。Examples\nsDialogs\InstallOptions.nsi が このファンクションの使用例を示しています。
将来、スクリプト自身を作成するファンクションも あるかもしれません。