Copyright (c) Hyperion Entertainment and contributors.

Difference between revisions of "Installation Utility"

From AmigaOS Documentation Wiki
Jump to navigation Jump to search
(Extended the alternatepath explanation)
 
(87 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
= How the installer works =
 +
= How the Installer Works =
   
−
== Basic concept ==
 +
== 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.
  
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.
  
In the end, there are only a few script commands required.
   
−
== Running an installation script ==
 +
== Running an Installation Script ==
   
−
=== From the command line ===
 +
=== From the Command Line ===
  +
  +
"Installation Utility" PACKAGE/A,PACKAGENAME/K,LANG=LANGUAGE/K,LOGO/K,BACKFILL/K
   
 
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:
  
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:
Line 21: Line 23:
 
=== From the Workbench ===
  
=== From the Workbench ===
   
−
Add a project icon to your script and use ''SYS:Utilities/Installation utility'' as the default tool.
 +
Add a project icon to your script and use ''SYS:Utilities/Installation Utility'' as the default tool.
−  
−
==== Tooltypes ====
  
−  
−
* PACKAGE (Default: ''package.py'')
  
   
  +
==== Tool Types ====
−
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.
  
   
  +
Installation Utility supports the following tool types:
−
* LOGO
  
   
  +
{| class="wikitable"
−
You can use this tooltype to specify an image name to use in the installer window.
  
  +
! style="text-align:left;"| Tool Type
  +
! style="text-align:left;"| Description
  +
|- style="vertical-align: top;"
  +
| BACKFILL=<image file> || An image that will be used to fill the Installation Utility window's background.
  +
|- style="vertical-align: top;"
  +
| LANGUAGE=<language> || Language that your installation script should use. In order to work, your installation script must support the supplied language.
  +
|- style="vertical-align: top;"
  +
| LOGO=<image file> || An image that will be displayed on top of every installation page.
  +
|- style="vertical-align: top;"
  +
| PACKAGENAME=<name> || 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. (Default: ''package.py'')
  +
|}
   
−
= Example script =
 +
= Example Script =
   
 
A minimal install script looks like this:
  
A minimal install script looks like this:
Line 83: Line 92:
 
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.
  
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 ==
 +
== Python Functions in the Installer Package ==
   
 
=== NewPage ===
  
=== NewPage ===
  +
  +
<nowiki>pageId = NewPage( WELCOME|FINISH|DESTINATION|PACKAGESELECT|INSTALL|GUI|PROCESSING|LICENSE|README )</nowiki>
   
 
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:
  
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:
Line 91: Line 102:
 
; WELCOME
  
; WELCOME
 
: A message page, usually used for displaying a "welcome" message, although other uses are perfectly possible as well.
  
: A message page, usually used for displaying a "welcome" message, although other uses are perfectly possible as well.
−
: ''Note:'' this page is mandatory.
 +
: ''Note:'' This page is mandatory.
   
 
; FINISH
  
; FINISH
Line 98: Line 109:
 
; DESTINATION
  
; DESTINATION
 
: A page to select a directory to serve as the target for the installation.
  
: A page to select a directory to serve as the target for the installation.
−
: ''Note:'' this page is mandatory.
 +
: ''Note:'' This page is mandatory.
  +
  +
; PACKAGESELECT
  +
: A page for selecting packages to be installed.
  +
: ''Note:'' Installation Utility version 53.18 does not support page type PACKAGESELECT.
   
 
; INSTALL
  
; INSTALL
Line 108: Line 123:
 
; PROCESSING
  
; PROCESSING
 
: A page to display a simple progress bar for doing some Python-scripted processing.
  
: A page to display a simple progress bar for doing some Python-scripted processing.
  +
: ''Note:'' On Installation Utility version 53.18 the page has no progress bar.
   
 
; LICENSE
  
; LICENSE
 
: A brickwall page that displays a license agreement that only lets the user continue after accepting the 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".
 +
: ''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
  
; README
 
: A page that displays a text file from disk for reference/README purposes.
  
: A page that displays a text file from disk for reference/README purposes.
  +
: ''Note:'' The Installation Utility will look for a text file called "readme_''languagename''.language.txt", if not found, it will look for a file called "readme.txt".
   
 
If the page cannot be generated, an OSError exception is raised.
  
If the page cannot be generated, an OSError exception is raised.
Line 122: Line 139:
 
This function accepts a single argument, the page to display. This function should rarely be needed.
  
This function accepts a single argument, the page to display. This function should rarely be needed.
   
−
=== SetString, SetInteger, SetObject ===
 +
=== SetString ===
   
  +
<nowiki>SetString( pageId, variable, content )</nowiki>
−
This function sets a variable of the specified type on a page. It accepts three parameters:
  
  +
−
* The Page number to set the variable on
  
  +
=== SetInteger ===
−
* The name of the variable
  
  +
−
* The variable content.
  
  +
<nowiki>SetInteger( pageId, variable, content )</nowiki>
  +
  +
=== SetObject ===
  +
  +
<nowiki>SetObject( pageId, property, value )</nowiki>
  +
  +
SetObject allows you to change the properties of a page created with the NewPage function. The PAGEID argument tells which page's property will be changed (see the list of available properties below). The PROPERTY argument is the name of the property to be changed and VALUE is the value to be set for the property.
  +
  +
The following properties are available:
  +
{| class="wikitable"
  +
! style="text-align:left;" | Property
  +
! style="text-align:left;" | Explanation
  +
|-
  +
| '''align''' || Page's header alignment: left, center, or right.
  +
|-
  +
| '''destination''' || On a DESTINATION type page, holds the default installation directory path. The path is visible in the page's target directory gadget.
  +
|-
  +
| '''entryhandler''' || Names a subroutine that will be called when the user enters the page. The subroutine must return a boolean value.
  +
|-
  +
| '''message''' || Page's header content (plain text).
  +
|-
  +
| '''processor''' || Names a subroutine that will be called when the user enters the page. The subroutine must return a boolean value.
  +
|}
   
 
=== GetString, GetInteger, GetObject ===
  
=== GetString, GetInteger, GetObject ===
  +
  +
<nowiki>value = GetString( pageId, variable)</nowiki>
  +
  +
<nowiki>value = GetInteger( pageId, variable)</nowiki>
  +
  +
<nowiki>value = GetObject( pageId, variable)</nowiki>
   
 
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.
  
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 ===
  
=== RunInstaller ===
  +
  +
<nowiki>RunInstaller()</nowiki>
   
 
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.
  
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 ===
  
=== AddPackage ===
  +
  +
<nowiki>packageId = AddPackage(
  +
type = FILEPACKAGE|ARCHIVEPACKAGE|HANDLERPACKAGE
  +
[,name = <name>]
  +
[,description = <description>]
  +
[,optional = False|True]
  +
[,selected = False|True]
  +
[,diskspace = <diskspace>]
  +
[,featuregroup = <bitmask>]
  +
[,alternatepath = <path>]
  +
[,files = <file list>]
  +
)</nowiki>
   
 
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:
  
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:
Line 144: Line 204:
 
: 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.
  
: 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.
  
: This argument MUST be given.
  +
: ''Note:'' Installation Utility version 53.18 does not support package types ARCHIVEPACKAGE and HANDLERPACKAGE.
   
 
; name
  
; name
Line 170: Line 231:
   
 
; alternatepath
  
; 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.
 +
: Specifies an alternative installation path. When an alternative path has been defined, Installation Utility ignores the target directory selected in the DESTINATION page and installs the package to the alternative path location. An alternative path can be used when, for example, some files 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)
 +
