Open ReadMe Example | Qt Installer Framework Documentation 4.11.0

- Qt Installer Framework Documentation
- Tutorials and Examples
- Open ReadMe Example
- Qt Installer Framework 4.11.0

# Open ReadMe Example

Using a component script to add a check box for opening the readme file to the final installer page.

Open ReadMe illustrates how to use the `Component()` function to add a check box to the installation finished page and to open the readme file if end users select the check box.

## Configuring the Example Installer

The installer configuration file, config.xml, in the `config` directory specifies the text and default values used in the installer:

- The `<Name>` element sets the application name and adds it to the page name and introduction text.
- The `<Version>` element sets the application version number.
- The `<Title>` element sets the installer name and displays it on the title bar.
- The `<Publisher>` element sets the publisher of the software (as shown in the Windows Control Panel, for example).
- The `<StartMenuDir>` element sets the name of the default program group for the product in the Windows Start menu.
- The `<TargetDir>` element sets the default target directory location to be within the `IfwExamples` directory in the home directory of the current user (because it uses the pre-existing variable `,` @HomeDir@, as part of the value). For more information, see Predefined Variables.

     <?xml version="1.0" encoding="UTF-8"?>
     <Installer>
         <Name>Open Readme Example</Name>
         <Version>1.0.0</Version>
         <Title>Open Readme Example</Title>
         <Publisher>Qt-Project</Publisher>
         <StartMenuDir>Qt IFW Examples</StartMenuDir>
         <TargetDir>@HomeDir@/IfwExamples/openreadme</TargetDir>
     </Installer>

## Creating the Example Package Information File

The installer package information file, package.xml, in the `meta` directory specifies the components that are available for installation:

- The `<DisplayName>` element sets the human-readable name of the component.
- The `<Description>` element sets the human-readable description of the component.
- The `<Version>` element sets the version number of the component.
- The `<ReleaseDate>` element sets the date of release for this component version.

- The `<Default>` element is set to `true` to preselect the component in the installer.
- The `<Script>` element specifies the file name of the JavaScript file that is loaded to perform operations.
- The `<UserInterfaces>` element specifies the file name of the installer page (.ui file) to use.

     <?xml version="1.0" encoding="UTF-8"?>
     <Package>
         <DisplayName>Open readme</DisplayName>
         <Description>Show checkbox asking whether to open Readme at the end</Description>
         <Version>1.0.0-1</Version>
         <ReleaseDate>2013-01-01</ReleaseDate>
         <Default>true</Default>
         <Script>installscript.qs</Script>
         <UserInterfaces>
             <UserInterface>readmecheckboxform.ui</UserInterface>
         </UserInterfaces>
     </Package>

## Opening Files After Installation

In installscript.qs, we use the `Component()` function to connect to the `installationFinishedPageIsShown` signal when the installation is complete and to the `installationFinished` signal when the end users click Finish (Done on macOS):

     function Component()
     {
         installer.installationFinished.connect(this, Component.prototype.installationFinishedPageIsShown);
         installer.finishButtonClicked.connect(this, Component.prototype.installationFinished);
     }

We call the component::createOperations() function to override the default method for creating operations:

     Component.prototype.createOperations = function()
     {
         component.createOperations();
     }

If the installation is successful, we call the installer::addWizardPageItem() function to replace the last installer page with a custom page that contains the OpenReadMe check box:

     Component.prototype.installationFinishedPageIsShown = function()
     {
         try {
             if (installer.isInstaller() && installer.status == QInstaller.Success) {
                 installer.addWizardPageItem( component, "ReadMeCheckBoxForm", QInstaller.InstallationFinished );
             }
         } catch(e) {
             console.log(e);
         }
     }

We set the `readMeCheckBox` to `checked` by default and use the QDesktopServices::openURL() function to open the readme file:

     Component.prototype.installationFinished = function()
     {
         try {
             if (installer.isInstaller() && installer.status == QInstaller.Success) {
                 var checkboxForm = component.userInterface( "ReadMeCheckBoxForm" );
                 if (checkboxForm && checkboxForm.readMeCheckBox.checked) {
                     QDesktopServices.openUrl("file:///" + installer.value("TargetDir") + "/README.txt");
                 }
             }
         } catch(e) {
             console.log(e);
         }
     }

## Generating the Example Installer

To create the example installer, switch to the example source directory on the command line and enter the following command:

- On Windows:

       ..\..\bin\binarycreator.exe -c config\config.xml -p packages installer.exe

- On Linux or macOS:

       ../../bin/binarycreator -c config/config.xml -p packages installer

This creates the installer to the current directory.

Files:

- openreadme/config/config.xml
- openreadme/openreadme.pro
- openreadme/packages/or.qtproject.ifw.example.openreadme/data/README.txt
- openreadme/packages/or.qtproject.ifw.example.openreadme/meta/installscript.qs
- openreadme/packages/or.qtproject.ifw.example.openreadme/meta/package.xml
- openreadme/packages/or.qtproject.ifw.example.openreadme/meta/readmecheckboxform.ui