Installation Utility

How the installer works

Basic concept

The installation utility executes a python script that sets up the installation. In addition to standard Python commands the installation utility provides a module called "installer" and an interface to it. Using this interface you can create the different pages that can be found in almost all installation processes: a welcome page, a displayed licence page, a selection page, an installation page and finally a finish page. In the end, there are only a few script commands required.

Running an installation script

From the command line

In order to run an installation from the command line, invoke the installation utility giving your script file as an argument and if you want a logo to be displayed at the top of the window:

"SYS:Utilities/Installation utility" PACKAGE=myscript.py LOGO=mylogo.png

Note: the logo will be displayed all along the installation process.

Note2: right now you need to set these argument names with capital letters, as shown above.

From the Workbench

Add a project icon to your script and use SYS:Utilities/Installation utility as the default tool.

Tooltypes

• PACKAGE (Default: package.py)

This tooltype is used to specify the script name to execute. It is useful if you want to use a standalone icon that will open a script with a different name or in another directory.

• LOGO

You can use this tooltype to specify an image name to use in the installer window.

Example script

A minimal install script looks like this:

# Simple, basic installation script
from installer import *

# These will be used for the first page (welcome) and last page (finish)
welcomeText = "This is a welcome text, displayed at the first page"
finishText = "This is the finish message"

# Define the Welcome page
welcomePage = NewPage(WELCOME)
SetString(welcomePage, "message", welcomeText)

# Define the License page. The user must accept this license to continue the install process.
# The license text will be read from a text file called "license.txt" and will be displayed on the page.
licensePage = NewPage(LICENSE)

# Define a page to select the installation directory
destinationPage = NewPage(DESTINATION)
SetString(destinationPage, "message", "Please indicate where you want to install the files .")
SetString(destinationPage, "destination", "SYS:")

# Define a directory to be copied to the destination
filePack = AddPackage (FILEPACKAGE,
	name = "Full directory",
	description = "Directory to copy as-is in the destination",
	files = ["data"],
	optional = False
	)

# Define a progress page that is shown during the installation
installPage = NewPage(INSTALL)

# Create a "finish" page.
finalPage = NewPage(FINISH)
SetString(finalPage, "message", finishText)

# Finally, this runs the installation.
RunInstaller()

Python Interface

Introduction

The installer is entirely programmed in Python. For this purpose, it provides a Python module called 'installer' that serves as a functional interface to the GUI. The entire GUI is build out of pages. Pages present different kind of information to the user. The installation can be navigated with a pair of forward/backward buttons to visit each page in turn. Certain pages (notably the INSTALL page) will trigger the installation process itself, although the interface is flexible enough to make an installation that is entirely driven by the Python script. A minimal setup function will create a "default" layout of pages for an installer. The basic is to have a single archive that is installed into a destination drawer created on the disk - about 90% of all installers will do exactly this. Therefore a lot of the mechanics involved in this type of installer is automated.

Python Functions in the installer package

NewPage

This function creates a new page and returns its page number for later reference. The only argument to the function is the type of page to create. Possible values are:

WELCOME

A message page, usually used for displaying a "welcome" message, although other uses are perfectly possible as well.

Note: this page is mandatory.

FINISH

A message page that is specifically targeted at closing the installation. This page automatically gets the "finish" attribute set to make the installation change the "cancel" to the "finish" button.

DESTINATION

A page to select a directory to serve as the target for the installation.

Note: this page is mandatory.

INSTALL

The presence of this page automatically triggers the installation of the selected packages.

GUI

A page where GUI elements can be added and controlled via a Python handler.

PROCESSING

A page to display a simple progress bar for doing some Python-scripted processing.

LICENSE

A brickwall page that displays a license agreement that only lets the user continue after accepting the license.

Note: the installation utility will look for a text file called "license_languagename.language.txt", if not found, it will look for a file called "license.txt".

README

A page that displays a text file from disk for reference/README purposes.

If the page cannot be generated, an OSError exception is raised.

GotoPage

This function accepts a single argument, the page to display. This function should rarely be needed.

SetString, SetInteger, SetObject

This function sets a variable of the specified type on a page. It accepts three parameters:

• # The Page number to set the variable on
• # The name of the variable
• # The variable content.

GetString, GetInteger, GetObject

These functions are the reverse of the above - they read a variable from the page specified as its first argument and the name specified as the second argument. They return a default value if the name was not found.

RunInstaller

This function runs the installer's main loop, and needs to be the last command in an installation. Any subsequent scripting is done via handlers connected to the pages.

AddPackage

This function adds a package to the list of installable packages. The function's interface uses keywords to make it more readable. The keywords are

type

The type of package. This can be either FILEPACKAGE, ARCHIVEPACKAGE or HANDLERPACKAGE. A file package copies a list of files to the destination. An archive package unpacks a list of archives at the destination. Finally, a handler package is an abstract package that executes a handler when it is installed or upon certain actions.

This argument MUST be given.

name

A string that specifies the name of the package. This name is presented to the user of the installer on a PACKAGESELECT page.

A name should be given. It defaults to an empty string.

description

A textual description of the package. It is presented to the user next to the package list on a PACKAGESELECT page if the package is selected in the package list.

The description may be empty, although it is consider bad style. It defaults to an empty string.

optional

A boolean value indicating whether the package is optional to install or required to be installed. A value of True means the package is optional.

Default is True (package is optional)

selected

A boolean indicating whether the package should be pre-selected or not. If True, the package is selected the first time the PACKAGESELECT page is entered.

Default is True (package is selected), although the user might deselect the package on a PACKAGESELECT page

diskspace

An integer value specifying the number of bytes the package occupies after installation. If a zero size is given (or the parameter is omitted) the installer tries to figure out the size requirements automatically, but be warned this might be a time consuming process.

Defaults to zero (try to figure out yourself)

featuregroup

An integer bitmask giving one bit of each feature group defined. A one bit indicates this package is part of the group, while a zero bit indicates it isn't.

Defaults to zero (not in any feature group)

alternatepath

Specifies an alternative installation path. For example, some files might need to be installed into LIBS: instead of the usual destination. This feature should be used with care.

Defaults to None (i.e. no alternate path)

files

A list of strings, each string representing one file associated with this package. The interpretation of these files depend on the package type:

ARCHIVEPACKAGE: each file is an archive that is supposed to be extracted into the destination.

HANDLERPACKAGE: The strings are not interpreted in any way, it is up to the handler to do that.

FILEPACKAGE: Each string stands for a file or directory to be copied. Files are straight copies, while directory names are interpreted slightly different: if a directory name is given, that entire directory is copied to the destination, including the directory itself. For example, if you specify "System" then the destination directory will include a "System" directory. On the other hand, if you specify it as "System/" with a trailing slash, the content of the directory will be copied but not the directory itself, i.e. the destination directory would contain all the file and directories in the "System" directory but not the directory itself.

Note: directory/file names must be relative to the current directory i.e. where the installer is executed. You cannot use here a complete path name with the volume name like RAM:mydir.

The default is an empty list.

The result of this function is a package number, which can be used subsequently to adjust package settings or query certain features.

GUI's

GUI's must be created from scratch using a procedural interface. The following procedures deal with creating and handling the user interface. In general, the user interface must be generated once and cannot be changed afterwards (with exceptions, see below).

A GUI is started with a call to StartGUI(page_number). This will start to create a GUI on the indicated page number, and all subsequent calls will add to this GUI until EndGUI() is called. If the indicated page number is invalid or is not a GUI page, ever subsequent calls are ignored until a new StartGUI with a valid page number is called.

Immediately after the call, a single GUI object might be defined. In almost all cases, this will be a group to hold a number of GUI elements. Groups are defined with the BeginGroup and EndGroup calls.

BeginGroup takes the following keyword arguments:

orientation

This specifies whether the children of this group are laid out vertically or horizontally. By default the layout is vertically.

label

A short text string that can be displayed as a label for this group. The label is only used if a frame other than NONE_FRAME is specified. By default no label is used.

frame

One of the constants NONE_FRAME, THIN_FRAME, BUTTON_FRAME, GROUP_FRAME, FIELD_FRAME, DROPBOX_FRAME, SBAR_HORIZ_FRAME, SBAR_VERT_FRAME, BOX_FRAME, STANDARD_FRAME. They directly correspond to the bevel styles of bevel.image. Defaults to NONE_FRAME.

weight

An integer defining the weighted width or height of this group. This corresponds to layout.gadget's CHILD_WeightedWidth or CHILD_WeightedHeight tags, depending on the layout direction.

EndGroup has no parameters and automatically terminates the last group opened by BeginGroup.