: Defaults to None, i.e. no alternate path.
   
 
; files
  
; files
Line 183: Line 244:
 
The result of this function is a package number, which can be used subsequently to adjust package settings or query certain features.
  
The result of this function is a package number, which can be used subsequently to adjust package settings or query certain features.
   
−
== GUI's ==
 +
=== SetPackageOption ===
   
  +
<nowiki>SetPackageOption( packageId, option, value )</nowiki>
−
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).
  
   
  +
This function allows you to set package options. It accepts three parameters:
−
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.
  
  +
* package number
  +
* option to set
  +
* value
   
  +
=== SelectPackage ===
−
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.
  
   
  +
<nowiki>SelectPackage( packageId, False|True )</nowiki>
−
BeginGroup takes the following keyword arguments:
  
  +
−
; orientation
  
  +
Select or deselect a package for installation.
−
: This specifies whether the children of this group are laid out vertically or horizontally. By default the layout is vertically.
  
  +
−
; label
  
  +
=== IsPackageSelected ===
−
: 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
  
  +
<nowiki>selected = IsPackageSelected( packageId )</nowiki>
−
: 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
  
  +
Queries if a package is selected.
−
: 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.
  
  +
  +
=== AddPostInstallAction ===
  +
  +
<nowiki>AddPostInstallAction( action )</nowiki>
  +
  +
