4. Skrypty

Ten dokument zgodny jest z NSIS 3.1


4.1 Format pliku skryptu


Plik skryptu NSIS (.nsi) jest normalnym plikiem tekstowym z kodem skryptu.


Polecenia


Linie komend mają format: 'polecenie [parametry]'

File "mójplik"

Komentarze


Linie zaczynające się znakiem średnika ; lub hasha # są komentarzem. Możesz wstawiać komentarze za poleceniami. Możesz również używać komentarzy w stylu języka C, aby skomentować jedną lub więcej linii kodu.


; Komentarz
# Komentarz

# Komentarz \
    Kolejna linia komentarza (zobacz poniżej na sekcję `Długie komentarze`)

/*
Komentarz
Komentarz
*/

Name /* komentarz */ mójinstalator

File "mójplik" ; Komentarz

Jeśli chcesz wstawić parametr poprzedzony znakiem ; lub # umieść go w cudzysłowie.


Wtyczki


Aby wywołać wtyczkę, użyj składni: 'wtyczka::polecenie [parametry]'. Więcej informacji znajdziesz tutaj: Wtyczki.

nsExec::Exec "mójplik"

Liczby


W parametrach, które traktowane są jako liczby, użyj liczb dziesiętnych (liczba) lub liczb szesnastkowych (z poprzedzającym 0x, np. 0x12345AB), lub liczb ósemkowych (liczby zaczynające się od 0 bez x).

Kolory powinny być zapisywane w szesnastkowym formacie RGB, tak jak w HTML, ale bez znaku #.

IntCmp 1 0x1 lbl_equal

SetCtlColors $HWND CCCCCC

Łańcuchy znaków


W łańcuchach znaków, które zawierają spacje, używaj cudzysłowiów:

MessageBox MB_OK "Witaj!"

Znaki cudzysłowia mają tę właściwość, że zawierają parametr, jeśli zaczynają parametr. Mogą być one zarówno pojedynczymi znakami cudzysłowia, podwójnymi znakami cudzysłowia lub lewym pojedynczym cudzysłowiem.

Możesz ominąć znak cudzysłowia poprzez użycie znaku $\:

MessageBox MB_OK "Będę ' szczęśliwy"
	; wstawia ' do łańcucha znaków
MessageBox MB_OK 'Powiedział do mnie "Cześć!"'
	; wstawia " do łańcucha znaków
MessageBox MB_OK `Powiedział do mnie "Będę ' szczęśliwy!"`
	; wstawia znak ' jak i " do łańcucha znaków
MessageBox MB_OK "$\"Cudzysłów od mądrego człowieka$\" powiedział mądry człowiek"
	; pomijamy cudzysłów

Możliwe jest też wstawianie do łańcuchów znaków nowej linii, znaku tabulatora itp., poprzez użycie znaków $\r, $\n, $\t, itp. Więcej informacji znajdziesz tutaj: Stałe używane w łańcuchach znaków


Zmienne


Zmienne zaczynają się znakiem $. Zmienne użytkownika powinny być zadeklarowane.

Var MOJA_ZMIENNA
StrCpy $MOJA_ZMIENNA "wartosc_mojej_zmiennej"

Więcej infomacji...


Długie polecenia


Aby rozszerzyć polecenie na wiele linii, użyj znaku ukośnika odwrotnego (\) na końcu linii. Następna linia zostanie dołączona do końca poprzedniej. Na przykład:

CreateShortCut "$SMPROGRAMS\NSIS\ZIP2EXE project workspace.lnk" \
    "$INSTDIR\source\zip2exe\zip2exe.dsw"

MessageBox MB_YESNO|MB_ICONQUESTION \
    "Czy chcesz usunąć wszystkie pliki z folderu? \
    (Jeśli masz jakikolwiek plik, który utworzyłeś i chcesz \
      go zachować, kliknij Nie)" \
    IDNO NoRemoveLabel

Rozszerzanie linii w długich poleceniach działa również w komentarzach. Może być to trochę mylące, więc lepiej tego unikać.

# Komentarz \
    a tutaj wciąż komentarz...

Plik konfiguracyjny


Jeśli plik o nazwie "nsisconf.nsh" istnieje w katalogu konfiguracji, zostanie dołączony domyślnie, przed jakimkolwiek skryptem (chyba że, użyty zostanie przełącznik linii poleceń /NOCONFIG). Katalog konfiguracji w Windows jest tym samym, w którym znajdują się plik makensis.exe. Na innych platformach jego lokalizacja ustawiana jest przy instalacji i domyślnie jest to $PREFIX/etc/. Możesz zmienić to w czasie działania instalatora. Więcej informacji znajdziesz tutaj: Zmienne środowiskowe.

4.2 Zmienne


Wszystkie zmienne są zmiennymi globalnymi i mogą być użyte w sekcjach oraz funkcjach. Zauważ że, domyślnie, zmienne są ograniczone do 1024 znaków. Aby zwiększyć tę granicę, skompiluj NSIS z większą wartością NSIS_MAX_STRLEN lub użyj wydania specjalnego NSIS.


4.2.1 Zmienne użytkownika


$VARNAME

Zmienne użytkownika mogą być deklarowane poleceniem Var. Tych zmiennych możesz używać do przechowywania wartości, manipulowania łańcuchami znaków, itd.

4.2.1.1 Var

[/GLOBAL] nazwa_zmiennej

Deklaracja zmiennej użytkownika. Dozwolone znaki dla nazw zmiennych: [a-z][A-Z][0-9] oraz '_'. Wszystkie zdefiniowane zmienne są zmiennymi globalnymi, nawet jeśli zostały zdefiniowane w sekcji lub funkcji. Dla jasności, zmienne zdefiniowane w sekcji lub funkcji muszą być definiowane z flagą /GLOBAL. Flaga /GLOBAL nie jest wymagana poza sekcjami lub funkcjami.

Var przyklad

Function testVar
  Var /GLOBAL przyklad2

  StrCpy $przyklad "Wartość przykładowa"
  StrCpy $przyklad2 "Inna wartość przykładowa"
FunctionEnd


4.2.2 Inne zapisywalne zmienne


$0, $1, $2, $3, $4, $5, $6, $7, $8, $9, $R0, $R1, $R2, $R3, $R4, $R5, $R6, $R7, $R8, $R9

Rejestry. Zmienne te mogą być używane tak jak zmienne użytkownika, ale zazwyczaj używane są w współdzielonych funkcjach lub makrach. Nie musisz ich deklarować, więc nie ma ryzyka konfliktu nazw podczas ich używania w współdzielonym kodzie. Używając ich w kodzie współdzielonym, zaleca się używanie stosu, w celu zapisu i odczytu ich oryginalnych wartości. Zmienne te mogą być również użyte do komunikacji z wtyczkami, ponieważ mogą być odczytywane i zapisywane przez wtyczki DLL.


$INSTDIR

Katalog instalacji ($INSTDIR może być zmieniony poprzez polecenia StrCpy, ReadRegStr, ReadINIStr, itd. - Może być użyty, na przykład, w funkcji .onInit, do bardziej zaawansowanej detekcji lokalizacji instalacji).

Zauważ, że w kodzie deinstalatora, $INSTDIR zawiera katalog, w którym znajduje się deinstalator. Niekoniecznie zawiera tę sama wartość, co w instalatorze. Na przykład, jeśli zapiszesz deinstalatora do katalogu $WINDIR i użytkownik go nie przeniesie, w deinstalatorze katalogiem $INSTDIR będzie katalog $WINDIR. Jeśli zapiszesz deinstalator do innego katalogu, powinieneś przechować lokalizację katalogu $INSTDIR instalatora w rejestrze (lub w inny sposób) i następnie odczytać tę wartość w deinstalatorze.

$OUTDIR

Bieżący katalog wyjściowy (ustawiany poprzez polecenia SetOutPath lub StrCpy, ReadRegStr, ReadINIStr, itd.)

$CMDLINE

Linia poleceń instalatora. Format linii poleceń może być jednym z poniższych:

  • "pełna\ścieżka dostępu do\installer.exe" PARAMETR PARAMETR PARAMETR
  • installer.exe PARAMETR PARAMETR PARAMETR
  • O parsowaniu parametrów można dowiedzieć się więcej czytając opis funkcji GetParameters. Jeśli określono przełącznik linii poleceń /D= (zamiana katalogu instalacji) nie pokaże się w $CMDLINE.

$LANGUAGE

Identyfikator obecnie używanego języka. Na przykład, angielski to 1033, polski to: 1045. Możesz zmienić tę zmienną w sekcji .onInit.



4.2.3 Stałe


Stałe mogą być również używane w atrybucie InstallDir.

Zauważ, że niektóre z nowych stałych nie będą poprawnie pracować w niektórych systemach operacyjnych. Na przykład, $CDBURN_AREA będzie działać tylko na Windows XP i nowszych. Jeśli stała ta zostanie użyta w systemie Windows 98, będzie pusta. Poza tymi oznaczonymi, stałe powinny być dostępne w każdym systemie operacyjnym.


$PROGRAMFILES, $PROGRAMFILES32, $PROGRAMFILES64

Katalog z zainstalowanymi programami (Program Files, zazwyczaj 'C:\Program Files', ale wykrywany w czasie wykonania). W systemie Windows x64, stałe $PROGRAMFILES oraz $PROGRAMFILES32 wskazują na 'C:\Program Files (x86)', podczas gdy stała $PROGRAMFILES64 wskazuje na katalog 'C:\Program Files'. Instalując aplikacje 64-bitowe (x64), należy używać stałej $PROGRAMFILES64.


$COMMONFILES, $COMMONFILES32, $COMMONFILES64

Katalog z plikami wspólnymi (Common Files). Jest to katalog, w którym przechowywane sa elementy współdzielone przez różne aplikacje (zazwyczaj 'C:\Program Files\Common Files', ale wykrywany w czasie wykonania). W systemie Windows x64, stałe $COMMONFILES oraz $COMMONFILES32 wskazują na 'C:\Program Files (x86)\Common Files', podczas gdy stała $COMMONFILES64 wskazuje na katalog 'C:\Program Files\Common Files'. Instalując aplikacje 64-bitowe (x64), należy używać stałej $COMMONFILES64.


$DESKTOP

Katalog pulpitu windows (zazwyczaj 'C:\Windows\Desktop', ale wykrywany w czasie wykonania). Kontekst tej stałej (Wszyscy użytkownicy (All Users) lub Bieżący użytkownik (Current user)) zależny jest od ustawienia SetShellVarContext. Domyślnym jest Bieżący użytkownik.


$EXEDIR

Lokalizacja pliku wykonywalnego instalatora (teoretycznie możesz modyfikować tę zmienną, ale nie jest to dobry pomysł).


$EXEFILE

Nazwa pliku wykonywalnego instalatora.


$EXEPATH

Pełna ścieżka dostępu do pliku wykonywalnego instalatora.


${NSISDIR}

Symbol, który zawiera ścieżkę dostępu do katalogu, w którym zainstalowany jest NSIS. Użyteczny, w przypadku potrzeby wywołania zasobów, które znajdują się w katalogu NSIS, np. ikony, biblioteki interfejsów użytkownika (UI), itp.

Gdy instalator skompilowany jest z ustawieniem przechowywania makensis oraz danych w tym samym katalogu (domyślnie w Windows), jest tą samą lokalizacją dla makensis. Na innych platformach zaś ustawiana jest w czasie kompilacji (więcej informacji znajdziesz w pliku INSTALL). W obu przypadkach możesz modyfikować tę stałą w czasie wykonania, ustawiając zmienną środowiskową NSISDIR. Więcej informacji znajdziesz tutaj: Zmienne środowiskowe.


$WINDIR

Katalog Windows (zazwyczaj C:\Windows lub C:\WinNT, ale wykrywany w czasie wykonania).


$SYSDIR

Katalog systemowy windows (zazwyczaj C:\Windows\System or C:\WinNT\System32, ale wykrywany w czasie wykonania).


$TEMP

Systemowy katalog plików tymczasowych (zazwyczaj C:\Windows\Temp, ale wykrywany w czasie wykonania).


$STARTMENU

Katalog Menu Start (zazwyczaj w połączeniu z funkcją dodawania wpisów do menu CreateShortCut). Kontekst tej stałej (Wszyscy użytkownicy lub Bieżący użytkownik) zależny jest od ustawienia SetShellVarContext. Domyślnym jest Bieżący użytkownik.


$SMPROGRAMS

Katalog programów Menu Start (użyj jeśli chcesz wykorzystać $STARTMENU\Programs). Kontekst tej stałej (Wszyscy użytkownicy lub Bieżący użytkownik) zależny jest od ustawienia SetShellVarContext. Domyślnym jest Bieżący użytkownik.


$SMSTARTUP

Katalog Autostart / Programy Menu Start. Kontekst tej stałej (Wszyscy użytkownicy lub Bieżący użytkownik) zależny jest od ustawienia SetShellVarContext. Domyślnym jest Bieżący użytkownik.


$QUICKLAUNCH

Folder szybkiego uruchamiania, dla aktywnego pulpitu programu IE4 i nowszych wersji. Jeśli szybkie uruchamianie nie jest dostępne, zwraca tę samą wartość co stała $TEMP.


$DOCUMENTS

Katalog dokumentów. Typowa ścieżka dla bieżącego użytkownika to: 'C:\Documents and Settings\NazwaUżytkownika\Moje Dokumenty'. Kontekst tej stałej (Wszyscy użytkownicy lub Bieżący użytkownik) zależny jest od ustawienia SetShellVarContext. Domyślnym jest Bieżący użytkownik.

Stała ta nie jest dostępna w Windows 95 z niezainstalowanym programem Internet Explorer 4.


$SENDTO

Katalog, który zawiera skróty wpisów menu Wyślij do.


$RECENT

Katalog, który zawiera skróty do ostatnio używanych dokumentów użytkownika.


$FAVORITES

Katalog, który zawiera skróty do ulubionych stron internetowych, dokumentów itp. Kontekst tej stałej (Wszyscy użytkownicy lub Bieżący użytkownik) zależny jest od ustawienia SetShellVarContext. Domyślnym jest Bieżący użytkownik.

Stała nie jest dostępna w Windows 95 z niezainstalowanym programem Internet Explorer 4.


$MUSIC

Katalog Moja Muzyka z plikami multimedialnymi użytkownika. Kontekst tej stałej (Wszyscy użytkownicy lub Bieżący użytkownik) zależny jest od ustawienia SetShellVarContext. Domyślnym jest Bieżący użytkownik.

Stała dostępna jest w Windows XP, ME i nowszych wersjach.


$PICTURES

Katalog Moje Obrazy z plikami obrazków użytkownika. Kontekst tej stałej (Wszyscy użytkownicy lub Bieżący użytkownik) zależny jest od ustawienia SetShellVarContext. Domyślnym jest Bieżący użytkownik.

Stała dostępna jest w Windows 2000, XP, ME i nowszych wersjach.


$VIDEOS

Katalog z plikami wideo użytkownika. Kontekst tej stałej (Wszyscy użytkownicy lub Bieżący użytkownik) zależny jest od ustawienia SetShellVarContext. Domyślnym jest Bieżący użytkownik.

Stała dostępna jest w Windows XP, ME i nowszych wersjach.


$NETHOOD

Katalog, który zawiera obiekty, które mogą istnieć w katalogu Otoczenie sieciowe/Cała sieć.

Stała ta nie jest dostępna w Windows 95 z niezainstalowanym programem Internet Explorer 4 oraz aktywnym pulpitem.


$FONTS

Systemowy katalog czcionek.


$TEMPLATES

Katalog z szablonami dokumentów. Kontekst tej stałej (Wszyscy użytkownicy lub Bieżący użytkownik) zależny jest od ustawienia SetShellVarContext. Domyślnym jest Bieżący użytkownik.


$APPDATA

Katalog Danych aplikacji. Wykrywanie ścieżki bieżącego użytkownika wymaga programu Internet Explorer 4 lub nowszego. Wykrywanie ścieżki wszystkich użytkowników wymaga programu Internet Explorer 5 lub nowszego. Kontekst tej stałej (Wszyscy użytkownicy lub Bieżący użytkownik) zależny jest od ustawienia SetShellVarContext. Domyślnym jest Bieżący użytkownik.

Stała ta nie jest dostępna w Windows 95 z niezainstalowanym programem Internet Explorer 4 oraz aktywnym pulpitem.


$LOCALAPPDATA

Lokalny katalog Danych aplikacji (non-roaming).

Stała ta dostępna jest w Windows 2000 i nowszych wersjach.


$PRINTHOOD

Katalog, który zawiera obiekty, które mogą istnieć w katalogu Drukarki.

Stała ta nie jest dostępna w Windows 95 oraz Windows 98.


$INTERNET_CACHE

Katalog plików tymczasowych programu Internet Explorer.

Stała ta nie jest dostępna w Windows 95 oraz Windows NT z niezainstalowanym programem Internet Explorer 4 oraz aktywnym pulpitem.


$COOKIES

Katalog plików ciasteczek programu Internet Explorer.

Stała ta nie jest dostępna w Windows 95 oraz Windows NT z niezainstalowanym programem Internet Explorer 4 oraz aktywnym pulpitem.


$HISTORY

Katalog historii programu Internet Explorer.

Stała ta nie jest dostępna w Windows 95 oraz Windows NT z niezainstalowanym programem Internet Explorer 4 oraz aktywnym pulpitem.


$PROFILE

Katalog profilu użytkownika. Typową ścieżką jest: 'C:\Documents and Settings\NazwaUżytkownika'.

Ta stała dostępna jest w Windows 2000 i nowszych wersjach.


$ADMINTOOLS

Katalog z narzędziami administratora. Kontekst tej stałej (Wszyscy użytkownicy lub Bieżący użytkownik) zależny jest od ustawienia SetShellVarContext. Domyślnym jest Bieżący użytkownik.

Stała ta dostępna jest w Windows 2000, ME i nowszych wersjach.


$RESOURCES

Katalog z zasobami, w którym przechowywane są schematy i inne zasoby Windows (zazwyczaj 'C:\Windows\Resources', ale wykrywane w czasie wykonywania).

Ta stała dostępna jest w Windows XP i nowszych wersjach.


$RESOURCES_LOCALIZED

Katalog zlokalizowanych zasobów, w którym przechowywane są schematy i inne zasoby (zazwyczaj 'C:\Windows\Resources\1045', ale wykrywane w czasie wykonywania).

Ta stała dostępna jest w Windows XP i nowszych wersjach.


$CDBURN_AREA

Katalog, w którym przechowywane są pliki oczekujące na wypalenie na płycie CD.

Ta stała dostępna jest w Windows XP i nowszych wersjach.


$HWNDPARENT

Liczba dziesiętna reprezentująca uchwyt HWND okna rodzica.


$PLUGINSDIR

Ścieżka do folderu tymczasowego, tworzonego przy pierwszym użyciu wtyczki lub wywołaniu polecenia InitPluginsDir. Folder ten jest automatycznie usuwany po zamknięciu instalatora. Jest on idealnym miejscem na przechowywanie plików INI wtyczki InstallOptions, map bitowych wtyczek lub dowolnych innych plików, które są wymagane do działania wtyczki.



4.2.4 Stałe używane w łańcuchach znaków


$$

Stała używana do wyświetlania znaku $.


$\r

Stała używana do wyświetlania znaku karetki (przeniesienia do nowej linii) (\r).


$\n

Stała używana do wyświetlania znaku nowej linii (\n).


$\t

Stała używana do wyświetlania znaku tabulacji (\t).

4.3 Etykiety


Etykiety są miejscem w kodzie, do którego przenosi nas instrukcja Goto, lub innych instrukcji wymagających rozgałęzienia (takich jak IfErrors, MessageBox, IfFileExists oraz StrCmp). Etykiety muszą znajdować się w sekcji lub funkcji. Etykiety mają zasięg lokalny, co oznacza, że są one dostępne tylko w ramach sekcji lub funkcji, w których zostały utworzone. Aby zadeklarować etykietę, po prostu użyj zapisu:

MojaEtykieta:

Etykiety nie mogą rozpoczynać się znakami -, +, !, $, lub 0-9. Określając etykiety dla różnych instrukcji, które je wymagają, pamiętaj, że zarówno pusty łańcuch znaków ("") jak i 0 reprezentują następną instrukcję (co oznacza, że instrukcja Goto nie zostanie wykonana). Etykiety rozpoczynające się znakiem kropki(.) są etykietami globalnymi, co oznacza, że możesz przejść do nich z dowolnej funkcji lub sekcji (jednak nie możesz przeskoczyć do globalnej etykiety deinstalatora z instalatora i na odwrót).

4.4 Skoki warunkowe


W przeciwieństwie do etykiet, skoki warunkowe są, jak sugeruje nazwa, zależne od miejsca, z którego zostały wywołane. Możesz używać skoków warunkowych tam gdzie etykiet. Skoki warunkowe oznaczane są przez liczby. +1 oznacza przeskok do następnej instrukcji (domyślny krok), +2 przeskoczy jedną instrukcję i przejdzie do następnej instrukcji po bieżącej, -2 przeskoczy dwie instrukcje wstecz, a +10 przeskoczy 9 instrukcji, przechodząc do instrukcji dziesiątej po bieżącej.

Instrukcja jest każdym poleceniem, które jest realizowane w czasie wykonania, gdy uruchomiony jest instalator. Wszystkie przykładowo wymienione polecenia MessageBox, Goto, GetDLLVersion, FileRead, SetShellVarContext są instrukcjami. Inne, to jest AddSize, Section, SectionGroup, SectionEnd, SetOverwrite (i wszystkie po Flagi kompilatora), Name, SetFont, LangString nie są instrukcjami, ponieważ wykonywane są one w czasie kompilacji.

Przykłady:

 Goto +2
   MessageBox MB_OK "Nigdy nie zobaczysz tego komunikatu"
 MessageBox MB_OK "Poprzedni komunikat został pominięty, ten powinien zostać wyświetlony"
 Goto +4
 MessageBox MB_OK "Następny komunikat zostanie pominięty"
 Goto +3
 MessageBox MB_OK "Nigdy nie zobaczysz tego komunikatu"
 Goto -3
 MessageBox MB_OK "OK"

Zauważ, że polecenie wstawiania makra, nie jest rozważane jako jedna instrukcja, w sytuacji skoku warunkowego. Przed zastosowaniem skoku warunkowego makro jest rozwijane, więc skoki warunkowe mogą przeskoczyć do wnętrza kodu wstawianego makra. Poniższy, przykładowy kod, nie pominie makra. Wyświetli komunikat.

!macro relative_jump_test
  MessageBox MB_OK "Pierwsza linia makra"
  MessageBox MB_OK "Druga linia makra"
!macroend

Goto +2
!insertmacro relative_jump_test

4.5 Strony


Każdy instalator NSIS (okienkowy) posiada zbiór stron. Każda strona może być stroną wbudowaną w NSIS lub własną stroną, utworzoną przez funkcje użytkownika (poprzez użycie na przykład wtyczki nsDialogs lub InstallOptions).

Używając skryptu, możesz kontrolować kolejność wywoływania stron, ich wygląd oraz zachowanie. Możesz pomijać strony, nadawać im kolor (np. biały), wymuszać na użytkowniku pozostanie na stronie dopóki nie spełniony zostanie określony warunek, wyświetlać stronę 'Czytaj mnie', wyświetlać własne zaprojektowane strony do wprowadzania danych oraz więcej. W tej sekcji, nauczysz się w jaki sposób kontrolować wszystko co zostało powyżej wymienione.

Istnieją dwa podstawowe polecenia związane ze stronami: Page oraz UninstPage. Pierwsze z nich dodaje stronę do instalatora, druga zaś dodaje stronę do deinstalatora. Istnieje również polecenie PageEx, które pozwala na dodanie strony z większą ilością opcji. Polecenie PageEx pozwala na ustawienie opcji do określonej strony, zamiast używania domyślnego zbioru, który ustawiany jest poza PageEx.


4.5.1 Kolejność wywołań


Kolejność wywoływania stron ustalany jest po prostu poprzez zapis poleceń Page, UninstPage oraz PageEx w skrypcie w żądanej kolejności. Na przykład:

 Page license
 Page components
 Page directory
 Page instfiles
 UninstPage uninstConfirm
 UninstPage instfiles

Powyższy kod instruuje NSIS, by najpierw wyświetlona została strona z postanowieniami licencji, następnie strona z wyborem komponentów do zainstalowania, następnie strona wyboru katalogu instalacji oraz w końcu strona z oknem dziennika instalacji, na której wykonywane są poszczególne sekcje, tak jak w starszych instalatorach. Deinstalator wyświetli wpierw stronę z potwierdzeniem deinstalacji oprogramowania i następnie stronę dziennika z postępem deinstalacji.

