Wtyczka nsDialogs

Ten dokument zgodny jest z NSIS 3.9

Nowa generacja projektowania interfejsu użytkownika



1. Wprowadzenie

Wtyczka nsDialogs pozwala na tworzenie niestandardowych stron instalatora. Można tworzyć strony z dowolnymi kontrolkami. Kontrolki mogą być tworzone w dowolnej kolejności oraz mogą być dowolnie rozmieszczone. Możesz zatem tworzyć co chcesz, poczynając na prostej stronie, z jedną kontrolką etykiety, kończąc na stronach, które mają możliwość interakcji z użytkownikiem. Interfejs Modern UI 2, na przykład, używa wtyczki nsDialogs do tworzenia strony powitalnej oraz końcowej.

Wtyczka nsDialogs jest nową wtyczką NSIS, dodaną do projektu w wersji 2.29, jako zamiennik wtyczki InstallOptions. Wtyczka nsDialogs nie używa plików INI, zatem jest dużo szybsza od swojej poprzedniczki, wtyczki InstallOptions. Integracja ze skryptem jest ściślejsza, a zarazem bardziej naturalna - tworzenie kontrolek oparte jest na użyciu funkcji, zaś powiadomienia, będące reakcją na akcje użytkownika, wykonywane są bezpośrednio poprzez funkcje skryptu. W przeciwieństwie do wtyczki InstallOptions, nie ma predefiniowanego zbioru dostępnych kontrolek. Dzięki niskopoziomowemu dostępowi do funkcji Windows API, utworzony może być każdy typ kontrolki, a strony mogą być dowolnie dostosowywane.

To samo co czyni wtyczkę nsDialogs bardziej elastyczną, może sprawić problemy początkującym użytkownikom, którzy nie znają API Win32. Problem ten rozwiązany jest dzięki stworzeniu biblioteki predefiniowanych funkcji, zdefiniowanych w skrypcie, które pozwalają na utworzenie i obsługę kontrolek. Dzięki temu, nowi użytkownicy mają pełny dostęp do funkcjonalności wtyczki, zaś zaawansowani użytkownicy wciąż mają dostęp do podstawowych funkcjonalności lub po prostu ich nie używają.

2. Poradnik


2.1 Niestandardowa strona


Przed dodaniem kontrolek na stronę musisz utworzyć tę stronę przy użyciu wtyczki nsDialogs. Strony nsDialogs mogą być utworzone tylko w funkcji tworzenia niestandardowej strony - nie w sekcji ani w normalnej funkcji. Utwórzmy podstawowy skrypt z pustą stroną nsDialogs jako szkielet:

!include LogicLib.nsh

Name nsDialogs
OutFile nsDialogs.exe
XPStyle on

Var Dialog

Page custom nsDialogsPage
Page instfiles

Function nsDialogsPage
	nsDialogs::Create 1018
	Pop $Dialog

	${If} $Dialog == error
		Abort
	${EndIf}

	nsDialogs::Show
FunctionEnd


Section
SectionEnd

Pierwszym wywołaniem musi być zawsze nsDialogs::Create. Wywołanie to tworzy nowe okno dialogowe na stronie i zwraca jego uchwyt HWND na stos. Wynik musi być zdjęty ze stosu, aby zapobiec uszkodzeniu stosu. Jeśli wynikiem jest błąd error, okno dialogowe nie zostanie utworzone.

Wywołanie nsDialogs::Create akceptuje jeden parametr. Ma on swoje specyficzne przeznaczenie, ale żeby nie komplikować, ustalmy, że zawsze musi to być wartość 1018.

Uchwyt HWND jest liczbą, która identyfikuje okno dialogowe, i może być użyty w poleceniach SendMessage, SetCtlColors oraz API Win32.

Okno dialogowe nie jest jeszcze w pełni utworzone i możesz dokonać zmian przed jego wyświetleniem. Aby zakończyć tworzenie strony i wyświetlić okno dialogowe musisz użyć polecenia nsDialogs::Show. Funkcja ta nie zwraca wartości, póki użytkownik nie wciśnie przycisku 'Dalej', 'Wstecz' lub 'Anuluj'.


2.2 Dodawanie kontrolek