Add a post install action for the installation.
  +
  +
=== GetDeviceList ===
  +
  +
<nowiki>deviceList = GetDeviceList()</nowiki>
  +
  +
Get a list of mounted devices.
  +
  +
== GUIs ==
  +
  +
GUIs 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).
  +
  +
=== Creating a GUI ===
  +
  +
<nowiki>StartGUI( pageNumber )</nowiki>
  +
  +
<nowiki>EndGUI()</nowiki>
  +
  +
A GUI is started with a call to '''StartGUI( pageNumber )'''. 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.
  +
  +
=== Grouping UI Elements ===
  +
  +
<nowiki>BeginGroup(
  +
[orientation = GROUP_VERTICAL|GROUP_HORIZONTAL]
  +
[,label = <label>]
  +
[,frame = NONE_FRAME|THIN_FRAME,|BUTTON_FRAME|GROUP_FRAME|FIELD_FRAME
  +
|DROPBOX_FRAME|SBAR_HORIZ_FRAME|SBAR_VERT_FRAME|BOX_FRAME|STANDARD_FRAME]
  +
[,weight = <weight>]
  +
)</nowiki>
  +
  +
<nowiki>EndGroup()</nowiki>
  +
  +
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 (GROUP_VERTICAL) or horizontally (GROUP_HORIZONTAL). 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.
  
EndGroup has no parameters and automatically terminates the last group opened by BeginGroup.
  +
  +
=== UI Elements ===
   
 
User interface elements are added with the following calls. All of these return an ID number.
  
User interface elements are added with the following calls. All of these return an ID number.
   
−
=== AddLabel ===
 +
==== AddLabel ====
  +
  +
<nowiki>AddLabel(
  +
[label = <label>]
  +
[,frame = NONE_FRAME|THIN_FRAME,|BUTTON_FRAME|GROUP_FRAME|FIELD_FRAME
  +
|DROPBOX_FRAME|SBAR_HORIZ_FRAME|SBAR_VERT_FRAME|BOX_FRAME|STANDARD_FRAME]
  +
[,weight = <weight>]
  +
[,align = ALIGN_LEFT|ALIGN_RIGHT|ALIGN_CENTER|ALIGN_BLOCK]
  +
)</nowiki>
   
 
This call adds a text label, with selectable frame. The following keyword arguments are supported:
  
This call adds a text label, with selectable frame. The following keyword arguments are supported:
−
; label
 +
:; label
−
: A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense
 +
:: A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense
   
−
; frame
 +
:; frame
−
: A frame to put around the label.
 +
:: A frame to put around the label.
   
−
; weight
 +
:; weight
−
: The weight of the label, as explained above.
 +
:: The weight of the label, as explained above.
   
−
; align
 +
:; align
−
: Text alignment to use for the label
 +
:: Text alignment to use for the label. Possible values are: ALIGN_LEFT, ALIGN_RIGHT, ALIGN_CENTER, ALIGN_BLOCK
   
−
=== AddButton ===
 +
==== AddString ====
  +
  +
<nowiki>AddString(
  +
[label = <label>]
  +
[,value = <value>]
  +
[,weight = <weight>]
  +
[,handler = <callable object>]
  +
)</nowiki>
  +
  +
:; label
  +
:: A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense
  +
  +
:; value
  +
:: Value to use as the default string
  +
  +
:; weight
  +
:: The weight of the label, as explained above.
  +
  +
:; handler
  +
:: A Python callable object that is invoked when the string field 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.
  +
  +
==== AddButton ====
  +
  +
<nowiki>buttonId = AddButton(
  +
[label = <label>]
  +
[,frame = NONE_FRAME|THIN_FRAME,|BUTTON_FRAME|GROUP_FRAME|FIELD_FRAME
  +
|DROPBOX_FRAME|SBAR_HORIZ_FRAME|SBAR_VERT_FRAME|BOX_FRAME|STANDARD_FRAME]
  +
[,weight = <weight>]
  +
[,onclick = <callable object>]
  +
)</nowiki>
   
 
This call adds a push button object to the current group. The function supports the following keyword arguments:
  
This call adds a push button object to the current group. The function supports the following keyword arguments:
−
; label
 +
:; label
−
: A string specifying the label to be displayed within the button. Defaults to an empty label.
 +
