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 nsDialogs or InstallOptions for example).

The script controls the page 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 do 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. 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 the commands that affect a certain page type. Unless otherwise mentioned, these commands can be used both inside and outside of a PageEx block. If used inside a PageEx block they will only affect the current page being set by PageEx, otherwise they will set the default for all other pages.

下面的列表列出了影响特定页面类型的命令。除非另有说明，这些命令可以在PageEx块内部和外部使用。如果在一个PageEx块中使用，它们只会影响当前页面被PageEx设置，否则它们将为所有其他页面设置默认值。

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

Use Caption to set the page caption.

4.5.3 Callbacks

Each built-in page has three callback functions: the pre-function, the show function and the leave-function. The pre-function is called right before the page is created, the show-function is called right after it has been created but before it is shown and the leave-function is called right after the user has pressed the next button (before actually leaving the page).

每个内置页面有三个回调函数：pre-function、show-function和leave-function。pre-function在创建页面之前被调用，show-function在创建之后在显示之前被调用，leave-function在用户按下next按钮之后被调用（在实际离开页面之前）。

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 etc.
The leave-function allows you to force the user to stay on the current page using Abort.

pre-function允许使用Abort跳过页面。

show-function允许使用CreateFont、SetCtlColors、SendMessage等调整页面的用户界面。

leave-function允许使用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.

一个自定义页面只有两个回调函数，一个是强制创建的回调函数，另一个是类似于内置页面中的leave-function。

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

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

Page 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

license - license页面

components - 组件选择页面

directory - 安装目录选择页面

instfiles - 执行部分的安装页面

uninstConfirm - 卸载确认页面

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

安装程序的最后一页禁用了“取消”按钮，以防止混淆。要启用它，使用/ENABLECANCEL。

4.5.5 UninstPage

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

UninstPage 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

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.

添加安装页面，如果使用了un.前缀则添加卸载页面。每个PageEx必须有一个匹配的PageExEnd。在PageEx块中，您可以设置特定于此页面的选项，而不会用于其他页面。没有设置的选项将使用 PageEx块外设置或默认（如果什么都没有设置）。要设置页面的子标题，请使用Caption或SubCaption设置默认值。使用PageCallbacks设置PageEx页面的回调函数。

Example usage:

```nsis`` 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

```txt
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定义的页面设置回调函数。只能在PageEx块内使用。

PageEx license
  PageCallbacks licensePre licenseShow licenseLeave
PageExEnd

EP04 Scripting Reference (P5)