Skompilowanie powyższego skryptu i uruchomienie go daje w wyniku pustą stronę, która nie jest zbyt użyteczna. Dodamy teraz do niej kontrolki. Aby to zrobić, użyjemy makra ${NSD_Create*} zdefiniowanego w pliku nagłówkowym nsDialogs.nsh. Każde z tych makr przyjmuje 5 parametrów - x, y, width (szerokość), height (wysokość) oraz text (tekst). Każde makro zwraca na stos wartość - uchwyt HWND kontrolki. Tak jak w przypadku uchwytu okna dialogowego, wartość HWND kontrolki musi być zdjęta ze stosu i zapisana.

Każdy z parametrów wymiaru, które przyjmują makra mogą używać jeden z trzech różnych typów jednostek wymiaru - pikseli, jednostek dialogowych lub wartości procentowej rozmiaru okna dialogowego. Może również przyjmować wartości ujemne, wskazując na wymiar od końca. Aby użyć jednostek dialogowych, wartość wymiaru musi być zakończona literą u. Aby użyć wartości procentowych, wartość wymiaru musi być zakończona znakiem %. Każdy inny znak na końcu lub jego brak oznacza wymiar w pikselach.

Jednostki dialogowe pozwalają na tworzenie okien dialogowych, które skalowane są, gdy używane są różnej wielkości czcionki lub inna wartość DPI. Rozmiar okna w pikselach ustalany jest podczas wykonania na podstawie czcionki oraz wartości DPI. Na przykład, standardowe strony interfejsu NSIS mają rozmiar 266 jednostek dialogowych na szerokości oraz 130 na wysokości. Strony nowoczesnego interfejsu użytkownika mają rozmiar odpowiednio 300 jednostek dialogowych (szerokość) oraz 140 (wysokość). Na różnych rozdzielczościach, przy różnych czcionkach lub ustawieniach DPI, rozmiar okna dialogowego będzie miał zawsze ten sam rozmiar w jednostkach dialogowych, ale inny liczony w pikselach.

!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 1018
	Pop $Dialog

	${If} $Dialog == error
		Abort
	${EndIf}

	${NSD_CreateLabel} 0 0 100% 12u "Cześć, witam w nsDialogs!"
	Pop $Label

	${NSD_CreateText} 0 13u 100% -13u "Wpisz tutaj jakiś tekst..."
	Pop $Text

	nsDialogs::Show

FunctionEnd

Section
SectionEnd

Dostępne typy kontrolek, które można utworzyć używając makra ${NSD_Create*}: HLine, VLine, Label, Icon, Bitmap, BrowseButton, Link, Button, GroupBox, CheckBox, RadioButton (FirstRadioButton oraz AdditionalRadioButton), Text, MLText, Password, Number, FileRequest, DirRequest, RichEdit, ComboBox, DropList, ListBox, SortedListBox, ProgressBar, Animation, HTrackBar, VTrackBar, UpDown, HotKey, DatePicker, IPAddress, NetAddress.


2.3 Stan kontrolek


Mając już kontrolki, może zajść interakcja z użytkownikiem. Aby sprawdzić, jaką akcję wykonał użytkownik dodajmy wpierw do naszej strony funkcję zwrotną wyjścia. W funkcji tej, sprawdzony zostanie stan kontrolki tekstowej, którą utworzyliśmy i wyświetliliśmy użytkownikowi. Aby to zrobić, użyjemy makra ${NSD_GetText}. Dla kontrolek typu RadioButton oraz CheckBox użyjemy makra ${NSD_GetState}.

Zauważcie, że nie wszystkie kontrolki obsługują makro ${NSD_GetText}. Niektóre z nich wymagają użycia specjalnych komunikatów zdefiniowanych w pliku nagłówkowym WinMessages.nsh. Na przykład, kontrolka ListBox wymaga użycia LB_GETCURSEL oraz LB_GETTEXT. Z czasem, biblioteka makr pliku nagłówkowego nsDialogs.nsh zostanie wzbogacona o nowe, które będą obsługiwać więcej przypadków, takich jak powyższe.

!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 1018
	Pop $Dialog

	${If} $Dialog == error
		Abort
	${EndIf}

	${NSD_CreateLabel} 0 0 100% 12u "Cześć, witam w nsDialogs!"
	Pop $Label

	${NSD_CreateText} 0 13u 100% -13u "Wpisz tutaj jakiś tekst..."
	Pop $Text

	nsDialogs::Show

FunctionEnd

Function nsDialogsPageLeave

	${NSD_GetText} $Text $0
	MessageBox MB_OK "Wpisałeś:$\n$\n$0"

FunctionEnd

Section
SectionEnd

2.4 Powiadomienia w czasie rzeczywistym


Jedną z ekscytujących funkcjonalności wtyczki nsDialogs są funkcje zwrotne zdarzeń w oknie dialogowym. Wtyczka nsDialogs może wywołać funkcję zdefiniowaną w skrypcie, która wykona kod będący reakcją na akcje użytkownika, takie jak na przykład zmiana tekstu w kontrolce tekstowej lub kliknięcie na przycisk. Aby to zrobić, użyjemy makra ${NSD_OnClick} oraz ${NSD_OnChange}. Nie każda kontrolka obsługuje oba zdarzenia. Na przykład, kontrolka etykiety może jedynie informować o kliknięciu na nią.

Gdy funkcja zwrotna zostaje wywołana, na stosie odłożona zostaje wartość uchwytu HWND, która musi być zdjęta, aby nie dopuścić do uszkodzenia stosu. W poniższym prostym przykładzie, nie jest to zbyt użyteczne. Ale, w bardziej zaawansowanych skryptach, w których kilka kontrolek jest powiązanych z tą samą funkcją zwrotną, wartość uchwytu HWND na stosie jest bardzo przydatna, informując użytkownika o tym, której kontrolki stan się zmienił.

Nowy przykład pokazuje reakcję na wpisanie przez użytkownika tekstu Cześć w polu tekstowym.

!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 1018
	Pop $Dialog

	${If} $Dialog == error
		Abort
	${EndIf}

	${NSD_CreateLabel} 0 0 100% 12u "Cześć, witam w nsDialogs!"
	Pop $Label

	${NSD_CreateText} 0 13u 100% -13u "Wpisz tutaj jakiś tekst..."
	Pop $Text
	${NSD_OnChange} $Text nsDialogsPageTextChange

	nsDialogs::Show

FunctionEnd

Function nsDialogsPageLeave

	${NSD_GetText} $Text $0
	MessageBox MB_OK "Wpisałeś:$\n$\n$0"

FunctionEnd

Function nsDialogsPageTextChange

	Pop $1 # $1 == $ Text

	${NSD_GetText} $Text $0

	${If} $0 == "Cześć"

		MessageBox MB_OK "Dokładnie za tobą!"

	${EndIf}

FunctionEnd

Section
SectionEnd

2.5 Pamięć


Jak dotąd, mamy stronę, która posiada kilka podstawowych kontrolek. Ale co w przypadku, gdy użytkownik przejdzie do następnej strony i wróci do naszej? Bieżący kod, nie zapamięta danych wpisanych wcześniej przez użytkownika. Aby te dane zapamiętać, użyjemy używanej już funkcji zwrotnej, w której przechowamy wybór użytkownika w zmiennych. Wartości tych zmiennych wykorzystamy przy ponownym tworzeniu kontrolek. Aby lepiej zrozumieć zasadę zapamiętywania danych wprowadzanych przez użytkownika, dodamy również kontrolkę wyboru checkbox i użyjemy makra ${NSD_GetState} oraz ${NSD_SetState}, aby pobrać i ustawić stan tej kontrolki.

Dla większej przejrzystości kodu, usuńmy kilka powiadomień, wprowadzonych w poprzednim kroku poradnika.

!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 "Wpisz tutaj jakiś tekst..."

FunctionEnd

Function nsDialogsPage

	nsDialogs::Create 1018
	Pop $Dialog

	${If} $Dialog == error
		Abort
	${EndIf}

	${NSD_CreateLabel} 0 0 100% 12u "Cześć, witam w nsDialogs!"
	Pop $Label

	${NSD_CreateText} 0 13u 100% 12u $Text_State
	Pop $Text

	${NSD_CreateCheckbox} 0 30u 100% 10u "&Coś"
	Pop $Checkbox

	${If} $Checkbox_State == ${BST_CHECKED}
		${NSD_Check} $Checkbox
	${EndIf}

	# alternatywnie dla powyższego ${If}:
	#${NSD_SetState} $Checkbox_State

	nsDialogs::Show

FunctionEnd

Function nsDialogsPageLeave

	${NSD_GetText} $Text $Text_State
	${NSD_GetState} $Checkbox $Checkbox_State

FunctionEnd

Section
SectionEnd

3. Funkcje


3.1 Create


nsDialogs::Create rect

Tworzy nowe okno dialogowe. Parametr rect określa identyfikator kontrolki, której lokalizacja zostanie powielona. Zazwyczaj wartością jest 1018, co oznacza wbudowane strony. Nowoczesny interfejs użytkownika posiada również kontrolkę 1044 dla strony powitalnej oraz końcowej.