:: A string specifying the label to be displayed within the button. Defaults to an empty label.
   
−
; frame
 +
:; frame
−
: One of the constants mentioned above for the group. Defaults to BUTTON_FRAME.
 +
:: One of the constants mentioned above for the group. Defaults to BUTTON_FRAME.
   
−
; weight
 +
:; weight
−
: As above
 +
:: As above
   
−
; onclick
 +
:; onclick
−
: A Python callable object that is invoked when the button is clicked. The call is made with the following parameters:
 +
:: 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.
 +
::: 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.
  
The call returns an id that can be used to construct the variable name for handling attributes of this object.
   
−
=== AddCheckBox ===
 +
==== AddCheckBox ====
  +
  +
<nowiki>checkBoxId = AddButton(
  +
[label = <label>]
  +
[,weight = <weight>]
  +
[,checked = False|True]
  +
[,onclick = <callable object>]
  +
)</nowiki>
   
 
This call adds a checkbox object to the GUI. The following keyword arguments are valid:
  
This call adds a checkbox object to the GUI. The following keyword arguments are valid:
   
−
; label
 +
:; label
−
: A string that appears as a label to the right of the checkbox. Defaults to an empty label.
 +
:: A string that appears as a label to the right of the checkbox. Defaults to an empty label.
   
−
; weight
 +
:; weight
−
: As above
 +
:: As above
   
−
; checked
 +
:; 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.
 +
:: 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
 +
:; onclick
−
: A python callable object that is invoked when the checkbox is clicked. The call is made with the following parameters:
 +
:: 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.
 +
::: 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.
  
The call returns an id that can be used to construct the variable name for handling attributes of this object.
   
−
=== AddRadioButton ===
 +
==== AddRadioButton ====
  +
  +
<nowiki>radioButtonId = AddRadioButton(
  +
<label list>
  +
[,weight = <weight>]
  +
[,selected = False|True]
  +
[,onclick = <callable object>]
  +
)</nowiki>
   
 
This call adds a set of mutually exclusive radio buttons. The following keyword arguments are valid:
  
This call adds a set of mutually exclusive radio buttons. The following keyword arguments are valid:
   
  +
:; label list
−
; labels
  
−
: A list of Python strings, with each of these strings appearing as a choice on the Radio buttons. This parameter is required.
 +
:: A list of Python strings, with each of these strings appearing as a choice on the Radio buttons. This parameter is required.
   
−
; weight
 +
:; weight
−
: As above
 +
:: As above
   
−
; selected
 +
:; selected
−
: The number of the button initially selected. Defaults to the first button (0).
 +
:: The number of the button initially selected. Defaults to the first button (0).
   
−
; onclick
 +
:; onclick
−
: A python callable object that is invoked when the radio button is clicked. The call is made with the following parameters:
 +
:: 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.
 +
::: 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.
  
The call returns an id that can be used to construct the variable name for handling attributes of this object.
   
−
=== AddChooser ===
 +
==== AddChooser ====
  +
  +
<nowiki>chooserId = AddChooser(
  +
[label = <label>]
  +
[,choices = <list>]
  +
[,weight = <weight>]
  +
[,selected = False|True]
  +
[,mode = CHOOSER_POPUP|CHOOSER_DROPDOWN]
  +
[,onclick = <callable object>]
  +
)</nowiki>
   
 
This function adds a chooser gadget to the GUI. The following keyword arguments are valid:
  
This function adds a chooser gadget to the GUI. The following keyword arguments are valid:
   
−
; label
 +
:; 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.
 +
:: 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
 +
:; choices
−
: A list of text strings to be displayed as choices for the chooser. This argument is mandatory.
 +
:: A list of text strings to be displayed as choices for the chooser. This argument is mandatory.
   
−
; weight
 +
:; weight
−
: As above
 +
:: As above
   
−
; selected
 +
:; selected
−
: The number of the currently visible item in drop-down mode. Defaults to 0.
 +
:: The number of the currently visible item in drop-down mode. Defaults to 0.
   
  +
:; mode
−
; mode: One of the constants CHOOSER_POPUP or CHOOSER_DROPDOWN. This corresponds to the chooser.gadget CHOOSER_PopUp and CHOOSER_DropDown tag items.
  
  +
:: One of the constants CHOOSER_POPUP or CHOOSER_DROPDOWN. This corresponds to the chooser.gadget CHOOSER_PopUp and CHOOSER_DropDown tag items.
   
−
; onclick
 +
