updated outdated stuff, pages / plug-in calls / multiple languages improved, red defaults, fixes
git-svn-id: https://svn.code.sf.net/p/nsis/code/NSIS/trunk@3150 212acab6-be3b-0410-9dea-997c60f758d6
This commit is contained in:
joostverburg
parent
b0d4888c3a
commit
1026f26b40
6 changed files with 71 additions and 40 deletions
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
The commands below all adjust attributes of the installer. These attributes control how the installer looks and functions, including which pages are present in the installer, as what text is displayed in each part of each page, how the installer is named, what icon the installer uses, the default installation directory, what file it writes out, and more. Note that these attributes can be set anywhere in the file except in a Section or Function. With the exception of InstallDir, none of these attributes allow use of Variables other than $\\r and $\\n in their strings.
|
||||
|
||||
\\<b\\>Defaults are bold\\</b\\>
|
||||
\\<span style='color: red;'\\>Defaults are red\\</span\\>
|
||||
|
||||
\S2{aaddbrandingimage} AddBrandingImage
|
||||
|
||||
|
|
@ -40,9 +40,9 @@ Sets the text that is shown (by default it is 'Nullsoft Install System vX.XX') i
|
|||
|
||||
\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).
|
||||
When used outside a \R{pageex}{PageEx} block: Sets the text for the titlebar of the installer. the By default, it is 'Name Setup', where Name is specified with the \R{aname}{Name} instruction. 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).
|
||||
|
||||
If used inside a \R{pageex}{PageEx} block, it sets the caption for the page.
|
||||
When used inside a \R{pageex}{PageEx} block: Sets the subcaption of the current page.
|
||||
|
||||
\S2{achangeui} ChangeUI
|
||||
|
||||
|
|
@ -82,7 +82,15 @@ Replaces the default text ("Completed") that is printed at the end of the instal
|
|||
|
||||
\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 " ".
|
||||
Specifies texts on the component page.
|
||||
|
||||
text: Text above the controls
|
||||
|
||||
subtext: Text next to the installation type selection
|
||||
|
||||
subtext2: Text next to the components list.
|
||||
|
||||
The default will be used if a string is empty ("").
|
||||
|
||||
\S2{acrccheck} CRCCheck
|
||||
|
||||
|
|
@ -96,17 +104,21 @@ Specifies whether or not the installer will perform a CRC on itself before allow
|
|||
|
||||
Replaces the default details button text of "Show details", if parameter is specified (otherwise the default is used).
|
||||
|
||||
\S2{adirshow} DirShow
|
||||
|
||||
\c \\<b\\>show\\</b\\>|hide
|
||||
|
||||
Specifies whether or not the user will see the directory selection page. Note that if 'hide' is specified, the installer will still check the validity of the installation path (using internal logic and .onVerifyInstDir if it is declared). If the path is deemed invalid, the directory page will be shown. To completely disable the Directory page (and install without prompting, even if a valid installation path is not available), specify DirText with no parameter (this might be useful if the installer installs everything into $SYSDIR or something like that).
|
||||
|
||||
\S2{adirtext} DirText
|
||||
|
||||
\c [text] [subtext] [browse_button_text] [browse_dlg_text]
|
||||
|
||||
Atleast the first parameter is required. 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). Subtext overrides the default text above the path entry box ("Select the directory to install MyApp in:"). Browse_button_text overrides the default browse button text ("Browse...").
|
||||
Specifies texts on the directory page.
|
||||
|
||||
text: Text above the controls
|
||||
|
||||
subtext: Text on the directory selection frame
|
||||
|
||||
browse_button_text: Text on the Browse button
|
||||
|
||||
browse_dlg_text: Text on the "Browse For Folder" dialog.
|
||||
|
||||
The default will be used if a string is empty ("").
|
||||
|
||||
\S2{adirvar} DirVar
|
||||
|
||||
|
|
@ -187,7 +199,13 @@ Specifies if the displayed license must be accept explicit or not. This can be d
|
|||
|
||||
\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".
|
||||
Specifies texts on the license page.
|
||||
|
||||
text: Text above the controls.
|
||||
|
||||
browse_button_text: Text on the "I Agree" button.
|
||||
|
||||
The default will be used if a string is empty ("").
|
||||
|
||||
\S2{amiscbuttontext} MiscButtonText
|
||||
|
||||
|
|
@ -247,7 +265,9 @@ If parameters are specified, overrides the space required and space available te
|
|||
|
||||
\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)
|
||||
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).
|
||||
|
||||
You can also set a subcaption (or override the default) using \R{acaption}{Caption} inside a \R{pageex}{PageEx} block.
|
||||
|
||||
\S2{auninstallbuttontext} UninstallButtonText
|
||||
|
||||
|
|
@ -271,13 +291,19 @@ Sets the icon of the uninstaller. This icon file \e{must} have the exact same st
|
|||
|
||||
\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)
|
||||
Sets the default subcaptions for 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).
|
||||
|
||||
You can also set a subcaption (or override the default) using \R{acaption}{Caption} inside a \R{pageex}{PageEx} block.
|
||||
|
||||
\S2{auninstalltext} UninstallText
|
||||
|
||||
\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:".
|
||||
Specifies the texts on the uninstaller confirm page.
|
||||
|
||||
text: Text above the controls
|
||||
|
||||
subtext: Text next to the uninstall location
|
||||
|
||||
\S2{awindowicon} WindowIcon
|
||||
|
||||
|
|
@ -289,5 +315,5 @@ Sets whether or not the installer's icon is being displayed.
|
|||
|
||||
\c on|\\<b\\>off\\</b\\>
|
||||
|
||||
Sets whether or not an XP manifest will be added to the installer. This affects the uninstaller too.
|
||||
Sets whether or not an XP manifest will be added to the installer. An XP manifest makes the installer controls use the new XP style when running on Windows XP. This affects the uninstaller too.
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
\c dllfile [/NOUNLOAD] function_name
|
||||
|
||||
Calls a function_name inside a NSIS extension DLL. See Contrib\\ExDLL for an example of how to make one. Extension DLLs can access the stack and variables. Use /NOUNLOAD to force the installer to leave the DLL loaded.
|
||||
Calls a function_name inside a NSIS extension DLL. See Contrib\\ExDLL for an example of how to make one. Extension DLLs can access the stack and variables. Use /NOUNLOAD to force the installer to leave the DLL loaded. Note: To automatically extract and call plug-in DLLs, use a plug-in command instead of CallInstDLL.
|
||||
|
||||
\S2{copyfiles} CopyFiles
|
||||
|
||||
|
|
|
|||
|
|
@ -43,25 +43,31 @@ Does the same as \R{langstring}{LangString} only it loads the string from a text
|
|||
|
||||
\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 using \R{langstring}{LangStrings}.
|
||||
As of version 2 NSIS fully supports multiple languages. The interface of one installer can support multiple languages.
|
||||
|
||||
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 \L{../Contrib/Language files}{Contrib\\Language Files}.
|
||||
Use \R{loadlanguagefile}{LoadLanguageFile} for every langauge to load the default interface texts and language properties.
|
||||
|
||||
For an example of usage see \L{../Examples/languages.nsi}{languages.nsi}.
|
||||
The default interface texts can easily be changed using instructions like \R{acomponenttext}{ComponentText} etc.
|
||||
|
||||
You can also use the contents of the standard language strings in your own strings (for example, $(^Name) contains the installer's name set using the \R{aname}{Name} instruction). The names of all standard langauges strings are listed as comments just above the strings in the language files. The language files are located in \L{../Contrib/Language files}{Contrib\\Language Files}.
|
||||
|
||||
To create your own langauge strings, use \R{langstring}{LangString}.
|
||||
|
||||
For an example of an installer with multiple langauges, see \L{../Examples/languages.nsi}{languages.nsi}.
|
||||
|
||||
\S1{langselection} Language Selection
|
||||
|
||||
When the installer starts up it goes through these steps to select the interface language:
|
||||
|
||||
\n Get user's default language (GetUserDefaultLangID()) into \R{varconstant}{$LANGUAGE}
|
||||
\n Get user's default Windows language
|
||||
|
||||
\n Find a perfect match for the language id in \R{varconstant}{$LANGUAGE}
|
||||
\n Find a perfect match for the default langauge
|
||||
|
||||
\n If there is no perfect match, find a primary language match
|
||||
|
||||
\n If there is no match, use the first language defined in the script
|
||||
\n If there is no match, use the first language defined in the script (make sure your first language is a common one like English)
|
||||
|
||||
\n If \R{varconstant}{$LANGUAGE} has changed during .onInit, go through steps 2 to 4 again
|
||||
\n If the langauge variable \R{varconstant}{$LANGUAGE} has changed during .onInit, NSIS goes through steps 2 to 4 again.
|
||||
|
||||
\S1{langdll} LangDLL Plug-in
|
||||
|
||||
|
|
@ -71,4 +77,4 @@ For an example of usage see \L{../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.
|
||||
RTL languages are languages that are written from the right to the left (like Arabic and Hebrew). NSIS fully supports RTL languages. In the language file there is a place to specify if the language is RTL or not. To find out on runtime if the the current langaugeis RTL or not check the value of the $(^RTL) language string. It will be 1 if the language is RTL and 0 otherwise. This can be useful when using plug-ins that create dialogs, they usually have RTL settings too.
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ This code will tell NSIS to first show the license page, then the components sel
|
|||
|
||||
You can specify the same page type more than once.
|
||||
|
||||
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.
|
||||
For backwards compatibility with old NSIS scripts, the following installer pages will be added if no installer page commands are used: 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. When there are no uninstaller page commands, the following uninstaller pages will be added: uninstall confirmation page (if \R{auninstalltext}{UninstallText} was specified) and instfiles. This method is deprecated, converting scripts to use page commands is highly recommended because you can use the new standard language strings.
|
||||
|
||||
\S{pageoptions} Page Options
|
||||
|
||||
|
|
|
|||
|
|
@ -4,28 +4,24 @@ The abilities of the NSIS scripting language can be extended by utilising functi
|
|||
|
||||
When the NSIS compiler starts it scans the plugins directory for DLLs and makes a list of the plugins found and their exported functions. During compilation if a sequence such as fred::flintstone is encountered where the compiler expected to find a language keyword the compiler will look through this list. If a list entry specifies that fred.dll exports function flintstone NSIS will pack the fred.dll file into the created installer binary.
|
||||
|
||||
During execution of the created installer if a plugin command is executed NSIS will unpack the necessary DLL to the $TEMP directory, push all of the arguments specified (right-to-left order), and then execute the DLL function. If the /NOUNLOAD option is specified the DLL will not be unloaded until the installer exits or the next time you use the DLL without /NOUNLOAD. Please note that the last call to the plugin must not have the /NOUNLOAD flag or the plugin will not be deleted from $PLUGINSDIR, thus garbage will be left on the user's machine.
|
||||
During execution of a plugin command NSIS will unpack the necessary DLL to a temporary folder ($PLUGINSDIR), push all of the arguments specified (right-to-left order), and then execute the DLL function. If the /NOUNLOAD option is specified the DLL will not be unloaded until the installer exits or the next time you use the DLL without /NOUNLOAD. Please note that the last call to the plugin must not have the /NOUNLOAD flag or the plugin will not be deleted from $PLUGINSDIR, thus garbage will be left on the user's machine.
|
||||
|
||||
\S1{usingplug} Using Plugin Commands
|
||||
|
||||
The following two examples both invoke the same plugin command. The first example shows the (still okay) syntax that scripts written for versions of NSIS earlier than 2.0a4 had to use, and the second is how it can be scripted more succinctly now. The newer syntax automatically handles packing & extraction of the DLL file, and stacks up arguments for you too.
|
||||
A plug-in call looks like this:
|
||||
|
||||
\c ; Pre 2.0a4 syntax
|
||||
\c SetOutPath $TEMP
|
||||
\c GetTempFileName $8
|
||||
\c File /oname=$8 InstallOptions.dll
|
||||
\c Push "ini_file_location.ini"
|
||||
\c CallInstDLL dialog
|
||||
|
||||
\c ; Newer syntax
|
||||
\c InstallOptions::dialog "ini_file_location.ini"
|
||||
|
||||
InstallOptions needs the name of it's ini file as a parameter to the dialog function so it has to be pushed onto the stack before the dialog call is made. Some plugin commands may not need any parameters on the stack, others might require two or three. To use a plugin command you will need to read the documentation for the plugin so that you know what parameters it's functions require, if any.
|
||||
All parameters are pushed onto the stack (in this case, the plug-in function only needs one parameter). Some plugin commands may not need any parameters on the stack, others might require more of them. To use a plug-in command you will need to read the documentation for the plug-in so that you know what parameters its functions require.
|
||||
|
||||
\S1{disablingplug} Disabling Plugin Unloading
|
||||
|
||||
CallInstDLL has an option not to unload the DLL after usage. To use it with the newer plugin command syntax just specify the first parameter as /NOUNLOAD. For example:
|
||||
If you don't want to unload the DLL after calling a function, use /NOUNLOAD as the first parameter. For example:
|
||||
|
||||
\c InstallOptions::dialog /NOUNLOAD "ini_file_location.ini"
|
||||
\c dll:function /NOUNLOAD "param"
|
||||
|
||||
You can also use \R{setpluginunload}{SetPluginUnload} alwaysoff to avoid writing /NOUNLOAD each and every time you use the same plugin.
|
||||
You can also use \R{setpluginunload}{SetPluginUnload} alwaysoff to avoid writing /NOUNLOAD each and every time you use the same plugin.
|
||||
|
||||
\S1{calldiskplug} Calling plug-ins manually
|
||||
|
||||
If you want to call a plug-in that is stored on user's hard drive or somewhere else, use \R{callinstdll}{CallInstDLL}. Almost all plug-ins provide installer functionality, so using plug-in commands is way easier. Using \R{callinstdll}{CallInstDLL} can be useful when you have created plug-ins that should be linked to a certain version of your application and are being copied to the installation folder.
|
||||
|
|
|
|||
|
|
@ -7,6 +7,9 @@ pre {
|
|||
background-color: #F7F7F7;
|
||||
padding: 1px;
|
||||
}
|
||||
pre b {
|
||||
color: red;
|
||||
}
|
||||
a {
|
||||
color: #567599;
|
||||
text-decoration: none;
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue