Previous | Contents | Next

## 4.5 Pages

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 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, Page and 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 PageEx command which allows you to add a page to either one and with greater amount of options. PageEx allows you to set options to the specific page you are adding instead of using the default that's set outside of PageEx.

### 4.5.1 Ordering

The page order is set simply by the order Page, UninstPage and PageEx appear in the script. For example:

     Page license

     Page components

     Page directory

     Page instfiles

     UninstPage uninstConfirm

     UninstPage instfiles

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.

For backwards compatibility with old NSIS scripts, the following installer pages will be added if no installer page commands are used: license (if LicenseText and LicenseData were specified), components (if ComponentText was specified and there is more than one visible section), directory (if DirText was specified) and instfiles. When there are no uninstaller page commands, the following uninstaller pages will be added: uninstall confirmation page (if 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.

### 4.5.2 Page Options

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. Callback functions are described below and are not dealt with in this section.

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 PageEx block. If used inside a PageEx block they will only affect the current page being set by PageEx, else they will set the default for every other page.

License page

- LicenseText
- LicenseData
- LicenseForceSelection

Components selection page

- ComponentText

Directory selection page

- DirText
- DirVar - can only be used in PageEx
- DirVerify

Un/Installation log page

- DetailsButtonText
- CompletedText

Uninstall confirmation page

- DirVar - can only be used in PageEx
- UninstallText

To set the page caption use Caption.

### 4.5.3 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.

- The pre-function allows you to skip the page using Abort.
- The show-function allows you to tweak the page's user interface with CreateFont, SetCtlColors, SendMessage and others.
- The leave-function allows you to force the user to stay on the current page using 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:

     Page license skipLicense "" stayInLicense

     Page custom customPage "" ": custom page"

     Page instfiles

     Function skipLicense

       MessageBox MB_YESNO "Do you want to skip the license page?" IDNO no

         Abort

       no:

     FunctionEnd

     Function stayInLicense

       MessageBox MB_YESNO "Do you want to stay in the license page?" 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 "InstallOptions error:$\r$\n$R1"

       done:

     FunctionEnd

### 4.5.4 Page

    custom [creator_function] [leave_function] [caption] [/ENABLECANCEL]

      OR

    internal_page_type [pre_function] [show_function] [leave_function] [/ENABLECANCEL]

Adds an installer page. See the above sections for more information about built-in versus custom pages and about callback functions.

internal_page_type can be:

- license - license page
- components - components selection page
- directory - installation directory selection page
- instfiles - installation page where the sections are executed
- uninstConfirm - uninstall confirmation page

The last page of the installer has its cancel button disabled to prevent confusion. To enable it anyway, use /ENABLECANCEL.

### 4.5.5 UninstPage

    custom [creator_function] [leave_function] [caption] [/ENABLECANCEL]

      OR

    internal_page_type [pre_function] [show_function] [leave_function] [/ENABLECANCEL]

Adds an uninstaller page. See the above sections for more information about built-in versus custom pages and about callback functions.

See Page for possible values of internal_page_type.

### 4.5.6 PageEx

    [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 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 sub-caption for a page use Caption or SubCaption to set the default. To set the callback functions for a page set with PageEx use PageCallbacks. See the above sections for more information about built-in versus custom pages.

Example usage:

     PageEx license

       LicenseText "Readme"

       LicenseData readme.rtf

     PageExEnd

     PageEx license

       LicenseData license.txt

       LicenseForceSelection checkbox

     PageExEnd

### 4.5.7 PageExEnd

Ends a PageEx block.

### 4.5.8 PageCallbacks

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

Sets the callback functions for a page defined using PageEx. Can only be used inside a PageEx block. See the above sections for more information about callback functions.

    PageEx license

      PageCallbacks licensePre licenseShow licenseLeave

    PageExEnd

Previous | Contents | Next