Zwraca na stos uchwyt HWND nowego okna dialogowego lub błąd error.


3.2 CreateControl


nsDialogs::CreateControl class style extended_style x y width height text

Tworzy nową kontrolkę w bieżącym oknie dialogowym. Okno dialogowe musi istnieć, więc funkcja nsDialogs::Create musi być wywołana przed tą funkcją.

Zwraca na stos uchwyt HWND nowego okna dialogowego lub błąd error.


3.3 Show


nsDialogs::Show

Wyświetla stronę. Wywołaj tę funkcję po wywołaniu funkcji nsDialogs::Create, nsDialogs::CreateControl oraz całej reszty.

Nie zwracana jest żadna wartość.


3.4 SelectFileDialog


nsDialogs::SelectFileDialog mode initial_selection filter

Wyświetla użytkownikowi okno dialogowe wyboru pliku. Jeśli parametr mode ma wartość save, wyświetlane jest okno dialogowe zapisu pliku. Jeśli parametr mode ma wartość open, wyświetlane jest okno dialogowe wyboru pliku.

Parametr initial_selection może być użyty do przeglądania domyślnego katalogu z domyślną nazwą pliku. Jeśli parametr initial_selection jest pusty, domyślna nazwa pliku nie będzie ustalona i okno dialogowe wyboru pliku zostanie wyświetlone w bieżącym katalogu roboczym. Jeśli parametr initial_selection określa tylko nazwę pliku, na przykład "test.exe", okno dialogowe będzie ustawione, aby szukać pliku o nazwie test.exe w bieżącym katalogu roboczym. Jeśli parametr initial_selection określa tylko katalog, na przykład "C:\Program Files", okno dialogowe wyświetlane jest z zaznaczeniem tego katalogu, bez nazwy pliku. Jeśli parametr initial_selection określa katalog oraz nazwę pliku, na przykład "C:\Windows\System32\calc.exe", okno dialogowe zostanie ustawione na wyszukanie pliku o nazwie calc.exe w katalogu C:\Windows\System32.

Parametr filter jest listą dostępnych filtrów pliku, rozdzielonych znakiem pionowej kreski. Para filtrów składa się z wyświetlanego łańcucha znaków oraz wzorca symboli wieloznacznych w stylu DOS. Jeśli przekazana wartość parametru jest pusta, użyta zostanie domyślna wartość (Wszystkie pliki|*.*).

Zwraca na stosie zaznaczony plik lub pusty łańcuch znaków, jeśli użytkownik anulował operację.

nsDialogs::SelectFileDialog open "$DOCUMENTS\Config.ini" ".ini files|*.ini|All Files|*.*"
Pop $0
StrCmp $0 "" ...

3.5 SelectFolderDialog


nsDialogs::SelectFolderDialog title initial_selection

Wyświetla użytkownikowi okno dialogowe wyboru katalogu.

Zwraca na stosie zaznaczony katalog lub błąd "error", w przypadku gdy użytkownik anulował operację lub gdy wystąpił błąd.


3.6 SetRTL


nsDialogs::SetRTL rtl_setting

Włącza lub wyłącza tryb 'z prawej do lewej'. Jeśli parametr rtl_setting ma wartość 0, opcja jest wyłączana. Jeśli parametr rtl_setting ma wartość 1, opcja jest włączona. Funkcja ta musi być wywołana przed jakąkolwiek funkcją nsDialogs::CreateControl.

Nie zwracana jest żadna wartość.


3.7 GetUserData


nsDialogs::GetUserData control_HWND

Zwraca na stosie dane użytkownika powiązane z kontrolką. Aby ustawić te dane użyj funkcji nsDialogs::SetUserData.


3.8 SetUserData


nsDialogs::SetUserData control_HWND data

Wiąże dane data z kontrolką. Użyj funkcji nsDialogs::GetUserData, aby pobrać te dane.

Nie zwracana jest żadna wartość.


3.9 OnBack


nsDialogs::OnBack function_address

Ustawia funkcję zwrotną dla przycisku 'Wstecz'. Funkcja ta zostanie wywołana, jeśli użytkownik kliknie przycisk 'Wstecz'. Aby zapobiec powrotowi użytkownika na ostatnią stronę, wykorzystaj funkcję Abort.

Użyj funkcji GetFunctionAddress, aby pobrać adres wymaganej funkcji zwrotnej.