Możesz określić tę samą stronę kilka razy.

Aby zapewnić kompatybilność wsteczną z starszymi skryptami NSIS, następujące strony instalatora zostaną dodane, jeśli nie użyto żadnych poleceń wywoływania stron: license (jeśli polecenia LicenseText oraz LicenseData zostały określone), components (jeśli polecenie ComponentText zostało określone i jest więcej niż jedna widoczna sekcja), directory (jeśli polecenie DirText zostało określone) oraz instfiles. Gdy nie użyto żadnych poleceń wywoływania stron deinstalatora, następujące strony zostaną dodane: strona potwierdzenia deinstalacji (jeśli polecenie UninstallText zostało określone) oraz instfiles. Metoda ta jest obecnie odradzana, zaleca się konwersję skryptów do takich, które używają poleceń wywoływania stron, ponieważ możesz użyć nowego standardu językowych łańcuchów znaków.



4.5.2 Opcje strony


Każda strona ma swój unikalny zestaw danych, które definiują ich wygląd oraz działanie. W tej sekcji zostaną opisane, które dane poszczególnych stron są używane i w jaki sposób możesz je ustawiać. Funkcje zwrotne opisane są poniżej i w tej sekcji nie ma do nich odniesień.

Poniższa lista wypisuje polecenia, które mają wpływ na każdą z typu stron. Jeśli nie napisano inaczej, komendy te mogą być używane zarówno w jak i poza blokiem PageEx. Jeśli używane są wewnątrz bloku PageEx, będą one miały wpływ tylko na bieżącą stronę, ustawianą przez PageEx, w przeciwnym razie zaś ustawia ona domyślne ustawienia dla każdej z innych stron.


Strona z postanowieniami licencji


Strona wyboru komponentów


Strona wyboru katalogu docelowego


Strona dziennika instalacji/deinstalacji


Strona potwierdzająca deinstalację

Aby ustawić tekst w nagłówku strony, użyj polecenia Caption.



4.5.3 Funkcje zwrotne (Callbacks)


Każda wbudowana strona posiada trzy funkcje zwrotne (Callbacks): Funkcję poprzedzającą (Pre-Function), funkcję utworzenia/wyświetlania (Show-Creation) oraz funkcję wyjścia (Leave-Function). Funkcja poprzedzająca wywoływana jest tuż przed utworzeniem strony, funkcja utworzenia/wyświetlania wywoływana jest tuż po utworzeniu strony oraz funkcja wyjścia wywoływana jest tuż po naciśnięciu przez użytkownika przycisku Dalej, a co za tym idzie przed jej zamknięciem.

  • Funkcja poprzedzająca pozwala na pominięcie strony poprzez użycie polecenia Abort.
  • Funkcja utworzenia/wyświetlenia pozwala na ulepszenie interfejsu użytkownika strony poprzez użycie poleceń CreateFont, SetCtlColors, SendMessage i innych.
  • Funkcja wyjścia pozwala na wymuszenie na użytkowniku pozostania na bieżącej stronie poprzez użycie polecenia Abort.

Niestandardowe strony posiadają tylko dwie funkcje zwrotne. Pierwsza tworzy tę stronę (jest wymagana), druga zaś to funkcja wyjścia, która działa tak jak ta w stronach wbudowanych.

Przykłady:

 Page license skipLicense "" stayInLicense
 Page custom customPage "" ": custom page"
 Page instfiles

 Function skipLicense
   MessageBox MB_YESNO "Czy chcesz pominąć stronę z postanowieniami licencji?" IDNO no
     Abort
   no:
 FunctionEnd

 Function stayInLicense
   MessageBox MB_YESNO "Czy chcesz pozostać na stronie z postanowieniami licencji?" IDNO no
     Abort
   no:
 FunctionEnd

 Function customPage
   GetTempFileName $R0
   File /oname=$R0 customPage.ini
   InstallOptions::dialog $R0
   Pop $R1
   StrCmp $R1 "cancel" done
   StrCmp $R1 "back" done
   StrCmp $R1 "success" done
   error: MessageBox MB_OK|MB_ICONSTOP "Błąd InstallOptions:$\r$\n$R1"
   done:
 FunctionEnd


4.5.4 Page

custom [creator_function] [leave_function] [caption] [/ENABLECANCEL]
  LUB
internal_page_type [pre_function] [show_function] [leave_function] [/ENABLECANCEL]

Polecenie Page dodaje stronę do instalatora. Więcej informacji znajdziesz w sekcji powyżej, opisującej wbudowane strony, niestandardowe strony oraz funkcje zwrotne.

Wartością internal_page_type może być:

  • license - strona z postanowieniami licencji
  • components - strona wyboru komponentów do zainstalowania
  • directory - strona wyboru katalogu docelowego instalacji
  • instfiles - strona instalacji, na której wykonywane są sekcje
  • uninstConfirm - strona potwierdzająca deinstalację

Ostatnia strona instalatora ma przycisk Anuluj zablokowany, aby uniknąć ewentualnej pomyłki. Aby go aktywować, użyj polecenia /ENABLECANCEL.



4.5.5 UninstPage

custom [creator_function] [leave_function] [caption] [/ENABLECANCEL]
  LUB
internal_page_type [pre_function] [show_function] [leave_function] [/ENABLECANCEL]

Dodaje stronę deinstalatora. Więcej informacji znajdziesz w sekcji powyżej, opisującej wbudowane strony i strony własne oraz funkcje zwrotne.

O możliwych wartościach internal_page_type czytaj tutaj: Page.



4.5.6 PageEx

[un.](custom|uninstConfirm|license|components|directory|instfiles)

Dodaje stronę do instalatora lub deinstalatora (jeśli z przedrostkiem un.). Każda strona PageEx musi mieć odpowiadający jej PageExEnd. W bloku PageEx możesz ustawiać opcje, które są specyficzne dla danej strony i które nie zostaną użyte w innych. Opcje, które nie zostaną użyte przyjmą ustawienia z poza bloku PageEx lub domyślne, jeśli nic nie ustawiono. Aby ustalić opisy w nagłówku strony użyj poleceń Caption lub SubCaption. Aby ustalić funkcje zwrotne w PageEx użyj PageCallbacks. Więcej informacji o wbudowanych stronach i własnych znajdziesz w powyższych sekcjach.

Przykładowy sposób użycia:

 PageEx license
   LicenseText "Readme"
   LicenseData readme.rtf
 PageExEnd

 PageEx license
   LicenseData license.txt
   LicenseForceSelection checkbox
 PageExEnd


4.5.7 PageExEnd


Zamyka blok PageEx.



4.5.8 PageCallbacks

([creator_function] [leave_function]) | ([pre_function] [show_function] [leave_function])

Ustawia funkcje zwrotne dla strony zdefiniowanej przez PageEx. Może być użyte tylko we wnetrzu bloku PageEx. Więcej informacji znajdziesz powyżej, w opisie funkcji zwrotnych.

  PageEx license
  PageCallbacks licensePre licenseShow licenseLeave
  PageExEnd

4.6 Sekcje


Każdy instalator NSIS posiada jedną lub więcej sekcji. Każda z tych sekcji jest tworzona, modyfikowana i zamykana przy użyciu następujących poleceń.

  • Każda sekcja zawiera zero lub więcej instrukcji.
  • Sekcje wykonywane są w kolejności przez wynikowy instalator oraz jeśli ComponentText jest ustawiony, użytkownik będzie miał opcje wyłączenia/włączenia każdej widocznej sekcji.
  • Jeśli nazwą sekcji jest 'Uninstall' lub rozpoczyna się prefiksem 'un.', jest to sekcja deinstalatora.

4.6.1 Polecenia sekcji


4.6.1.1 AddSize


size_kb

Instruuje instalatora, poprzez podanie rozmiaru "size_kb", że bieżąca sekcja wymaga dodatkowego miejsca na dysku. Tylko wewnątrz sekcji (nie odniesie skutku poza sekcją lub w funkcji).

Section
   AddSize 500
SectionEnd


4.6.1.2 Section


[/o] [([!]|[-])section_name] [section_index_output]

Rozpoczyna i otwiera nową sekcję. Jeśli section_name jest pusta, pominięta lub zaczynająca się znakiem -, to jest to sekcja ukryta i użytkownik nie będzie miał opcji jej wyłączenia. Jeśli nazwą sekcji jest 'Uninstall' lub jest poprzedzona prefiksem 'un.', to jest to sekcja deinstalatora. Jeśli section_index_output jest określony, parametr będzie zdefiniowany (!defined) indeksem sekcji (może być użyte dla SectionSetText itp.). Jeśli nazwa sekcji zaczyna się znakiem !, sekcja zostanie wyświetlona pogrubioną czcionką. Jeśli określony jest przełącznik /o, sekcja będzie domyślnie odznaczona.

Section "-ukryta sekcja"
SectionEnd

Section # ukryta sekcja
SectionEnd

Section "!pogrubiona sekcja"
SectionEnd

Section /o "opcjonalna"
SectionEnd

Section "instalacja czegoś" SEC_IDX
SectionEnd

Aby uzyskać dostęp do indeksu sekcji, musi być użyty nawias klamrowy i kod musi znajdować się poniżej sekcji w skrypcie.

Section test1 sec1_id
SectionEnd

Section test2 sec2_id
SectionEnd

Function .onInit
  SectionGetText ${sec2_id} $0
  MessageBox MB_OK "Nazwa ${sec2_id}:$\n$0" # wyświetli 'Nazwa 1: test2'
FunctionEnd
Function .onInit
  SectionGetText ${sec2_id} $0
  MessageBox MB_OK "Nazwa ${sec2_id}:$\n$0" # wyświetli 'Nazwa ${sec2_id}: test1'
    # plus ostrzeżenie:
    #   Wykryto nieznaną zmienną/stałą "{sec2_id}", ignorowana
FunctionEnd

Section test1 sec1_id
SectionEnd

Section test2 sec2_id
SectionEnd


4.6.1.3 SectionEnd


Polecenie zamyka bieżącą otwartą sekcję.



4.6.1.4 SectionIn


insttype_index [insttype_index] [RO]

Polecenie to określa, do którego typu instalacji (zobacz InstType) domyślnie należy bieżąca sekcja. Można określić również wiele poleceń SectionIn (są łączone). Jeśli określisz RO jako parametr, to sekcja będzie tylko do odczytu, zo oznacza, że użytkownik nie będzie mógł zmienić jej stanu. Pierwszy typ instalacji zdefiniowany poleceniem InstType jest indeksowany od 1, następny równy jest 2 i tak dalej.

InstType "Pełna"
InstType "Minimalna"

Section "Sekcja"
SectionIn 1 2
SectionEnd

Section "Inna sekcja"
SectionIn 1
SectionEnd


4.6.1.5 SectionGroup


[/e] section_group_name [index_output]

Polecenie to wstawia grupę sekcji. Grupa sekcji musi być zamknięta poleceniem SectionGroupEnd, oraz powinna zawierać jedną (1) lub więcej sekcji. Jeśli grupa sekcji zaczyna się znakiem !, nazwa tej grupy zostanie wyświetlona pogrubioną czcionką. Jeśli określono przełącznik /e, grupa sekcji będzie domyślnie rozwinięta. Jeśli określono index_output, parametrem będzie !defined z indeksem sekcji (który może być użyty w SectionSetText etc). Jeśli nazwa grupy sekcji poprzedzona jest prefiksem 'un.', grupa sekcji jest grupą sekcji deinstalatora.

SectionGroup "Jakieś elementy"
Section "Sekcja"
SectionEnd
Section "Kolejna sekcja"
SectionEnd
SectionGroupEnd


4.6.1.6 SectionGroupEnd


Zamyka grupę sekcji otwartą poleceniem SectionGroup.



4.6.2 Sekcja deinstalacji


Specjalna Sekcja o nazwie 'Uninstall' musi być utworzona, aby utworzyć deinstalatora. Sekcja ta powinna usuwać z systemu wszystkie pliki, klucze rejestru itd., które zostały zainstalowane przez instalatora. Poniżej znajduje się przykład prostej sekcji deinstalacji:

Section "Uninstall"
  Delete $INSTDIR\Uninst.exe ; usuwa się (poniżej znajduje się wyjaśnienie, jak to jest możliwe)
  Delete $INSTDIR\MójProgram.exe
  RMDir $INSTDIR
  DeleteRegKey HKLM SOFTWARE\MójProgram
SectionEnd

Pierwsza instrukcja, Delete działa (to jest usuwa deinstalatora), ponieważ deinstalator jest kopiowany w tle do tymczasowego katalogu systemu, dla deinstalacji.

Zauważ, że kod deinstalatora, $INSTDIR zawiera ścieżkę dostępu do katalogu, w którym znajduje się deinstalator. Niekoniecznie zawiera on tę samą wartość, która w tej samej zmiennej znajdowała się w instalatorze.

4.7 Funkcje


Funkcje są podobne do Sekcji, zawierając również zero lub więcej instrukcji. Funkcje użytkownika nie są bezpośrednio wywoływane przez instalatora, ale wywoływane są z Sekcji, przy użyciu instrukcji Call. Funkcje Zwrotne wywoływane są przez instalatora, gdy wystąpi określone zdarzenie.

Funkcje muszą być zadeklarowana poza Sekcją lub inną Funkcją.


4.7.1 Polecenia funkcji


4.7.1.1 Function


[function_name]

Zaczyna i otwiera nową funkcję. Nazwy funkcji function_name, zaczynające się znakiem "." (np. ".Cokolwiek") są ogólnie zarezerwowane dla funkcji zwrotnych. Nazwy funkcji, zaczynające się przedrostkiem "un." określają funkcje, które zostaną utworzone w Deinstalatorze. Na skutek tego, normalne sekcje instalatora oraz funkcje nie mogą wywoływać funkcji deinstalatora, oraz Sekcje Deinstalatora oraz funkcje deinstalatora nie mogą wywoływać normalnych funkcji.

Function Funkcja
  # jakieś polecenia
FunctionEnd

Section
  Call Funkcja
SectionEnd


4.7.1.2 FunctionEnd


Polecenie to zamyka bieżącą otwartą funkcję.



4.7.2 Funkcje zwrotne


Możesz tworzyć funkcje zwrotne, które mają specjalne nazwy, które będą wywoływane przez instalatora, w określonych miejscach instalacji. Poniżej znajduje się lista obecnie dostępnych funkcji zwrotnych:

4.7.2.1 Funkcje zwrotne instalacji


4.7.2.1.1 .onGUIInit

Ta funkcja zwrotna jest wywoływana tuż przed załadowaniem i wyświetleniem pierwszej strony, co pozwala na ulepszenie interfejsu użytkownika.

Przykład:

!include "WinMessages.nsh"

 Function .onGUIInit
   # 1028 jest numerem id kontrolki z tekstem opisującym firmę (branding text)
   GetDlgItem $R0 $HWNDPARENT 1028
   CreateFont $R1 "Tahoma" 10 700
   SendMessage $R0 ${WM_SETFONT} $R1 0
   # ustaw kolor tła na biały oraz kolor tekstu na czerwony
   SetCtlColors $R0 FFFFFF FF0000
 FunctionEnd


4.7.2.1.2 .onInit

Ta funkcja zwrotna jest wywoływana, gdy instalator jest bliski zakończenia inicjalizacji. Jeśli funkcja '.onInit' wywoła polecenie Abort, instalator natychmiast zakończy działanie.

Poniżej znajdują się dwa przykłady, jak można jej użyć:

 Function .onInit
   MessageBox MB_YESNO "Ten program zainstaluje. Kontynuować?" IDYES NoAbort
     Abort ; powoduje zamknięcie instalatora.
   NoAbort:
 FunctionEnd

lub:

 Function .onInit
   ReadINIStr $INSTDIR $WINDIR\wincmd.ini Configuration InstallDir
   StrCmp $INSTDIR "" 0 NoAbort
     MessageBox MB_OK "Nie znaleziono programu Total Commander. \
	                       Nie udało się pobrać ścieżki instalacji."
     Abort ; powoduje zamknięcie instalatora.
   NoAbort:
 FunctionEnd


4.7.2.1.3 .onInstFailed

Ta funkcja zwrotna jest wywoływana, gdy użytkownik wciśnie przycisk 'Anuluj', gdy instalacja nie powiedzie się (jeśli nie uda się wyodrębnić pliku, lub skrypt instalatora użyje polecenia Abort).

Przykład:

  Function .onInstFailed
    MessageBox MB_OK "Życzę więcej szczęścia następnym razem."
  FunctionEnd


4.7.2.1.4 .onInstSuccess

Ta funkcja zwrotna jest wywoływana, gdy instalacja zakończy się sukcesem, tuż po zamknięciu okna instalacji (czyli po kliknięciu przez użytkownika na przycisk 'Zamknij', jeśli instrukcje AutoCloseWindow lub SetAutoClose są ustawione na fałsz (false)).

Przykład:

  Function .onInstSuccess
    MessageBox MB_YESNO "Gratulacje, udało się. Czy chcesz zobaczyć plik readme?" IDNO NoReadme
      Exec notepad.exe ; otwiera plik readme lub cokolwiek chcesz.
    NoReadme:
  FunctionEnd


4.7.2.1.5 .onGUIEnd

Ta funkcja zwrotna jest wywoływana tuż po zamknięciu okna instalatora. Użyj jej do zwolnienia pamięci wtyczek interfejsu, jeśli jest taka potrzeba.



4.7.2.1.6 .onMouseOverSection

Ta funkcja zwrotna jest wywoływana zawsze, gdy kursor myszy znajdujący się nad drzewem sekcji zmieni swoją pozycję. Pozwala to na ustawienie opisów dla każdej z sekcji, na przykład. Numer id sekcji, nad którym aktualnie znajduje się kursor myszy, przechowywany jest tymczasowo w zmiennej $0.

Przykład:

  Function .onMouseOverSection
    FindWindow $R0 "#32770" "" $HWNDPARENT
    GetDlgItem $R0 $R0 1043 ; opis elementu (musi zostać uprzednio dodany do UI)

    StrCmp $0 0 "" +2
      SendMessage $R0 ${WM_SETTEXT} 0 "STR:Opis pierwszej sekcji"

    StrCmp $0 1 "" +2
      SendMessage $R0 ${WM_SETTEXT} 0 "STR:Opis drugiej sekcji"
  FunctionEnd


4.7.2.1.7 .onRebootFailed

Ta funkcja zwrotna jest wywoływana, jeśli funkcja Reboot nie powiedzie się. Polecenia WriteUninstaller, wtyczki, File oraz WriteRegBin nie powinny być używane w tej funkcji zwrotnej.

Przykład:

 Function .onRebootFailed
   MessageBox MB_OK|MB_ICONSTOP "Funkcja Reboot nie powiodła się. \
                                                         Zrestartuj komputer ręcznie." /SD IDOK
 FunctionEnd


4.7.2.1.8 .onSelChange

Ta funkcja zwrotna jest wywoływana, gdy zmienia się zaznaczenie na stronie komponentów. Użyteczna w połączeniu z instrukcjami SectionSetFlags oraz SectionGetFlags.

Zmiany zaznaczenia obejmują zarówno zaznaczenie sekcji jak i zmianę typu instalacji. Numeru ID zmienionej sekcji przechowywany jest w zmiennej $0. Zmienna $0 ma wartość -1, jeśli typ instalacji został zmieniony. Powiadomienia wysyłane są tylko dla zmian zainicjowanych przez użytkownika i wysyłane jest tylko jedno powiadomienie na daną akcję, nawet gdy ta akcja ma wpływ na sekcje potomne i/lub grupy rodziców.



4.7.2.1.9 .onUserAbort

Ta funkcja zwrotna jest wywoływana, gdy użytkownik kliknie przycisk 'Anuluj', a instalacja wciąż jest prawidłowa. Jeśli ta funkcja wywoła funkcję Abort, instalacja nie zostanie przerwana.

Przykład:

 Function .onUserAbort
   MessageBox MB_YESNO "Przerwać instalację?" IDYES NoCancelAbort
     Abort ; nie pozwala na zamknięcie instalatora.
   NoCancelAbort:
 FunctionEnd


4.7.2.1.10 .onVerifyInstDir

Ta funkcja zwrotna aktywuje kontrolkę, w zależności od tego czy ścieżka instalacji jest poprawna lub nie. Kod ten wywoływany jest za każdym razem, gdy użytkownik zmieni katalog instalacji, więc nie powinna robić niczego dziwnego w instrukcji MessageBox lub podobnej. Jeśli funkcja ta wywoła funkcję Abort, ścieżka instalacji w zmiennej $INSTDIR będzie uważana za nieprawidłową.

Przykład:

  Function .onVerifyInstDir
    IfFileExists $INSTDIR\Winamp.exe PathGood
      Abort ; jeśli $INSTDIR nie jest katalogiem Winampa, nie pozwól na instalację
    PathGood:
  FunctionEnd


4.7.2.2 Funkcje zwrotne deinstalacji


4.7.2.2.1 un.onGUIInit

Ta funkcja zwrotna jest wywoływana tuż przed załadowaniem i wyświetleniem pierwszej strony, co pozwala na ulepszenie interfejsu użytkownika deinstalatora.

Spójrz na przykład opisany w .onGUIInit.



4.7.2.2.2 un.onInit

Ta funkcja zwrotna jest wywoływana, gdy deinstalator jest bliski zakończenia inicjalizacji. Jeśli funkcja 'un.onInit' wywoła polecenie Abort, deinstalator natychmiast zakończy działanie. Zauważ, że funkcja ta może zweryfikować oraz/lub zmodyfikować zmienną $INSTDIR, jeśli jest taka potrzeba.

Poniżej znajdują się dwa przykłady, jak można jej użyć:

  Function un.onInit
    MessageBox MB_YESNO "Ten program odinstaluje. Kontynuować?" IDYES NoAbort
      Abort ; zamyka deinstalatora.
    NoAbort:
  FunctionEnd

lub:

  Function un.onInit
    IfFileExists $INSTDIR\mójplik.exe found
      MessageBox MB_OK "Ścieżka dostępu deinstalatora niepoprawna"
      Abort
    found:
  FunctionEnd


4.7.2.2.3 un.onUninstFailed

Ta funkcja zwrotna jest wywoływana, gdy użytkownik naciśnie przycisk 'Anuluj', gdy deinstalacja nie powiedzie się (jeśli użyto polecenia Abort lub z innego powodu nie powiedzie się).

Przykład:

  Function un.onUninstFailed
    MessageBox MB_OK "Życzę więcej szczęścia następnym razem."
  FunctionEnd


4.7.2.2.4 un.onUninstSuccess

Ta funkcja zwrotna jest wywoływana, gdy deinstalacja zakończy się sukcesem, tuż po zamknięciu okna deinstalacji (czyli po kliknięciu przez użytkownika na przycisk 'Zamknij', jeśli instrukcja SetAutoClose jest ustawiona na fałsz (false)).

Przykład:

  Function un.onUninstSuccess
    MessageBox MB_OK "Gratulacje, deinstalacja udała się."
  FunctionEnd


4.7.2.2.5 un.onGUIEnd

Ta funkcja zwrotna jest wywoływana tuż po zamknięciu okna deinstalatora. Użyj jej do zwolnienia pamięci wtyczek interfejsu, jeśli jest taka potrzeba.



4.7.2.2.6 un.onRebootFailed

Ta funkcja zwrotna jest wywoływana, jeśli funkcja Reboot nie powiedzie się. Polecenia WriteUninstaller, wtyczki, File oraz WriteRegBin nie powinny być używane w tej funkcji zwrotnej.

Przykład:

 Function un.onRebootFailed
   MessageBox MB_OK|MB_ICONSTOP "Funkcja Reboot nie powiodła się. \
                                                         Zrestartuj komputer ręcznie." /SD IDOK
 FunctionEnd


4.7.2.2.7 un.onSelChange

Ta funkcja zwrotna jest wywoływana, gdy zmienia się zaznaczenie na stronie komponentów. Użyteczna w połączeniu z instrukcjami SectionSetFlags oraz SectionGetFlags.

Zmiany zaznaczenia obejmują zarówno zaznaczenie sekcji jak i zmianę typu instalacji. Numeru ID zmienionej sekcji przechowywany jest w zmiennej $0. Zmienna $0 ma wartość -1, jeśli typ instalacji został zmieniony. Powiadomienia wysyłane są tylko dla zmian zainicjowanych przez użytkownika i wysyłane jest tylko jedno powiadomienie na daną akcję, nawet gdy ta akcja ma wpływ na sekcje potomne i/lub grupy rodziców.



4.7.2.2.8 un.onUserAbort

Ta funkcja zwrotna jest wywoływana, gdy użytkownik wciśnie przycisk 'Anuluj', a proces deinstalacji wciąż jest prawidłowy. Jeśli ta funkcja wywoła funkcję Abort, deinstalacja nie zostanie przerwana.