User interface elements are added with the following calls. All of these return an ID number.

AddLabel

This call adds a text label, with selectable frame. The following keyword arguments are supported:

label

A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense

weight

The weight of the label, as explained above.

frame

A frame to put around the label.

AddButton

This call adds a push button object to the current group. The function supports the following keyword arguments:

label

A string specifying the label to be displayed within the button. Defaults to an empty label.

frame

One of the constants mentioned above for the group. Defaults to BUTTON_FRAME.

weight

As above

onclick

A Python callable object that is invoked when the button is clicked. The call is made with the following parameters:

handler(page_number, element_id) where page_number is the page number of the GUI page and element_id is the element id returned by this call.

The call returns an id that can be used to construct the variable name for handling attributes of this object.

AddCheckBox

This call adds a checkbox object to the GUI. The following keyword arguments are valid:

label

A string that appears as a label to the right of the checkbox. Defaults to an empty label.

weight

As above

checked

An integer that specifies whether the checkbox is initially checked or not. A zero means the checkbox is clear, any other value says the box is checked.

onclick

A python callable object that is invoked when the checkbox is clicked. The call is made with the following parameters:

handler(page_number, element_id, state) where page_number and element_id are the same as above, and state is a 0 if the user just unchecked the checkbox, or a 1 is it was just checked.

The call returns an id that can be used to construct the variable name for handling attributes of this object.

AddRadioButton

This call adds a set of mutually exclusive radio buttons. The following keyword arguments are valid:

labels

A list of Python strings, with each of these strings appearing as a choice on the Radio buttons. This parameter is required.

weight

As above

selected

The number of the button initially selected. Defaults to the first button (0).

onclick

A python callable object that is invoked when the radio button is clicked. The call is made with the following parameters:

handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the button number that was selected.

The call returns an id that can be used to construct the variable name for handling attributes of this object.

AddChooser

This function adds a chooser gadget to the GUI. The following keyword arguments are valid:

label

A test string to be displayed in the chooser in pop-up mode (see below). Defaults to an empty string, and is not used for drop-down mode.

choices

A list of text strings to be displayed as choices for the chooser. This argument is mandatory.

weight

As above

selected

The number of the currently visible item in drop-down mode. Defaults to 0.

mode

One of the constants CHOOSER_POPUP or CHOOSER_DROPDOWN. This corresponds to the chooser.gadget CHOOSER_PopUp and CHOOSER_DropDown tag items.

onclick

A python callable object that is invoked when the chooser is clicked. The call is made with the following parameters:

handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the title number that was selected.

The call returns an id that can be used to construct the variable name for handling attributes of this object.

AddSpace

This call adds a bit of space to the GUI. It accepts only one parameter:

weight

An integer specifying the weight of the space. Defaults to 1.

The call does not return a value. Space does not have any variables.

User Interface Settings

In order to change some aspects of user interface elements (like the selection status of a checkbox) or read their current state, two functions exist called GetUIAttr and SetUIAttr.

The former reads an attribute from an identified user interface element (identified by the page number and element id) while the latter sets (and updates the on-screen representation) of an equally identified element.

A number of attributes can be set and gotten from UI elements; some of them are shared among more than one element type, while others are specific. The following list names the attributes:

GUI_LABEL (string)

The label displayed on a UI element.

Applies to BUTTON, LABEL, GROUP, CHECKBOX

GUI_SELECTED (integer)

The selected item in a chooser or radio button.

Applies to CHOOSER and RADIOBUTTON

GUI_CHECKED (integer)

Whether the checkbox checkmark is set or not.

Applies to CHECKBOX

GUI_ONCLICK (Python callable)

The handler invoked when the UI element is activated.

Applies to CHOOSER, BUTTON, LABEL, GROUP, CHECKBOX, RADIOBUTTON

The GetUIAttr function's prototype looks like this:

result = GetUIAttr(page_nr, id, attr)

page_nr and id identify the object by giving the GUI's page number and the element id returned by the creation call. The attr parameter is one of the attributes given above. Valid parameters for attr are GUI_SELECTED, GUI_CHECKED and GUI_ONCLICK.

For SetUIAttr, the prototype looks like this:

SetUIAttr(page_nr, id, attr, value)

page_nr and id and attr are the same as above. The value parameter specifies the new value of the attribute, and must match the type for the attribute or the call will have no effect.