Installation Utility

How the installer works
-----------------------

The installer executes a python script that sets up the installation. At the
basic level, there are only a few script commands required. A minimal install
script looks like this:


- BEGIN ------------------------------------------------------------------------
# Simple, basic installation script
from installer import installer

# 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"

# Create the installer
myInstall = installer()

# Set up the installer for a basic default setup. This means
# - A welcome page with the above text	
# - A page to select the installation directory
# - A selection page for the features to install	
# - A progress page that is shown during the installation
# - A "finish" page.

myInstall.Setup(installer.SETUP_DEFAULT)

# Set the welcome and finish texts
myInstall.WelcomeText(welcomeText)
myInstall.FinishText(finishText)

# This adds an installable feature. The name is displayed in the selection list.
# The optional parameter determines whether this can be left out or not (it is
# made mandatory in this case). selected means that the feature is initially
# selected for installation. The description is displayed to the right of the
# feature list when the feature is selected.
# Finally, files is a list of files, directories, or archives that belong to
# this feature, relative to the installation's base directory (i.e. where the 
# install script resides).
myInstall.AddInstallableFeature(
	name = "Basic Installation",
	optional = False,
	selected = True,
	description = "Descriptional text displayed on the right",
	files = ["base.lha"]
)

# this sets the default path to "SYS:". In addition, it also tells the installer
# that the path should not be changed.
myInstall.SetDefaultPath("SYS:", installer.RECOMMENDED)

# Finally, this runs the installation.
myInstall.Run()
- END --------------------------------------------------------------------------

This script is a very basic installer without any additional bells and whistles.
If you need something more complicated that this, then the setup will be a bit
more complicated. The following script results in the same installer as the 
previous one, but it does most of the setup "by hand".

- BEGIN ------------------------------------------------------------------------
# The same installer, just done manually
from installer import installer

# 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"

# Create the installer
myInstall = installer()

# Set up the installer without any pages.

myInstall.Setup(installer.SETUP_EMPTY)

# This adds a welcome text page
myInstall.AddWelcomePage(welcomeText);

# This adds an installation directory page
myInstall.AddDirectoryPage(text = "Please select an installation directory",
	default="SYS:",
	recommendation=installer.RECOMMENDED);

# Add the feature selection page. If you ommit this page, the feature selection
# cannot be changed by the user.
myInstall.AddFeaturePage("Select the features to be installed");

# This adds an installable feature. The name is displayed in the selection list.
# The optional parameter determines whether this can be left out or not (it is
# made mandatory in this case). selected means that the feature is initially
# selected for installation. The description is displayed to the right of the
# feature list when the feature is selected.
# Finally, files is a list of files, directories, or archives that belong to
# this feature, relative to the installation's base directory (i.e. where the 
# install script resides).
myInstall.AddInstallableFeature(
	name = "Basic Installation",
	optional = False,
	selected = True,
	description = "Descriptional text displayed on the right",
	files = ["base.lha"]
)

myInstall.AddFinishPage(finnishText);

# Finally, this runs the installation.
myInstall.Run()
- END --------------------------------------------------------------------------