:; onclick
−
: A python callable object that is invoked when the chooser is clicked. The call is made with the following parameters:
 +
:: 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.
 +
::: 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.
  
The call returns an id that can be used to construct the variable name for handling attributes of this object.
   
−
=== AddSpace ===
 +
==== AddSpace ====
  +
  +
<nowiki>AddSpace([weight = <weight>])</nowiki>
   
 
This call adds a bit of space to the GUI. It accepts only one parameter:
  
This call adds a bit of space to the GUI. It accepts only one parameter:
   
−
; weight
 +
:; weight
−
: An integer specifying the weight of the space. Defaults to 1.
 +
:: An integer specifying the weight of the space. Defaults to 1.
   
 
The call does not return a value. Space does not have any variables.
  
The call does not return a value. Space does not have any variables.
   
−
== User Interface Settings ==
 +
=== UI Element Settings ===
   
  +
<nowiki>value = GetUIAttr( pageId, elementId, GUI_LABEL|GUI_SELECTED|GUI_CHECKED|GUI_ONCLICK )</nowiki>
−
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.
  
  +
  +
<nowiki>SetUIAttr( pageId, elementId, GUI_LABEL|GUI_SELECTED|GUI_CHECKED|GUI_ONCLICK, <value> )</nowiki>
  +
  +
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.
  
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.
Line 332: Line 517:
 
: The handler invoked when the UI element is activated.
  
: The handler invoked when the UI element is activated.
 
: Applies to CHOOSER, BUTTON, LABEL, GROUP, CHECKBOX, RADIOBUTTON
  
: Applies to CHOOSER, BUTTON, LABEL, GROUP, CHECKBOX, RADIOBUTTON
−  
−
The GetUIAttr function's prototype looks like this:
  
−  
−
<syntaxhighlight>
  
−
result = GetUIAttr(page_nr, id, attr)
  
−
</syntaxhighlight>
  
−  
−
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:
  
−  
−
<syntaxhighlight>
  
−
SetUIAttr(page_nr, id, attr, value)
  
−
</syntaxhighlight>
  
−  
−
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.
  
   
 
= Hints =
  
= Hints =

Latest revision as of 20:43, 29 July 2022

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

 "Installation Utility" PACKAGE/A,PACKAGENAME/K,LANG=LANGUAGE/K,LOGO/K,BACKFILL/K

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.

Tool Types

Installation Utility supports the following tool types:

Tool Type Description
BACKFILL=<image file> An image that will be used to fill the Installation Utility window's background.
LANGUAGE=<language> Language that your installation script should use. In order to work, your installation script must support the supplied language.
LOGO=<image file> An image that will be displayed on top of every installation page.
PACKAGENAME=<name> 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. (Default: package.py)

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

pageId = NewPage( WELCOME|FINISH|DESTINATION|PACKAGESELECT|INSTALL|GUI|PROCESSING|LICENSE|README )

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.
PACKAGESELECT
A page for selecting packages to be installed.
Note: Installation Utility version 53.18 does not support page type PACKAGESELECT.
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.
Note: On Installation Utility version 53.18 the page has no progress bar.
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.
Note: The Installation Utility will look for a text file called "readme_languagename.language.txt", if not found, it will look for a file called "readme.txt".

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

SetString( pageId, variable, content )

SetInteger

SetInteger( pageId, variable, content )

SetObject

SetObject( pageId, property, value )

SetObject allows you to change the properties of a page created with the NewPage function. The PAGEID argument tells which page's property will be changed (see the list of available properties below). The PROPERTY argument is the name of the property to be changed and VALUE is the value to be set for the property.

The following properties are available:

Property Explanation
align Page's header alignment: left, center, or right.
destination On a DESTINATION type page, holds the default installation directory path. The path is visible in the page's target directory gadget.
entryhandler Names a subroutine that will be called when the user enters the page. The subroutine must return a boolean value.
message Page's header content (plain text).
processor Names a subroutine that will be called when the user enters the page. The subroutine must return a boolean value.

GetString, GetInteger, GetObject

value = GetString( pageId, variable)

value = GetInteger( pageId, variable)

value = GetObject( pageId, variable)

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

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