Nie zwracana jest żadna wartość.


3.10 OnChange


nsDialogs::OnChange control_HWND function_address

Ustawia funkcję zwrotną notyfikacji o zmianie stanu danej kontrolki. Za każdym razem, gdy kontrola zmienia swój stan, funkcja zostanie wywołana, a uchwyt HWND kontrolki zostanie odłożony na stosie.

Użyj funkcji GetFunctionAddress, aby pobrać adres wymaganej funkcji zwrotnej.

Nie zwracana jest żadna wartość.


3.11 OnClick


nsDialogs::OnClick control_HWND function_address

Ustawia funkcję zwrotną notyfikacji o kliknięciu na daną kontrolkę. Za każdym razem, gdy kontrolka zostanie kliknięta, funkcja zostanie wywołana, a uchwyt HWND kontrolki zostanie odłożony na stosie.

Użyj funkcji GetFunctionAddress, aby pobrać adres wymaganej funkcji zwrotnej.

Nie zwracana jest żadna wartość.


3.12 OnNotify


nsDialogs::OnNotify control_HWND function_address

Ustawia funkcję zwrotną notyfikacji danej kontrolki. Za każdym razem, gdy kontrolka odbierze komunikat WM_NOTIFY, funkcja zostanie wywołana, a uchwyt HWND kontrolki, kod notyfikacji oraz wskaźnik na strukturę NMHDR zostanie odłożony na stosie.

Użyj funkcji GetFunctionAddress, aby pobrać adres wymaganej funkcji zwrotnej.

Nie zwracana jest żadna wartość.


3.13 CreateTimer


nsDialogs::CreateTimer function_address timer_interval

Ustawia czasomierz, który wywoła funkcję zwrotną danej kontrolki w ustalonych, stałych odstępach czasu. Czas interwału określony jest w milisekundach.

Użyj funkcji GetFunctionAddress, aby pobrać adres wymaganej funkcji zwrotnej.

Nie zwracana jest żadna wartość.


3.14 KillTimer


nsDialogs::KillTimer function_address

Usuwa z pamięci poprzednio utworzony czasomierz.

Użyj funkcji GetFunctionAddress, aby pobrać adres wymaganej funkcji zwrotnej.

Nie zwracana jest żadna wartość.

4. Makra

Plik nagłówkowy nsDialogs.nsh zawiera mnóstwo makr, które sprawiają, że używanie wtyczki nsDialogs jest prostsze. Poniżej wymieniono te makra, wraz z zastosowaniem, składnią, parametrami wejściowymi i zwracanymi wartościami.



NSD_Create*


${NSD_Create*} x y width height text

Tworzy nową kontrolkę w bieżącym oknie dialogowym. Okno dialogowe musi istnieć, więc makro nsDialogs::Create musi być wywołane przed tą funkcją.

Dostępne warianty:

  • ${NSD_CreateHLine}
  • ${NSD_CreateVLine}
  • ${NSD_CreateLabel}
  • ${NSD_CreateIcon}
  • ${NSD_CreateBitmap}
  • ${NSD_CreateBrowseButton}
  • ${NSD_CreateLink}
  • ${NSD_CreateButton}
  • ${NSD_CreateGroupBox}
  • ${NSD_CreateCheckBox}
  • ${NSD_CreateRadioButton} (${NSD_CreateFirstRadioButton} oraz ${NSD_CreateAdditionalRadioButton})
  • ${NSD_CreateText}
  • ${NSD_CreateMLText}
  • ${NSD_CreatePassword}
  • ${NSD_CreateNumber}
  • ${NSD_CreateFileRequest}
  • ${NSD_CreateDirRequest}
  • ${NSD_CreateRichEdit}
  • ${NSD_CreateComboBox}
  • ${NSD_CreateDropList}
  • ${NSD_CreateListBox}
  • ${NSD_CreateSortedListBox}
  • ${NSD_CreateProgressBar}
  • ${NSD_CreateAnimation}
  • ${NSD_CreateHTrackBar}
  • ${NSD_CreateVTrackBar}
  • ${NSD_CreateUpDown}
  • ${NSD_CreateHotKey}
  • ${NSD_CreateDatePicker} (Wymagany Internet Explorer 3.1 oraz ${NSD_InitCommonControlsEx})
  • ${NSD_CreateIPAddress} (Wymagany Internet Explorer 4 oraz ${NSD_InitCommonControl_IPAddress})
  • ${NSD_CreateNetAddress} (Wymagany system Windows Vista oraz ${NSD_InitCommonControl_NetAddress})