/*!
\page python_iface Python Interface
\section python_intro 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 \b 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 \c 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.

\section python_command Python Functions in the installer package
\subsection python_NewPage 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:
- \c WELCOME: A message page, usually used for displaying a "welcome" message, althoug
 other uses are perfectly possible as well.
- \c 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.
- \c DESTINATION: A page to select a directory to serve as the target for the installation.
- \c PACKAGESELECT: A page that lets a user select the packages in the installation that should
 be installed.
- \c INSTALL: The presense of this page automatically triggers the installation of the selected
 packages.
- \c GUI: A page where GUI elements can be added and controlled via a Python handler.
- \c PROCESSING: A page to display a simple progress bar for doing some Python-scripted
 processing.
- \c LICENSE: A brickwall page that displays a license agreement that only lets the user
 continue after accepting the license.
- \c 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.

\subsection python_GotoPage GotoPage
This function accepts a single arguemnt, the page to display. This function should rarely
be needed.

\subsection python_Set 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.

\subsection python_Get 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.

\subsection python_runinstaller RunInstaller
This funciton 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.

\subsection python_addpackage 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

- \c type<br>
  The type of package. This can be either \c FILEPACKAGE, \c ARCHIVEPACKAGE or
  \c 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.<br>
  This argument MUST be given.

- \c name<br>
  A string that specifies the name of the package. This name is presented to the user
  of the installer on a PACKAGESELECT page.<br>
  A name should be given. It defaults to an empty string.

- \c description<br>
  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.<br>
  The description may be empty, although it is consider bad style. It defaults to an empty
  string.

- \c optional<br>
  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.<br>
  Default is True (package is optional)

- \c selected<br>
  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. <br>
  Default is True (package is selected), although the user might deselect the package on
  a PACKAGESELECT page

- \c diskspace<br>
  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.<br>
  Defaults to zero (try to figure out yourself)

- \c featuregroup<br>
  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.<br>
  Defaults to zero (not in any feature group)

- \c alternatepath<br>
  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.<br>
  Defaults to None (i.e. no alternate path)

- \c files<br>
  A list of strings, each string representing one file associated with this package. The
  interpretation of these files depend on the package type:
  - \c ARCHIVEPACKAGE: each file is an archive that is supposed to be extracted into the
    destination.
  - \c HANDLERPACKAGE: The strings are not interpreted in any way, it is up to the hanlder
    to do that.
  - \c 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.
  <br>
  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.

\subsection python_GUI 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 \c 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 \c EndGUI() is
called. If the indicated page number is invalid or is not a GUI page, ever subsequent calls
are ignored until a new \c 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
\c BeginGroup and \c EndGroup calls.
\c BeginGroup takes the following keyword arguments:
- \c orientation: This specifies whether the children of this group are laid out vertically
  or horizontally. By default the layout is vertically.
- \c 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 \c NONE_FRAME is specified. By default no label is used.
- \c frame: One of the constants \c NONE_FRAME, \c THIN_FRAME, \c BUTTON_FRAME,
  \c GROUP_FRAME, \c FIELD_FRAME, \c DROPBOX_FRAME, \c SBAR_HORIZ_FRAME,
  \c SBAR_VERT_FRAME, \c BOX_FRAME, \c STANDARD_FRAME. They directly correspond to the
  bevel styles of \c bevel.image. Defaults to \c NONE_FRAME.
- \c weight: An integer defining the weighted width or height of this group. This corresponds
  to \c layout.gadget's \c CHILD_WeightedWidth or \c CHILD_WeightedHeight tags, depending
  on the layout direction.

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

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

\subsubsection python_addlabel AddLabel
This call adds a text label, with selectable frame. The following keyword arguments are
supported:
- \c label: A string that specifies the label to be displayed. Default is empty, although
  an empty label doesn't make much sense
- \c weight: The weight of the label, as explained above.
- \c frame: A frame to put around the label.

\subsubsection python_addbutton AddButton
This call adds a pushbutton object to the current group. The function supports the following
keyword arguments:
- \c label: A string specifying the label to be displayed within the button. Defaults
  to an empty label.
- \c frame: One of the constants mentioned above for the group. Defaults to \c BUTTON_FRAME.
- \c weight: As above
- \c onclick: A Python callable object that is invoked when the button is clicked. The
  call is made with the following parameters: <br>
 <tt>handler(page_number, element_id)</tt> where \c page_number is the page number of the GUI
  page and \c 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.

\subsubsection python_addcheckbox AddCheckBox
This call adds a checkbox object to the GUI. The following keyword arguments are valid:
- \c label: A string that appears as a label to the right of the checkbox. Defaults to
   an empty label.
- \c weight: As above
- \c 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.
- \c onclick: A python callable object that is invoked when the checkbox is clicked. The
  call is made with the following parameters:<br>
  <tt>handler(page_number, element_id, state)</tt> where \c page_number and \c element_id
  are the same as above, and \c 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.

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

- \c labels: A list of Python strings, with each of these strings appearing as a choice
  on the Radio buttons. This parameter is required.
- \c weight: As above
- \c selected: The number of the button initially selected. Defaults to the first button (0).
- \c onclick: A python callable object that is invoked when the radio button is clicked. The
  call is made with the following parameters:<br>
  <tt>handler(page_number, element_id, selected)</tt> where \c page_number and \c 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.

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

- \c 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.
- \c choices: A list of text strings to be displayed as choices for the chooser.
  This argument is mandatory.
- \c weight: As above
- \c selected: The number of the currently visible item in drop-down mode. Defaults to 0.
- \c mode: One of the constants \c CHOOSER_POPUP or \c CHOOSER_DROPDOWN. This corresponds to
  the \c chooser.gadget \c CHOOSER_PopUp and \c CHOOSER_DropDown tag items.
- \c onclick: A python callable object that is invoked when the chooser is clicked. The
  call is made with the following parameters:<br>
  <tt>handler(page_number, element_id, selected)</tt> where \c page_number and \c 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.

\subsubsection python_addspace AddSpace
This call adds a bit of space to the GUI. It accepts only one parameter:
- \c 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.

\subsubsection python_UISettings User Interface Settings

In order to change some aspects of user iterface elements (like the selection status of
a checkbox) or read their current state, two functions exist called \c GetUIAttr and \c 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:

- \c GUI_LABEl (string) The label displayed on a UI element.<br>
	Applies to \c BUTTON, \c LABEL, \c GROUP, \c CHECKBOX
- \c GUI_SELECTED (integer) The selected item in a chooser or radio button.<br>
	Applies to \c CHOOSER and \c RADIOBUTTON
- \c GUI_CHECKED (integer) Whether the checkbox checkmark is set or not<br>
	Applies to \c CHECKBOX
- \c GUI_ONCLICK (Python callable) The handler invoked when the UI element is activated<br>
    Applies to \c CHOOSER, \c BUTTON, \c LABEL, \c GROUP, \c CHECKBOX, \c RADIOBUTTON

The GetUIAttr function's prototype looks like this:

<tt>result = GetUIAttr(page_nr, id, attr)</tt><br>

\c page_nr and \c id identify the object by giving the GUI's page number and the element id
returned by the creation call. The \c 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:

<tt>SetUIAttr(page_nr, id, attr, value)</tt><br>

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

*/