packageId = AddPackage(
   type = FILEPACKAGE|ARCHIVEPACKAGE|HANDLERPACKAGE
   [,name = <name>]
   [,description = <description>]
   [,optional = False|True]
   [,selected = False|True]
   [,diskspace = <diskspace>]
   [,featuregroup = <bitmask>]
   [,alternatepath = <path>]
   [,files = <file list>]
)

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.
Note: Installation Utility version 53.18 does not support package types ARCHIVEPACKAGE and HANDLERPACKAGE.
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. When an alternative path has been defined, Installation Utility ignores the target directory selected in the DESTINATION page and installs the package to the alternative path location. An alternative path can be used when, for example, some files 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.

SetPackageOption

SetPackageOption( packageId, option, value )

This function allows you to set package options. It accepts three parameters:

  • package number
  • option to set
  • value

SelectPackage

SelectPackage( packageId, False|True )

Select or deselect a package for installation.

IsPackageSelected

selected = IsPackageSelected( packageId )

Queries if a package is selected.

AddPostInstallAction

AddPostInstallAction( action )

Add a post install action for the installation.

GetDeviceList

deviceList = GetDeviceList()

Get a list of mounted devices.

GUIs

GUIs 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).

Creating a GUI

StartGUI( pageNumber )

EndGUI()

A GUI is started with a call to StartGUI( pageNumber ). 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.

Grouping UI Elements

BeginGroup(
   [orientation = GROUP_VERTICAL|GROUP_HORIZONTAL]
   [,label = <label>]
   [,frame = NONE_FRAME|THIN_FRAME,|BUTTON_FRAME|GROUP_FRAME|FIELD_FRAME
    |DROPBOX_FRAME|SBAR_HORIZ_FRAME|SBAR_VERT_FRAME|BOX_FRAME|STANDARD_FRAME]
   [,weight = <weight>]
)

EndGroup()

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 (GROUP_VERTICAL) or horizontally (GROUP_HORIZONTAL). 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.

UI Elements

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

AddLabel

AddLabel(
    [label = <label>]
    [,frame = NONE_FRAME|THIN_FRAME,|BUTTON_FRAME|GROUP_FRAME|FIELD_FRAME
     |DROPBOX_FRAME|SBAR_HORIZ_FRAME|SBAR_VERT_FRAME|BOX_FRAME|STANDARD_FRAME]
    [,weight = <weight>]
    [,align = ALIGN_LEFT|ALIGN_RIGHT|ALIGN_CENTER|ALIGN_BLOCK]
)

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
frame
A frame to put around the label.
weight
The weight of the label, as explained above.
align
Text alignment to use for the label. Possible values are: ALIGN_LEFT, ALIGN_RIGHT, ALIGN_CENTER, ALIGN_BLOCK

AddString

AddString(
    [label = <label>]
    [,value = <value>]
    [,weight = <weight>]
    [,handler = <callable object>]
)
label
A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense
value
Value to use as the default string
weight
The weight of the label, as explained above.
handler
A Python callable object that is invoked when the string field 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.

AddButton

buttonId = AddButton(
    [label = <label>]
    [,frame = NONE_FRAME|THIN_FRAME,|BUTTON_FRAME|GROUP_FRAME|FIELD_FRAME
     |DROPBOX_FRAME|SBAR_HORIZ_FRAME|SBAR_VERT_FRAME|BOX_FRAME|STANDARD_FRAME]
    [,weight = <weight>]
    [,onclick = <callable object>]
)

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

checkBoxId = AddButton(
    [label = <label>]
    [,weight = <weight>]
    [,checked = False|True]
    [,onclick = <callable object>]
)

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

radioButtonId = AddRadioButton(
    <label list>
    [,weight = <weight>]
    [,selected = False|True]
    [,onclick = <callable object>]
)

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

label list
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

chooserId = AddChooser(
    [label = <label>]
    [,choices = <list>]
    [,weight = <weight>]
    [,selected = False|True]
    [,mode = CHOOSER_POPUP|CHOOSER_DROPDOWN]
    [,onclick = <callable object>]
)

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

AddSpace([weight = <weight>])

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.

UI Element Settings

value = GetUIAttr( pageId, elementId, GUI_LABEL|GUI_SELECTED|GUI_CHECKED|GUI_ONCLICK )

SetUIAttr( pageId, elementId, GUI_LABEL|GUI_SELECTED|GUI_CHECKED|GUI_ONCLICK, <value> )

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

Hints

  • See the AmigaOS 4 installation script on the AmigaOS Installation CD. It is a big script full of functions. Take it as example and experiment.
Retrieved from "http://wiki.amigaos.net/w/index.php?title=Installation_Utility&oldid=12317"