Przykład:

  Function un.onUserAbort
    MessageBox MB_YESNO "Przerwać deinstalację?" IDYES NoCancelAbort
      Abort ; nie pozwala na zamknięcie deinstalatora.
    NoCancelAbort:
  FunctionEnd

4.8 Atrybuty instalatora



4.8.1 Atrybuty ogólne


Wszystkie poniższe polecenia ustawiają atrybuty instalatora. Atrybuty te kontrolują jego wygląd oraz zachowanie się - które strony będą wyświetlane oraz jakie teksty będą wyświetlane na każdej ze stron, jaka jest nazwa instalatora, jakiej ikony używa instalator, domyślny katalog instalacji, plik przez niego zapisywany i więcej. Pamiętaj, że te atrybuty mogą być ustawiane gdziekolwiek w pliku skryptu, poza Sekcją oraz Funkcją.

Domyślne wartości są pogrubione oraz podkreślone


4.8.1.1 AddBrandingImage


(left|right|top|bottom) (width|height) [padding]

Polecenie AddBrandingImage dodaje obrazek producenta na górze, dole, po lewej lub po prawej stronie instalatora. Jego rozmiar ustawiany jest zgodnie z określonymi wartościami szerokości/wysokości (width/height), szerokości/wysokości instalatora oraz czcionki instalatora. Końcowy rozmiar nie zawsze będzie taki jak chciałeś; spójrz na wyjście polecenia, aby zobaczyć aktualny rozmiar. Dzieje się tak, ponieważ zależy to od czcionki instalatora, dlatego przed użyciem polecenia AddBrandingImage powinieneś użyć polecenia SetFont. Domyślną wartością odstępu (padding) jest 2.

Polecenie AddBrandingImage tylko dodaje miejsce na obrazek. Aby ustawić obrazek w czasie wykonania, użyj polecenia SetBrandimgImage.

AddBrandingImage left 100
AddBrandingImage right 50
AddBrandingImage top 20
AddBrandingImage bottom 35
AddBrandingImage left 100 5


4.8.1.2 AllowRootDirInstall


true|false

Polecenie AllowRootDirInstall kontroluje czy instalacja przeprowadzana jest do głównego katalogu dysku lub bezpośrednio do współdzielonej sieci. Ustaw wartość parametru na 'true', aby zmienić bezpieczne zachowanie, które uniemożliwia użytkownikowi wybranie lokalizacji typu C:\ lub \\Serwer\Share, jako katalog instalacji (i później, deinstalacji). Dodatkowe możliwości dostosowywania strony wyboru katalogu znajdziesz w .onVerifyInstDir.



4.8.1.3 AutoCloseWindow


true|false

Polecenie AutoCloseWindow określa czy okno instalatora jest automatycznie zamykane po zakończeniu instalacji, czy też nie. Polecenie to można zmienić w sekcji przy użyciu polecenia SetAutoClose.



4.8.1.4 BGFont


[font_face [height [weight] [/ITALIC] [/UNDERLINE] [/STRIKE]]]

Polecenie BGFont określa czcionkę używaną do wyświetlania tekstu na gradientowym tle. Aby ustawić kolor, użyj polecenia BGGradient. Jeśli nie określono parametrów, użyta zostanie domyślna czcionka. Domyślną czcionką jest czcionka Times New Roman, pogrubiona oraz pochylona.



4.8.1.5 BGGradient


[off|(topc botc [textcolor|notext])]

Polecenie BGGradient określa czy używać gradientowego tła okna, czy też nie. Jeśli wartość parametru ustawiono na 'off', instalator nie będzie wyświetlał okna tła, jeśli nie określono parametrów, użyty zostanie domyślny gradient z czerni do niebieskiego, w przeciwnym razie do utworzenia gradientu używane są kolory top_color lub bottom_color. Top_color oraz bottom_color określane są przy użyciu formatu RRGGBB (w zapisie szesnastkowym, jak w HTML, oprócz znaku poprzedzającego '#', który używany jest do komentarza). Parametr 'textcolor' może być również określony, lub 'notext', co wyłączy tekst dużego tła.



4.8.1.6 BrandingText


/TRIM(LEFT|RIGHT|CENTER) text

Polecenie BrandingText ustawia tekst, który wyświetlany jest u dołu okna instalacji (domyślnie tekstem tym jest 'Nullsoft Install System vX.XX'). Ustawiając ten tekst na pusty ("") sprawiamy, że używany jest domyślny; aby ustawić brak tekstu, użyj " " (spację). Jeśli nie jest to dla ciebie ważne, pozostaw tekst domyślny, żeby wszyscy wiedzieli dlaczego instalator działa dobrze. ;). Użyj parametrów /TRIMLEFT, /TRIMRIGHT lub /TRIMCENTER, aby obciąć rozmiar kontrolki do rozmiaru tekstu.

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane w sekcji .onInit.



4.8.1.7 Caption


caption

Polecenie Caption, jeśli używane jest poza blokiem PageEx, ustawia tekst dla tytułu okna instalatora. Domyślnie tekstem tym jest 'Name Setup', gdzie nazwa (Name) jest określona przez instrukcję Name. Możesz jednak nadpisać to przez tekst 'Instalator mojej aplikacji' lub cokolwiek innego. Jeśli określisz pusty tekst (""), użyty zostanie domyślny (możesz też określić tekst " ", aby usunąć tekst tytułu okna).

Gdy polecenie to używane jest wewnątrz bloku PageEx, ustawia ono podtytuł bieżącej strony.

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane w funkcji .onInit.



4.8.1.8 ChangeUI


dialog ui_file.exe

Polecenie ChangeUI zamienia okno dialogowe (IDD_LICENSE, IDD_DIR, IDD_SELCOM, IDD_INST, IDD_INSTFILES, IDD_UNINST lub IDD_VERIFY) oknem dialogowym o tym samym numerze ID zasobu w pliku ui_file.exe. Możesz również określić okno dialogowe jako 'all', jeśli chcesz zamienić wszystkie 7 okien dialogowych na raz z tego samego pliku UI. Przykłady wyglądu poszczególnych okien dialogowych znajdziesz w katalogu Contrib\UIs, jako podkatalog katalogu NSIS.

  • IDD_LICENSE

    Musi zawierać IDC_EDIT1 (kontrolka RICHEDIT).

  • IDD_DIR

    Musi zawierać IDC_DIR (kontrolka edycji tekstu), IDC_BROWSE (przycisk) oraz IDC_CHECK1 (pole wyboru).

  • IDD_SELCOM

    Musi zawierać IDC_TREE1 (kontrolka SysTreeView32), oraz IDC_COMBO1 (pole kombinowane).

  • IDD_INST

    Musi zawierać IDC_BACK (przycisk), IDC_CHILDRECT (kontrolka statyczna rozmiaru wszystkich innych okien dialogowych), IDC_VERSTR (static), IDOK (przycisk), oraz IDCANCEL (przycisk). Jeśli zostanie znaleziona kontrolka obrazka (kontrolka statyczna static ze stylem SS_BITMAP) w tym oknie dialogowym, zostanie ona użyta jako domyślna dla polecenia SetBrandingImage.

  • IDD_INSTFILES

    Musi zawierać IDC_LIST1 (kontrolka SysListView32), IDC_PROGRESS (kontrolka msctls_progress32), oraz IDC_SHOWDETAILS (przycisk).

  • IDD_UNINST

    Musi zawierać IDC_EDIT1 (pole edycji).

  • IDD_VERIFY

    Musi zawierać IDC_STR (static).

ChangeUI all "${NSISDIR}\Contrib\UIs\sdbarker_tiny.exe"


4.8.1.9 CheckBitmap


bitmap.bmp

Polecenie CheckBitmap określa mapę bitową obrazka, który używany jest do zaznaczania wybranych opcji na drzewie wyboru komponentów do zainstalowania.

Mapa bitowa powinna mieć rozmiar 96x16 pikseli, nie więcej niż 8bpp (256 kolorów) i zawierać sześć obrazków 16x16 dla różnych stanów (w kolejności: maska zaznaczania, odznaczony, zaznaczony, zaszarzony, odznaczony & tylko do odczytu, zaznaczony & tylko do odczytu). Użyj magenty, jako koloru maskującego (obszar ten będzie przezroczysty).



4.8.1.10 CompletedText


text

Polecenie CompletedText zastępuje domyślny tekst ("Completed"), który jest wypisywany po zakończeniu instalacji, jeśli określono parametr. W przeciwnym razie używany jest domyślny.

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane przed wypisaniem komunikatu.



4.8.1.11 ComponentText


[text [subtext] [subtext2]]

Polecenie ComponentText służy do zmiany domyślnego tekstu na stronie wyboru komponentów.

  • text

    Tekst powyżej kontrolki, na prawo od ikonki instalatora.

  • subtext

    Tekst naprzeciwko wyboru typu instalacji.

  • subtext2

    Tekst na lewo od listy komponentów do zainstalowania i poniżej typu instalacji.

Domyślny tekst będzie użyty wtedy gdy ten łańcuch znaków jest pusty ("").

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane przed utworzeniem strony wyboru komponentów.



4.8.1.12 CRCCheck


on|off|force

Polecenie CRCCheck określa czy instalator ma sprawdzać swoją sumę kontrolną CRC, przed kontynuowaniem instalacji. Pamiętaj, że jeśli użytkownik użyje przełącznika /NCRC w linii poleceń przy wykonywaniu programu, a ty nie określiłeś parametru 'force', suma kontrolna CRC nie będzie sprawdzana, a użytkownik będzie miał możliwość instalacji (potencjalnie) uszkodzonego instalatora.



4.8.1.13 DetailsButtonText


show details text

Polecenie DetailsButtonText zamienia domyślny tekst przycisku "Pokaż Szczegóły" (Show details), jeśli określono parametr (w przeciwnym razie użyty zostanie domyślny).

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane przed utworzeniem strony dziennika instalacji (instfiles).



4.8.1.14 DirText


[text] [subtext] [browse_button_text] [browse_dlg_text]

Polecenie DirText służy do zmiany domyślnego tekstu na stronie wyboru katalogu docelowego instalacji.

  • text

    Tekst znajdujący się powyżej kontrolek, po prawej stronie ikonki instalacji.

  • subtext

    Tekst znajdujący się na ramce wyboru katalogu docelowego.

  • browse_button_text

    Tekst znajdujący się na przycisku 'Przeglądaj...'.

  • browse_dlg_text

    Tekst znajdujący się w oknie dialogowym "Przeglądaj w poszukiwaniu folderu", które pojawia się po kliknięciu w przycisk "Przeglądaj...".

Jeśli łańcuch znaków jest pusty użyty zostanie domyślny tekst ("").

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane przed utworzeniem strony wyboru katalogu docelowego instalacji.



4.8.1.15 DirVar


user_var(dir input/output)

Polecenie DirVar określa zmienną, która przechowuje katalog instalacji. Zmienna ta powinna także zawierać domyślną wartość. Pozwala to na łatwe utworzenie dwóch różnych stron wyboru katalogu, które nie będą wymagały od ciebie przenoszenia wartości do i z poza katalogu $INSTDIR. Domyślną zmienną jest $INSTDIR. Może być ona użyta tylko na stronie PageEx oraz dla katalogu oraz stron potwierdzenia deinstalacji.

Var INNY_KATALOG
PageEx katalog
  DirVar $INNY_KATALOG
PageExEnd

Section
  SetOutPath $INSTDIR
  File "plik.dat"
  SetOutPath $INNY_KATALOG
  File "inny plik.dat"
SectionEnd


4.8.1.16 DirVerify


auto|leave

