diff options
Diffstat (limited to 'doc/scripting.qdoc')
| -rw-r--r-- | doc/scripting.qdoc | 305 |
1 files changed, 305 insertions, 0 deletions
diff --git a/doc/scripting.qdoc b/doc/scripting.qdoc new file mode 100644 index 000000000..ece1e0fce --- /dev/null +++ b/doc/scripting.qdoc @@ -0,0 +1,305 @@ +/*! + \contentspage{index.html}{InstallerFramework} + \page scripting.html + + \title Component Scripting + + \section1 Scripting abilities inside of components + + Each component can specify one script, which is loaded and run by the + installer. The format has to be compatible to QScriptEngine. + + \section1 Contruction + + The script has to provide an object Component, which will be created by the + Installer when loading the script. Therefore the script must contains at + least a function Component(), which can do all the initialization needed, + like putting user interfaces in place or connecting signals/slots: + + \code + function Component() + { + // let's assume we have a user interface ErrorPage - which should not be complete + installer.addWizardPage( component, "ErrorPage", QInstaller.ReadyForInstallation ); + component.userInterface( "ErrorPage" ).complete = false; + } + \endcode + + The example above places the user interface "ErrorPage" (which is the class + name of the ui file loaded from errorpage.ui) in front of the installer + page "Ready for Installation" and sets his completeness to false. See the + documentation for addWizardPage and userInterface for details. + + \section1 Installer Hooks + + You can add several hook methods into your script: + + \list + \o \bold{Component.prototype.retranslateUi} is called, whenever the language of the Installer changes. + \o \bold{Component.prototype.createOperations} - see QInstaller::Component::createOperations + \o \bold{Component.prototype.createOperationsForArchive} - see QInstaller::Component::createOperationsForArchive + \o \bold{Component.prototype.createOperationsForPath} - see QInstaller::Component::createOperationsForPath + \endlist + + \section1 Global variables + + The Installer puts the following symbols into the scripts space: + + \list + \o \bold{installer} A reference to the component's Installer + \o \bold{component} A reference to the component's Component + \endlist + + All methods marked with \a Q_INVOKABLE as well as all signals, slots and + properties can be used by the script. + + \section1 Message boxes + + You can show a QMessageBox from within the script by using: + + \code + QMessageBox.critical + QMessageBox.information + QMessageBox.question + QMessageBox.warning + \endcode + + For your convenience, the values for QMessageBox::StandardButton are made + available by using QMessageBox.Ok, QMessageBox.Open, ... + + \section1 Adding operations to the component + + In certain situations if it very useful to add custom operations after + extracting the content. Those include copying files as well as patching + content of files, etc. + Update operations can be created and added to the installation from within + a script using QInstaller::Component::addOperation. + Every operation has an unique key used for identification and up to five + parameters. Inside of the parameters, you can use variables as set in + QInstaller::Installer::setValue. See the list of + \l{Predefined variables}{predefined variables}. + + Following a list of all available operations, which + can be added to a installation script. + + \section2 Copy + + \bold Syntax: "Copy" \a source \a target + + Copies a file from \a source to \a target. + + + \section2 Move + + \bold Syntax: "Move" \a source \a target + + Moves a file from \a source to \a target. + + + \section2 Delete + + \bold Syntax: "Delete" \a filename + + Deletes the file specified by \a filename. + + + \section2 Mkdir + + \bold Syntax: "Mkdir" \a path + + Creates the directory path \a path. + + + \section2 Rmdir + + \bold Syntax: "Rmdir" \a path + + Removes the directory path \a path. + + + \section2 AppendFile + + \bold Syntax: "AppendFile" \a filename \a text + + Appends \a text to the file specified by \a filename. \a is threated as ASCII text. + + + \section2 PrependFile + + \bold Syntax: "PrependFile" \a filename \a text + + Prepends \a text to the file specified by \a filename. \a is threated as ASCII text. + + + \section2 Execute + + \bold Syntax: "Execute" [{\a exitcodes}] \a command [\a parameter1 [\a parameter2 [\a parameter3 [\a parameter4]]]] + + Executes the command specified by \a command. Up to four parameters can be passed. + + Optionally, you can pass a comma separated list of numbers in {} as first argument, which defines the "valid" exit codes + of the process, i.e. the codes the execution is considered being successful. This defaults to "{0}". + + \section2 CreateShortcut + + \bold Syntax: "CreateShortcut" \a filename \a linkname [\a arguments] + + Creates a shortcut from the file specified by \a filename to \a linkname. + On Windows, this will create a .lnk file which can have \a arguments, on Unix this will create a symobic link. + + + \section2 CreateDesktopEntry + + \bold Syntax: "CreateDesktopEntry" \a filename \a "key=value[\nkey2=value2[\nkey3=value3]]]" + + Creates an INI-file like .desktop file as specified by freedesktop.org + If \a filename is absolute, the desktop entry is stored there. Otherwise it's stored in locations defined in $XDG_DATA_DIRS/applications + or $XDG_DATA_HOME/applications, including the default pathes for boths, as defined by freedesktop.org. + + The key/value pairs are written in the file. + + The file is set to a encoding of UTF-8. + + \section2 InstallIcons + + \bold Syntax: "InstallIcons" \a directory + + Installs the contents of \a directory into a location as specified by freedesktop.org, i.e. in any of $XDG_DATA_DIRS/icons or /usr/share/icons + or $HOME/.icons. The files are removed from their initial location. Make sure to add this operation after the operation extracting them form the archive. + + \section2 Extract + + \bold Syntax: "Extract" \a archive \a targetdirectory + + Extracts \a archive to \a targetdirectory + + + \section2 GlobalConfig + + \bold Syntax: "GlobalConfig" \a company \a application \a key \a value <br> + \a or <br> + \bold Syntax: "GlobalConfig" \a filename \a key \a value + + Stores \a value for \a key in a configuration file. The configuration file is either + specified by \a filename (using QSettings::NativeFormat, which might be the Windows registry) + or via the \a application and the \a company name. + + + \section2 EnvironmentVariable + + \bold Syntax: "EnvironmentVariable" \a key \a value [[\a persistent] \a system] + + Sets the envirnoment variable \a key to a \a value. If \a persistent is set to true, the variable + will be set persistently. This is currently only supported on Windows. If \a system is set to true, the + persistent variable will be set system wide, not only for the current user. + + + \section2 RegisterFileType + + \bold Syntax: "RegisterFileType" \a extension \a command [\a description [\a contentType [\a icon]]]. + + Registers the file type with \a extension to be opened via \a command. Optionally, you can specify + a \a description, a \a contentType and an \a icon. This is currently only supported on Windows. + + + \section1 Custom Operations + + It is possible to register custom installation operations in the Installer. This works by deriving KDUpdater::UpdateOperation. + See the following code to know which methods must be implemented: + + \code + #include <KDUpdater/UpdateOperation> + + class CustomOperation : public KDUpdater::UpdateOperation + { + public: + CustomOperation() + { + setName( "CustomOperation" ); + } + + void backup() + { + // do whatever is needed to restore the state in undoOperation() + } + + bool performOperation() + { + const QStringList args = arguments(); + // do whatever is needed to do for the given arguments + + bool success = ...; + return success; + } + + void undoOperation() + { + // restore the previous state, as saved in backup() + } + + bool testOperation() + { + // currently unused + return true; + } + + CustomOperation* clone() const + { + return new CustomOperation; + } + + QDomDocument toXml() + { + // automatically adds the operation's arguments and everything set via setValue + QDomDocument doc = KDUpdater::UpdateOperation::toXml(); + + // if you need any information to undo the operation you did, + // add them to the doc here + + return doc; + } + + bool fromXml( const QDomDocument& doc ) + { + // automatically loads the operation's arguments and everything set via setValue + if( !KDUpdater::UpdateOperation::fromXml( doc ) ) + return false; + + // if you need any information to undo the operation you did, + // read them from the doc here + + return true; + } + }; + \endcode + + Finally, you need to register your custom operation class: + \code + #include <KDupdater/UpdateOperationFactory> + + KDUpdater::UpdateOperationFactory::instance().registerUpdateOperation< CustomOperation >( "CustomOperation" ); + \endcode + + Now you can use your operation in the installer like every other of the predefined operations. + + \section1 Predefined variables + + Inside scripts you can use predefined variables to ease directory access. Those variables are + + \list + \o \bold ProductName The name of the product to be installed as defined in config.xml + \o \bold ProductVersion The version of the product to be installed as defined in config.xml + \o \bold Title The title of the installation program as defined in config.xml + \o \bold Publisher The publisher of the installation program as defined in config.xml + \o \bold Url Product URL as defined in config.xml + \o \bold StartMenuDir Start menu group as defined in config.xml. Applies only to Microsoft Windows + \o \bold LicenseFile File name of the program license as defined in config.xml + \o \bold TargetDir Target directory for installation as selected by the user. + \o \bold DesktopDir Directory containing the user's desktop. + \o \bold os The current platform, might be "x11", "win" or "mac" + \endlist + + \note You can use these variables inside of the parameter list for + installation operations. \a{"{TargetDir}/settings.xml"} might be expanded + to \a{"C:/Program Files/My Program/settings.xml"}. +*/ |