dragonleo/NSIS
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

* PageEx - every page can be used everywhere and as many times as needed

Browse source 
* DirVar - easy way to add another dir page
* default strings in the language file (Page directory is enough, no need for DirText)
* strings from the language file are now LangStrings that can be used in the script
* no more /LANG - one string for all languages
* any lang strings can be used everywhere, installer or uninstaller (no un.)
* no more unprocessed strings - variables can be used almost everywhere (except in licenseData and InstallDirRegKey)
* DirText parm for browse dialog text
* SetBkColor -> SetCtlColors - can now set text color too
* fixed SetOutPath and File /r bug
* fixed File /a /oname bug
* added $_CLICK for pages
* added quotes support in lang files (patch #752620)
* extraction progress
* separate RTL dialogs for RTL langs (improved RTL too)
* InstallOptions RTL
* StartMenu RTL
* fixed RegDLL?
* added IfSilent and SetSilent (SetSilent only works from .onInit)
* fixed verify window (it never showed) (bug #792494)
* fixed ifnewer readonly file problem (patch #783782)
* fixed wininit.ini manipulation when there is another section after [rename]
* fixed some ClearType issues
* fixed a minor bug in the resource editor
* fixed !ifdef/!endif stuff, rewritten
* lots of code and comments clean ups
* got rid of some useless exceptions handling and STL classes (still much more to go)
* lots of optimizations, of course ;)
* updated system.dll with support for GUID, WCHAR, and fast VTable calling (i.e. COM ready)
* minor bug fixes


git-svn-id: https://svn.code.sf.net/p/nsis/code/NSIS/trunk@2823 212acab6-be3b-0410-9dea-997c60f758d6
This commit is contained in:
kichik 2003-09-04 18:25:57 +00:00
parent bb8879b7ae
commit 74ea2dc585
91 changed files with 5180 additions and 4101 deletions
Download patch file Download diff file Expand all files Collapse all files

48
Docs/src/attributes.but
View file

@ -32,13 +32,13 @@ Specifies whether or not to use a gradient background window. If 'off', the inst
\S2{abrandingtext} BrandingText
\c [/LANG=lang_id] /TRIM(LEFT|RIGHT|CENTER) text
\c /TRIM(LEFT|RIGHT|CENTER) text
Sets the text that is shown (by default it is 'Nullsoft Install System vX.XX') in the bottom of the install window. Setting this to an empty string ("") uses the default; to set the string to blank, use " " (a space). If it doesn't matter to you, leave it the default so that everybody can know why the installer didn't suck. heh. Use /TRIMLEFT, /TRIMRIGHT or /TRIMCENTER to trim down the size of the control to the size of the string.
\S2{acaption} Caption
\c [/LANG=lang_id] caption
\c caption
Sets what the titlebars of the installer will display. By default, it is 'Name Setup', where Name is specified with the \R{aname}{Name command}. You can, however, override it with 'MyApp Installer' or whatever. If you specify an empty string (""), the default will be used (you can however specify " " to achieve a blank string)
@ -72,13 +72,13 @@ This bitmap should have a size of 96x16 pixels, no more than 8bpp (256 colors) a
\S2{acompletedtext} CompletedText
\c [/LANG=lang_id] Completed text
\c Completed text
Replaces the default text ("Completed") that is printed at the end of the install if parameter is specified. Otherwise, the default is used.
\S2{acomponenttext} ComponentText
\c [[/LANG=lang_id] text [subtext] [subtext2]]
\c [text [subtext] [subtext2]]
Specifies a string that is above the component list. This can be something that notifies the user what it is they are actually installing. Note that if no parameter is specified, or if the ComponentText command is omitted, then the component page will not be visible, and all of the sections will be installed. Note: if text is specified and non-empty and you leave subtext or subtext2 empty, the defaults will be used (to set one to blank, use a string like " "). empty strings mean default on subtext and subtext2. Likewise, if you wish to enable the component page, but don't want any text on the top line, set text to " ".
@ -90,7 +90,7 @@ Specifies whether or not the installer will perform a CRC on itself before allow
\S2{adetailsbuttontext} DetailsButtonText
\c [/LANG=lang_id] show details text
\c show details text
Replaces the default details button text of "Show details", if parameter is specified (otherwise the default is used).
@ -102,13 +102,19 @@ Specifies whether or not the user will see the directory selection page. Note th
\S2{adirtext} DirText
\c [[/LANG=lang_id] text [subtext] [browse text]]
\c [text] [subtext] [browse_button_text] [browse_dlg_text]
Specifies a string that is above the directory selection area. If this command is not specified, or no parameter is specified, then the directory page is never visible to the user (even if DirShow show is specified). If subtext is specified and not empty, it overrides the default text above the path entry box ("Select the directory to install MyApp in:"). If browse button text is specified but not empty, it overrides the default browse button text ("Browse...").
\S2{adirvar} DirVar
\c user_var(dir input/output)
Specifies which variable is to be used to contain the directory selected. This variable should contain the default value too. This allows to easily create two different directory pages that will not require you to move values in and out of $INSTDIR. The default variable is $INSTDIR. This can only be used in \R{pageex}{PageEx} and for directory and uninstConfirm pages.
\S2{a} FileErrorText
\c [/LANG=lang_id] file error text
\c file error text
Replaces the default text that comes up when a file cannot be written to. This string can contain a reference to $0, which is the filename ($0 is temporarily changed to this value). Example: "Can not write to file $\\r$\\n$0$\\r$\\ngood luck, bitch.".
@ -120,7 +126,7 @@ Sets the icon of the installer. Every icon in the icon file will be included in
\S2{ainstallbuttontext} InstallButtonText
\c [/LANG=lang_id] install button text
\c install button text
If parameter is specified, overrides the default install button text (of "Install") with the specified text.
@ -150,7 +156,7 @@ Valid values for flag are "smooth" (smooth the progress bar) or "colored" (color
\S2{ainsttype} InstType
\c install_type_name | /NOCUSTOM | ([/LANG=lang_id] /CUSTOMSTRING=str) | /COMPONENTSONLYONCUSTOM
\c install_type_name | /NOCUSTOM | /CUSTOMSTRING=str | /COMPONENTSONLYONCUSTOM
Adds an install type to the install type list, or disables the custom install type. There can be as many as 32 types, each one specifying the name of the install. Instead of an "hard-coded" name you can use User Variables which are processed at Runtime. This allows you to change InstType name dynamically. Another way of changing the InstType name during runtime is the \R{sinsttypesettext}{InstTypeSetText} command. The difference is that with InstTypeSetText you are saving your precious user variables. The first type is the default (generally 'Typical'). Each type is numbered, starting at 1. See SectionIn for information on how those numbers are used. If the /NOCUSTOM switch is specified, then the "custom" install type is disabled, and the user has to choose one of the pre-defined install types. Alternatively, if the /CUSTOMSTRING switch is specified, the parameter will override the "Custom" install type text. Alternatively, if the /COMPONENTSONLYONCUSTOM flag is specified, the component list will only be show
n if the "Custom" install type is selected.
@ -163,33 +169,33 @@ Sets the background color of the license data. Color is specified using the form
\S2{alicensedata} LicenseData
\c [/LANG=lang_id] licdata.(txt|rtf)
\c licdata.(txt|rtf)
Specifies a text file or a RTF file to use for the license that the user can read. Omit this to not have a license displayed. Note that the file must be in the evil DOS text format (\\r\\n, yeah!)
Specifies a text file or a RTF file to use for the license that the user can read. Omit this to not have a license displayed. Note that the file must be in the evil DOS text format (\\r\\n, yeah!). To define a multilingual license data use \R{licenselangstring}{LicenseLangString}.
If you make your license file a RTF file it is recommended you edit it with WordPad and not MS Word. Using WordPad will result in a much smaller file.
\S2{alicenseforceselection} LicenseForceSelection
\c [/LANG=lang_id] (checkbox [accept_text] | radiobuttons [accept_text] [decline_text] | \\<b\\>off\\</b\\>)
\c (checkbox [accept_text] | radiobuttons [accept_text] [decline_text] | \\<b\\>off\\</b\\>)
Specifies if the displayed license must be accept explicit or not. This can be done either by a checkbox or by radiobuttons. By default the "next button" is disabled and will only be enabled if the checkbox is enabled or the right radio button is selected. If off is specified the "next button" is enabled by default.
\S2{alicensetext} LicenseText
\c [[/LANG=lang_id] text [button_text]]
\c [text [button_text]]
Specifies a string that is above the license text. Omit this to not have a license displayed. If button_text is specified, it will override the default button text of "I Agree".
\S2{amiscbuttontext} MiscButtonText
\c [[/LANG=lang_id] back button text [next button text] [cancel button text] [close button text]]
\c [back button text [next button text] [cancel button text] [close button text]]
Replaces the default text strings for the four buttons (< Back, Next >, Cancel and Close). If parameters are omitted, the defaults are used.
\S2{aname} Name
\c [/LANG=lang_id] name
\c name
Sets the name of the installer. The name is usually simply the product name such as 'MyApp' or 'CrapSoft MyApp'.
@ -231,25 +237,25 @@ Specifies whether or not the uninstaller should be silent. If it is 'silent' or
\S2{aspacetexts} SpaceTexts
\c [[/LANG=lang_id] req text [avail text]]
\c [req text [avail text]]
If parameters are specified, overrides the space required and space available text ("Space required: " and "Space available: " by default). If 'none' is specified as the required text no space texts will be shown.
\S2{asubcaption} SubCaption
\c [[/LANG=lang_id] page_number subcaption]
\c [page_number subcaption]
Overrides the subcaptions for each of the installer pages (0=": License Agreement",1=": Installation Options",2=": Installation Directory", 3=": Installing Files", 4=": Completed"). If you specify an empty string (""), the default will be used (you can however specify " " to achieve a blank string)
\S2{auninstallbuttontext} UninstallButtonText
\c [/LANG=lang_id] button text
\c button text
Changes the text of the button that by default says "Uninstall" in the uninstaller. If no parameter is specified, the default text is used. See also \R{WriteUninstaller}{WriteUninstaller} (replaces UninstallEXEName).
\S2{auninstallcaption} UninstallCaption
\c [/LANG=lang_id] caption
\c caption
Sets what the titlebars of the uninstaller will display. By default, it is 'Name Uninstall', where Name is specified with the Name command. You can, however, override it with 'MyApp uninstaller' or whatever. If you specify an empty string (""), the default will be used (you can however specify " " to achieve a blank string)
@ -261,13 +267,13 @@ Sets the icon of the uninstaller. This icon file \e{must} have the exact same st
\S2{auninstallsubcaption} UninstallSubCaption
\c [/LANG=lang_id] page_number subcaption
\c page_number subcaption
Overrides the subcaptions for each of the uninstaller pages (0=": Confirmation",1=": Uninstalling Files",2=": Completed"). If you specify an empty string (""), the default will be used (you can however specify " " to achieve a blank string)
\S2{auninstalltext} UninstallText
\c [/LANG=lang_id] text [subtext]
\c text [subtext]
Specifies the text on the first page of the uninstaller. If subtext is specified and not empty, it will replace the default secondary text on that page, "Uninstall from:".

3
Docs/src/callback.but
View file

@ -17,7 +17,8 @@ Example:
\c GetDlgItem $R0 $HWNDPARENT 1028
\c CreateFont $R1 "Tahoma" 10 700
\c SendMessage $R0 ${WM_SETFONT} $R1 0
\c SetBkColor $R0 0x00FFFFFF
\c # set background color to white and text color to red
\c SetCtlColors $R0 FFFFFF FF0000
\c FunctionEnd
\S3{oninit} .onInit

6
Docs/src/flowcontrol.but
View file

@ -69,6 +69,12 @@ Checks for existence of file(s) file_to_check_for (which can be a wildcard, or a
Checks the reboot flag, and jumps to jump_if_set if the reboot flag is set, otherwise jumps to jump_if_not_set. The reboot flag can be set by Delete and Rename, or manually with SetRebootFlag.
\S2{ifsilent} IfSilent
\c [jump_if_silent] [jump_if_not]
Checks the silent flag, and jumps to jump_if_silent if the installer is silent, otherwise jumps to jump_if_not. The silent flag can be set by \R{asilentinstall}{SilentInstall}, \R{asilentuninstall}{SilentUninstall}, \R{setsilent}{SetSilent} and by the user passing /S on the command line.
\S2{intcmp} IntCmp
\c val1 val2 jump_if_equal [jump_if_val1_less] [jump_if_val1_more]

28
Docs/src/history.but
View file

@ -5,6 +5,10 @@
\b User variables ($VARNAME) that can be declared with the \R{var}{Var} command
\b Added \R{pageex}{PageEx}, \R{pagecallbacks}{PageCallbacks} and \R{adirvar}{DirVar} - it's now a lot easier to add the same page type twice
\b Extraction progress
\b \W{../Contrib/Modern UI/Readme.html}{Modern UI 1.65}: Easier page macro system, language specific fonts, \R{alicenseforceselection}{LicenseForceSelection} support, new options for Finish page / language selection dialog, fixes, more
\b Added \R{asetallowskipfiles}{AllowSkipFiles}: Set whether the user should be able to skip a file when overwriting failed
@ -15,7 +19,19 @@
\b \W{../Contrib/Makensisw/Readme.txt}{MakeNSISW 2.0}: UI to define symbols, toolbar, more
\b NLF language files (v5): More strings translatable (K/M/G Byte, registering, unregistering), language specific fonts
\b NLF language files (v6): language specific fonts, RTL and more strings
\b Full \R{rtl}{RTL} support (set in language file)
\b Inner LangStrings can be used in the script
\b No more /LANG, only LangStrings - easier to set one string to all languages
\b LangStrings are no longer installer/uninstaller specific (no un.)
\b No more unprocessed strings, variables can be used everywhere
\b Added \R{ifsilent}{IfSilent} and \R{setsilent}{SetSilent} to allow better /S interaction
\b /o Switch for \R{ssection}{Section} provides ability to unselect the section by default
@ -23,6 +39,10 @@
\b Added \R{ssectionsetsize}{SectionSetSize}, \R{ssectiongetsize}{SectionGetSize}, \R{ssetcurinsttype}{SetCurInstType}, \R{sgetcurinsttype}{GetCurInstType}
\b New parameter for DirText to set the browse dialog text
\b Better ClearType support
\b System Plug-in: Fixed a bug with calling proc(void) and added e switch to get GetLastError return value
\b Components Tree: Fixed problems with sub-sections with RO sections as children, SF_EXPAND now refreshes the components tree, Added SF_PSELECTED for partially selected sub-sections
@ -37,7 +57,7 @@
\b Added \R{rmdir}{RMDir /REBOOTOK}: Remove folders on reboot
\b Added \R{setbkcolor}{SetBkColor}: Background colors can be set for non-static controls, transparent background support
\b Added \R{setctlcolors}{SetCtlColors}: Sets background and text color for every dialog control
\b \R{ainsttype}{InstType} /NOCUSTOM and /COMPONENTSONLYONCUSTOM work together
@ -47,9 +67,9 @@
\b Fixed a problem regarding borders in Plug-ins BgImage and InstallOptions
\b Fixed plug-ins directory init function generation
\b Minor bug fixes
\b Fixed overlapping chars in directory input
\b Code clean-ups and some more comments
\\<b\\>Notes:\\</b\\>

67
Docs/src/langs.but
View file

@ -6,19 +6,17 @@
Loads a language file for the construction of a language table. All of the language files that come with NSIS are in \W{../Contrib/Language files}{Contrib\\Language Files}
For ease of use LoadLanguageFile defines $\{LANG_language_file\} as the language id. Use it with /LANG, LangString, LangStringUP, and LangDLL.
For ease of use LoadLanguageFile defines $\{LANG_language_file\} as the language id. Use it with \R{langstring}{LangString}, LangDLL and \R{viaddversionkey}{VIAddVersionKey}.
\S2{langstring} LangString and LangStringUP
\S2{langstring} LangString
\c [un.]name language_id string
\c name language_id string
Defines a multilingual string and spares the comparing of $LANGUAGE to every language you have in your installer for every string you use. This also allows you to make section names and install types multilingual. To use in the uninstaller make sure you name the string with the un. prefix before.
Defines a multilingual string. This means the its value will be different (or not, it's up to you) for every language. It allows you to easily make your installer multilingual without the need to add massive swithces to the script.
LangStrings can you only be used on their own. You can't include them in other strings. "look at my $(string)! isn't it beautiful?" will be seen exactly as written, $(string) will not be expanded. If you want to use LangStrings in other strings you can first copy the LangString to a variable and then use the variable wherever you want. This is a temporary situation, it will be changed before NSIS 2 final.
Each LangString has a name that identifies it and a value for each language used by the installer. To use a LangString you must know its name. LangStrings can be used in any runtime string in the script. To use a LangString all you need to add to the string is $(LangString_name_here) where you want the LangString to be inserted.
\\<b\\>Note #1:\\</b\\> Unlike defines that use curly braces - \{\}, multilingual strings use parenthesis - ().
\\<b\\>Note #2:\\</b\\> If you see weird characters between letters in the string when you use LangString, use LangStringUP (LangString for unprocessed string such as InstType)
\\<b\\>Note:\\</b\\> Unlike defines that use curly braces - \{\}, multilingual strings use parenthesis - ().
For example, instead of:
@ -35,53 +33,42 @@ Use:
\c LangString message ${LANG_FRENCH} "French message"
\c LangString message ${LANG_KOREAN} "Korean message"
\c
\c MessageBox MB_OK $(message)
\c MessageBox MB_OK "A translated message: $(message)"
\S2{licenselangstring} LicenseLangString
\c name lang_id license_path
Does the same as \R{langstring}{LangString} only it loads the string from a text/RTF file and defines a special LangString that can be used only by \R{alicensedata}{LicenseData}.
\S0{langs} Multiple Languages
As of version 2 NSIS fully supports multiple languages. An installer can have more than one language. Each string in the installer can be easily translated, and so can script strings such as messages in a message box.
As of version 2 NSIS fully supports multiple languages. An installer can have more than one language. Each string in the installer can be easily translated using \R{langstring}{LangStrings}.
Each installer has one or more language table which holds references to strings in the strings table. To create a language table all you need to do is use \R{loadlanguagefile}{LoadLanguageFile}, define strings used in your installer for that language such as Name and Caption, message box, install type, and other strings using \R{langstring}{LangString} or \R{langstring}{LangStringUP} and you have built your installer a language table.
Each installer has one or more language tables which hold references to strings in the strings table. To create a language table all you need to do is use that language. Either use \R{loadlanguagefile}{LoadLanguageFile} or define a \R{langstring}{LangString} and you have built your installer a language table. To make sure all of the inner strings NSIS uses are there you should load a language file using use \R{loadlanguagefile}{LoadLanguageFile}. The strings from the language file will be used as defaults in case you don't define some strings in the script. The language file strings can be used by the script too, not just internally by NSIS. Each string in the language file is assigned to a specific LangString. That LangString's name is listed as a comment just above the string in the English language file for your convenience. The language file is located in \W{../Contrib/Language files}{Contrib\\Language Files}.
For an example of usage see \W{../Examples/languages.nsi}{languages.nsi}.
\S1{langselection} Language Selection
When the installer starts up it goes through these stages to select the interface language:
When the installer starts up it goes through these steps to select the interface language:
\n Find a perfect match between the user default language (GetUserDefaultLangID())
\n Get user's default language (GetUserDefaultLangID()) into \R{varconstant}{$LANGUAGE}
\n Find a perfect match for the language id in \R{varconstant}{$LANGUAGE}
\n If there is no perfect match, find a primary language match
\n If no match, take the first language defined in the script
\n If there is no no match, use the first language defined in the script
\n If \R{varconstant}{$LANGUAGE} has changed during .onInit, go through steps 1 to 3 with the language inside $LANGUAGE instead of the default user language.
\S1{/lang} The /LANG Parameter
All of the installer (and uninstaller) attributes setting commands have an optional parameter /LANG. This parameter tells the script compiler in which language table to put the specified string.
For example:
\c Caption /LANG=${LANG_ENGLISH} "English caption"
\c Caption /LANG=${LANG_FRENCH} "French caption"
\c Caption /LANG=${LANG_DUTCH} "Dutch caption"
When the installer will select the English language the caption will be "English caption", when it selects French the caption will be "French caption" and when it selects Dutch the caption will be "Dutch caption".
If no /LANG parameter is specified, the compiler will assume the last used language, or the last loaded language.
\c LoadLanguageFile "${NSISDIR}\Language files\English.nlf"
\c Name "English name"
\c LoadLanguageFile "${NSISDIR}\Language files\German.nlf"
\c Name "German name"
\c Caption "German caption"
\c Caption /LANG=${LANG_ENGLISH} "English caption"
\c ComponentText "English components text"
\c ComponentText /LANG=${LANG_GERMAN} "German components text"
\n If \R{varconstant}{$LANGUAGE} has changed during .onInit, go through steps 2 to 4 again
\S1{langdll} LangDLL Plug-in
The LangDLL plug-in lets you give the user the option to choose the language of the installer. Just push the language id ($\{LANG_*\}) and its name for every language in your installer, then the number of languages pushed, the caption, and the text that tells the user to select the language, call the plug-in function named LangDialog, pop the returned value into $LANGUAGE and you're good to go. If the user click on the cancel button the return value will be "cancel".
The LangDLL plug-in allows you to give the user an option to choose the language of the installer. Just push the language id ($\{LANG_*\}) and its name for every language in your installer, then the number of languages pushed, the caption, and the text that tells the user to select the language, call the plug-in function named LangDialog, pop the returned value into $LANGUAGE and you're good to go. If the user clicks on the cancel button the return value will be "cancel".
For an example of usage see \W{../Examples/languages.nsi}{languages.nsi}.
For an example of usage see \W{../Examples/languages.nsi}{languages.nsi}.
\S1{rtl} RTL Languages
RTL languages are languages that are written from right to left. NSIS fully supports RTL languages. In the language file there is a place to specify if the language is RTL or not. If it is, NSIS will create another set of dialogs for the language that will be RTL. To find out on runtime if the language you're currently using is RTL or not check the value of the $(^RTL) language string. It will be 1 if the language is RTL and 0 otherwise.

102
Docs/src/pages.but
View file

@ -2,30 +2,74 @@
Each (non-silent) NSIS installer has a set of pages. Each page can be a NSIS built-in page or a custom page created by a user's function (with \W{../Contrib/InstallOptions/Readme.html}{InstallOptions} for example).
Using the script you can control the pages' order, appearance, and behavior. You can skip pages, paint them white, force the user to stay in a certain page until a certain condition is met, show a readme page, show custom designed pages for input and more. In this section, you will learn how to control all of the above.
There are two basic commands regarding pages, \R{page}{Page} and \R{uninstpage}{UninstPage}. The first adds a page to the installer, the second adds a page to the uninstaller. On top of those two there is the \R{pageex}{PageEx} command which allows you to add a page to either one and with greater amount of options. \R{pageex}{PageEx} allows you to set options to the specific page you are adding instead of using the default that's set outside of \R{pageex}{PageEx}.
\S{pageoreder} Ordering
The page order is set simply by the order they are in the script. For example:
The page order is set simply by the order \R{page}{Page}, \R{uninstpage}{UninstPage} and \R{pageex}{PageEx} appear in the script. For example:
\c Page license
\c Page components
\c Page directory
\c Page instfiles
\c UninstPage uninstConfirm
\c UninstPage isntfiles
This code will show the license page, then the components selection page, then the directory selection page and then the install log, just like in old installers.
This code will tell NSIS to first show the license page, then the components selection page, then the directory selection page and finally the install log where sections are executed, just like in old installers. The uninstaller will first show the uninstall confirmation page and then the uninstallation log.
You can specify the same page type more than once, just make sure you know what you are doing.
You can specify the same page type more than once.
Please note that you must still use \R{alicensetext}{LicenseText} and \R{alicensedata}{LicenseData} for the license page to show, \R{acomponenttext}{ComponentText} for the components selection page to show and \R{adirtext}{DirText} for the directory page to show.
If you don't use any page command the installer's pages order will be just as in older versions: license (if \R{alicensetext}{LicenseText} and \R{alicensedata}{LicenseData} were specified), components (if \R{acomponenttext}{ComponentText} was specified and there is more than one visible section), directory (if \R{adirtext}{DirText} was specified) and instfiles. The uninstaller's pages order will be: uninstall confirmation page (if \R{auninstalltext}{UninstallText} was specified) and instfiles.
If you don't use any Page command the installer pages order will be just as in older version: license (if \R{alicensetext}{LicenseText} and \R{alicensedata}{LicenseData} were specified), components (if \R{acomponenttext}{ComponentText} was specified and there is more than one visible section), directory (if \R{adirtext}{DirText} was specified), instfiles.
\S{pageoptions} Page Options
\S{pagecallbacks} Callbacks
Each page has its unique set of data that defines how it will look and act. This section describes what data each type of page uses and how you can set it. \R{pagecallbacks_explain}{Callback functions} are described below and are not dealt with in this section.
Each built-in page has three callback functions. The pre-function, the show-creation function and the leave-function. The pre-function is called right before the page is created, the show-function is called right after it is created and before it is shown so you can tweak its user interface with \R{createfont}{CreateFont}, \R{setbkcolor}{SetBkColor } and \R{sendmessage}{SendMessage}; the leave-function is called right after the user has pressed the next button and before the page is left.
The list below lists what commands affect the certain page type. Unless mentioned otherwise, these commands can be used both in and out of a \R{pageex}{PageEx} block. If used inside a \R{pageex}{PageEx} block they will only affect the current page being set by \R{pageex}{PageEx}, else they will set the default for every other page.
A custom page has only two callback functions, one that creates it which is mandatory, and one leave-function that acts just like the leave-function for built-in pages.
\e{License page}
Use \R{abort}{Abort} from a built-in page's pre-function to skip the page, and from a built-in page's leave-function to stay in the page.
\b \R{alicensetext}{LicenseText}
\b \R{alicensedata}{LicenseData}
\b \R{alicenseforceselection}{LicenseForceSelection}
\e{Components selection page}
\b \R{acomponenttext}{ComponentText}
\e{Directory selection page}
\b \R{adirtext}{DirText}
\b \R{adirvar}{DirVar} - can only be used in \R{pageex}{PageEx}
\e{Un/Installation log page}
\b \R{adetailsbuttontext}{DetailsButtonText}
\b \R{acompletedtext}{CompletedText}
\e{Uninstall confirmation page}
\b \R{adirvar}{DirVar} - can only be used in \R{pageex}{PageEx}
\b \R{auninstalltext}{UninstallText}
\S{pagecallbacks_explain} Callbacks
Each built-in page has three callback functions. The pre-function, the show-creation function and the leave-function. The pre-function is called right before the page is created, the show-function is called right after it is created and before it is shown and the leave-function is called right after the user has pressed the next button and before the page is left.
\b The pre-function allows you to skip the page using \R{abort}{Abort}.
\b The show-function allows you to tweak the page's user interface with \R{createfont}{CreateFont}, \R{setctlcolors}{SetCtlColors}, \R{sendmessage}{SendMessage} and others.
\b The leave-function allows you to force the user to stay on the current page using \R{abort}{Abort}.
A custom page only has two callback functions, one that creates it which is mandatory, and one leave-function that acts just like the leave-function for built-in pages.
Examples:
@ -59,12 +103,44 @@ Examples:
\S{page} Page
\c ((custom [creator_function] [leave_function] [caption]) | ((license|components|directory|instfiles) [pre_function] [show_function] [leave_function])) [define_if_last]
\c custom [creator_function] [leave_function] [caption]
\c OR
\c (license|components|directory|instfiles|uninstConfirm) [pre_function] [show_function] [leave_function]
Adds an installer page. See the above sections for more information about built-in versus custom pages and about callback functions. If define_if_last is specified, the parameter will be !defined if the page turns out to be the last page before a instfiles page. This helps you decide on dynamic scripts (such as the \W{../contrib/Modern UI/Readme.html}{Modern UI script}) what to put in this page's text, "click the install button to start installation" or "click next to continue" for example.
Adds an installer page. See the above sections for more information about built-in versus custom pages and about callback functions.
\S{uninstpage} UninstPage
\c ((custom [creator_function] [leave_function] [caption]) | ((uninstConfirm|instfiles) [pre_function] [show_function] [leave_function])) [define_if_last]
\c custom [creator_function] [leave_function] [caption]
\c OR
\c (license|components|directory|instfiles|uninstConfirm) [pre_function] [show_function] [leave_function]
Adds an uninstaller page. See the above sections for more information about built-in versus custom pages and about callback functions. See Page for an explanation about define_if_last.
Adds an uninstaller page. See the above sections for more information about built-in versus custom pages and about callback functions.
\S{pageex} PageEx
\c [un.](custom|uninstConfirm|license|components|directory|instfiles)
Adds an installer page or an uninstaller page if the un. prefix was used. Every PageEx must have a matching \R{pageexend}{PageExEnd}. In a PageEx block you can set options that are specific to this page and will not be used for other pages. Options that are not set will revert to what was set outside the PageEx block or the default if nothing was set. To set the callback functions for a page set with PageEx use \R{pagecallbacks}{PageCallbacks}. See the above sections for more information about built-in versus custom pages.
Example usage:
\c PageEx license
\c LicenseText "Readme"
\c LicenseData readme.rtf
\c PageExEnd
\c
\c PageEx license
\c LicenseData license.txt
\c LicenseForceSelection checkbox
\c PageExEnd
\S{pageexend} PageExEnd
Ends a PageEx block.
\S{pagecallbacks} PageCallbacks
\c ([creator_function] [leave_function]) | ([pre_function] [show_function] [leave_function])
Sets the callback functions for a page defined using \R{pageex}{PageEx}. Can only be used inside a \R{pageex}{PageEx} block. See the above sections for more information about callback functions.

19
Docs/src/tutorial.but
View file

@ -27,16 +27,27 @@ The default extension for a script file is .nsi. Header files have the .nsh exte
\H{tutstructure} Scripting structure
A NSIS script can contain Installer Attributes and Sections/Functions. You can also use Compiler Commands for compile-time operations. The minimum is \R{aoutfile}{OutFile}, which tells NSIS where to write the installer, and one section.
A NSIS script can contain Installer Attributes and Sections/Functions. You can also use Compiler Commands for compile-time operations. Required is the \R{aoutfile}{OutFile} instruction, which tells NSIS where to write the installer, and one section.
\S1{installerattributes} Installer Attributes
Installer Attributes determine the behavior and the look and feel of your installer. With these attributes you can define what pages are shown in which order, texts that will be shown during the installation, the number of installation types etc. Most of these commands can only be set and are not changeable during runtime.
Installer Attributes determine the behavior and the look and feel of your installer. With these attributes you can change texts that will be shown during the installation, the number of installation types etc. Most of these commands can only be set and are not changeable during runtime.
The most basic attributes are \R{aname}{Name}, \R{ainstalldir}{InstallDir} and \R{adirtext}{DirText}.
Other basic instructions are \R{aname}{Name} and \R{ainstalldir}{InstallDir}.
For more information about installer attributes, have a look at \R{instattribs}{Installer Attributes}.
\S1{tut-pages} Pages
An non-silent installer has a set of wizard pages to let the user configure the installer. You can set which pages to display using the \R{page}{Page} command (or \R{pageex}{PageEx} for more advanced settings). A typical set of pages looks like this:
\c Page license
\c Page components
\c Page directory
\c Page instfiles
\c UninstPage uninstConfirm
\c UninstPage isntfiles
\S1{tut-sections} Sections
In a common installer there are several things the user can install. For example in the NSIS distribution installer you can choose to install the source code, additional plug-ins, examples and more. Each of these components has its own piece of code. If the user selects to install this component, then the installer will execute that code. In the script, that code is in sections. Each visible section is a component for the user to choose from. We will not discuss invisible sections in this tutorial. It is possible to build your installer with only one section, but if you want to use the components page and let the user choose what to install you'll have to use more than one section.
@ -119,7 +130,7 @@ After calling the function, the variables contain the same value as before. Note
\S2{tutdebug} Debugging Scripts
The more you work with NSIS the more complex the scripts will become. This will increase the potential of mistakes, especially when dealing with lots of variables. There are a few possibilities to help you debuging the code. To display the contents of variables you should use \R{messagebox}{MessageBoxes} or \R{detailprint}{DetailPrint}. To get a brief overview about all variables you should use the plugin \W{http://nsis.sourceforge.net/archive/viewpage.php?pageid=140}{Dumpstate}. By default all actions of the Installer are printed out in the Log Window. You can access the log if you right-click in the Log Window and select "Copy Details To Clipboard". There is also a way to write it directly to a file. See \R{dumplogtofile}{here}. Very useful if you force to close the installer automatically using \R{setautoclose}{SetAutoClose}.
The more you work with NSIS the more complex the scripts will become. This will increase the potential of mistakes, especially when dealing with lots of variables. There are a few possibilities to help you debuging the code. To display the contents of variables you should use \R{messagebox}{MessageBoxes} or \R{detailprint}{DetailPrint}. To get a brief overview about all variables you should use the plugin \W{http://nsis.sourceforge.net/archive/viewpage.php?pageid=140}{Dumpstate}. By default all actions of the Installer are printed out in the Log Window. You can access the log if you right-click in the Log Window and select "Copy Details To Clipboard". There is also a way to write it directly to a file, see \R{dumplogtofile}{here}.
\S1{compilercommands} Compiler Commands

14
Docs/src/ui.but
View file

@ -86,11 +86,19 @@ Shows or hides the details, depending on which parameter you pass. Overrides the
Sets mode at which commands print their status. None has commands be quiet, listonly has status text only added to the listbox, textonly has status text only printed to the status bar, and both enables both (the default). For extracting many small files, textonly is recommended (especially on win9x with smooth scrolling enabled).
\S2{setbkcolor} SetBkColor
\S2{setctlcolors} SetCtlColors
\c hwnd color
\c hwnd (branding | (text_color (transparent|bg_color)))
Sets a background color for a static control, edit control, button or a dialog. Use GetDlgItem to get the handle (HWND) of the control. To make the control transparent specify "transparent" as the color value. \e{Do not} use this on branding image controls!
Sets a background color and the text color for a static control, edit control, button or a dialog. Use GetDlgItem to get the handle (HWND) of the control. To make the control transparent specify "transparent" as the background color value. You can also specify branding instead of text color and background color to make the control completely gray. This is used by the branding text control in the MUI.
\S2{setsilent} SetSilent
\c silent | normal
Sets the installer to silent mode or normal mode. See \R{asilentinstall}{SilentInstall} for more information about silent installations. Can only be used in \R{oninit}{.onInit}.
Sets the installer
\S2{showwindow} ShowWindow