Zwraca na stosie uchwyt HWND nowego okna dialogowego lub błąd 'error'.


NSD_OnBack


${NSD_OnBack} function_name

Więcej szczegółów znajdziesz w opisie funkcji OnBack.


NSD_OnChange


${NSD_OnChange} control_HWND function_name

Więcej szczegółów znajdziesz w opisie funkcji OnChange.

Przykład użycia znajdziesz w opisie Powiadomienia w czasie rzeczywistym.


NSD_OnClick


${NSD_OnClick} control_HWND function_name

Więcej szczegółów znajdziesz w opisie funkcji OnClick.


NSD_OnNotify


${NSD_OnNotify} control_HWND function_name

Więcej szczegółów znajdziesz w opisie funkcji OnNotify.


NSD_SetFocus


${NSD_SetFocus} control_HWND

Ustawia fokus kontrolki (uaktywnia ją).


NSD_CreateTimer


${NSD_CreateTimer} function_name timer_interval

Więcej szczegółów znajdziesz w opisie funkcji CreateTimer.


NSD_KillTimer


${NSD_KillTimer} function_name

Więcej szczegółów znajdziesz w opisie funkcji KillTimer.


NSD_AddStyle


${NSD_AddStyle} control_HWND style

Dodaje jeden lub więcej styli okna do kontrolki. Poszczególne wartości styli, powinne być rozdzielone znakiem pionowej kreski `|'.

Opis stylu znajdziesz na stronach MSDN.


NSD_AddExStyle


${NSD_AddExStyle} control_HWND style

Dodaje jeden lub więcej rozszerzonych styli okna do kontrolki. Poszczególne wartości styli, powinne być rozdzielone znakiem pionowej kreski `|'.

Opis stylu znajdziesz na stronach MSDN.


NSD_RemoveStyle


${NSD_RemoveStyle} control_HWND style

Usuwa jeden lub więcej styli okna kontrolki.


NSD_RemoveExStyle


${NSD_RemoveExStyle} control_HWND style

Usuwa jeden lub więcej rozszerzonych styli okna kontrolki.


NSD_GetText


${NSD_GetText} control_HWND output_variable

Pobiera tekst kontrolki i przechowuje go w zmiennej output_variable. Szczególnie przydatne dla kontrolek tekstowych.

Przykład użycia znajdziesz w opisie Stan kontrolek.


NSD_SetText


${NSD_SetText} control_HWND text

Ustawia tekst kontrolki.


NSD_Edit_SetTextLimit


${NSD_Edit_SetTextLimit} control_HWND limit

Ustala ograniczenie liczby znaków wprowadzanych do kontrolki tekstowej.


NSD_Edit_SetReadOnly


${NSD_Edit_SetReadOnly} control_HWND readonly

Wartość 1 ustawia kontrolkę tekstową tylko do odczytu, zaś 0 pozwala na wpisywanie danych.


NSD_Edit_SetCueBannerText


${NSD_Edit_SetCueBannerText} control_HWND displaywhenfocused text

Ustawia tekst podpowiedzi, gdy kontrolka jest pusta. Tekst podpowiedzi widoczny jest tylko w systemie WinXP lub nowszym. Wymagane jest ustawienie XPStyle on.


NSD_RichEd_SetTextLimit


${NSD_RichEd_SetTextLimit} control_HWND limit

Ustawia limit znaków w kontrolce.


NSD_RichEd_SetEventMask


${NSD_RichEd_SetEventMask} control_HWND eventmask

NSD_RichEd_SetCustomBackgroundColor


${NSD_RichEd_SetCustomBackgroundColor} control_HWND COLORREF

NSD_GetState


${NSD_GetState} control_HWND output_variable

Pobiera stan kontrolki wyboru CheckBox lub RadioButton. Możliwe są dwa stany: ${BST_CHECKED} (opcja zaznaczona) oraz ${BST_UNCHECKED} (opcja odznaczona).

Przykład użycia znajdziesz w opisie Pamięć.


NSD_SetState


${NSD_SetState} control_HWND state

Ustala stan kontrolki wyboru CheckBox lub RadioButton. Możliwe są dwa stany state: ${BST_CHECKED} (opcja zaznaczona) oraz ${BST_UNCHECKED} (opcja odznaczona).

Przykład użycia znajdziesz w opisie Pamięć.


NSD_Check


