Home > Element Reference : Install

Contents

### Install

An object used for installations. This object is only available within an installation script.

The methods can can be called without the preceding Install reference. Most of the functions only add an operation to an installation queue. When the function performInstall is called, each operation from the queue is performed. This makes it convenient to cancel an installation by calling cancelInstall. Functions generally return error codes, but you can also use the getLastError function to get the error code generated by the last function, if any.

More information about Install

Properties and Methods:

Install | addDirectory | addFile | alert | archive
arguments | buildID | cancelInstall | confirm | deleteRegisteredFile
execute | gestalt | getComponentFolder | getFolder | getLastError
getWinProfile | getWinRegistry | initInstall | jarfile | loadResources
logComment | patch | performInstall | platform | refreshPlugins
registerChrome | resetError | setPackageFolder | uninstall | url

#### Properties and Methods:

##### Install

Refers to the Install object itself. This property is used to allow syntax such as Install.initInstall() or initInstall().

##### addDirectory ( jarDir )
addDirectory ( regName , jarDir , destDir , subDir )
addDirectory ( regName , version , jarDir , destDir , subDir )
addDirectory ( regName , version , jarDir , destDir , subDir , force )

Assigns a new directory to be installed from the installation file. Parameters are as follows:

regName | The registry name of the package being installed. This should be of the form /Company Name/Package Name/Program
version | The version of the files in the directory being installed, as digits separated by periods, such as 1.5.3.9
jarDir | The directory within the XPI archive to be installed. The contents of this directory will be installed.
destDir | The destination directory to install into. If this parameter is not supplied, you must first call setPackageFolder first to set the destination directory for the installation.
subDir | The name of the directory to create.
force | If true, the directory contents are always installed. If false, the files are only installed if the existing files, if any, are older versions. Newer versions are not installed. If not specified, the default is true.

##### addFile ( sourceFile )
addFile ( regName , sourceFile , destDir , target )
addFile ( regName , version , sourceFile , destDir , target )
addFile ( regName , version , sourceFile , destDir , target , force )

Assigns a new file to be installed from the installation file. Parameters are as follows:

regName | The registry name of the package which the file belongs to.
version | The version of the file being installed, as digits separated by periods, such as 2.9.15.67
sourceFile | The name of the file within the XPI archive to be installed.
destDir | The destination directory to install into. If this parameter is not supplied, you must first call setPackageFolder first to set the destination directory for the installation.
target | If you want to change the name of the file, you can assign a different one using the target parameter. Otherwise, just pass in a null string.
force | If true, the file is always installed. If false, the file is only installed if the existing file, if it exists, is an older version. If not specified, the default is true.

##### alert ( text )

Displays an alert dialog. Equivalent to the window.alert function.

##### archive

This property is equivalent to the jarfile property.

##### arguments

Returns the HTTP arguments to the installer archive. This property is read only.

##### buildID

The build ID of the browser.

##### cancelInstall ( errorCode )

Cancels an installation. The queue of files to be installed and other operations to perform is emptied. Use this function when an error occurs and you need to stop an installation. You should present a message to the user indicating why. The argument may be used to supply an error code.

##### confirm ( text )

Displays a confirmation dialog. Equivalent to the window.confirm function.

##### deleteRegisteredFile ( regName )

Assigns an installed file or directory to be deleted during the installation process.

##### execute ( sourceFile , args )

Assigns a file in the installation package to be executed during the installation. You may supply arguments to the file, which, of course, must be an executable file.

##### gestalt ( selector )

Performs a Macintosh gestalt operation and returns the result. The selector should be a four character string that corresponds to the gestalt selector you want to examine. The function does nothing on non-Macintosh systems.

##### getComponentFolder ( regName )
getComponentFolder ( regName , subDir )

Returns the directory where the component installed with the name regName is located. You may optionally append a subdirectory to the path at the same time. Returns a null string if the component is not found.

##### getFolder ( folder )
getFolder ( folder , subDir )

Returns a special folder object given by the folder argument. You may also use a subdirectory argument to have this directory or file appended to the returned folder. You can later use the returned value as the first argument to the getFolder function to get a further subdirectory. The subdirectory does not have to exist. To check for existence of a directory, use the File.exists function.

Despite the name, you can also use this function to get files.

The following strings can be used as the first argument:

Plugins | Program | Temporary | Profile
Preferences | OS Drive | file:/// | Components
Chrome | Win System | Windows | Mac System
Mac Desktop | Mac Trash | Mac Startup | Mac Shutdown
Mac Apple Menu | Mac Control Panel | Mac Extension | Mac Fonts
Mac Preferences | Mac Documents | Unix Local | Unix Lib

##### getLastError ( )

Returns the last error code generated by the installer functions.

##### getWinProfile ( folder , file )

Returns an object which can be used to read and write to Windows INI files. The arguments specify the folder and filename of the INI file. This function does nothing on non-Windows systems.

##### getWinRegistry ( )

Returns an object which can be used to read and write to the Windows registry. This function does nothing on non-Windows systems.

##### initInstall ( packageName , regPackage , version )

Initializes for an installation. Call this function at the beginning of your installation script. The packageName is the name of the package being installed. This name should be the name as the user sees it. The second parameter should be the registry name of the package. This should be of the form /Company Name/Package Name. The third parameter is a version number of the package.

##### jarfile

A file object that refers to the JAR file of the installer. This property is read only.

##### loadResources ( sourceFile )

Loads the property file from the install archive and returns a string bundle created from it. You can use these strings in dialog boxes to present localized text.

##### logComment ( text )

Logs the specified text to an installation log.

##### patch ( jarPath )
patch ( regName , sourceFile , destDir , target )
patch ( regName , version , sourceFile , destDir , target )

Assigns a patch to be applied to an installed file. Arguments are similar to the addFile function except that the file refers to a patch file instead. An error occurs if the file is not already installed.

##### performInstall ( )

Begins the installation process. Call this at the end of the installation script once you have specified files and directories to be installed.

##### platform

The platform that the package is being installed on. This is equivalent to the value of the navigator.platform property, but it isn't available in install scripts.

##### refreshPlugins ( )

Refreshes the list of installed plugins.

##### registerChrome ( type , folder )
registerChrome ( type , folder , jarpath )

Assigns a new content, skin or locale to be registered into the chrome system. It can then be referred to with a chrome URL. The type may be one of the following values:

- Install.SKIN - Register a new skin
- Install.LOCALE - Register a new locale
- Install.CONTENT - Register a new content package

The folder argument must be one generated from a call to getFolder. The folder should be a reference to the directory containing the contents.rdf manifest file for the chrome to be registered. (not a reference to the contents.rdf file itself however). It may also be a reference to a JAR file, in which case you should set jarpath to the path to the contents.rdf within the JAR file. This function does not install any files. You must call addDirectory or addFile first.

##### resetError ( )

Clears the error code status.

##### setPackageFolder ( folder )

Sets the destination directory for the package. The folder argument should be set to this directory and must be one generated from a call to getFolder.

##### uninstall ( regName )

Uninstalls a package with the given name.

##### url

Returns the URL of the installer archive. This property is read only.

Copyright (C) 1999 - 2004 XulPlanet.com