diff options
author | Leena Miettinen <riitta-leena.miettinen@theqtcompany.com> | 2015-01-13 14:29:12 +0100 |
---|---|---|
committer | Leena Miettinen <riitta-leena.miettinen@theqtcompany.com> | 2015-01-19 14:26:14 +0100 |
commit | 7c43fead21e01ee2da8d0c3f49d858ab145d538f (patch) | |
tree | 62aee5cca1d9edeb7b123df0e893571067305bc2 /doc | |
parent | 5cb27de6ec5da994aa61f0bcc94f0b396051992d (diff) |
Doc: add information about control scripts
Modify the Customizing Installers topic to also
discuss Control scripts.
Change-Id: I7a140c9bcf913ae914bf4c611f658ecc70c84fce
Reviewed-by: Jarek Kobus <jaroslaw.kobus@theqtcompany.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/installerfw.qdoc | 118 | ||||
-rw-r--r-- | doc/operations.qdoc | 2 |
2 files changed, 100 insertions, 20 deletions
diff --git a/doc/installerfw.qdoc b/doc/installerfw.qdoc index 74fabf6bc..4467eaac1 100644 --- a/doc/installerfw.qdoc +++ b/doc/installerfw.qdoc @@ -315,32 +315,67 @@ \title Customizing Installers - The following sections describe how you can extend the predefined installer - by adding operations to the pages and by adding new pages and language - variants. + You can use scripting to customize installers by: + + \list + + \li Adding Qt Installer Framework \e operations that are prepared by the + scripts and performed by the installer. + + \li Adding new pages that you specify in the package.xml file and place + in the \c packages directory. + + \li Modifying existing pages by inserting custom user interface + elements into them as single widgets. + + \li Adding language variants. + + \endlist + + You can use both \e {component scripts} and a \e {control script} to + customize installers. A component script is associated with a particular + component by specifying it in the \c Script element of the package.xml + file of the component. The script is loaded when the component's metadata is + fetched. For more information about component scripts, see + \l{Component Scripting}. + + A control script is associated with the whole installer by specifying it + in the \c ControlScript element of the control.xml file of the installer. + Control scripts can be part of the installer resources or be passed on the + command line. They can be used to modify the installer pages that are + presented to users before components are loaded. Also, you can use them to + modify pages in the uninstaller. For more information, see + \l{Controller Scripting}. + + For more information about the global JavaScript objects that can be used in + component and control scripts, see \l{Scripting API}. \section1 Adding Operations - Components can use the ECMAScript scripting language to perform additional - operations at any time during the installation process. Typically, - components manipulate files by moving, copying, or patching them. + You can use component scripts to perform Qt Installer Framework operations + during the installation process. Typically, operations manipulate files by + moving, copying, or patching them. Use the + QInstaller::Component::addOperation or + QInstaller::Component::addElevatedOperation function to add operations. For + more information, see \l {Adding Operations to Components}. - For more information about scripting, see \l{Component Scripting}. + In addition, you can implement methods to register custom installation + operations in the installer by deriving KDUpdater::UpdateOperation. For + more information, see \l {Registering Custom Operations}. + + For a summary of available operations, see \l {Operations}. \section1 Adding Pages A component can contain one or more user interface files, which are placed - into the installer by a script. The installer automatically loads all user - interface files listed in package.xml. You can access the loaded widgets - by calling \c QInstaller::Component::userInterface with the class name of - the widget, as illustrated by the following code snippet: + into the installer by a component or control script. The installer + automatically loads all user interface files listed in the + \c UserInterfaces element of the package.xml file. - \code - component.userInterface( "MyPage" ).checkbox.checked = true; - \endcode + \section2 Using Component Scripts to Add Pages To add a new page to the installer, use - the \c QInstaller::Installer::addWizardPage method and specify the location + the installer::addWizardPage() method and specify the location of the new page. For example, the following code adds an instance of \c MyPage before the ready for installation page: @@ -348,13 +383,45 @@ installer.addWizardPage( component, "MyPage", QInstaller.ReadyForInstallation ); \endcode + You can use component scripts to access the loaded widgets + by calling the \l component::userInterface() method with the class name of + the widget, as illustrated by the following code snippet: + + \code + component.userInterface( "MyPage" ).checkbox.checked = true; + \endcode + + \section2 Using Control Scripts to Add Pages + + To register a custom page, use the installer::addWizardPage() method + and the object name set in the UI file (for example, \c "MyPage"). Then + call the \c{Dynamic${ObjectName}Callback()} function (for example, + \c {DynamicMyPageCallback()}): + + \code + function Controller() + { + installer.addWizardPage(component, "MyPage", QInstaller.TargetDirectory) + } + + Controller.prototype.DynamicMyPageCallback() + { + var page = gui.pageWidgetByObjectName("DynamicMyPage"); + page.myButton.click, + page.myWidget.subWidget.setText("hello") + } + \endcode + + You can access widgets by using their object names that are set in the UI + file. For example, \c myButton and \c myWidget are widget object names in + the code above. + \section1 Adding Widgets - You can also insert custom user interface elements into the installer as - single widgets (such as a check box). + You can use component or control scripts to insert custom user interface + elements into the installer as single widgets (such as a check box). - To insert a single widget, use the - \c QInstaller::Installer::addWizardPageItem method. + To insert a single widget, use the installer::addWizardPageItem method. For example, the following code snippet adds an instance of \c MyWidget to the component selection page from within a script: @@ -362,6 +429,19 @@ installer.addWizardPageItem( component, "MyWidget", QInstaller.ComponentSelection ); \endcode + \section1 Interacting with Installer Functionality + + You can use control scripts to execute installer functions automatically in + tests, for example. The following snippet illustrates how to automatically + click the \uicontrol Next button on the target directory selection page: + + \code + Controller.prototype.TargetDirectoryPageCallback = function() + { + gui.clickButton(buttons.NextButton); + } + \endcode + \section1 Translating Pages The installer uses the Qt Translation system to support the translation of diff --git a/doc/operations.qdoc b/doc/operations.qdoc index 3e3b05e7c..ed1465648 100644 --- a/doc/operations.qdoc +++ b/doc/operations.qdoc @@ -33,7 +33,7 @@ \title Operations - The operations are prepared by component scripts and performed by the + The operations are prepared by component and controller scripts and performed by the installer. \note Operations are performed threaded. |