${NSD_Check} control_HWND

Zaznacza kontrolkę wyboru CheckBox lub RadioButton. Rezultat jest taki sam, jak użycie makra ${NSD_SetState} z parametrem ${BST_CHECKED}.


NSD_Uncheck


${NSD_Uncheck} control_HWND

Odznacza kontrolkę wyboru CheckBox lub RadioButton. Rezultat jest taki sam, jak użycie makra ${NSD_SetState} z parametrem ${BST_UNCHECKED}.

Przykład użycia znajdziesz w opisie Pamięć.


NSD_CB_AddString


${NSD_CB_AddString} combo_HWND string

Dodaje łańcuch znaków do kontrolki pola kombinowanego ComboBox.


NSD_CB_InsertString


${NSD_CB_InsertString} combo_HWND index string
${NSD_CB_PrependString} combo_HWND string
${NSD_CB_AppendString} combo_HWND string

Wstawia łańcuch znaków w odpowiedniej pozycji do kontrolki pola kombinowanego ComboBox.


NSD_CB_SelectString


${NSD_CB_SelectString} combo_HWND string

Zaznacza łańcuch znaków kontrolki pola kombinowanego ComboBox.


NSD_CB_GetCount


${NSD_CB_GetCount} combo_HWND $output_variable

NSD_LB_AddString


${NSD_LB_AddString} listbox_HWND string

Dodaje łańcuch znaków do kontrolki listy Listbox.


NSD_LB_InsertString


${NSD_LB_InsertString} listbox_HWND index string
${NSD_LB_PrependString} listbox_HWND string
${NSD_LB_AppendString} listbox_HWND string

Wstawia łańcuch znaków w określonej pozycji do kontrolki listy Listbox.


NSD_LB_DelString


${NSD_LB_DelString} listbox_HWND string

Usuwa łańcuch znaków z listy Listbox.


NSD_LB_DelItem


${NSD_LB_DelItem} listbox_HWND itemindex

Usuwa łańcuch znaków z listy Listbox.


NSD_LB_Clear


${NSD_LB_Clear} listbox_HWND

Usuwa wszystkie łańcuchy znaków z listy Listbox.


NSD_LB_GetCount


${NSD_LB_GetCount} listbox_HWND output_variable

Pobiera liczbę łańcuchów znaków listy Listbox.


NSD_LB_SelectString


${NSD_LB_SelectString} listbox_HWND string

Zaznacza łańcuch znaków na liście Listbox.


NSD_LB_GetSelection


${NSD_LB_GetSelection} listbox_HWND output_variable

Pobiera zaznaczony łańcuch znaków z listy Listbox. Zwraca pusty łańcuch znaków, jeśli nie zaznaczono żadnego łańcucha znaków.


NSD_Anim_OpenFile


${NSD_Anim_OpenFile} anim_HWND avi_path

Otwiera określony klip wideo w formacie .AVI.


NSD_Anim_Play


${NSD_Anim_Play} anim_HWND

Odtwarza klip wideo w pętli.


NSD_Anim_Stop


${NSD_Anim_Stop} anim_HWND

Zatrzymuje odtwarzanie.


NSD_TrackBar_GetPos


${NSD_TrackBar_GetPos} track_HWND $output

NSD_TrackBar_SetPos


${NSD_TrackBar_SetPos} track_HWND pos

NSD_TrackBar_SetRangeMin


${NSD_TrackBar_SetRangeMin} track_HWND minpos

NSD_TrackBar_SetRangeMax


${NSD_TrackBar_SetRangeMax} track_HWND maxpos

NSD_TrackBar_SetTicFreq


${NSD_TrackBar_SetTicFreq} track_HWND frequency

Ustawia odstęp dla znaczników.


NSD_UD_SetBuddy


${NSD_UD_SetBuddy} ud_HWND buddy_HWND

NSD_UD_GetPos


${NSD_UD_GetPos} ud_HWND $output

NSD_UD_SetPos


${NSD_UD_SetPos} ud_HWND pos

NSD_UD_SetPackedRange


${NSD_UD_SetPackedRange} ud_HWND packedrange

Ustawia zakres minimum-maksimum. Dwie 16 bitowe liczby całkowite ze znakiem spakowane w liczbie 32-bitowej.


NSD_HK_GetHotKey


${NSD_HK_GetHotKey} hk_HWND $output

Bity z zakresu 0..7 określają kod klawiszy wirtualnych, a bity z zakresu 8..15 określają flagi modyfikatorów HOTKEYF.