Polecenie DirVerify weryfikuje katalog docelowy. Jeśli użyjemy polecenia `DirVerify leave', przycisk 'Dalej' nie będzie wyłączony w przypadku, gdy katalog instalacji nie jest prawidłowy lub jest za mało miejsca. Zamiast tego ustawiona zostanie flaga, którą możesz odczytać w funkcji wyjścia (leave) używając polecenia GetInstDirError.

PageEx directory
  DirVerify leave
  PageCallbacks "" "" dirLeave
PageExEnd


4.8.1.17 FileErrorText


File error text

Polecenie FileErrorText zamienia domyślny tekst, który wyświetlany jest, gdy nie można zapisać pliku. Ten łańcuch znaków może zawierać odniesienie do zmiennej $0, która przechowuje nazwę pliku (wartość zmiennej $0 jest tymczasowo zmieniana na tę wartość). Przykład: "Nie można zapisać do pliku $\r$\n$0$\r$\nPowodzenia.".

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane przed użyciem polecenia File.



4.8.1.18 Icon


[path\]icon.ico

Polecenie Icon ustawia ikonę instalatora. Każda z ikonek składających się na plik ikony zostanie dołączona do instalatora. Użyj polecenia UninstallIcon, aby ustawić ikonę deinstalatora.



4.8.1.19 InstallButtonText


install button text

Polecenie InstallButtonText, jeśli określono parametr, nadpisuje domyślny tekst na przycisku instalacji ("Instaluj") na określony tekst.

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane przed wyświetleniem przycisku instalacji.



4.8.1.20 InstallColors


/windows | (foreground_color background_color)

Polecenie InstallColors ustawia kolory, które używane są na ekranie informującym o instalacji. Domyślnymi kolorami są odpowiednio kolor 00FF00 (zielony) oraz 000000 (czarny). Użyj formatu RRGGBB (zapis w systemie szesnastkowym, tak jak w HTML, ale bez poprzedzającego dany kolor znaku '#', ponieważ znak '#' zarezerwowany jest dla komentarza). Pamiętaj, że jeśli użyty zostanie tylko parametr "/windows", użyte zostaną domyślne kolory Windows.



4.8.1.21 InstallDir


definstdir

Polecenie InstallDir ustawia domyślny katalog instalacji. Zmienne, które mogą być użyte do utworzenia tego łańcucha znaków opisane są w sekcji zmienne (szczególnie zmienna $PROGRAMFILES). Zwróć uwagę, że część łańcucha znaków poprzedzająca ostatni znak '\' zostanie użyta, jeśli użytkownik wybierz przycisk 'Przeglądaj...' i może być dołączona do łańcucha znaków w czasie instalacji (aby zablokować takie działanie, zakończ katalog znakiem '\', jednak użycie go wymusi zamknięcie całej linii parametru w znak cudzysłowia). Jeśli nie bardzo rozumiesz o co chodzi, popróbuj trochę jak działa przycisk 'Przeglądaj...'.



4.8.1.22 InstallDirRegKey


root_key subkey key_name

Polecenie InstallDirRegKey sprawdza w rejestrze łańcuch znaków określający katalog instalacji i używa go jako katalog instalacji, jeśli jest prawidłowy. Jeśli ten atrybut jest obecny, nadpisuje on atrybut InstallDir, jeśli klucz rejestru jest prawidłowy, a w przeciwnym razie używa domyślnego atrybutu InstallDir. Przeszukując wpis rejestru, polecenie automatycznie usuwa znaki cudzysłowia. Jeśli łańcuch znaków katalogu instalacji kończy się ".exe", nazwa pliku zostanie automatycznie usunięta z łańcucha znaków (np. jeśli łańcuch znaków to "C:\Program Files\Foo\app.exe", zostanie on skrócony do "C:\Program Files\Foo"). Aby skonfigurować katalog instalacji, ustaw zmienną $INSTDIR w funkcji .onInit.

Łańcuchy znaków języka oraz zmienne nie mogą być użyte z poleceniem InstallDirRegKey.

InstallDirRegKey HKLM Software\NSIS ""
InstallDirRegKey HKLM Software\ACME\Thingy InstallLocation


4.8.1.23 InstProgressFlags


[flag [...]]

Polecenie InstProgressFlags ustawia widok paska postępu instalacji. Prawidłowymi flagami są "smooth" (pasek postępu jest wygładzony) lub "colored" (pasek postępu używa kolorów ustawionych przez polecenie InstallColors).

Przykłady: "InstProgressFlags" (domyślny wygląd Windows), "InstProgressFlags smooth" (nowy wygładzony wygląd), "InstProgressFlags smooth colored" (wygładzony wygląd z kolorami).

Uwaga: Zarówno "smooth" jak i "colored" działają z włączonym poleceniem XPStyle, jeśli instalator uruchomiony jest w systemie Windows XP z nowoczesną kompozycją.



4.8.1.24 InstType


install_type_name | /NOCUSTOM | /CUSTOMSTRING=str | /COMPONENTSONLYONCUSTOM

Polecenie InstType dodaje typy instalacji do listy typów instalacji lub wyłącza niestandardowy typ instalacji. Możesz użyć do 32 typów instalacji, każdy z nich określony jest przez nazwę. Jeśli nazwa poprzedzona jest prefiksem 'un.', jest to typ instalacji deinstalatora. Nazwa typu instalacji może zawierać zmienne, które zostaną przetworzone w czasie wykonania, przed wyświetleniem strony wyboru komponentów instalacji.

Innym sposobem zmiany nazwy typu instalacji InstType w czasie wykonania jest użycie polecenia InstTypeSetText. Różnica jest taka, że używając polecenia InstTypeSetText nie musisz używać swoich zmiennych użytkownika.

Pierwszy typ jest typem domyślnym ('Typical'). Jeśli określono przełącznik /NOCUSTOM, typ instalacji niestandardowej "Custom" jest wyłączony i użytkownik musi wybrać jeden z predefiniowanych typów instalacji. Jeśli natomiast określono przełącznik /CUSTOMSTRING, parametr ten zastąpi tekst niestandardowego typu instalacji "Custom". Również, jeżeli określono flagę /COMPONENTSONLYONCUSTOM, lista komponentów do zainstalowania zostanie wyświetlona tylko wtedy, gdy zaznaczony jest niestandardowy typ instalacji "Custom".

Polecenie to akceptuje zmienne dla nazw typów instalacji. Jeśli uzywane są zmienne, muszą one być zainicjowane przed utworzeniem strony wyboru komponentów instalacji.



4.8.1.25 LicenseBkColor


color | /gray | /windows

Polecenie LicenseBkColor ustawia kolor tła danych licencji. Kolor określany jest w formacie RRGGBB (zapis w systemie szesnastkowym, tak jak w HTML, ale bez poprzedzającego dany kolor znaku '#', ponieważ znak '#' zarezerwowany jest dla komentarza). Domyślnym kolorem jest kolor szary '/gray'. Możesz również użyć kolorów zdefiniowanych przez Windows używając parametru '/windows'.



4.8.1.26 LicenseData


licdata.(txt|rtf)

Polecenie LicenseData określa plik tekstowy lub plik w formacie RTF dla tekstu licencji, którą może przeczytać użytkownik. Pomiń to polecenie, jeśli nie chcesz wyświetlać tekstu licencji. Pamiętaj, że plik musi być w formacie tekstowym DOS (\r\n, tak!). Aby zdefiniować wielojęzykowe dane licencji użyj polecenia LicenseLangString.

Jeśli twój plik licencji jest w formacie RTF zaleca się edytować go w programie WordPad, nie w programie MS Word. Użycie programu WordPad generuje znacznie mniejszy plik.

Użyj polecenia LicenseLangString, aby wyświetlić różne teksty licencji dla każdego z użytych języków.



4.8.1.27 LicenseForceSelection


(checkbox [accept_text] | radiobuttons [accept_text] [decline_text] | off)

Polecenie LicenseForceSelection określa, czy wyświetlona licencja musi być zaakceptowana czy też nie. Może to być zrealizowane przez użycie pola wyboru lub przycisków typu radio. Domyślnie, przycisk "Dalej" jest wyłączony i będzie włączony tylko wtedy, gdy pole wyboru jest zaznaczone lub przycisk radio po prawej stronie jest zaznaczony. Jeśli parametr 'off' jest określony, przycisk "Dalej" jest domyślnie włączony.

LicenseForceSelection checkbox
LicenseForceSelection checkbox "Zgadzam się"
LicenseForceSelection radiobuttons
LicenseForceSelection radiobuttons "Zgadzam się"
LicenseForceSelection radiobuttons "Zgadzam się" "Nie zgadzam się"
LicenseForceSelection radiobuttons "" "Nie zgadzam się"
LicenseForceSelection off


4.8.1.28 LicenseText


[text [button_text]]

Polecenie LicenseText zmienia domyślny tekst na stronie licencji.

  • text

    Tekst wyświetlany powyżej kontrolek, po prawej stronie od ikony instalatora.

  • button_text

    Tekst wyświetlany na przycisku "Zgadzam się".

Jeśli łańcuch znaków jest pusty ("") użyty zostanie domyślny tekst.

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane przed utworzeniem strony licencji.



4.8.1.29 ManifestDPIAware


notset|true|false

Polecenie ManifestDPIAware informuje, że instalator uwzględnia DPI. Aplikacje uwzględniające DPI nie są skalowane przez mechanizm DWM (wirtualizacja DPI), więc tekst nigdy nie jest rozmyty. NSIS nie skaluje map bitowych używanych przez drzewo komponentów na stronie wyboru komponentów i niektóre wtyczki mogą mieć problemy ze zgodnością, więc warto przetestować instalator z różnymi ustawieniami DPI po określeniu parametru na true.

Więcej informacji o aplikacjach DPI-aware znajdziesz na stronach MSDN.



4.8.1.30 ManifestSupportedOS


none|all|WinVista|\\Win7|Win8|Win8.1|Win10\\|{GUID} [...]

Polecenie ManifestSupportedOS informuje, że instalator kompatybilny jest z określonymi wersjami Windows. Polecenie to dodaje wpis SupportedOS do sekcji kompatybilności w pliku manifest aplikacji. Domyślna lista Win7+8+8.1+10 zostanie prawdopodobnie w przyszłości uaktualniona o nowsze wersje Windows. Parametr none jest domyślnym, jeśli polecenie RequestExecutionLevel ustawione jest na none z powodów kompatybilności.

Windows 8.1 oraz nowsze nie zwrócą prawdziwego numeru wersji, jeśli wsparcie dla określonej wersji Windows nie zostanie zadeklarowane. O innych zmianach w zachowaniu się aplikacji możesz przeczytać więcej na stronach MSDN.



4.8.1.31 MiscButtonText


[back button text [next button text] [cancel button text] [close button text]]

Polecenie MiscButtonText zamienia domyślne teksty znajdujące się na przyciskach (< Wstecz, Dalej >, Anuluj oraz Zamknij). Jeśli w poleceniu pominięte zostaną parametry, użyte zostaną domyślne teksty.

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane w funkcji .onInit.



4.8.1.32 Name


name [name_doubled_ampersands]

Polecenie Name ustawia nazwę instalatora. Nazwą jest zazwyczaj nazwa produktu, taka jak 'Moja Aplikacja' lub 'Aplikacja MojejFirmy'. Jeśli w nazwie znajduje się jeden lub więcej znaków ampersand (&), ustaw drugi parametr dla tej samej nazwy, tyle że używając podwójnych znaków ampersand. Na przykład, jeśli nazwa instalatora to: "Foo & Bar", użyj:

 Name "Foo & Bar" "Foo && Bar"

Jeśli nazwa instalatora zawiera znaki ampersand i używasz dla niego polecenia LangString, musisz utworzyć inną nazwę, która zawiera podwójny znak ampersand w drugim parametrze.

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane w funkcji .onInit.



4.8.1.33 OutFile


[path\]install.exe

Polecenie OutFile określa wyjściowy plik dla pliku instalatora. To jest plik, który tworzy program MakeNSIS, nie ma wpływu na zawartość instalatora.



4.8.1.34 RequestExecutionLevel


none|user|highest|admin

Polecenie RequestExecutionLevel określa żądany poziom wykonania aplikacji dla systemów Windows Vista lub nowszych. Wartość ta jest zapisywana w instalatorze oraz deinstalatorze w pliku manifest w formacie XML, który informuje system operacyjny jaki poziom uprawnień jest wymagany dla instalatora.

Poziom uprawnień user to poziom uprawnień zwykłego użytkownika, nie są wymagane uprawnienia administratora.

Poziom uprawnień highest wymaga podwyższonego poziomu wykonania dla bieżącego użytkownika i wymaga weryfikacji i ewentualnego podniesienia tych uprawnień przez użytkownika, jeśli znajduje się on w grupie administratorów. W oknie dialogowym użytkownik może być poproszony o wpisanie hasła użytkownika.

Poziom uprawnień admin, który jest domyślnym poziomem uprawnień, wymaga uprawnień administratora i wymaga weryfikacji oraz podniesienia uprawnień przez użytkownika.

Określenie uprawnień na none powoduje to, że manifest jest pusty i to system operacyjny Windows decyduje o poziomie uprawnień dla instalatora. System Windows automatycznie identyfikuje instalatory NSIS i nakłada potrzebę uprawnień administratora. Z tego też powodu, parametr none oraz admin dają taki sam efekt.

Zaleca się, przynajmniej przez Microsoft, że każda aplikacja powinna być oznaczona żądanym poziomem wykonania. Instalatory, które nie są odpowiednio oznaczone działają w trybie zgodności. Obejście tego trybu obejmuje automatyczne przenoszenie skrótów utworzonych w menu Start użytkownika do menu Start wszystkich użytkowników. Instalatory, które nie kopiują niczego do folderów systemowych lub nie zapisują danych do rejestru w gałęzi HKLM powinny być oznaczone poziomem wykonania user.

Więcej informacji na ten temat można znaleźć w witrynie MSDN.



4.8.1.35 SetFont


[/LANG=lang_id] font_face_name font_size

Polecenie SetFont ustawia czcionkę instalatora. Należy pamiętać o tym, że wybrana czcionka musi być zainstalowana w systemie użytkownika. Nie używaj mało popularnych czcionek, które tylko ty posiadasz.

Użyj przełącznika /LANG, jeśli chcesz użyć różnej czcionki dla różnych języków. Na przykład:

 SetFont /LANG=${LANG_ENGLISH} " Czcionka dla języka angielskiego" 9
 SetFont /LANG=${LANG_FRENCH} "Czcionka dla języka francuskiego" 10

Istnieją dwie definicje dla łańcucha znaków LangString o nazwach ^Font oraz ^FontSize. Zawierają one nazwę czcionki oraz rozmiar czcionki dla każdego z języków.



4.8.1.36 ShowInstDetails


hide|show|nevershow

Polecenie ShowInstDetails określa czy tekst dziennika instalacji jest wyświetlany czy też nie. Parametr 'hide' domyślnie ukrywa szczegóły instalacji, zezwalając użytkownikowi na ich podgląd. Parametr 'show' domyślnie wyświetla szczegóły instalacji, zaś parametr 'nevershow' uniemożliwia użytkownikowi zobaczenie szczegółów instalacji. Polecenie to może być zmienione w sekcji przy użyciu polecenia SetDetailsView.



4.8.1.37 ShowUninstDetails


hide|show|nevershow

Polecenie ShowUninstDetails określa czy tekst dziennika deinstalacji jest wyświetlany czy też nie. Parametr 'hide' domyślnie ukrywa szczegóły instalacji, zezwalając użytkownikowi na ich podgląd. Parametr 'show' domyślnie wyświetla szczegóły instalacji, zaś parametr 'nevershow' uniemożliwia użytkownikowi zobaczenie szczegółów instalacji. Polecenie to może być zmienione w sekcji przy użyciu polecenia SetDetailsView.



4.8.1.38 SilentInstall


normal|silent|silentlog

Polecenie SilentInstall określa czy instalator działa w trybie cichym czy też nie. Jeśli użyjemy parametru 'silent' lub 'silentlog', wszystkie sekcje instalatora, które posiadają flagę SF_SELECTED są instalowane w trybie cichym (możesz ustawić tę flagę używając instrukcji SectionSetFlags), co oznacza brak okien instalatora (skrypt może wciąż wyświetlać dowolne informacje, możesz użyć instrukcji MessageBox wraz z przełącznikiem /SD).

Pamiętaj, że jeśli użyjesz parametru 'normal', a użytkownik uruchomił instalator z przełącznikiem /S (ważna jest wielkość liter) w wierszu poleceń, instalator będzie działał tak, jakby użyto polecenia SilentInstall z parametrem 'silent'. Uwaga: Zobacz również opis instrukcji LogSet.

Więcej informacji znajdziesz w sekcji 4.12.



4.8.1.39 SilentUnInstall


normal|silent

Polecenie SilentUnInstall określa czy deinstalator działa w trybie cichym czy też nie. Jeśli użyjemy parametru 'silent' lub 'silentlog', wszystkie sekcje deinstalatora są wykonywane w trybie cichym, co oznacza brak okien deinstalatora (skrypt może wciąż wyświetlać dowolne informacje, możesz użyć instrukcji MessageBox wraz z przełącznikiem /SD).

Pamiętaj, że jeśli użyjesz parametru 'normal', a użytkownik uruchomił deinstalator z przełącznikiem /S w wierszu poleceń, deinstalator będzie działał tak, jakby użyto polecenia SilentUnInstall z parametrem 'silent'. Uwaga: Zobacz również opis instrukcji LogSet.

Więcej informacji znajdziesz w sekcji 4.12.



4.8.1.40 SpaceTexts


[req text [avail text]]

Polecenie SpaceTexts, jeśli użyto parametrów, zastępuje teksty na stronie wyboru lokalizacji (domyślnie: "Wymagane miejsce: " oraz "Dostępne miejsce: "). Jeżli użyto parametru 'none' teksty informujące o wolnym miejscu na dysku nie zostaną wyświetlone.

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane przed utworzeniem strony wyboru komponentów.



4.8.1.41 SubCaption


[page_number subcaption]

Polecenie SubCaption ustawia domyślne teksty dla podtytułów na stronach instalatora (0=": Umowa licencyjna",1=": Opcje instalacji",2=": Folder instalacyjny", 3=": Instalowanie plików", 4=": Zakończono"). Jeśli określony zostanie pusty łańcuch znaków (""), użyte zostaną domyślne teksty (możesz jednak wpisać jedną spację " ", aby zachować pusty łańcuch znaków).

Możesz również ustawić tekst podtytułu (lub zastąpić domyślny) używając polecenia Caption wewnątrz bloku strony PageEx.

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane przed utworzeniem odpowiedniej strony.



4.8.1.42 UninstallButtonText


text

Polecenie UninstallButtonTextzmienia tekst na przycisku deinstalatora. Domyślnym tekstem jest "Odinstaluj". Jeśli nie użyto parametru, użyty zostaje tekst domyślny. Zobacz również opis instrukcji WriteUninstaller (zamienia UninstallEXEName).

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane przed wyświetleniem przycisku deinstalacji.



4.8.1.43 UninstallCaption


caption

Polecenie UninstallCaption ustawia teksty wyświetlane na pasku tytułu deinstalatora. Domyślnym tekstem jest 'Deinstalacja Name', gdzie: 'Name' określone jest poleceniem .Name. Możesz zastąpić ten tekst dowolnym tekstem, np. 'Deinstalacja mojej aplikacji'. Jeśli określony zostanie pusty łańcuch znaków (""), użyte zostaną domyślne teksty (możesz jednak wpisać jedną spację " ", aby zachować pusty łańcuch znaków).

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane w funkcji un.onInit.



4.8.1.44 UninstallIcon


[path\]icon.ico

Polecenie UninstallIcon ustawia ikonę dla deinstalatora.



4.8.1.45 UninstallSubCaption


page_number subcaption

Polecenie UninstallSubCaption ustawia domyślne teksty dla podtytułów na stronach deinstalatora (0=": Potwierdzenie", 1=": Deinstalowanie plików", 2=": Zakończono"). Jeśli określony zostanie pusty łańcuch znaków (""), użyte zostaną domyślne teksty (możesz jednak wpisać jedną spację " ", aby zachować pusty łańcuch znaków).

Możesz również ustawić tekst podtytułu (lub zastąpić domyślny) używając polecenia Caption wewnątrz bloku strony PageEx.

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane przed utworzeniem odpowiedniej strony.



4.8.1.46 UninstallText


text [subtext]

Polecenie UninstallText określa tekst znajdujący się na stronie potwierdzenia deinstalacji.

  • text

    Tekst, który znajduje się nad kontrolkami

  • subtext

    Tekst obok lokalizacji deinstalacji

Akceptowane są zmienne. Jeśli używane są zmienne, muszą być one zainicjowane przed utworzeniem strony potwierdzenia deinstalacji.



4.8.1.47 WindowIcon


on|off

Polecenie WindowIcon określa, czy ikona instalatora jest wyświetlana czy też nie.



4.8.1.48 XPStyle


on|off

Polecenie XPStyle określa, czy manifest XP zostanie dołączony do instalatora, czy też nie. Manifest XP sprawia, że instalator używa nowego stylu XP, jeśli uruchomiony jest w systemie Windows XP. Dotyczy to również deinstalatora.



4.8.2 Flagi kompilatora


Poniższe polecenia określają sposób generowania kodu oraz kompresji danych przez instalator. Jeśli nie wspomniano, że jest inaczej, polecenia te działają wszędzie w skrypcie i mają wpływ na każdą linię kodu znajdującą się poniżej (aż do nadpisania przez inne polecenie). Nie można ich przeskoczyć używając instrukcji z sekcji Instrukcje kontroli wykonania.

Dla przykładu, w poniższym skrypcie, plik blah.dat nigdy nie zostanie nadpisany.

${If} $0 == 0
  SetOverwrite on
${Else}
  SetOverwrite off
${EndIf}
File blah.dat # Nadpisywanie jest tutaj zawsze wyłączone!

Zamiast powyższego, powinieneś użyć poniższej składni.

${If} $0 == 0
  SetOverwrite on
  File blah.dat
${Else}
  SetOverwrite off
  File blah.dat
${EndIf}

4.8.2.1 AllowSkipFiles


on|off

Polecenie AllowSkipFiles określa czy użytkownik może pominąć plik lub nie. Użytkownik ma opcję pominięcia pliku, jeśli polecenie SetOverwrite jest ustawione na wartość 'on' (domyślna) i otwarcie pliku do zapisu przy próbie wyodrębnienia pliku przez instalator nie powiedzie się.

Jeśli parametr ma wartość off, przycisk 'Ignoruj' (pozwalający użytkownikowi pominięcie pliku) nie pojawi się i użytkownik będzie miał tylko możliwość przerwania instalacji (przycisk 'Anuluj') lub ponownej próby otwarcia pliku do zapisu (przycisk 'Ponów'). Jeśli parametr ma wartość on, użytkownik będzie miał możliwość pominięcia pliku (ustawiona zostanie flaga błędu - patrz SetOverwrite).



4.8.2.2 FileBufSize


buffer_size_in_mb

Polecenie FileBufSize ustawia rozmiar buforów wewnętrznego pliku kompilatora. Polecenie to pozwala kontrolować użycie pamięci przez kompilator poprzez ograniczenie rozmiaru pliku ładowanego do pamięci. Jako że, kompilator potrzebuje zarówno wejścia jak i wyjścia, używana jest podwójna wartość pamięci dla buforów pliku. Polecenie to nie ogranicza buforów kompresji, które mogłyby zabrać kolejnych kilka MB, ani nie ogranicza innych buforów wewnętrznych kompilatora, ale te normalnie nie powinny przekroczyć 1MB. Ustawienie bardzo małej liczby powinno zwiększyć wydajność. Ustawienie bardzo dużej liczby może wyczerpać zasoby systemowe i wymusić anulowanie procesu kompilacji przez kompilator. Domyślną wartością jest 32MB.



4.8.2.3 SetCompress


auto|force|off

Polecenie SetCompress ustawia flagę kompresji, która jest używana przez instalator, aby określić czy dane mają być kompresowane czy też nie. Zazwyczaj flaga SetCompress ma wpływ na polecenia występujące po niej, a ostatnie polecenie SetCompress w pliku określa czy sekcja informacji o instalatorze oraz dane deinstalatora mają być kompresowane czy też nie. Jeśli flaga kompresji ma wartość 'auto', pliki są kompresowane, jeśli rozmiar po skompresowaniu jest mniejszy niż bez kompresji. Jeśli flaga kompresji ma wartość 'force', używana jest zawsze wersja skompresowana. Jeśli flaga kompresji ma wartość 'off' kompresja nie jest używana (co może być szybsze).

Pamiętaj, że ta opcja nie ma znaczenia, jeśli używasz kompresji typu SOLID.



4.8.2.4 SetCompressor


[/SOLID] [/FINAL] zlib|bzip2|lzma

Polecenie SetCompressor ustawia algorytm kompresji używany do kompresji plików/danych instalatora. Polecenie to może być użyte tylko poza sekcją i funkcją oraz przed danymi, które są skompresowane. Nie można użyć różnych metod kompresji dla różnych plików w tym samym instalatorze. Zaleca się użyć tego polecenia na samym początku skryptu, aby uniknąć błędów kompilacji.

Obsługiwane są trzy metody kompresji: ZLIB, BZIP2 and LZMA.

Kompresja typu ZLIB (domyślna) używa algorytmu deflate. Jest to metoda szybka i prosta. Przy domyślnym poziomie kompresji wykorzystuje około 300 KB pamięci.

Kompresja typu BZIP2 zazwyczaj daje lepsze współczynniki kompresji niż algorytm kompresji ZLIB, ale jest nieco wolniejsza i używa więcej pamięci. Przy domyślnym poziomie kompresji wykorzystuje około 4 MB pamięci.

Kompresja typu LZMA jest nowym algorytmem kompresji, który daje bardzo dobre współczynniki kompresji. Szybkość dekompresji jest wysoka (10-20 MB/s na procesorze taktowanym zegarem 2GHz), szybkość kompresji natomiast jest niższa. Rozmiar pamięci używanej do dekompresji jest równy rozmiarowi słownika plus kilka dodatkowych kilobajtów, domyślnie jest to 8 MB.

Jeśli używany jest przełącznik /FINAL, kolejne wywołania polecenia SetCompressor zostaną zignorowane.

Jeśli używany jest przełącznik /SOLID, wszystkie dane instalatora zostaną skompresowane w jednym bloku danych. Powoduje to uzyskanie większych współczynników kompresji.



4.8.2.5 SetCompressorDictSize


dict_size_mb

Polecenie SetCompressorDictSize ustawia rozmiar słownika kompresora LZMA, w megabajtach (MB). Domyślnym rozmiarem jest 8 MB.



4.8.2.6 SetDatablockOptimize


on|off

Polecenie SetDatablockOptimize instruuje kompilator czy używać optymalizacji bloku danych. Optymalizacja bloku danych polega na sprawdzeniu przez kompilator czy dana porcja danych dodawana do bloku danych już nie jest zapisana. Jeśli te dane są już zapisane kompilator odnosi się do nich (co pozwala na zmniejszenie rozmiaru bloku danych). Zaleca się zostawić tę opcję włączoną (wartość 'on').



4.8.2.7 SetDateSave


on|off

Polecenie SetDateSave ustawia flagę zapisywania czasu/daty pliku, która jest używana przez instrukcję File, aby określić czy zapisać ostatnią datę i czas zapisu pliku lub też nie, żeby można ją było przywrócić w czasie instalacji. Prawidłowe wartości flagi to 'on' oraz 'off'. Wartość flagi 'on' jest wartością domyślną.



4.8.2.8 SetOverwrite


on|off|try|ifnewer|ifdiff|lastused

Polecenie SetOverwrite ustawia flagę nadpisywania, która jest używana przez instrukcję File, do określenia czy dany plik ma nadpisać już istniejący plik czy też nie. Jeśli flaga nadpisywania ma wartość 'on', pliki są nadpisywane (jest to domyślne zachowanie). Jeśli flaga nadpisywania ma wartość 'off', istniejące już pliki nie są nadpisywane. Jeśli flaga nadpisywania ma wartość 'try', pliki są nadpisywane, jeśli jest to możliwe (co oznacza, że jeśli nie można nadpisać danego pliku, jest on pomijany bez jakiejkolwiek interakcji z użytkownikiem). Jeśli flaga nadpisywania ma wartość 'ifnewer', pliki nadpisywane są tylko wtedy, gdy istniejące pliki są starsze niż instalowany nowy plik. Jeśli flaga nadpisywania ma wartość 'ifdiff', pliki są nadpisywane tylko wtedy, gdy istniejący plik jest starszy lub nowszy niż instalowany nowy plik. Pamiętaj, że jeśli używasz trybu 'ifnewer' lub 'ifdiff', czas zapisu plików docelowych jest ustawiany zgodnie z ustawieniami polecenia SetDateSave.

SetOverwrite off
File program.cfg # Plik konfiguracyjny, którego nie chcemy nadpisać
SetOverwrite on


4.8.2.9 Unicode


true|false

Polecenie Unicode tworzy instalator Unicode. Polecenie to może być użyte tylko poza sekcjami oraz funkcjami oraz zanim jakiekolwiek dane zostaną skompresowane.





4.8.3 Informacje o wersji


4.8.3.1 VIAddVersionKey


[/LANG=lang_id] keyname value

Dodaje pole do zakładki Wersja we Właściwościach Pliku. Może to być pole zarówno systemowe jak i zdefiniowane przez użytkownika. Poniższe pola są zdefiniowane przez System:

  • ProductName
  • Comments
  • CompanyName
  • LegalCopyright
  • FileDescription
  • FileVersion
  • ProductVersion
  • InternalName
  • LegalTrademarks
  • OriginalFilename
  • PrivateBuild
  • SpecialBuild

Nazwy tych pól tłumaczone są na język systemowy, podczas gdy pola zdefiniowane przez użytkownika pozostają nieprzetłumaczone.

VIAddVersionKey /LANG=${LANG_ENGLISH} "ProductName" "Aplikacja Testowa"
VIAddVersionKey /LANG=${LANG_ENGLISH} "Comments" "Komentarz testowy"
VIAddVersionKey /LANG=${LANG_ENGLISH} "CompanyName" "Nazwa Firmy"
VIAddVersionKey /LANG=${LANG_ENGLISH} "LegalTrademarks" "Aplikacja testowa jest znakiem \
towarowym Nazwa Firmy"
VIAddVersionKey /LANG=${LANG_ENGLISH} "LegalCopyright" "© Nazwa Firmy"
VIAddVersionKey /LANG=${LANG_ENGLISH} "FileDescription" "Aplikacja Testowa"
VIAddVersionKey /LANG=${LANG_ENGLISH} "FileVersion" "1.2.3"


4.8.3.2 VIProductVersion


[version_string_X.X.X.X]

Dodaje Product Version (wersję produktu) do bloku informacji o wersji VS_FIXEDFILEINFO.

VIProductVersion "1.2.3.4"


4.8.3.3 VIFileVersion


[version_string_X.X.X.X]

Dodaje File Version (wersję pliku) do bloku informacji o wersji VS_FIXEDFILEINFO (powinieneś również dodać łańcuch znaków FileVersion używając VIAddVersionKey, dzięki czemu informacje te są wyświetlane na górze zakładki Wersja we Właściwościach Pliku). Jeśli nie określisz wersji pliku (File Version) zostanie użyta wersja produktu (Product Version) w bloku VS_FIXEDFILEINFO.

VIFileVersion "1.2.3.4"

4.9 Instrukcje



4.9.1 Instrukcje podstawowe


Instrukcje, których NSIS używa w skryptach są podobne do instrukcji języka PHP oraz Assemblera. Nie ma konstrukcji języka wyższego poziomu, ale instrukcje same w sobie są (w większości) wysokiego poziomu oraz masz dostęp do poręcznego operowania na łańcuchach znaków (np. nie musisz martwić się o łączenie łańcuchów znaków, etc). Masz do dyspozycji 25 rejestrów (20 ogólnego przeznaczenia oraz 5 specjalnego przeznaczenia) oraz stos.

4.9.1.1 Delete


[/REBOOTOK] file

Instrukcja Delete usuwa plik 'file' (który może być plikiem lub symbolem wieloznacznym, ale określony powinien być pełną ścieżką dostępu) z systemu docelowego. Jeśli określono parametr /REBOOTOK i plik nie można usunąć, zostanie on usunięty przy następnym rozruchu komputera -- jeśli plik zostanie usunięty przy ponownym rozruchu komputera, ustawiona zostanie flaga ponownego rozruchu komputera. Flaga błędu jest ustawiana, gdy plik istnieje, ale nie można go usunąć. Flaga błędu nie jest ustawiana przy próbie usunięcia pliku, który nie istnieje.

Delete $INSTDIR\dowolny_plik.dat


4.9.1.2 Exec


command

Instrukcja Exec uruchamia określony program i kontynuuje natychmiast dalsze działanie. Uruchamiany plik musi istnieć w docelowym systemie, nie w systemie kompilującego skrypt. Stała $OUTDIR używana jest do określenia katalogu roboczego. Flaga błędu jest ustawiana, jeśli nie można uruchomić procesu. Uwaga, jeśli linia polecenia 'command' zawiera znaki spacji, powinieneś umieścić ją w znakach cudzysłowia, aby oddzielić ją od parametrów, np.: Exec '"$INSTDIR\Program.exe" Parametry'. Jeśli nie umieścisz linii poleceń w cudzysłowie, polecenie nie powiedzie się w systemie z linii Windows 9x, z parametrami czy też bez parametrów.

Exec '"$INSTDIR\Dowolny_Program.exe"'
Exec '"$INSTDIR\Dowolny_Program.exe" Dowolne Parametry'


4.9.1.3 ExecShell


action command [parameters] \
[SW_SHOWDEFAULT | SW_SHOWNORMAL | SW_SHOWMAXIMIZED | SW_SHOWMINIMIZED | SW_HIDE]

Instrukcja ExecShell uruchamia określony program używając funkcji ShellExecute. Pamiętaj, że akcja 'action' ma wartość zazwyczaj "open", "print", etc, ale może to być również pusty łańcuch znaków, który wskazuje na domyślną akcję. Parametry 'parameters' oraz tryb wyświetlania SW_* są opcjonalne. Stała $OUTDIR używana jest do określenia katalogu roboczego. Flaga błędu jest ustawiana, jeśli nie można uruchomić procesu.

ExecShell "open" "http://nsis.sf.net/"
ExecShell "open" "$INSTDIR\readme.txt"
ExecShell "print" "$INSTDIR\readme.txt"


4.9.1.4 ExecWait


command [user_var(exit code)]

Instrukcja ExecWait uruchamia określony program i czeka na zakończenie uruchomionego procesu. Więcej informacji znajdziesz przy poleceniu Exec. Jeśli nie określono wyjściowej zmiennej polecenie ExecWait ustawia flagę błędu, jeśli uruchomiony program zwróci niezerowy kod błędu lub jeśli wystąpił błąd. Jeśli określono wyjściową zmienną, polecenie ExecWait przypisuje zmiennej kod wyjścia (flaga błędu ustawiana jest tylko wtedy, gdy wystąpi błąd; jeśli błąd wystąpi, zawartość zmiennej użytkownika jest niezdefiniowana). Uwaga, jeśli linia polecenia 'command' zawiera znaki spacji, powinieneś umieścić ją w znakach cudzysłowia, aby oddzielić ją od parametrów, np.: ExecWait '"$INSTDIR\Program.exe" Parametry'.Jeśli nie umieścisz linii poleceń w cudzysłowie, polecenie nie powiedzie się w systemie z linii Windows 9x, z parametrami czy też bez parametrów.

ExecWait '"$INSTDIR\Dowolny_Program.exe"'
ExecWait '"$INSTDIR\Dowolny_Program.exe"' $0
DetailPrint "Dowolny_Program zwrócił $0"


4.9.1.5 File


[/nonfatal] [/a] ([/r] [/x file|wildcard [...]] (file|wildcard) [...] | /oname=file.dat infile.dat)

Instrukcja File dodaje plik(i) do wyodrębnienia w bieżącym katalogu roboczym ($OUTDIR).

  • Nazwa pliku wyjściowego: $OUTDIR\nazwa_pliku.
  • Użyj przełącznika /oname=X, aby zmienić nazwę wyjściową pliku. 'X' może zawierać zmienne i może być to ścieżka bezwzględna lub względna, ustawiona dla katalogu roboczego $OUTDIR poleceniem SetOutPath. Używając tego przełącznika, możesz określić tylko jeden plik. Jeśli nazwa wyjściowa zawiera znaki spacji, umieść cały parametr w znaku cudzysłowia, włącznie z /oname, tak jak pokazano to w poniższych przykładach.
  • Symbole wieloznaczne są obsługiwane.
  • Jeśli użyty zostanie przełącznik /r, pliki oraz katalogi spełniające określone kryteria są wyszukiwane rekursywnie w podkatalogach. Jeśli określono tylko jeden segment ścieżki (np. File /r katalog), bieżący katalog będzie przeszukiwany rekursywnie. Jeśli określono więcej niż jeden segment (np. File /r katalog\*.*), ostatni segment ścieżki będzie użyty dla sprawdzenia kryteriów wyszukiwania, zaś reszta jako ścieżka dostępu do katalogu przeszukiwania rekursywnego. Jeśli nazwa katalogu spełnia kryteria wyszukiwania, cała jego zawartość jest rekursywnie dodawana. Zachowana jest struktura katalogu.
  • Użyj przełącznika /x, aby wykluczyć określone pliki lub katalogi.
  • Jeśli użyty zostanie przełącznik /a, atrybuty dodawanych plików zostaną zachowane.
  • Polecenie File ustawia flagę błędu, jeśli tryb nadpisywania ustawiony jest na 'try' i nie można nadpisać danego pliku lub jeśli tryb nadpisywania ustawiony jest na 'on' i nie można nadpisać pliku oraz jeśli użytkownik wybierze opcję Ignoruj.
  • Jeśli użyty zostanie przełącznik /nonfatal i nie znaleziono żadnych plików, wyświetlony zostanie tylko komunikat ostrzegawczy zamiast błędu.
File nazwa_pliku.exe
File /a nazwa_pliku.exe
File *.exe
File /r *.dat
File /r data
File /oname=temp.dat nazwa_pliku.ext
File /oname=$TEMP\temp.dat nazwa_pliku.ext
File "/oname=$TEMP\nazwa ze spacjami.dat" nazwa_pliku.ext
File /nonfatal "plik, który nie istnieje"
File /r /x CVS MójProjekt\*.*
File /r /x *.res /x *.obj /x *.pch source\*.*

Uwaga: Używając przełącznika /r, zarówno katalogi jak i pliki spełniające określone kryteria będą wyszukiwane. Dzieje się to zawsze przy użyciu lub bez użycia symboli wieloznacznych, nawet jeśli podana ścieżka dostępu dokładnie wskazuje na dany katalog. Oznacza to, że poniższa struktura katalogów:

<DIR> something
  File.dat
  another.dat
<DIR> dir
  something
  <DIR> dir2
    file2.dat
<DIR> another
  <DIR> something
    readme.txt

z poniższym użyciem polecenia File:

File /r something

spełni warunki kryterium wyszukiwania dla katalogu o nazwie something w katalogu źródłowym, pliku o nazwie something w katalogu o nazwie dir oraz katalogu o nazwie something w katalogu o nazwie another. Aby kryterium wyszukiwania dotyczyło tylko katalogu o nazwie something, który znajduje się w głównym katalogu, użyj poniższej składni:

File /r something\*.*

Dodając symbol wieloznaczny \*.* sprawimy, że użyty on zostanie jako kryterium wyszukiwania i katalog something zostanie użyty jako katalog, w którym przeprowadzone zostanie wyszukiwanie. Gdy określimy tylko katalog something, bieżący katalog zostanie rekursywnie przeszukany dla dowolnego wystąpienia katalogu o nazwie something i w ten sposób katalog another\something również spełni kryterium wyszukiwania.



4.9.1.6 Rename


[/REBOOTOK] source_file dest_file

Instrukcja Rename zmienia nazwę pliku źródłowego 'source_file' na plik docelowy 'dest_file'. Możesz użyć tego polecenia do przeniesienia pliku z dowolnej lokalizacji w systemie do innej oraz możesz przenieść katalog do innej lokalizacji znajdującej się na tym samym dysku. Plik docelowy nie może istnieć, w przeciwnym razie przeniesienie pliku nie powiedzie się (chyba, że używasz parametru /REBOOTOK). Jeśli określisz parametr /REBOOTOK i pliku nie można przenieść (jeśli, na przykład, plik docelowy już istnieje), to plik ten zostanie przeniesiony po ponownym uruchomieniu komputera. Jeśli plik zostanie przeniesiony po ponownym uruchomieniu komputera, flaga ponownego rozruchu komputera zostanie ustawiona. Flaga błędu zostanie ustawiona, jeśli nie można zmienić nazwy pliku (i parametr /REBOOTOK nie jest używany) lub jeśli plik źródłowy nie istnieje.

Jeśli nie określono ścieżki bezwzględnej użyty zostanie bieżący katalog. Bieżacy katalog to ten, który został ustawiony przy użyciu instrukcji SetOutPath. Jeśli nie użyto instrukcji SetOutPath bieżącym katalogiem jest katalog $EXEDIR (katalog, w którym znajduje się instalator).

Rename $INSTDIR\plik.ext $INSTDIR\plik.dat


4.9.1.7 ReserveFile


[/nonfatal] [/r] [/x file|wildcard [...]] file [file...] | [/nonfatal] /plugin file.dll

Instrukcja ReserveFile rezerwuje plik w bloku danych do późniejszego użycia. Pliki dodawane są do skompresowanego bloku danych w kolejności występowania w skrypcie. Funkcje jednak, nie koniecznie są wywoływane w kolejności ich występowania w skrypcie. Dlatego, jeśli dodasz plik w funkcji, która zostanie wywołana wcześniej, ale umieścisz funkcję na końcu skryptu, wszystkie pliki dodane wcześniej będą musiały być zdekompresowane, aby móc użyć żądanego pliku. Proces ten może potrwać jakiś czas, jeśli jest dużo plików.

Najlepszym przykładem takiej funkcji jest funkcja .onInit. Wywoływana ona jest na samym początku, zanim pojawi się cokolwiek innego. Jeśli umieścisz ją na końcu skryptu, wyodrębnisz kilka plików w niej i jeśli masz dużo plików dodanych wcześniej w skrypcie, instalator może długo się ładować. Tutaj właśnie to polecenie jest użyteczne, pozwala bowiem na przyspieszenie procesu ładowania instalatora poprzez dodanie pliku na samą górę bloku danych, zapobiegając sięgania przez NSIS na sam dół skompresowanego bloku danych.

Użyj przełącznika /plugin, aby zarezerwować wtyczkę znajdującą się w katalogu $\{NSISDIR\}\\Plugins\\*.

Więcej informacji o parametrach znajdziesz w opisie polecenia File.



4.9.1.8 RMDir


[/r] [/REBOOTOK] directory_name

Instrukcja RMDir usuwa określony katalog (pełna ścieżka dostępu bez symboli wieloznacznych). Jeśli nie użyjemy przełącznika /r to katalog zostanie usuniety tylko wtedy, jeśli jest pusty. Jeśli natomiast użyjemy przełącznika /r katalog zostanie usunięty rekursywnie, więc wszystkie katalogi oraz pliki w określonym katalogu zostaną usunięte. Jeśli użyjemy parametru /REBOOTOK dowolny plik lub katalog, którego nie można usunąć zostanie usunięty przy ponownym uruchomieniu komputera -- jeśli dowolny plik lub katalog zostanie usunięty podczas ponownego uruchomienia komputera ustawiona zostanie flaga ponownego rozruchu komputera. Flaga błędu zostanie ustawiona, jeśli dowolny plik lub katalog nie może być usunięty.

RMDir $INSTDIR
RMDir $INSTDIR\data
RMDir /r /REBOOTOK $INSTDIR
RMDir /REBOOTOK $INSTDIR\DLLs

Należy pamiętać o tym, że bieżący katalog roboczy nie może być usunięty. Bieżący katalog roboczy ustawiany jest przy użyciu instrukcji SetOutPath. Na przykład, poniższy fragment kodu nie ma możliwości usunięcia katalogu.

SetOutPath $TEMP\dir
RMDir $TEMP\dir

Natomiast, poniższy przykład pozwala na usunięcie katalogu.

SetOutPath $TEMP\dir
SetOutPath $TEMP
RMDir $TEMP\dir

Ostrzeżenie: Używając składni RMDir /r $INSTDIR w deinstalatorze nie jest bezpieczne. Choć jest to mało prawdopodobne, użytkownik może wybrać katalog 'Program Files' jako katalog instalacji, więc polecenie to usunie cały katalog 'Program Files', włącznie z innymi programami, które nie mają związku z deinstalowanymi plikami programu. Użytkownik może również umieścić inne pliki i oczekiwać na ich usunięcie wraz z programem. Rozwiązaniem jest deinstalacja tylko tych plików, które zainstalowane zostały przez instalator.



4.9.1.9 SetOutPath


outpath

Instrukcja SetOutPath ustawia wyjściową ścieżkę dostępu ($OUTDIR) i tworzy ją (rekursywnie, jeśli jest taka potrzeba), jeśli nie istnieje. Musi być pełną ścieżką dostępu, zazwyczaj jednak określana jest jako zmienna $INSTDIR (możesz określić zmienną $INSTDIR pojedynczym znakiem "-").

SetOutPath $INSTDIR
File program.exe


4.9.2 Instrukcje plikowe, rejestru, plików INI


We wszystkich poniższych instrukcjach operujących na rejestrze Windows użyj pustego łańcucha znaków dla nazwy klucza, który określa domyślny klucz (dwa znaki cudzysłowia puste w środku - ""). Program regedit.exe wyświetla tę nazwę jako (Domyślna).

Jeśli nie określono pełnej ścieżki dostępu dla dowolnej z instrukcji operujących na plikach INI, użyty zostanie katalog Windows.


4.9.2.1 DeleteINISec


ini_filename section_name

Instrukcja DeleteINISec usuwa całą sekcję '[section_name]' z pliku INI 'ini_filename'. Jeśli nie można usunąć sekcji z pliku INI, ustawiona zostanie flaga błędu. Flaga błędu natomiast nie zostanie ustawiona, jeśli nie można znaleźć sekcji.

WriteINIStr $TEMP\plik.ini Sekcja1 Klucz_Pierwszy 123
WriteINIStr $TEMP\plik.ini Sekcja1 Klucz_Drugi 1234
WriteINIStr $TEMP\plik.ini Sekcja2 Klucz_NSIS true
DeleteINISec $TEMP\plik.ini Sekcja1


4.9.2.2 DeleteINIStr


ini_filename section_name str_name

Instrukcja DeleteINIStr usuwa łańcuch znaków 'str_name' z sekcji '[section_name]' z pliku INI 'ini_filename'. Jeśli nie można usunąć łańcucha znaków z pliku INI, ustawiona zostanie flaga błędu. Flaga błędu natomiast nie zostanie ustawiona, jeśli nie można znaleźć łańcucha znaków.

WriteINIStr $TEMP\plik.ini Sekcja1 Klucz_Pierwszy 123
WriteINIStr $TEMP\plik.ini Sekcja1 Klucz_Drugi 1234
DeleteINIStr $TEMP\plik.ini Sekcja1 Klucz_Drugi


4.9.2.3 DeleteRegKey


[/ifempty] root_key subkey

Instrukcja DeleteRegKey usuwa klucz rejestru. Jeśli określono przełącznik /ifempty, klucz rejestru zostanie usunięty tylko wtedy, gdy nie posiada żadnych podkluczy (w przeciwnym razie, całe drzewo rejestru zostanie usunięte). Prawidłowe wartości dla klucza głównego 'root_key' wymienione są w opisie polecenia WriteRegStr. Flaga błędu ustawiana jest, jeśli nie można usunąć klucza z rejestru (lub jeśli nie istniał).

DeleteRegKey HKLM "Software\Moja firma\Moje oprogramowanie"
DeleteRegKey /ifempty HKLM "Software\Klucz, który może mieć podklucze"


4.9.2.4 DeleteRegValue


root_key subkey key_name

Instrukcja DeleteRegValue usuwa wartość klucza rejestru. Prawidłowe wartości dla klucza głównego 'root_key' wymienione są w opisie polecenia WriteRegStr. Flaga błędu ustawiana jest, jeśli nie można usunąć wartości klucza z rejestru (lub jeśli jej nie było).

DeleteRegValue HKLM "Software\Moja firma\Moje oprogramowanie" "Dowolna wartość"


4.9.2.5 EnumRegKey


user_var(output) root_key subkey index

Instrukcja EnumRegKey przypisuje zmiennej użytkownika $x nazwy indeksów 'index' kluczy w kluczu 'root_key\Subkey'. Prawidłowe wartości dla klucza głównego 'root_key' wymienione są w opisie polecenia WriteRegStr. Polecenie zwraca pusty łańcuch znaków, jeśli nie ma już więcej kluczy oraz zwraca pusty łańcuch znaków i ustawia flagę błędu jeśli wystąpił błąd.

StrCpy $0 0
loop:
  EnumRegKey $1 HKLM Software $0
  StrCmp $1 "" done
  IntOp $0 $0 + 1
  MessageBox MB_YESNO|MB_ICONQUESTION "$1$\n$\nWięcej?" IDYES loop
done:


4.9.2.6 EnumRegValue


user_var(output) root_key subkey index

Instrukcja EnumRegValue przypisuje zmiennej użytkownika $x nazwy indeksów 'index' wartości klucza w kluczu 'root_key\Subkey'. Prawidłowe wartości dla klucza głównego 'root_key' wymienione są w opisie polecenia WriteRegStr. Polecenie zwraca pusty łańcuch znaków oraz ustawia flagę błędu, jeśli nie ma już więcej wartości kluczy lub jeśli wystąpił błąd.

StrCpy $0 0
loop:
  ClearErrors
  EnumRegValue $1 HKLM Software\Microsoft\Windows\CurrentVersion $0
  IfErrors done
  IntOp $0 $0 + 1
  ReadRegStr $2 HKLM Software\Microsoft\Windows\CurrentVersion $1
  MessageBox MB_YESNO|MB_ICONQUESTION "$1 = $2$\n$\nWięcej?" IDYES loop
done:


4.9.2.7 ExpandEnvStrings


user_var(output) string

Instrukcja ExpandEnvStrings zamienia zmienne środowiskowe w łańcuchu znaków 'string' na zmienną użytkownika $x. Jeśli zmienna środowiskowa nie istnieje, nie zostanie ona zamieniona. Na przykład, jeśli używasz "%var%" i zmienna 'var' nie istnieje, rezultatem polecenia będzie "%var%". Jeśli wystąpi błąd, zmienna zostanie ustawiona na pustą oraz ustawiona zostanie flaga błędu.

ExpandEnvStrings $0 "WINDIR=%WINDIR%$\nTEMP=%TEMP%"


4.9.2.8 FlushINI


ini_filename

Instrukcja FlushINI czyści bufory pliku INI. System Windows 9x przechowuje wszystkie zmiany pliku INI w pamięci. Polecenie to powoduje natychmiastowy zapis tych zmian na dysk. Użyj tego polecenia, jeśli ręcznie edytujesz plik INI, usuwasz go, przenosisz lub kopiujesz zaraz po tym jak użyto polecenia WriteINIStr, DeleteINISec lub DeleteINStr.

WriteINIStr $TEMP\plik.ini test test test
FlushINI $TEMP\plik.ini
Delete $TEMP\plik.ini


4.9.2.9 ReadEnvStr


user_var(output) name

Instrukcja ReadEnvStr odczytuje wartość "name" z łańcucha znaków zmiennej środowiskowej i przypisuje wartość do zmiennej użytkownika $x. Jeśli wystąpi błąd odczytu łańcucha znaków, zmiennej użytkownika przypisany zostanie pusty łańcuch znaków oraz ustawiona zostanie flaga błędu.

ReadEnvStr $0 WINDIR
ReadEnvStr $1 TEMP


4.9.2.10 ReadINIStr


user_var(output) ini_filename section_name entry_name

Instrukcja ReadINIStr odczytuje wartość z klucza 'entry_name' w sekcji '[section_name]' z pliku INI 'ini_filename' do zmiennej użytkownika $x. Jeśli klucz nie zostanie znaleziony ustawiana jest flaga błędu, a zmiennej $x przypisany zostanie pusty łańcuch znaków.

ReadINIStr $0 $INSTDIR\winamp.ini winamp outname


4.9.2.11 ReadRegDWORD


user_var(output) root_key sub_key name

Instrukcja ReadRegDWORD odczytuje 32 bitową wartość typu DWORD z rejestru do zmiennej użytkownika $x. Prawidłowe wartości dla klucza głównego 'root_key' wymienione są w opisie polecenia WriteRegStr. Ustawiana jest flaga błędu oraz zmienna $x przyjmuje wartość pustego łańcucha znaków ("" równy 0), jeśli zwrócona wartość typu DWORD jest pusta. Jeśli wartość nie jest pusta, ale nie jest to wartość typu DWORD, zostanie ona odczytana jako łańcuch znaków oraz ustawiona zostanie flaga błędu.

ReadRegDWORD $0 HKLM Software\NSIS VersionBuild


4.9.2.12 ReadRegStr


user_var(output) root_key sub_key name

Instrukcja ReadRegStr odczytuje dane z rejestru do zmiennej użytkownika $x. Prawidłowe wartości dla klucza głównego 'root_key' wymienione są w opisie polecenia WriteRegStr. Ustawiana jest flaga błędu oraz zmienna $x przyjmuje wartość pustego łańcucha znaków (""), jeśli zwrócony łańcuch znaków jest pusty. Jeśli wartość nie jest pusta, ale jest to wartość typu REG_DWORD, zostanie ona odczytana i przekonwertowana na łańcuch znaków oraz flaga błędu zostanie ustawiona.

ReadRegStr $0 HKLM Software\NSIS ""
DetailPrint "NSIS jest zainstalowany w: $0"


4.9.2.13 WriteINIStr


ini_filename section_name entry_name value

Instrukcja WriteINIStr zapisuje klucz 'entry_name' o wartości 'value' do sekcji '[section_name]' pliku INI 'ini_filename'. Flaga błędu ustawiana jest, jeśli łańucha znaków nie można zapisać do pliku INI.

WriteINIStr $TEMP\plik.ini sekcja1 klucz_pierwszy 123
WriteINIStr $TEMP\plik.ini sekcja1 klucz_drugi 1234
WriteINIStr $TEMP\plik.ini sekcja2 klczu_nsis true


4.9.2.14 WriteRegBin


root_key subkey key_name valuedata

Instrukcja WriteRegBin zapisuje blok danych binarnych do rejestru. Prawidłowe wartości dla klucza głównego 'root_key' wymienione są w opisie polecenia WriteRegStr. Wartość 'Valuedata' zapisywana jest szesnastkowo (np. DEADBEEF01223211151). Flaga błędu ustawiana jest, jeśli danych binarnych nie można zapisać do rejestru. Jeśli klucz rejestru jeszcze nie istnieje zostanie on utworzony.

WriteRegBin HKLM "Software\Moja firma\Moje oprogramowanie" "Wartość binarna" DEADBEEF01223211151


4.9.2.15 WriteRegDWORD


root_key subkey key_name value

Instrukcja WriteRegDWORD zapisuje do rejestru wartość typu dword (32 bitowa liczba całkowita). Można określić zmienną użytkownika. Prawidłowe wartości dla klucza głównego 'root_key' wymienione są w opisie polecenia WriteRegStr. Flaga błędu ustawiana jest, jeśli wartość typu dword nie może być zapisana do rejestru. Jeśli klucz rejestru jeszcze nie istnieje zostanie on utworzony.

WriteRegDWORD HKLM "Software\Moja firma\Moje oprogramowanie" "Wartość typu DWORD" 0xDEADBEEF


4.9.2.16 WriteRegStr


root_key subkey key_name value

Instrukcja WriteRegStr zapisuje łańcuch znaków do rejestru. Więcej szczegółów znajdziesz w opisie polecenia WriteRegExpandStr.

WriteRegStr HKLM "Software\Moja firma\Moje oprogramowanie" "Wartość typu String" "Łańuch znaków"


4.9.2.17 WriteRegExpandStr


root_key subkey key_name value

Instrukcja WriteRegExpandStr zapisuje łańcuch znaków do rejestru. Klucz główny root_key musi być jednym z poniższych:

  • HKCR lub HKEY_CLASSES_ROOT
  • HKLM lub HKEY_LOCAL_MACHINE
  • HKCU lub HKEY_CURRENT_USER
  • HKU lub HKEY_USERS
  • HKCC lub HKEY_CURRENT_CONFIG
  • HKDD lub HKEY_DYN_DATA
  • HKPD lub HKEY_PERFORMANCE_DATA
  • SHCTX lub SHELL_CONTEXT

Jeśli klucz główny root_key jest kluczem SHCTX lub SHELL_CONTEXT, zostanie on zastąpiony przez klucz HKLM, jeśli polecenie SetShellVarContext ustawione jest na all (wszyscy użytkownicy) oraz przez klucz HKCU, jeśli polecenie SetShellVarContext ustawione jest na current (bieżący użytkownik).

Flaga błędu ustawiana jest, jeśli nie można zapisać łańcucha znaków do rejestru. Łańcuch znaków jest typu REG_SZ dla polecenia WriteRegStr lub REG_EXPAND_STR dla polecenia WriteRegExpandStr. Jeśli klucz rejestru jeszcze nie istnieje zostanie on utworzony.

WriteRegExpandStr HKLM "Software\Moja firma\Moje oprogramowanie" "Wartość typu Expand String" \
                                "%WINDIR%\notepad.exe"


4.9.3 Instrukcje ogólnego przeznaczenia


4.9.3.1 CallInstDLL


dllfile function_name

Instrukcja CallInstDLL wywołuje funkcję o nazwie function_name, która znajduje się we wtyczce, będącej rozszerzeniem NSIS w postaci biblioteki dll. W tym przykładzie znajdziesz sposób jak taką wtyczkę stworzyć: '../Examples/Plugin/'. Wtyczki mają dostęp do stosu oraz zmiennych. Uwaga: Aby automatycznie wyodrębnić oraz wywołać biblioteki wtyczek, użyj polecenia wtyczki, zamiast polecenia CallInstDLL.

Push "Parametr"
Push "Inny parametr"
CallInstDLL $INSTDIR\biblioteka_dll.dll JakasFunkcja

Dla łatwiejszej obsługi wtyczek, skorzystaj z nowej składni wywoływania wtyczek.



4.9.3.2 CopyFiles


[/SILENT] [/FILESONLY] filespec_on_destsys destination_path [size_of_files_in_kb]

Instrukcja CopyFiles kopiuje pliki z lokalizacji źródłowej do lokalizacji docelowej w systemie użytkownika. Polecenie to użyteczne jest ze stałą $EXEDIR, jeśli chcesz skopiować dane z nośnika instalacyjnego lub skopiować z jednego miejsca w systemie do innego. Możesz zobaczyć okno dialogowe Windows prezentujące proces kopiowania plików, jeśli operacja ta trwa zbyt długo (aby go ukryć, użyj przełącznika /SILENT). Ostatni parametr może być użyty do określenia rozmiaru plików, które zostaną skopiowane (w kilobajtach), dzięki czemu instalator będzie mógł w przybliżeniu określić wymaganą przestrzeń na dysku. W przypadku wystąpienia błędu lub gdy użytkownik anuluje proces kopiowania (tylko w przypadku, gdy nie jest używany przełącznik /SILENT), zostanie ustawiona flaga błędu. Jeśli określono przełącznik /FILESONLY, kopiowane są tylko pliki.

W tej instrukcji używane muszą być ścieżki bezwzględne. Używanie ścieżek względnych będzie mieć nieprzewidywalne skutki.

CreateDirectory $INSTDIR\backup
CopyFiles $INSTDIR\*.dat $INSTDIR\backup


4.9.3.3 CreateDirectory


path_to_create

Instrukcja CreateDirectory tworzy określony katalog (rekursywnie, jeśli jest to wymagane). Jeśli nie uda się utworzyć katalogu, ustawiana jest flaga błędu.

Powinieneś zawsze używać ścieżek bezwzględnych.

CreateDirectory $INSTDIR\jakis\katalog


4.9.3.4 CreateShortcut


[/NoWorkingDir] link.lnk target.file \
[parameters [icon.file [icon_index_number [start_options [keyboard_shortcut [description]]]]]]

Instrukcja CreateShortcut tworzy skrót 'link.lnk', który prowadzi do pliku docelowego 'target.file', z opcjonalnymi parametrami 'parameters'.

Ikoną używaną dla skrótu jest 'icon.file,icon_index_number'; dla ustawień domyślnych ikony użyj pustego łańcucha znaków zarówno dla 'icon.file' oraz 'icon_index_number'.

Parametr 'start_options' powinien być jednym z następujących: SW_SHOWNORMAL, SW_SHOWMAXIMIZED, SW_SHOWMINIMIZED lub pustym łańcuchem znaków.

Parametr 'keyboard_shortcut' powinien być w formie: 'flag|c', gdzie: 'flag' może być kombinacją (użyj znaku |): ALT, CONTROL, EXT lub SHIFT. 'c' jest znakiem do użycia (a-z, A-Z, 0-9, F1-F24, etc). Pamiętaj, że łańcuch znaków nie może zawierać znaków spacji. Dobrym przykładem jest: "ALT|CONTROL|F8". Stała $OUTDIR używana jest do określenia katalogu roboczego. Możesz go zmienić używając polecenia SetOutPath przed utworzeniem skrótu lub przełącznika /NoWorkingDir, jeśli nie potrzebujesz ustawiać katalogu roboczego.

Parametr 'description' powinien opisywać skrót lub komentarz, jeśli skrót tworzony jest w Windows XP. Jeśli nie można utworzyć skrótu, ustawiana jest flaga błędu (np. z powodu nieprawidłowych ścieżek (skrótu lub ścieżki docelowej) lub innego błędu).

CreateDirectory "$SMPROGRAMS\Moja firma"
CreateShortCut "$SMPROGRAMS\Moja firma\Mój Program.lnk" "$INSTDIR\Mój Program.exe" \
  "Parametry wiersza poleceń" "$INSTDIR\Mój Program.exe" 2 SW_SHOWNORMAL \
  ALT|CTRL|SHIFT|F5 "Opis programu"


4.9.3.5 GetDLLVersion


filename user_var(high dword output) user_var(low dword output)

Instrukcja GetDLLVersion pobiera informacje o wersji z pliku DLL "filename" (lub dowolnego innego pliku wykonywalnego, który zawiera informacje o wersji). W przypadku pomyślnego pobrania informacji o wersji, polecenie ustawia wyjściowe zmienne użytkownika w postaci liczb dword: high oraz low, zaś w przypadku niepowodzenia zmienne wyjściowe użytkownika są puste i ustawiana jest flaga błędu. Poniższy przykład odczytuje wersję biblioteki DLL i kopiuje te informacje do zmiennej $0:

GetDllVersion "$INSTDIR\MojaBibliotekaDLL.dll" $R0 $R1
IntOp $R2 $R0 / 0x00010000
IntOp $R3 $R0 & 0x0000FFFF
IntOp $R4 $R1 / 0x00010000
IntOp $R5 $R1 & 0x0000FFFF
StrCpy $0 "$R2.$R3.$R4.$R5"


4.9.3.6 GetDLLVersionLocal


localfilename user_var(high dword output) user_var(low dword output)

Instrukcja GetDLLVersionLocal podobne jest do polecenia GetDLLVersion, ale działa w systemie kompilującego skrypt instalatora (używa dwu poleceń StrCpy). Polecenie pobiera do dwu wyjściowych zmiennych informacje o wersji pliku DLL w systemie kompilującego. Użyj polecenia !getdllversion jeśli potrzebujesz użyć wartości VIProductVersion.



4.9.3.7 GetFileTime


filename user_var(high dword output) user_var(low dword output)

Instrukcja GetFileTime pobiera ostatni czas zapisu pliku "filename". W przypadku pomyślnego pobrania tych informacji, polecenie ustawia wyjściowe zmienne użytkownika w postaci liczb dword: high oraz low, zaś w przypadku niepowodzenia zmienne wyjściowe użytkownika są puste i ustawiana jest flaga błędu.



4.9.3.8 GetFileTimeLocal


localfilename user_var(high dword output) user_var(low dword output)

Instrukcja GetFileTimeLocal jest podobne do polecenia GetFileTime, ale działa w systemie kompilującego skrypt instalatora (używa dwu poleceń StrCpy). Polecenie pobiera do dwu wyjściowych zmiennych informacje o czasie zapisu pliku w systemie kompilującego.



4.9.3.9 GetFullPathName


[/SHORT] user_var(output) path_or_file

Instrukcja GetFullPathName przypisuje pełną ścieżkę określonego pliku do zmiennej użytkownika $x. Jeśli część ścieżki parametru nie zostanie znaleziona, zostanie ustawiona flaga błędu i zmienna $x będzie pusta. Jeżeli określono parametr /SHORT, ścieżka jest konwertowana do postaci krótkich nazw plików. Jednakże, jeśli parametr /SHORT nie zostanie określony, ścieżka nie jest przekształcana do postaci długich nazw plików. Aby uzyskać długą nazwę pliku, wywołaj polecenie GetLongPathName za pomocą wtyczki System. Należy pamiętać, że polecenie GetLongPathName jest dostępne tylko w systemie Windows 98, Windows 2000 i nowszych.

StrCpy $INSTDIR $PROGRAMFILES\NSIS
SetOutPath $INSTDIR
GetFullPathName $0 ..
DetailPrint $0 # Wypisze C:\Program Files
GetFullPathName /SHORT $0 $INSTDIR
DetailPrint $0 # Wypisze C:\Progra~1\NSIS
StrCpy $0 C:\Progra~1\NSIS
System::Call 'kernel32::GetLongPathName(t r0, t .r1, i ${NSIS_MAX_STRLEN}) i .r2'
StrCmp $2 error +2
StrCpy $0 $1
DetailPrint $0 # Wypisze C:\Program Files\NSIS


4.9.3.10 GetTempFileName


user_var(output) [base_dir]

Instrukcja GetTempFileName przypisuje nazwę pliku tymczasowego do zmiennej użytkownika $x. Plik zostanie utworzony, więc będziesz mógł go nadpisać czym chcesz. Nazwa pliku tymczasowego jest unikalna. Jeśli chcesz utworzyć plik tymczasowy w innej lokalizacji niż katalog plików tymczasowych Windows, określ katalog bazowy 'base_dir'. Użyj polecenia Delete, aby usunąć plik po zakończeniu operowania na nim.

GetTempFileName $0
File /oname=$0 jakis_plik.dat
# zrób coś z plikiem jakis_plik.dat
Delete $0


4.9.3.11 SearchPath


user_var(output) filename

Instrukcja SearchPath przypisuje do zmiennej użytkownika $x pełną ścieżkę do pliku określonego w drugim parametrze. Jeśli plik nie zostanie znaleziony, ustawiona zostanie flaga błędu i zmienna $x będzie pusta. Użycie polecenia SearchPath() powoduje przeszukiwanie katalogów systemowych.



4.9.3.12 SetFileAttributes


filename attribute1|attribute2|...

Instrukcja SetFileAttributes ustawia atrybuty pliku 'filename'. Prawidłowe atrybuty mogą być łączone przy użyciu znaku '|' i są to:

  • NORMAL lub FILE_ATTRIBUTE_NORMAL (aby skrócić zapis, możesz użyć 0)
  • ARCHIVE lub FILE_ATTRIBUTE_ARCHIVE
  • HIDDEN lub FILE_ATTRIBUTE_HIDDEN
  • OFFLINE lub FILE_ATTRIBUTE_OFFLINE
  • READONLY lub FILE_ATTRIBUTE_READONLY
  • SYSTEM lub FILE_ATTRIBUTE_SYSTEM
  • TEMPORARY lub FILE_ATTRIBUTE_TEMPORARY

Jeśli nie można ustawić atrybutów pliku, ustawiona zostanie flaga błędu (np. plik nie istnieje lub nie masz wystarczających uprawnień).Możesz ustawić tylko atrybuty. Nie ma możliwości ich usunięcia. Jeśli chcesz usunąć atrybut, użyj NORMAL. Dzięki temu, wszystkie inne atrybuty zostaną usunięte. Polecenie to nie obsługuje symboli wieloznacznych (wildcard).



4.9.3.13 RegDLL


dllfile [entrypoint_name]

Instrukcja RegDLL ładuje określoną bibliotekę DLL i wywołuje serwer rejestracji DllRegisterServer (lub nazwę punktu wejścia 'entrypoint_name', jeśli jest określony). Jeśli wystąpi błąd, ustawiana jest flaga błędu (np. nie można załadować biblioteki DLL, zainicjalizować OLE, znaleźć punktu wejścia lub funkcja zwraca tylko ERROR_SUCCESS (=0)).

Użyj polecenia SetOutPath, aby ustawić bieżący katalog dla bibliotek DLL, który zależny jest od innych bibliotek DLL, które znajdują się w określonej lokalizacji lub w katalogu Windows. Na przykład, jeśli biblioteka foo.dll zależy od biblioteki bar.dll, która znajduje się w katalogu $INSTDIR, użyj:

 SetOutPath $INSTDIR
 RegDLL $INSTDIR\foo.dll


4.9.3.14 UnRegDLL


dllfile

Instrukcja UnRegDLL ładuje określoną bibliotekę DLL i wywołuje serwer wyrejestrowania DllUnregisterServer. Jeśli wystąpi błąd, ustawiana jest flaga błędu (np. nie można załadować biblioteki DLL, zainicjalizować OLE, znaleźć punktu wejścia lub funkcja zwraca tylko ERROR_SUCCESS (=0)).





4.9.4 Instrukcje kontroli wykonania


4.9.4.1 Abort


user_message

Instrukcja Abort anuluje instalację, zatrzymuje wykonywanie skryptu oraz wyświetla komunikat 'user_message' w obszarze statusu. Uwaga: Możesz użyć tego polecenia w funkcjach zwrotnych, aby zrobić specjalne rzeczy. Funkcje zwrotne stron również używają polecenia Abort do specjalnych celów.

Abort
Abort "Nie można zainstalować"


4.9.4.2 Call


function_name | :label_name | user_var(input)

Instrukcja Call wywołuje funkcje o nazwie function_name, etykiety o nazwie label_name lub zmienne, które określają adres. Adres zwracany jest przez funkcje GetCurrentAddress, GetFunctionAddress lub GetLabelAddress. Wywołania zwracają wartości, jeśli użyta zostanie instrukcja Return. Sekcje oraz funkcje automatycznie kończą się instrukcją Return. Funkcje deinstalatora nie mogą być wywołane z funkcji oraz sekcji instalatora i na odwrót.

Function func
  Call :label
  DetailPrint "#1: Ten tekst pojawi się raz."
label:
  DetailPrint "#2: Ten tekst pojawi się przed i po komunikacie #1."
  Call :.global_label
FunctionEnd

Section
  Call func
  Return

.global_label:
  DetailPrint "#3: Została wywołana globalna etykieta"
SectionEnd


4.9.4.3 ClearErrors


Instrukcja ClearErrors czyści flagę błędu.

ClearErrors
IfErrors 0 +2
  MessageBox MB_OK "Ten kominukat o błędzie nigdy się nie wyświetli"


4.9.4.4 GetCurrentAddress


user_var(output)

Instrukcja GetCurrentAddress pobiera adres bieżącej instrukcji (GetCurrentAddress) oraz przechowuje ją w wyjściowej zmiennej użytkownika 'output'. Ta zmienna użytkownika może być przekazana do poleceń Call lub Goto.

Function func
  DetailPrint "Funkcja"
  IntOp $0 $0 + 2
  Call $0
  DetailPrint "Koniec funkcji"
FunctionEnd

Section
  DetailPrint "Sekcja"
  DetailPrint "Sekcja"
  GetCurrentAddress $0
  Goto callFunc

  DetailPrint "Powrót do sekcji"
  Return

callFunc:
  Call func
  DetailPrint "Koniec sekcji"
SectionEnd


4.9.4.5 GetFunctionAddress


user_var(output) function_name

Instrukcja GetFunctionAddress pobiera adres funkcji oraz przechowuje ją w wyjściowej zmiennej użytkownika 'output'. Ta zmienna użytkownika może być przekazana do poleceń Call lub Goto. Zwróć uwagę, że jeśli użyjesz polecenia Goto dla adresu, który jest wyjściem dla polecenia GetFunctionAddress, twoja funkcja nigdy nie zostanie zwrócona.

Function func
  DetailPrint "Funkcja"
FunctionEnd

Section
  GetFunctionAddress $0 func
  Call $0
SectionEnd


4.9.4.6 GetLabelAddress


user_var(output) label

Instrukcja GetLabelAddress pobiera adres etykiety oraz przechowuje ją w wyjściowej zmiennej użytkownika 'output'. Ta zmienna użytkownika może być przekazana do poleceń Call lub Goto. Zwróć uwagę, że możesz wywołać to polecenie tylko dla etykiet dostępnych z funkcji, ale możesz wywołać je zewsząd (co jest potencjalnie niebezpieczne). Również, jeśli użyjesz polecenia Call, aby wywołać wyjście polecenia GetLabelAddress, kod zostanie wykonany do momentu powrotu (jawnie lub niejawnie, na końcu funkcji), a następnie nastąpi powrót do wyrażenia tuż po poleceniu Call.

label:
DetailPrint "Etykieta"
GetLabelAddress $0 label
IntOp $0 $0 + 4
Goto $0
DetailPrint "Zakończono"


4.9.4.7 Goto


label_to_jump_to | +offset| -offset| user_var(target)

Instrukcja Goto przenosi do etykiety 'label_to_jump_to, jeśli jest ona określona:'.

Jeśli określono +offset lub -offset, skok zależny jest od instrukcji offset. Polecenie Goto +1 przenosi do następnej instrukcji, polecenie Goto -1 przenosi do poprzedniej instrukcji, etc.

Jeśli określono zmienną użytkownika, polecenie Goto powoduje przeskok do adresu bezwzględnego (ogólnie, będziesz chciał pobrać tę wartość z funkcji, jak GetLabelAddress). Polecenia określające flagi kompilatora oraz polecenie SectionIn nie są instrukcjami, więc przeskoki nad nimi nie dają efektu.

Goto label
Goto +2
Goto -2
Goto $0


4.9.4.8 IfAbort


label_to_goto_if_abort [label_to_goto_if_no_abort]

Jeśli wywołano polecenie Abort, polecenie IfAbort "zwróci" wartość True. Zdarzyć się to może, gdy użytkownik wybierze Abort, dla pliku, którego nie udało się utworzyć (lub nadpisać) lub jeśli użytkownik wywołał polecenie Abort ręcznie. Funkcja ta może być wywołana tylko z funkcji wyjścia (leave) strony instalacji komponentów.

Page instfiles "" "" instfilesLeave

Function instfilesLeave
  IfAbort 0 +2
    MessageBox MB_OK "Przerwane przez użytkownika"
FunctionEnd


4.9.4.9 IfErrors


jumpto_iferror [jumpto_ifnoerror]

Instrukcja IfErrors sprawdza i czyści flagę błędu oraz jeśli jest ustawione, przechodzi do instrukcji 'jumpto_iferror', w przeciwnym razie przechodzi do 'jumpto_ifnoerror'. Flaga błędu jest ustawiana przez inne instrukcje, gdy wystąpi błąd (taki jak próba usunięcia pliku, który jest w użyciu).

ClearErrors
File Plik.dat
IfErrors 0 +2
  Call ErrorHandler


4.9.4.10 IfFileExists


file_to_check_for jump_if_present [jump_otherwise]

Instrukcja IfFileExists sprawdza czy dany plik(i) 'file_to_check_for' istnieje (może to być symbol wieloznaczny (wildcard) lub katalog). Jeśli plik istnieje, przechodzi do etykiety 'jump_if_present', jeśli nie istnieje, przechodzi do etykiety 'jump_otherwise'. Jeśli chcesz sprawdzić, czy plik jest katalogiem, użyj polecenia IfFileExists KATALOG\*.*

IfFileExists $WINDIR\notepad.exe 0 +2
  MessageBox MB_OK "Program Notatnik jest zainstalowany"


4.9.4.11 IfRebootFlag


jump_if_set [jump_if_not_set]

Instrukcja IfRebootFlag sprawdza flagę ponownego rozruchu komputera. Jeśli flaga ta jest ustawiona, przechodzi do etykiety 'jump_if_set', jeśli nie jest, przechodzi do etykiety 'jump_if_not_set'. Flaga ponownego rozruchu komputera może być ustawiona przez polecenia Delete, Rename lub ręcznie używając polecenia SetRebootFlag.

IfRebootFlag 0 noreboot
  MessageBox MB_YESNO "Aby zakończyć instalację wymagane jest ponowne uruchomienie komputera. \
                                        Czy chcesz teraz ponownie uruchomić komputer?" IDNO noreboot
    Reboot
noreboot:


4.9.4.12 IfSilent


jump_if_silent [jump_if_not]

Instrukcja IfSilent sprawdza flagę 'silent'. Jeśli instalator jest uruchomiony w trybie cichym, przechodzi do etykiety 'jump_if_silent', w przeciwnym razie przechodzi do etykiety 'jump_if_not'. Flaga 'silent' może być ustawiona przez polecenia SilentInstall, SilentUninstall, SetSilent oraz przez użytkownika poprzez użycie przełącznika /S w wierszu poleceń.

IfSilent +2
  ExecWait '"$INSTDIR\nonsilentprogram.exe"'


4.9.4.13 IntCmp


val1 val2 jump_if_equal [jump_if_val1_less] [jump_if_val1_more]

Instrukcja IntCmp porównuje dwie wartości liczb całkowitych val1 oraz val2. Jeśli wartości val1 oraz val2 są sobie równe, przechodzi do etykiety 'jump_if_equal'. Jeśli wartość val1 < val2, przechodzi do etykiety 'jump_if_val1_less', w przeciwnym razie, jeśli wartość val1 > val2, przechodzi do etykiety 'jump_if_val1_more'.

IntCmp $0 5 is5 lessthan5 morethan5
is5:
  DetailPrint "$$0 == 5"
  Goto done
lessthan5:
  DetailPrint "$$0 < 5"
  Goto done
morethan5:
  DetailPrint "$$0 > 5"
  Goto done
done:


4.9.4.14 IntCmpU


val1 val2 jump_if_equal [jump_if_val1_less] [jump_if_val1_more]

Instrukcja IntCmpU porównuje dwie wartości liczb całkowitych bez znaku val1 oraz val2. Jeśli wartości val1 oraz val2 są sobie równe, przechodzi do etykiety 'jump_if_equal'. Jeśli wartość val1 < val2, przechodzi do etykiety 'jump_if_val1_less', w przeciwnym razie, jeśli wartość val1 > val2, przechodzi do etykiety 'jump_if_val1_more'. Wykonuje porównanie dla liczb całkowitych bez znaku.



4.9.4.15 MessageBox


mb_option_list messagebox_text [/SD return] [return_check jumpto] [return_check_2 jumpto_2]

Instrukcja MessageBox wyświetla komunikat MessageBox, który zawiera tekst "messagebox_text". Identyfikator 'mb_option_list' musi być jednym lub wieloma (rozdzielonych znakiem '|', np. MB_YESNO|MB_ICONSTOP) z następujących.

  • MB_OK - Komunikat z przyciskiem 'OK'
  • MB_OKCANCEL - Komunikat z przyciskami 'OK' oraz 'Anuluj'
  • MB_ABORTRETRYIGNORE - Komunikat z przyciskami 'Przerwij', 'Ponów' oraz 'Ignoruj'
  • MB_RETRYCANCEL - Komunikat z przyciskami 'Ponów' oraz 'Anuluj'
  • MB_YESNO - Komunikat z przyciskami 'Tak' oraz 'Nie'
  • MB_YESNOCANCEL - Komunikat z przyciskami 'Tak, 'Nie' oraz 'Anuluj'
  • MB_ICONEXCLAMATION - Komunikat z ikonką Wykrzyknika
  • MB_ICONINFORMATION - Komunikat z ikonką Informacji
  • MB_ICONQUESTION - Komunikat z ikonką Pytajnika
  • MB_ICONSTOP - Komunikat z ikonką Zatrzymania
  • MB_USERICON - Komunikat z ikonką instalatora
  • MB_TOPMOST - Komunikat wyświetlany jest na górze
  • MB_SETFOREGROUND - Komunikat wyświetlany jest na pierwszym planie
  • MB_RIGHT - Tekst komunikatu wyrównywany jest do prawej
  • MB_RTLREADING - Odczyt RTL
  • MB_DEFBUTTON1 - Przycisk 1 jest przyciskiem domyślnym
  • MB_DEFBUTTON2 - Przycisk 2 jest przyciskiem domyślnym
  • MB_DEFBUTTON3 - Przycisk 3 jest przyciskiem domyślnym
  • MB_DEFBUTTON4 - Przycisk 4 jest przyciskiem domyślnym

Zwracana wartość 'Return_check' może być równa 0 (lub pusta lub przerwano) lub przyjmować jedną z poniższych:

  • IDABORT - Przycisk 'Przerwij'
  • IDCANCEL - Przycisk 'Anuluj'
  • IDIGNORE - Przycisk 'Ignoruj'
  • IDNO - Przycisk' Nie'
  • IDOK - Przycisk 'OK'
  • IDRETRY - Przycisk 'Ponów'
  • IDYES - Przycisk 'Tak'

Jeśli wartością zwracaną przez polecenie MessageBox jest 'return_check', instalator przejdzie do etykiety 'jumpto'.

Użyj przełącznika /SD z jedną z powyższych wartości 'return_check', aby określić opcję, która zostanie użyta gdy instalator działa w trybie cichym. Więcej informacji znajduje się w sekcji 4.12.

MessageBox MB_OK "Prosty komunikat"
MessageBox MB_YESNO "Czy to prawda?" IDYES true IDNO false
true:
  DetailPrint "To jest prawda!"
  Goto next
false:
  DetailPrint "To nie jest prawdą"
next:
MessageBox MB_YESNO "Czy to prawda? (domyślnie 'Tak', w trybie cichym)" /SD IDYES IDNO false2
  DetailPrint "To jest prawda (lub cichy instalator)!"
  Goto next2
false2:
  DetailPrint "To nie jest prawdą"
next2:


4.9.4.16 Return


Instrukcja Return zwraca wartość z funkcji lub sekcji.

Function func
  StrCmp $0 "Zwroc teraz" 0 +2
    Return
  # Zrób coś
FunctionEnd

Section
  Call func
  ;"Return" tutaj zwróci wartość
SectionEnd


4.9.4.17 Quit


Instrukcja Quit powoduje natychmiastowe zakończenie działania instalatora. Po wywołaniu polecenia Quit, instalator zakończy działanie (żadna funkcja zwrotna nie zostanie uruchomiona).



4.9.4.18 SetErrors


Instrukcja SetErrors ustawia flagę błędu.

SetErrors
IfErrors 0 +2
  MessageBox MB_OK "Ten komunikat zostanie zawsze wyświetlony"


4.9.4.19 StrCmp


str1 str2 jump_if_equal [jump_if_not_equal]

Instrukcja StrCmp porównuje łańcuchy znaków str1 oraz str2 (wielkość znaków nie jest uwzględniana). Jeśli łańcuchy znaków str1 oraz str2 są takie same, przechodzi do etykiety 'jump_if_equal', w przeciwnym razie przechodzi do etykiety 'jump_if_not_equal'.

StrCmp $0 "łańcuch znaków" 0 +3
  DetailPrint '$$0 == "łańcuch znaków"'
  Goto +2
  DetailPrint '$$0 != "łańcuch znaków"'


4.9.4.20 StrCmpS


str1 str2 jump_if_equal [jump_if_not_equal]

Instrukcja StrCmpS działa tak samo jak polecenie StrCmp, ale rozróżniane są wielkości liter.



4.9.5 Instrukcje plikowe


4.9.5.1 FileClose


handle

Zamyka uchwyt handle pliku, otwartego poleceniem FileOpen.



4.9.5.2 FileOpen


user_var(handle output) filename openmode

Otwiera plik o nazwie "filename", i ustawia wartość zmiennej wyjściowej uchwytem. Tryb 'openmode' powinien być ustawiony na jeden z "r" (odczyt), "w" (zapis, cała zawartość pliku jest niszczona) lub "a" (dodane, w znaczeniu, że plik jest otwierany do odczytu i zapisu, zawartość jest zachowywana). We wszystkich trybach otwarcia, wskaźnik pliku umieszczany jest na początek pliku. Jeśli nie można otworzyć pliku, wyjściowy uchwyt ustawiany jest na pusty oraz ustawiana jest flaga błędu.

Jeśli nie określono ścieżki bezwzględnej użyty zostanie bieżący katalog. Bieżący katalog jest katalogiem ustawionym ostatnią instrukcją SetOutPath. Jeśli nie użyłeś wcześniej instrukcji SetOutPath, bieżący katalog jest katalogiem $EXEDIR.

FileOpen $0 $INSTDIR\plik.dat r
FileClose $0


4.9.5.3 FileRead


handle user_var(output) [maxlen]

Odczytuje łańcuch znaków (ANSI) z pliku otwartego poleceniem FileOpen. Łańcuch znaków jest odczytywany aż do napotkania znaku nowej linii (lub znaku karetki), lub pustego bajtu (null) lub długości maksymalnej 'maxlen', jeśli została określona. Domyślnie, łańcuchy znaków ograniczone są do 1024 znaków (możesz jednak skompilować lub pobrać specjalny build z większą wartością NSIS_MAX_STRLEN). Jeśli osiągnięto koniec pliku i nie ma więcej danych do odczytu, wyjściowy łańcuch znaków 'output' pozostanie pusty i ustawiona zostanie flaga błędu.

Unicode: Tekst DBCS jest obsługiwany, ale konwersja ograniczona jest do UCS-2/BMP, zastępcze pary nie są obsługiwane. Podczas konwersji używana jest domyślna systemowa strona kodowa ANSI (ACP)).

ClearErrors
FileOpen $0 $INSTDIR\plik.dat r
IfErrors done
FileRead $0 $1
DetailPrint $1
FileClose $0
done:


4.9.5.4 FileReadUTF16LE


handle user_var(output) [maxlen]

Funkcja ta dostępna jest tylko przy kompilacji instalatora Unicode.

Odczytuje łańcuch znaków (znaki UTF-16LE) z pliku otwartego przy pomocy polecenia FileOpen. Łańcuch znaków jest odczytywany aż do napotkania znaku nowej linii (lub znaku karetki) lub pustego znaku (null wide-character) lub długości maksymalnej 'maxlen', jeśli została określona. Domyślnie, łańcuchy znaków ograniczone są do 1024 znaków (możesz jednak skompilować lub pobrać specjalny build z większą wartością NSIS_MAX_STRLEN). Jeśli osiągnięto koniec pliku i nie ma więcej danych do odczytu, wyjściowy łańcuch znaków 'output' pozostanie pusty i ustawiona zostanie flaga błędu. Znacznik BOM na początku pliku, jeśli istnieje, zostaje pominięty.

ClearErrors
FileOpen $0 $INSTDIR\plik.dat r
IfErrors done
FileReadUTF16LE $0 $1
DetailPrint $1
FileClose $0
done:


4.9.5.5 FileReadByte


handle user_var(output)

Odczytuje bajt z pliku otwartego poleceniem FileOpen. Bajt przechowywany jest na wyjściu 'output' jako liczba całkowita (integer) w zakresie (0-255). Jeśli osiągnięto koniec pliku i nie ma więcej danych do odczytu, zmienna 'output' pozostanie pusta i ustawiona zostanie flaga błędu.

ClearErrors
FileOpen $0 $INSTDIR\plik.dat r
IfErrors done
FileReadByte $0 $1
FileReadByte $0 $2
DetailPrint "$1 $2"
FileClose $0
done:


4.9.5.6 FileReadWord


handle user_var(output)

Funkcja ta dostępna jest tylko przy kompilacji instalatora Unicode.

Odczytuje słowo (2-bajty) z pliku otwartego przy użyciu polecenia FileOpen. Słowo przechowywane jest na wyjściu 'output' jako liczba całkowita (integer) w zakresie (0-65535). Jeśli osiągnięto koniec pliku i nie ma więcej danych do odczytu, zmienna 'output' pozostanie pusta i ustawiona zostanie flaga błędu.

ClearErrors
FileOpen $0 $INSTDIR\plik.dat r
IfErrors done
FileReadWord $0 $1
FileReadWord $0 $2
DetailPrint "$1 $2"
FileClose $0
done:


4.9.5.7 FileSeek


handle offset [mode] [user_var(new position)]

Przenosi wskaźnik pliku otwartego poleceniem FileOpen. Gdy pominięto parametr mode lub określony jest jako SET, pozycja pliku ustawiana jest na "offset", względem początku pliku. Gdy parametr mode określony jest jako CUR, pozycja pliku ustawiana jest na "offset", względem bieżącej pozycji pliku. Gdy parametr mode określony jest jako END, pozycja pliku ustawiana jest na "offset", względem końca pliku. Jeśli końcowy parametr nowej pozycji "new position" jest określony, nowa pozycja pliku przechowywana będzie w tej zmiennej.

ClearErrors
FileOpen $0 $INSTDIR\plik.dat r
IfErrors done
FileSeek $0 -5 END
FileRead $0 $1
DetailPrint $1
FileClose $0
done:


4.9.5.8 FileWrite


handle string

Zapisuje łańcuch znaków ANSI do pliku otwartego poleceniem FileOpen. Jeśli podczas zapisu wystąpi błąd, ustawiona zostanie flaga błędu.

(Jeśli kompilujesz instalator Unicode, funkcja konwertuje łańcuch znaków 'string' do ANSI/MBCS. Podczas konwersji używana jest domyślna systemowa strona kodowa ANSI (ACP))

ClearErrors
FileOpen $0 $INSTDIR\plik.dat w
IfErrors done
FileWrite $0 "jakiś tekst"
FileClose $0
done:


4.9.5.9 FileWriteUTF16LE


[/BOM] handle string

Funkcja ta dostępna jest tylko przy kompilacji instalatora Unicode.

Zapisuje łańcuch znaków Unicode (UTF-16LE) do pliku otwartego poleceniem FileOpen. Jeśli wystąpi błąd, ustawiona zostanie flaga błędu. Znacznik BOM może być dodany do pustych plików przy użyciu przełącznika /BOM.

ClearErrors
FileOpen $0 $INSTDIR\plik.dat w
IfErrors done
FileWriteUTF16LE $0 "jakiś tekst"
FileClose $0
done:


4.9.5.10 FileWriteByte


handle string

Zapisuje całkowitoliczbową (integer) interpretację łańcucha znaków 'string' do pliku otwartego poleceniem FileOpen. Oczywiście możesz wpisać bezpośrednio wartość całkowitą. Poniższy kod zapisuje znaki końca wiersza: "Powrotu Karetki / Nowej linii" - Enter do pliku.

FileWriteByte uchwyt_pliku "13"
FileWriteByte uchwyt_pliku "10"

Jeśli podczas zapisu wystąpi błąd, ustawiona zostanie flaga błędu. Pamiętaj, że używane są niskie bajty liczby całkowitej, np. zapis 256 jest taki sam jak 0, etc.



4.9.5.11 FileWriteWord


handle string

Funkcja ta dostępna jest tylko przy kompilacji instalatora Unicode.

Zapisuje całkowitoliczbową (integer) interpretację łańcucha znaków 'string' jako liczba WORD (2 bajty, zakres: 0-65535) do pliku otwartego poleceniem FileOpen. Oczywiście możesz wpisać bezpośrednio wartość całkowitą. Poniższy kod zapisuje znaki końca wiersza: "Powrotu Karetki / Nowej linii" - Enter do pliku.

FileWriteWord uchwyt_pliku "13"
FileWriteWord uchwyt_pliku "10"

Jeśli podczas zapisu wystąpi błąd, ustawiona zostanie flaga błędu. Pamiętaj, że używane jest niska liczba WORD liczby całkowitej, np. zapis 65536 jest taki sam jak 0, etc.



4.9.5.12 FindClose


handle

Zamyka wyszukiwanie otwarte poleceniem FindFirst.



4.9.5.13 FindFirst


user_var(handle output) user_var(filename output) filespec

Wykonuje wyszukiwanie 'filespec', umieszczając pierwszy znaleziony plik w zmiennej użytkownika filename_output. Wstawia również uchwyt wyszukiwania do zmiennej użytkownika handle_output. Jeśli nie znaleziono żadnego pliku, obie zmienne wyjścia ustawiane są na puste i ustawiana jest flaga błędu. Najlepiej używać tego polecenia z poleceniami FindNext oraz FindClose. Pamiętaj, że wartość zmiennej filename output jest nazwą pliku bez ścieżki dostępu.

FindFirst $0 $1 $INSTDIR\*.txt
loop:
  StrCmp $1 "" done
  DetailPrint $1
  FindNext $0 $1
  Goto loop
done:
  FindClose $0


4.9.5.14 FindNext


handle user_var(filename_output)

Kontynuuje wyszukiwanie rozpoczęte poleceniem FindFirst. Uchwyt handle powinien być uchwytem zmiennej handle_output zwróconej przez polecenie FindFirst. Jeśli wyszukiwanie jest kompletne (nie ma już więcej plików spełniających kryteria wyszukiwania), zmienna filename_output ustawiana jest jako pusta i ustawiana jest flaga błędu. Pamiętaj, że wartość zmiennej filename_output jest nazwą pliku bez ścieżki dostępu.



4.9.6 Instrukcje deinstalatora


4.9.6.1 WriteUninstaller


[Path\]exename.exe

Zapisuje instalatora do określonej nazwy pliku (i opcjonalnie ścieżki dostępu). Działa poprawnie tylko z sekcji instalacji lub funkcji i wymaga posiadania sekcji deinstalacji w skrypcie. Zobacz również Konfigurację Deinstalacji. Możesz wywołać to polecenie raz lub więcej razy, aby zapisać jedną lub więcej kopii deinstalatora.

WriteUninstaller $INSTDIR\uninstaller.exe


4.9.7 Różne instrukcje


4.9.7.1 GetErrorLevel


user_var(error level output)

Zwraca ostatni poziom błędów, ustawiony przez polecenie SetErrorLevel lub -1 jeśli nie został użyty.

GetErrorLevel $0
IntOp $0 $0 + 1
SetErrorLevel $0


4.9.7.2 GetInstDirError


user_var(error output)

Użyj w funkcji wyjścia strony wyboru katalogu docelowego. Odczytuje ustawienie flagi, jeśli użyto polecenia 'DirVerify leave'. Możliwe wartości:

  • 0: Bez błędów
  • 1: Nieprawidłowy katalog instalacji
  • 2: Niewystarczająca ilość miejsca na dysku
!include LogicLib.nsh
PageEx directory
  DirVerify leave
  PageCallbacks "" "" dirLeave
PageExEnd

Function dirLeave
  GetInstDirError $0
  ${Switch} $0
    ${Case} 0
      MessageBox MB_OK "prawidłowy katalog instalacji"
      ${Break}
    ${Case} 1
      MessageBox MB_OK "nieprawidłowy katalog instalacji!"
      Abort
      ${Break}
    ${Case} 2
      MessageBox MB_OK "brak miejsca na dysku!"
      Abort
      ${Break}
  ${EndSwitch}
FunctionEnd


4.9.7.3 InitPluginsDir


Inicjalizuje katalog wtyczek ($PLUGINSDIR), jeśli nie został jeszcze zainicjowany.

InitPluginsDir
File /oname=$PLUGINSDIR\image.bmp image.bmp


4.9.7.4 Nop


Nie robi nic.



4.9.7.5 SetErrorLevel


error_level

Ustawia poziom błędów instalatora lub deinstalatora na poziom błędów error_level. Aby dowiedzieć się więcej, czytaj o Poziomach błędów.

IfRebootFlag 0 +2
  SetErrorLevel 4


4.9.7.6 SetRegView


32|64|lastused

Instrukcja SetRegView ustawia widok rejestru dla instrukcji rejestru. W systemie Windows x64 dostępne są dwa widoki. Jeden, dla aplikacji 32-bitowych oraz drugi, dla aplikacji x64. Domyślnie, aplikacje 32-bitowe uruchamiane w systemie 64-bitowym w podsystemie WOW64 mają dostęp tylko do widoku 32-bitowego. Używając polecenia SetRegView 64 zezwolisz instalatorowi na dostęp do 64-bitowego widoku rejestru Windows.

Polecenie dotyczy instrukcji: DeleteRegKey, DeleteRegValue, EnumRegKey, EnumRegValue, ReadRegDWORD, ReadRegStr, WriteRegBin, WriteRegDWORD, WriteRegStr oraz WriteRegExpandStr.

Polecenie nie obejmuje instrukcji InstallDirRegKey. W zamian, rejestr można odczytać używając instrukcji ReadRegStr w funkcji .onInit.

SetRegView 32
ReadRegStr $0 HKLM Software\Microsoft\Windows\CurrentVersion ProgramFilesDir
DetailPrint $0 # Wypisuje C:\Program Files (x86)
SetRegView 64
ReadRegStr $0 HKLM Software\Microsoft\Windows\CurrentVersion ProgramFilesDir
DetailPrint $0 # Wypisuje C:\Program Files
Function .onInit
  SetRegView 64
  ReadRegStr $INSTDIR HKLM Software\NSIS ""
  SetRegView 32
FunctionEnd


4.9.7.7 SetShellVarContext


current|all

Ustawia zawartość zmiennej $SMPROGRAMS i innych folderów powłoki. Jeśli parametr ustawiony jest na bieżący 'current' (domyślnie), używane są foldery powłoki bieżącego użytkownika. Jeśli parametr ustawiony jest na wszyscy 'all', używany jest folder powłoki 'all users'. Folder all users może nie być obsługiwany na wszystkich systemach operacyjnych. Jeśli folderu all users nie znaleziono, użyty zostanie bieżący folder użytkownika. Należy mieć na uwadze, że "zwykły użytkownik" nie posiada praw do zapisu w obszarze katalogu all users. Tylko administratorzy mają pełne prawa do zapisu w obszarze katalogu all users. Informację tę możesz sprawdzić używając wtyczki UserInfo. Dla przykładu zobacz Contrib\UserInfo\UserInfo.nsi.

Zauważ, że jeśli polecenie zostało użyte w kodzie instalatora, będzie miało wpływ tylko na instalator, a jeśli zostało użyte w kodzie deinstalatora, będzie miało wpływ tylko na deinstalatora. Aby można było oddziaływać na oba, musisz użyć tego polecenia w obu.

SetShellVarContext current
StrCpy $0 $DESKTOP
SetShellVarContext all
StrCpy $1 $DESKTOP
MessageBox MB_OK $0$\n$1


4.9.7.8 Sleep


sleeptime_in_ms

Wstrzymuje wykonywanie instalatora na okres czasu równy 'sleeptime_in_ms' milisekund. Parametr 'sleeptime_in_ms' może być zmienną, np. "$0" lub liczbą, np. "666".

DetailPrint "usypianie..."
Sleep 3000
DetailPrint "powrót do pracy"




4.9.8 Instrukcje do manipulowania łańcuchami znaków


4.9.8.1 StrCpy


user_var(destination) str [maxlen] [start_offset]

Ustawia zmienną użytkownika $x przez str. Pamiętaj, że str może zawierać ine zmienne, lub ustawianą zmienną użytkownika (łączenie łańcuchów znaków tą metodą jest możliwe, itd.). Jeśli określony jest maxlen, łańcuch znaków będzie miał maksymalny rozmiar znaków maxlen (jeśli maxlen jest ujemny, łańcuch znaków zostanie obcięty o abs(maxlen) znaków od końca). Jeśli określono początkową odległość start_offset, źródło jest oddalone o tę wartość (jeśli start_offset jest ujemna, zacznie od abs(start_offset) końca łańcucha znaków).

StrCpy $0 "a string" # = "a string"
StrCpy $0 "a string" 3 # = "a s"
StrCpy $0 "a string" -1 # = "a strin"
StrCpy $0 "a string" "" 2 # = "string"
StrCpy $0 "a string" "" -3 # = "ing"
StrCpy $0 "a string" 3 -4 # = "rin"


4.9.8.2 StrLen


user_var(length output) str

Ustawia zmienną użytkownika $x długością łańcucha znaków str.

StrLen $0 "123456" # = 6


4.9.9 Obsługa stosu


4.9.9.1 Exch


[user_var | stack_index]

Jeśli nie określono żadnego parametru, wymienia dwa górne elementy stosu. Jeśli parametr jest określony i jest zmienną użytkownika, zmienia górny element stosu z parametrem. Jeśli parametr jest określony i jest dodatnią liczbą całkowitą, instrukcja Exch zamieni element będący na samej górze z elementem, który jest określony przez odległość od góry stosu w parametrze. Jeśli na stosie nie ma wystarczającej ilości elementów, aby dokończyć zamianę, wystąpi błąd krytyczny (aby pomóc ci odpluskwić kod :).

Push 1
Push 2
Exch
Pop $0 # = 1
Push 1
Push 2
Push 3
Exch 2
Pop $0 # = 1
StrCpy $0 1
Push 2
Exch $0 # = 2
Pop $1 # = 1


4.9.9.2 Pop


user_var(out)

Zdejmuje łańcuch znaków ze stosu i przypisuje do zmiennej użytkownika $x. Jeśli stos jest pusty, ustawiona zostanie flaga błędu.

Push 1
Pop $0 # = 1


4.9.9.3 Push


string

Odkłada łańcuch znaków string na stos. Ten łańcuch znaków może być następnie zdjęty z niego (instrukcją Pop).

Push "łańcuch znaków"


4.9.10 Obsługa typu Integer


4.9.10.1 IntFmt


user_var(output) format numberstring

Formatuje liczbę w "numberstring" używając formatu "format" i przypisuje wyjście do zmiennej użytkownka $x. Przykładowy sformatowany łańcuch znaków zawiera "%08X" "%u"

IntFmt $0 "0x%08X" 195948557
IntFmt $0 "%c" 0x41


4.9.10.2 IntOp


user_var(output) value1 OP [value2]

Łączy wartość value1 oraz wartość value2 (w oparciu o OP) w określoną zmienną użytkownika (user_var). OP zdefiniowane jest jako jedno z poniższych:

  • +: DODAJE wartość value1 oraz wartość value2
  • -: ODEJMUJE wartość value2 od wartości value1
  • *: MNOŻY wartość value1 oraz wartość value2
  • /: DZIELI wartość value1 przez wartość value2
  • %: DZIELI Z RESZTĄ wartości value1 przez wartość value2
  • |: BINARNE LUB (OR) wartości value1 oraz wartość value2
  • &: BINARNE ORAZ (AND) wartości value1 oraz wartość value2
  • ^: BINARNE XOR wartości value1 oraz wartość value2
  • >>: PRZESUNIĘCIE BITOWE W PRAWO wartości value1 o wartość value2
  • <<: PRZESUNIĘCIE BITOWE W LEWO wartości value1 o value2
  • ~: NEGACJA BITOWA wartości value1 (np. 7 staje się 4294967288)
  • !: NEGACJA LOGICZNA wartości value1 (np. 7 staje się 0)
  • ||: LOGICZNE LUB (OR) wartości value1 oraz wartości value2
  • &&: LOGICZNE ORAZ (AND) wartości value1 oraz wartości value2
IntOp $0 1 + 1
IntOp $0 $0 + 1
IntOp $0 $0 << 2
IntOp $0 $0 ~
IntOp $0 $0 & 0xF


4.9.11 Instrukcje ponownego uruchamiania komputera


4.9.11.1 Reboot


Uruchamia ponownie komputer. Bądź ostrożny z tą instrukcją. Jeśli się nie powiedzie wywoływana jest instrukcja .onRebootFailed. W każdym przypadku, instrukcja ta nigdy nie zwraca wyniku, tak jak Quit.

  MessageBox MB_YESNO|MB_ICONQUESTION "Czy chcesz uruchomić ponownie komputer?" IDNO +2
  Reboot


4.9.11.2 SetRebootFlag


true|false

Ustawia flagę ponownego uruchamiania komputera (true lub false). Wartość flagi może być odczytana dzięki instrukcji IfRebootFlag.

SetRebootFlag true
IfRebootFlag 0 +2
  MessageBox MB_OK "Ten komunikat będzie zawsze wyświetlany"


4.9.12 Instrukcje dziennika instalacji


4.9.12.1 LogSet


on|off

Instrukcja LogSet określa, czy włączony jest zapis dziennika instalacji do pliku $INSTDIR\install.log. Zmienna $INSTDIR musi mieć wartość, zanim wywołasz tę funkcję, w przeciwnym razie nie będzie działać. Pamiętaj, że ustawienie NSIS_CONFIG_LOG musi być ustawione (scons NSIS_CONFIG_LOG=yes) w czasie kompilacji (domyślnie nie jest), aby obsłużyć to polecenie. Zobacz Kompilacja NSIS, aby dowiedzieć się więcej o rekompilacji NSIS.



4.9.12.2 LogText


text

Jeśli włączony jest dziennik instalacji, wstawia tekst "text" do pliku dziennika.

IfFileExists $WINDIR\notepad.exe 0 +2
  LogText "$$WINDIR\notepad.exe istnieje"


4.9.13 Zarządzanie sekcjami


4.9.13.1 SectionSetFlags


section_index section_flags

Ustawia flagi dla sekcji. Flaga jest 32 bitową liczbą całkowitą. Pierwszy bit (najniższy) reprezentuje informację, czy sekcja jest aktualnie zaznaczona, drugi bit mówi o tym, czy sekcja jest grupą sekcji (zmieniaj tylko wtedy, gdy naprawdę wiesz co robisz), trzeci bit mówi o tym, czy sekcja jest grupą sekcji (znowu, nie modyfikuj), czwarty bit mówi o tym, czy sekcja jest wyświetlana pogrubioną czcionką lub nie, piaty bit mówi o tym, czy sekcja jest tylko do odczytu, szósty bit mówi o tym, czy grupa sekcji ma być automatycznie rozwinięta, siódmy bit ustawiany jest dla grupy sekcji, która jest częściowo zaznaczona, ósmy bit jest wykorzystywany wewnętrznie dla zmian częściowego zaznaczenia grupy sekcji oraz dziewiąty bit używany jest do odzwierciedlania zmian nazwy sekcji. Flaga błędu zostanie ustawiona jeśli wybrano sekcję z poza zakresu.

Każda flaga posiada nazwę, z prefiksem `SF_`:

!define SF_SELECTED   1
!define SF_SECGRP     2
!define SF_SECGRPEND  4
!define SF_BOLD       8
!define SF_RO         16
!define SF_EXPAND     32
!define SF_PSELECTED  64

Aby zobaczyć przykład użycia spójrz na skrypt one-section.nsi (../Examples/one-section.nsi).

Więcej przydatnych makr oraz definicji znajdziesz w pliku 'Include\Sections.nsh'.

Section test id_sekcji_test
SectionEnd

Function .onInit
  # ustawia sekcję 'test' jako zaznaczoną oraz tylko do odczytu
  IntOp $0 ${SF_SELECTED} | ${SF_RO}
  SectionSetFlags ${id_sekcji_test} $0
FunctionEnd


4.9.13.2 SectionGetFlags


section_index user_var(output)

Pobiera flagi sekcji. Popatrz powyżej na opis flag. Flaga błędu zostanie ustawiona, jeśli wybrano sekcję z poza zakresu.

Section test id_sekcji_test
SectionEnd

Function .onSelChange
  # utrzymaj zaznaczenie sekcji 'test'
  SectionGetFlags ${id_sekcji_test} $0
  IntOp $0 $0 | ${SF_SELECTED}
  SectionSetFlags ${id_sekcji_test} $0
FunctionEnd


4.9.13.3 SectionSetText


section_index section_text

Ustawia opis dla section_index sekcji. Jeśli tekst ustawiany jest na "", to sekcja zostanie ukryta. Flaga błędu zostanie ustawiona, jeśli wybrano sekcję z poza zakresu.

Section "" id_sekcji_test
SectionEnd

Function .onInit
  # zmień nazwę sekcji na $WINDIR
  SectionSetText ${id_sekcji_test} $WINDIR
FunctionEnd


4.9.13.4 SectionGetText


section_index user_var(output)

Przechowuje opis tekstowy section_index sekcji w output. Jeśli sekcja jest ukryta, przechowuje pusty łańcuch znaków. Flaga błędu zostanie ustawiona, jeśli wybrano sekcję z poza zakresu.

Section test id_sekcji_test
SectionEnd

Function .onInit
  # przypisuje zmienną $WINDIR do nazwy sekcji
  SectionGetText ${id_sekcji_test} $0
  StrCpy $0 "$0 - $WINDIR"
  SectionSetText ${id_sekcji_test} $0
FunctionEnd


4.9.13.5 SectionSetInstTypes


section_index inst_types

Ustawia typ instalacji sekcji określonej przez section_index domyślnie na włączony stan. Pamiętaj, że indeks sekcji section_index zaczyna się od zera. Każdy bit inst_types jest flagą, która mówi o tym, czy sekcja jest w danym typie instalacji czy też nie. Na przykład, jeśli masz zdefiniowane 3 typy instalacji i chcesz by pierwsza z sekcji należała do typu instalacji 1 oraz 3, to polecenie powinno wyglądać jak poniżej:

SectionSetInstTypes 0 5

Ponieważ binarna wartość 5 równa się "00000101". Flaga błędu zostanie ustawiona, jeśli wybrano sekcję z poza zakresu.

Section test id_sekcji_test
SectionEnd

Function .onInit
  # wiąże sekcję 'test' z typem instalacji 3 oraz 4
  SectionSetInstTypes ${id_sekcji_test} 12
FunctionEnd


4.9.13.6 SectionGetInstTypes


section_index user_var(output)

Pobiera tablicę flag typów instalacji sekcji. Zobacz powyżej SectionSetInstTypes, aby dowiedzieć się w jaki sposób obsłużyć output. Flaga błędu zostanie ustawiona, jeśli indeks sekcji jest z poza zakresu.

Section test id_sekcji_test
SectionEnd

Function .onInit
  # wiąże sekcję 'test' z typem instalacji 5, na górze jej istniejacych powiązań
  SectionGetInstTypes ${id_sekcji_test} $0
  IntOp $0 $0 | 16
  SectionSetInstTypes ${id_sekcji_test} $0
FunctionEnd


4.9.13.7 SectionSetSize


section_index new_size

Ustawia rozmiar sekcji określonej przez indeks sekcji section_index. Pamiętaj, że indeksowanie rozpoczyna się od zera. Wartość dla rozmiaru musi być wpisana w kilobajtach i obsługuje tylko całe liczby.

Section test id_sekcji_test
SectionEnd

Function .onInit
  # ustawia wymagany rozmiar sekcji 'test' na 100 bajtów
  SectionSetSize ${id_sekcji_test} 100
FunctionEnd


4.9.13.8 SectionGetSize


section_index user_var

Pobiera rozmiar sekcji określonej przez indeks sekcji 'section_index' i przechowuje go w podanej wartości zmiennej użytkownika 'user_var'. Pamiętaj, że indeksowanie rozpoczyna się od zera. Flaga błędu zostanie ustawiona, jeśli indeks sekcji jest z poza zakresu.

Section test id_sekcji_test
SectionEnd

Function .onInit
  # zwiększa wymagany rozmiar sekcji 'test' o 100 KiB
  SectionGetSize ${id_sekcji_test} $0
  IntOp $0 $0 + 100
  SectionSetSize ${id_sekcji_test} $0
FunctionEnd


4.9.13.9 SetCurInstType


inst_type_idx

Ustawia aktualny typ instalacji InstType. Indeks typu instalacji inst_type_idx powinien zawierać się pomiędzy 0 a 31. Flaga błędu nie jest ustawiana, jeśli użyje się typ instalacji InstType z poza zakresu.



4.9.13.10 GetCurInstType


user_var

Pobiera aktualny typ instalacji InstType i przechowuje go w zmiennej użytkownika user_var. Jeśli wybrany jest pierwszy typ instalacji, do zmiennej user_var zostanie przypisana wartość 0. Jeśli wybrany zostanie drugi typ instalacji, do zmiennej user_var zostanie przypisana wartość 1 i tak dalej. Wartość ${NSIS_MAX_INST_TYPES} (domyślnie 32) oznacza, że wybrany został niestandardowy typ instalacji. Pamiętaj, że wybranie typu instalacji "Niestandardowa" z menu nie wystarcza. Wartość obliczana jest przez sekcje, które są zaznaczone.



4.9.13.11 InstTypeSetText


inst_type_idx text

Ustawia Tekst text określonego typu instalacji InstType. Jeśli tekst jest pusty, typ instalacji InstType zostaje usunięty. Używając poprzedniego nieużywanego numeru indeksu typu instalacji inst_type_idx, możesz stworzyć nowy typ instalacji. Aby dodać/usunąć Sekcje do/z tego nowego typu instalacji InstType, zobacz polecenie SectionSetInstTypes. W przeciwieństwie do SectionIn indeks rozpoczyna się od zera, co oznacza, że indeksem pierwszego typu instalacji jest 0.

InstType a
InstType b

Function .onInit
  # ustaw nazwę pierwszego typu instalacji na $WINDIR
  InstTypeSetText 0 $WINDIR
  # ustaw nazwę drugiego typu instalacji na $TEMP
  InstTypeSetText 1 $TEMP
FunctionEnd


4.9.13.12 InstTypeGetText


inst_type_idx user_var

Pobiera Tekst określonego typu instalacji InstType.

InstType a
InstType b

Function .onInit
  InstTypeGetText 0 $0
  DetailPrint $0 # wypisze 'a'
  InstTypeGetText 1 $0
  DetailPrint $0 # wypisze 'b'
FunctionEnd


4.9.14 Instrukcje interfejsu użytkownika


4.9.14.1 BringToFront


Ustawia okno instalatora jako widoczne oraz na wierzchu listy okien. Jeśli aplikacja została uruchomiona w taki sposób, że wyświetlana jest na wierzchu instalatora, BringToFront przywróci okno instalatora z powrotem.

Najnowsze wersje Windows ograniczają ustawienia okien pierwszoplanowych. Jeśli użytkownik pracuje z inną aplikacją podczas instalowania, może być powiadomiony przy użyciu innej metody.



4.9.14.2 CreateFont


user_var(handle output) face_name [height] [weight] [/ITALIC] [/UNDERLINE] [/STRIKE]

Tworzy czcionkę i przypisuje jej uchwyt do zmiennej user_var. Więcej informacji o różnych parametrach znajdziesz na stronach MSDN, o funkcji Win32 API - CreateFont().

Możesz pobrać bieżącą czcionkę używaną przez NSIS poprzez użycie ^Font oraz ^FontSize dla łańcuchów znaków LangString.

!include WinMessages.nsh
GetDlgItem $0 $HWNDPARENT 1
CreateFont $1 "Times New Roman" "7" "700" /UNDERLINE
SendMessage $0 ${WM_SETFONT} $1 1


4.9.14.3 DetailPrint


user_message

Dodaje łańcuch znaków "user_message" do widoku szczegółów instalatora.

DetailPrint "Ten komunikat zostanie wyświetlony w oknie instalacji"


4.9.14.4 EnableWindow


hwnd (1|0)

Włącza lub wyłącza wejście myszy lub klawiatury, dla określonego okna lub kontrolki. Możliwymi stanami są 0 (wyłączone) lub 1 (włączone).

GetDlgItem $0 $HWNDPARENT 1
EnableWindow $0 0
Sleep 1000
EnableWindow $0 1


4.9.14.5 FindWindow


user_var(hwnd output) windowclass [windowtitle] [windowparent] [childafter]

Wyszukuje okno. Zachowuje się tak, jak funkcja win32 FindWindowEx(). Wyszukuje przez klasę okna windowclass (oraz/lub tytuł okna windowtitle, jeśli jest określony). Jeśli określone są windowparent lub childafter, wyszukiwanie zostanie odpowiednio ograniczone. Jeśli windowclass lub windowtitle są określone jako "", nie bedą użyte w wyszukiwaniu. Jeśli nie znaleziono okna, zmienna użytkownika przyjmie wartość 0. Aby zrealizować zachowanie FindWindow w starym stylu, użyj FindWindow z SendMessage.

FindWindow $0 "#32770" "" $HWNDPARENT
FindWindow $0 "moja klasa okna" "mój tytuł okna"


4.9.14.6 GetDlgItem


user_var(output) dialog item_id

Pobiera uchwyt kontrolki identyfikowanej przez item_id w określonym oknie dialogowym dialog. Jeśli chcesz pobrać uchwyt kontrolki w wewnętrznym oknie dialogowym, wpierw użyj FindWindow user_var(output) "#32770" "" $HWNDPARENT, aby pobrać uchwyt wewnętrznego okna dialogowego.

GetDlgItem $0 $HWNDPARENT 1 # dalej/przycisk instaluj


4.9.14.7 HideWindow


Ukrywa okno instalatora.



4.9.14.8 IsWindow


HWND jump_if_window [jump_if_not_window]

Jeśli HWND jest oknem, użyj polecenia Goto jump_if_window, w przeciwnym przypadku, polecenie Goto jump_if_not_window (jeśli określone).

GetDlgItem $0 $HWNDPARENT 1
IsWindow $0 0 +3
  MessageBox MB_OK "znaleziono okno"
  Goto +2
  MessageBox MB_OK "brak okna"


4.9.14.9 LockWindow


on|off

LockWindow on uniemożliwia głównemu oknu przerysowywania siebie przy zmianach. Gdy użyjesz LockWindow off, wszystkie kontrolki, które nie zostały przerysowane od czasu użycia LockWindow on zostaną przerysowane. Sprawia to, że migotanie stron jest przyjemniejsze dla oka, ponieważ teraz miga cała grupa kontrolek w tym samym czasie, a nie jednej. Indywidualne migotanie kontrolki jest bardziej widoczne na starszych komputerach.



4.9.14.10 SendMessage


HWND msg wparam lparam [user_var(return value)] [/TIMEOUT=time_in_ms]

Wysyła komunikat do HWND. Jeśli określona jest zmienna użytkownika $x, jako ostatni parametr (lub przedostatni, jeśli użyjesz przełącznika /TIMEOUT), zwracana wartość SendMessage przechowywana będzie w niej. Pamiętaj, że określając 'msg' musisz użyć wartości całkowitej komunikatu. Jeśli chcesz wysłać łańcuch znaków użyj "STR:łańcuch znaków" jako wParam lub lParam, gdy jest taka potrzeba.

  • WM_CLOSE 16
  • WM_COMMAND 273
  • WM_USER 1024

Dołącz plik WinMessages.nsh do skryptu, by mieć zdefiniowane wszystkie komunikaty Windows we własnym skrypcie.

Aby wysłać łańcuch znaków, umieść STR: przed parametrem, na przykład: "STR:jakiś łańcuch znaków".

Użyj przełącznika /TIMEOUT=time_in_ms aby określić czas time-out, w milisekundach.

!include WinMessages.nsh
FindWindow $0 "Winamp v1.x"
SendMessage $0 ${WM_CLOSE} 0 0


4.9.14.11 SetAutoClose


true|false

Nadpisuje domyślną flagę automatycznego zamykania okna (określoną w instalatorze przez polecenie AutoCloseWindow, oraz z parametrem false dla deinstalatora). Ustaw parametr 'true', aby okno instalacji zniknęło natychmiast po zakończeniu instalacji, lub 'false', aby uczynić to ręcznie.



4.9.14.12 SetBrandingImage


[/IMGID=item_id_in_dialog] [/RESIZETOFIT] path_to_bitmap_file.bmp

Ustawia bieżący plik bitmapy jako obrazek firmowy. Jeśli nie określono IMGID, użyta zostanie pierwsza znaleziona kontrolka obrazka lub kontrolka obrazka utworzona przez AddBrandingImage. Pamiętaj, że bitmapa musi znajdować się na komputerze użytkownika. Użyj najpierw polecenia File, by ją tam umieścić. Jeśli określony jest przełącznik /RESIZETOFIT obrazek będzie automatycznie dopasowywany (nędznie) do rozmiaru kontrolki obrazka. Jeśli użyłeś polecenia AddBrandingImage możesz pobrać ten rozmiar, poprzez skompilowanie skryptu i wyszukanie tej informacji w wyjściu, przy poleceniu AddBrandingImage. SetBrandingImage nie będzie działać, jeśli zostanie wywołane z funkcji .onInit!



4.9.14.13 SetDetailsView


show|hide

Wyświetla bądź ukrywa szczegóły, w zależności od użytego parametru. Nadpisuje domyślny widok szczegółów, który jest ustawiany przez ShowInstDetails.



4.9.14.14 SetDetailsPrint


none|listonly|textonly|both|lastused

Ustawia tryb, w którym polecenia wypisują swój status. Przy parametrze None szczegóły poleceń nie są wypisywane, przy parametrze listonly tekst statusu dodawany jest na listę elementów, przy parametrze textonly tekst statusu wydrukowywany jest tylko w pasku statusu, zaś parametr both aktywuje oba powyższe tryby (domyślnie). Do wyodrębniania wielu małych plików zaleca się aktywowanie trybu textonly (zwłaszcza w systemach win9x, z włączonym płynnym przewijaniem).

SetDetailsPrint none
File "tajny plik.dat"
SetDetailsPrint both


4.9.14.15 SetCtlColors


hwnd [/BRANDING] [text_color] [transparent|bg_color]

Ustawia kolor tła i kolor tekstu dla statycznej kontrolki, kontrolki edycji, przycisku lub okna dialogowego. text_color oraz bg_color nie akceptują zmiennych. Użyj instrukcji GetDlgItem, aby pobrać uchwyt (HWND) kontrolki. Aby kontrolka uzyskała właściwości przezroczystości, użyj wpisu "transparent", jako wartość koloru tła. Możesz również określić przełącznik /BRANDING z lub bez koloru tekstu i kolorem tła, aby uczynić kontrolkę całkowicie szarą (lub użyć innego koloru, jaki wybierzesz). Własność ta używana jest dla tekstu branding w MUI.

FindWindow $0 "#32770" "" $HWNDPARENT
GetDlgItem $0 $0 1006
SetCtlColors $0 0xFF0000 0x00FF00

Uwaga: ustawienie koloru tła pół wyboru na "transparent" może nie działać poprawnie, gdy używasz polecenia 'XPStyle on'. Tło może być wtedy całkowicie czarne, zamiast przezroczystego, jeśli używasz styli systemu Windows.



4.9.14.16 SetSilent


silent | normal

Ustawia tryb wykonywania instalatora - cichy lub normalny. Więcej informacji o cichych instalatorach znajdziesz w SilentInstall. Instrukcja ta może być użyta tylko i wyłącznie w funkcji .onInit.



4.9.14.17 ShowWindow


hwnd show_state

Ustawia widoczność okna. Możliwe stany show_states są takie same jak w funkcji Windows ShowWindow. Stałe SW_* zdefiniowane są w pliku nagłówkowym Include\WinMessages.nsh.

!include WinMessages.nsh
GetDlgItem $0 $HWNDPARENT 1
ShowWindow $0 ${SW_HIDE}
Sleep 1000
ShowWindow $0 ${SW_SHOW}




4.9.15 Instrukcje interfejsu wielojęzykowego


4.9.15.1 LoadLanguageFile


plik_językowy.nlf

Wczytuje plik językowy dla struktury tablicy języka. Wszystkie pliki językowe, które rozprowadzane są z NSIS znajdują się w pliku Contrib\Language Files

Po wstawieniu pliku językowego ${LANG_langfile} zostanie zdefiniowany jako numer id języka (na przykład, ${LANG_ENGLISH} zostanie zdefiniowany jako 1033). Używaj tej instrukcji razem z instrukcjami LangString, LicenseLangString, LangDLL oraz VIAddVersionKey.



4.9.15.2 LangString


name language_id string

Definiuje wielojęzykowy łańcuch znaków. Oznacza to, że jego wartości mogą być różne (lub nie, to zależy od ciebie) dla każdego języka. Pozwala na łatwe tworzenie wielojęzykowych instalatorów, bez potrzeby dodawania wielu przełączników do skryptu.

Każdy łańcuch znaków języka posiada unikalną nazwę identyfikującą go oraz wartość dla każdego z języków używanych przez instalatora. Mogą one być używane w dowolnym łańcuchu znaków w skrypcie, podczas wykonania. Wszystko co musisz zrobić, by móc użyć łańcucha znaków języka, to dodać do tego łańcucha znaków zmienną $(LangString_nazwa), tam gdzie chcesz wstawić LangString.

Uwagi:

  • W przeciwieństwie do definicji, które używają nawiasów klamrowych - {}, łańcuchy znaków języka używają nawiasów otwartych - ().
  • Jeśli zmienisz język w funkcji .onInit, Pamiętaj, że łańcuchy znaków języka w funkcji .onInit wciąż będą używać języka wykrytego w oparciu o domyślny język systemu Windows, ponieważ język inicjalizowany jest po wykonaniu funkcji .onInit.
  • Zawsze ustawiaj łańcuchy znaków języka dla każdego języka w swoim skrypcie.
  • Jeśli ustawisz numer ID języka na 0 użyty zostanie ostatnio używany język LangString lub LoadLanguageFile.

Przykład użycia:

 LangString komunikat ${LANG_ENGLISH} "Angielski komunikat"
 LangString komunikat ${LANG_FRENCH} "Francuski komunikat"
 LangString komunikat ${LANG_KOREAN} "Koreański komunikat"
 LangString komunikat ${LANG_POLISH} "Polski komunikat"
 MessageBox MB_OK "Przetłumaczony komunikat: $(komunikat)"


4.9.15.3 LicenseLangString


name language_id license_path

Spełnia taką samą funkcję co instrukcja LangString, ale wczytuje łańcuchy znaków z pliku tekstowego/RTF oraz definiuje specjalny LangString, który może być użyty tylko przez instrukcję LicenseData.

LicenseLangString licencja ${LANG_ENGLISH} license-english.txt
LicenseLangString licencja ${LANG_FRENCH} license-french.txt
LicenseLangString licencja ${LANG_GERMAN} license-german.txt
LicenseLangString licencja ${LANG_POLISH} polska_licencja.txt
LicenseData $(licencja)

4.10 Interfejs wielojęzykowy


Poczynając od wersji 2 NSIS w pełni obsługuje instalatory wielojęzykowe. Interfejs jednego instalatora może korzystać z wielu języków.

Użyj polecenia LoadLanguageFile dla każdego języka, aby załadować domyślne teksty interfejsu oraz właściwości języka.

Domyślne teksty interfejsu mogą być łatwo zmienione poprzez użycie instrukcji, takich jak ComponentText itd.

Możesz również użyć standardowych łańcuchów znaków języka we własnych (na przykład, $(^Name) zawiera nazwę instalatora, nadaną poprzez użycie polecenia Name). Nazwy wszystkich standardowych łańcuchów znaków języka są wylistowane jako komentarz tuż powyżej łańcuchów znaków w plikach językowych. Pliki językowe znajdują się w katalogu "Contrib\Language Files".

Aby utworzyć własny łańcuch znaków języka, użyj polecenia LangString.

Przykład instalatora wykorzystującego interfejs z wieloma językami znajdziesz w pliku "languages.nsi" w katalogu z przykładami.


4.10.1 Wybór języka


Gdy instalator uruchamia się, wykonuje poniższe kroki, aby wybrać interfejs językowy:

  1. Pobranie domyślnego języka interfejsu Windows
  2. Znalezienie idealnego dopasowania dla języka
  3. Jeśli nie znaleziono idealnego dopasowania, znajduje pierwszy pasujący język
  4. Jeśli nie znaleziono dopasowania, używa pierwszego języka zdefiniowanego w skrypcie (upewnij się, że twój pierwszy język jest powszechny, jak angielski (English))
  5. Jeśli zmienna języka $LANGUAGE zmieniła swoją wartość w funkcji .onInit, NSIS rozpatruje ponownie kroki od 2 do 4.


4.10.2 Wtyczka LangDLL


Wtyczka LangDLL umożliwia użytkownikowi wybranie języka instalatora. Wystarczy odłożyć na stos ID języka (${LANG_langfile}) oraz jego nazwę dla każdego języka twojego instalatora, następnie odłożyć liczbę tych języków, tekst w nagłówku oraz tekst, który mówi użytkownikowi, aby wybrał język, potem wywołać funkcję wtyczki LangDialog, a w końcu pobrać zwróconą wartość do zmiennej $LANGUAGE. Jeśli użytkownik kliknie na przycisk anuluj, zwróconą wartością będzie "cancel".

Przykład użycia znajdziesz w pliku "languages.nsi", który znajduje się w katalogu z przykładami.



4.10.3 Języki RTL


Języki RTL są językami, które zapisywane są z prawej do lewej (np. Arabski i Hebrajski). NSIS w pełni wspiera języki RTL. W pliku językowym jest miejsce, w którym określamy, czy plik jest językiem RTL czy też nie. Aby dowiedzieć się tego podczas wykonania, sprawdź wartość zmiennej $(^RTL) łańcucha znaków języka. Wartość ta będzie równa 1, jeśli język jest typu RTL, w przeciwnym razie równy jest 0. Może to być przydatne, gdy używa się wtyczek, które tworzą okna dialogowe. Zazwyczaj mają one także ustawienia RTL.

4.11 Wtyczki


Możliwości języka skryptowego NSIS mogą być rozszerzone o funkcjonalność, którą dostarczają biblioteki DLL, zwane wtyczkami. Prawdopodobnie najlepszym znanym przykładem ich wykorzystania jest wtyczka InstallOptions.dll, która jest rozprowadzana z każdą dystrybucją NSIS.

Po uruchomieniu kompilatora NSIS, skanuje on katalog wtyczek w poszukiwaniu bibliotek DLL. Następnie tworzy listę bibliotek, które znalazł oraz wszystkich funkcji, które one udostępniają. Kompilator podczas kompilacji skryptu każdorazowo przeszukuje tę listę, jeśli w miejscu gdzie kompilator spodziewa się znaleźć słowo kluczowe, znaleziona zostanie sekwencja, taka jak: 'fred::flintstone'. Jeśli okaże się, że biblioteka fred.dll eksportuje funkcję 'flintstone', NSIS dołączy plik fred.dll do utworzonego pliku binarnego instalatora.

Podczas wykonywania funkcji eksportowanej przez wtyczkę, NSIS rozpakuje odpowiednią bibliotekę DLL do katalogu tymczasowego ($PLUGINSDIR), odłoży wszystkie wymagane argumenty (w kolejności z prawej do lewej), a następnie wykona tę funkcję.


4.11.1 Wywoływanie funkcji wtyczek


Wywołanie wtyczki wygląda następujaco:

InstallOptions::dialog "lokalizacja_pliku_ini.ini"

Wszystkie parametry odkładane sa na stos (w takim przypadku, funkcja wtyczki wymaga tylko jednego parametru). Niektóre polecenia wtyczki mogą nie wymagać żadnego parametru na stosie, inne mogą wymagać ich więcej. Aby użyć polecenia wtyczki będziesz musiał przeczytać dokumentację określonej wtyczki, by dowiedzieć się jakich parametrów funkcja wymaga.



4.11.2 Ręczne wywoływanie wtyczek


Jeśli chcesz wywołać wtyczkę, która jest zapisana na dysku użytkownika lub gdzie indziej, użyj polecenia CallInstDLL. Prawie wszystkie wtyczki zgodne są z funkcjonalnością instalatora, więc używanie poleceń wtyczki jest łatwiejsze. Użycie polecenia CallInstDLL może być użyteczne, gdy utworzyłeś wtyczki, które powinny być linkowane do określonej wersji twojej aplikacji i które są kopiowane do katalogu instalacji.

4.12 Ciche instalatory/deinstalatory


Ciche instalatory (bezokienkowe) są instalatorami, które nie wymagają interakcji z użytkownikiem i nie posiadają interfejsu użytkownika. Użytkownik nie widzi żadnego okna dialogowego i nie są mu zadawane żadne pytania. Instalatory takie są przydatne dla administratorów sieci, którzy chcą szybko i sprawnie instalować lub deinstalować jakieś oprogramowanie na wielu komputerach, bez interwencji użytkownika. Użyteczne są również dla programistów, którzy chcą załączyć inny instalator do swojego i wykonując go pobrać potrzebne dane, bez potrzeby pokazywania dwu instalatorów.

Instalatory oraz deinstalatory NSIS mogą być zarówno bezokienkowe jak i okienkowe. Gdy instalator lub deinstalator działa w trybie cichym, nie wszystkie funkcje zwrotne są wywoływane. Funkcje .onGUIInit, .onGUIEnd oraz ich odpowiedniki w deinstalatorze, a także każda funkcja zwrotna powiązana z określoną stroną lub typem strony nie zostanie wywołana.

Istnieje kilka metod na sprawienie, by instalator lub deinstalator działał w trybie cichym:

  1. SilentInstall oraz SilentUninstall
  2. SetSilent
  3. Użycie przełącznika /S w linii poleceń (wielkość liter ma znaczenie)

Aby sprawdzić czy instalator/deinstalator działa w trybie cichym, użyj polecenia IfSilent.

Aby mieć pewność, że twój instalator działa w trybie cichym, powinieneś przed każdym poleceniem, które może wymagać interwencji użytkownika lub utworzenia okna sprawdzać wynik polecenia IfSilent. Polecenie MessageBox, które najczęściej powoduje problemy w instalatorach działających w trybie cichym, posiada przełącznik /SD, ustalający domyślną wartość odpowiedzi na zapytanie. Jeśli chcesz, aby twój instalator/deinstalator działał całkowicie w trybie cichym, powinieneś użyć tego przełącznika. Wszystkie wbudowane okna dialogowe komunikatów w NSIS mają przypisane domyślne wartości dla trybu cichych instalatorów. Przykład silent.nsi demonstruje wszystkie aspekty tego zagadnienia.

Jako że, strona wyboru katalogu nie jest wyświetlana w trybie cichych instalatorów, użytkownik ma możliwość określenia katalogu docelowego poprzez linię poleceń (opcja działa również w instalatorach/deinstalatorach w normalnym trybie okienkowym). Aby to zrobić, należy użyć przełącznika /D, jak pokazano w przykładzie:

foo.exe /S /D=C:\Program Files\Foo

Jeśli twój instalator/deinstalator wymaga więcej informacji, których nie można pobrać w trybie cichym, możesz umożliwić użytkownikowi określić te informacje poprzez linię poleceń i przetworzyć je w funkcji .onInit. Możesz użyć funkcji GetOptions.

!include FileFunc.nsh
!insertmacro GetParameters
!insertmacro GetOptions

Function .onInit
  ${GetParameters} $R0
  ClearErrors
  ${GetOptions} $R0 /USERNAME= $0
FunctionEnd

Powyższy przykład skopiuje wartość podaną przez użytkownika po parametrze /USERNAME= do zmiennej $0. Pozwala to na określenie wymaganych informacji w linii poleceń, zamiast używania interfejsu użytkownika. Użytkownik może użyć:

foo.exe /S /USERNAME=Bar /D=C:\Program Files\Foo

lub:

foo.exe /S /USERNAME=łańcuch znaków ze spacjami /D=C:\Program Files\Foo

lub:

foo.exe /S /USERNAME="łańcuch znaków ze spacjami" /D=C:\Program Files\Foo

Jeśli twój instalator/deinstalator wymaga podania większej ilości informacji i chcesz skorzystać z trybu cichego, powinieneś umożliwić użytkownikowi dostęp do pliku z odpowiedziami. Powinno być to bardziej wygodne, niż zapisywanie wszystkich tych informacji w linii poleceń.