WSZYSTKIE MATERIAŁY I PROJEKTY, KTÓRE UDOSTĘPNIONE SĄ NA MOJEJ STRONIE INTERNETOWEJ SĄ WCIĄŻ DOSTĘPNE BEZPŁATNIE (BEZ NATRĘTNYCH REKLAM I WYSKAKUJĄCYCH OKIENEK).
Wtyczka nsDialogs
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ść.
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_OnBack, NSD_OnChange, NSD_OnClick, NSD_OnNotify
- NSD_SetFocus
- NSD_CreateTimer, NSD_KillTimer
- NSD_AddStyle, NSD_AddExStyle, NSD_RemoveStyle, NSD_RemoveExStyle
- NSD_GetText, NSD_SetText
- Tekst, Hasło i Liczba: NSD_Edit_SetTextLimit, NSD_Edit_SetReadOnly, NSD_Edit_SetCueBannerText
- RichEdit: NSD_RichEd_SetTextLimit, NSD_RichEd_SetEventMask, NSD_RichEd_SetCustomBackgroundColor
- Pole wyboru (CheckBox) i Przycisk opcji (RadioButton): NSD_GetState, NSD_SetState, NSD_Check, NSD_Uncheck
- Pole Kombi (ComboBox) Lista rozwijana (DropList): NSD_CB_AddString, NSD_CB_PrependString, NSD_CB_AppendString, NSD_CB_InsertString, NSD_CB_DelString, NSD_CB_DelItem, NSD_CB_Clear, NSD_CB_GetCount, NSD_CB_SelectString
- Pole listy (ListBox): NSD_LB_AddString, NSD_LB_PrependString, NSD_LB_AppendString, NSD_LB_InsertString, NSD_LB_DelString, NSD_LB_DelItem, NSD_LB_Clear, NSD_LB_GetCount, NSD_LB_SelectString, NSD_LB_GetSelection
- Animacja: NSD_Anim_OpenFile, NSD_Anim_Play, NSD_Anim_Stop
- Pasek śledzenia (HTrackBar, VTrackBar): NSD_TrackBar_GetPos, NSD_TrackBar_SetPos, NSD_TrackBar_SetRangeMin, NSD_TrackBar_SetRangeMax, NSD_TrackBar_SetTicFreq
- UpDown: NSD_UD_SetBuddy, NSD_UD_GetPos, NSD_UD_SetPos,NSD_UD_SetPackedRange
- Skrót (HotKey): NSD_HK_GetHotKey, NSD_HK_SetHotKey
- Selektor Daty (DatePicker): NSD_Date_GetDateFields
- Mapa bitowa (Bitmap): NSD_SetBitmap, NSD_SetStretchedBitmap, NSD_ClearBitmap, NSD_FreeBitmap
- Ikona (Icon): NSD_SetIcon, NSD_SetIconFromInstaller, NSD_ClearIcon, NSD_FreeIcon
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_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_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_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_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_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_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_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_TrackBar_SetTicFreq
${NSD_TrackBar_SetTicFreq} track_HWND frequency
Ustawia odstęp dla znaczników.
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_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_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_FreeIcon
${NSD_FreeIcon} icon_handle
Zwalnia uchwyt ikonki wczytanej wcześniej przy użyciu makra ${NSD_SetIcon} lub ${NSD_SetIconFromInstaller}.
5. FAQ
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.