NSD_HK_SetHotKey


${NSD_HK_SetHotKey} hk_HWND packedhotkey

NSD_Date_GetDateFields


${NSD_Date_GetDateFields} HWND

Zwraca na stosie miesiąc, dzień oraz rok.


NSD_SetBitmap


${NSD_SetBitmap} control_HWND image_path $output_variable

Wczytuje mapę bitową z lokalizacji określonej parametrem image_path i wyświetla ją na kontrolce o uchwycie control_HWND utworzonej przy użyciu makra ${NSD_CreateBitmap}. Uchwyt obrazka przechowywany jest w zmiennej użytkownika output_variable. Zmienna ta powinna być zwolniona przy użyciu makra ${NSD_FreeBitmap}.

Obrazek musi zostać wyodrębniony na komputer użytkownika przed wywołaniem tego makra. Dobrym miejscem jest katalog plików tymczasowych NSIS - $PLUGINSDIR

!include nsDialogs.nsh

Name nsDialogs
OutFile nsDialogs.exe

Page custom nsDialogsImage
Page instfiles

Var Dialog
Var ImageCtrl
Var BmpHandle

Function .onInit
	InitPluginsDir
	File /oname=$PLUGINSDIR\image.bmp "${NSISDIR}\Contrib\Graphics\Header\nsis-r.bmp"
FunctionEnd

Function nsDialogsImage
	nsDialogs::Create 1018
	Pop $Dialog

	${If} $Dialog == error
		Abort
	${EndIf}

	${NSD_CreateBitmap} 0 0 100% 100% ""
	Pop $ImageCtrl
	${NSD_SetBitmap} $ImageCtrl $PLUGINSDIR\image.bmp $BmpHandle

	nsDialogs::Show

	${NSD_FreeBitmap} $BmpHandle
FunctionEnd

Section
SectionEnd

NSD_SetStretchedBitmap


${NSD_SetStretchedBitmap} control_HWND image_path $output_variable

Wczytuje i wyświetla mapę bitową, tak jak makro ${NSD_SetImage}, ale rozmiar mapy bitowej dopasowywany jest do rozmiaru kontrolki.


NSD_ClearBitmap


${NSD_ClearBitmap} control_HWND

Usuwa obrazek mapy bitowej z kontrolki.


NSD_FreeBitmap


${NSD_FreeImage} image_handle

Zwalnia uchwyt mapy bitowej wczytanej wcześniej przy użyciu makra ${NSD_SetImage} lub ${NSD_SetStretchedBitmap}.


NSD_SetIcon


${NSD_SetIcon} control_HWND image_path output_variable

Makro to działa tak samo jak makro ${NSD_SetImage}, ale używane jest do wczytywania ikon utworzonych przy użyciu makra ${NSD_CreateIcon}. Uchwyt obrazka przechowywany jest w zmiennej użytkownika output_variable. Zmienna ta powinna być zwolniona przy użyciu makra ${NSD_FreeIcon}.


NSD_SetIconFromInstaller


${NSD_SetIconFromInstaller} control_HWND output_variable

Wczytuje ikonkę używaną w instalatorze i wyświetla ją na kontrolce o uchwycie control_HWND utworzonej przy użyciu makra ${NSD_CreateIcon}. Uchwyt obrazka przechowywany jest w zmiennej użytkownika output_variable. Zmienna ta powinna być zwolniona przy użyciu makra ${NSD_FreeIcon}.


NSD_ClearIcon


${NSD_ClearIcon} control_HWND

Usuwa obrazek ikonki z kontrolki.


NSD_FreeIcon


${NSD_FreeIcon} icon_handle

Zwalnia uchwyt ikonki wczytanej wcześniej przy użyciu makra ${NSD_SetIcon} lub ${NSD_SetIconFromInstaller}.

5. FAQ


Pytanie:

Czy wtyczka nsDialogs obsługuje pliki INI wtyczki InstallOptions?

Odpowiedź:

Plik nagłówkowy nsDialogs.nsh zawiera funkcję CreateDialogFromINI, która pozwala na utworzenie okna dialogowego nsDialogs na podstawie pliku INI. Obsługuje ona wszystkie kontrolki, które obsługiwane są przez wtyczkę InstallOptions, ale nie obsługuje flag oraz notyfikacji. Przykład Examples\nsDialogs\InstallOptions.nsi pokazuje w jaki sposób można użyć tej funkcji.