Select an external file during the installation

This tutorial will guide you in configuring your project to display an Open File dialog during the installation.

A typical installation task would be to allow a registered user to select the license file for your application before or after the package is installed. Since Windows Installer does not provide a way to display an Open File dialog, a custom action is required in order to achieve this task.

Advanced Installer (starting with version 5.0) includes a predefined custom action that will display an Open File dialog, allowing the user to select a file from his system. Optionally, you can customize the dialog to a certain degree by specifying the dialog title, filters and file name that will be used to initialize the Open File dialog.

This feature is available in the Enterprise version of Advanced Installer. The typical use involves adding a "Browse" Button and an Edit control to a new or existing dialog. The user can enter the path to a file manually in the Edit control or click the "Browse" Button to select the file from his system.

1. Displaying an Open File dialog during installation
2. Customizing the Open File dialog
3. Sample project

Displaying an Open File dialog during installation

The steps required for adding this functionality to your Enterprise project are presented below:

1. Switch to the Custom Actions page and add the predefined "BrowseForFile" custom action under the "UI Custom Actions" section. You do not need to modify any settings for this custom action.

2. Switch to the Dialogs page and select the desired dialog in the tree control or create a new one.

3. Add a Button control and an Edit control to this dialog. A Static Text control can be used instead of an Edit control if you do not want the user to enter the file path manually (another method would be to set the "Enabled" attribute of the Edit control to "False").

4. Set the "Text" attribute of the button to "[ButtonText_Browse]" (or some other string value that is appropriate for your project). You can also assign a meaningful name to the Button control by setting the "Name" attribute.

5. Assign a meaningful name to the Edit control and also set its "Property Name" attribute. In what follows, it is assumed that the property attached to the Edit control is called "MY_FILEPATH". This property will be set to the full path of the file selected by the user.

6. Now it is required to link the "BrowseForFile" custom action to the "Browse" button click event. This is done using a DoAction control event. Select the "Browse" button on your dialog, select the "Published Events" tab at the bottom and add a DoAction control event by clicking "New". Configure the control event as follows:

    Event         |    Argument     |   Condition
------------------|-----------------|-----------------
   DoAction       |  BrowseForFile  | (leave default)

7. The next step is to set the property of the Edit control ("MY_FILEPATH") to the full path of the file selected by the user via the Open File dialog. The "BrowseForFile" custom action sets an Advanced Installer-predefined property (named "AI_OFN_FILEPATH") to the path of the file selected by the user. If the user clicks "Cancel" or closes the Open File dialog, "AI_OFN_FILEPATH" will be empty (not set).

In order to achieve this, add a SetProperty control event to the "Browse" button and configure it as shown below. Make sure that this control event comes after the DoAction event defined above. Also make sure that you specify the condition as shown, such that the Edit control is not modified if the user clicks "Cancel" in the Open File dialog. Replace "MY_FILEPATH" with the property attached to your Edit control (or Static Text control).

    Event         |     Argument      |   Condition
------------------|-------------------|-----------------
  [MY_FILEPATH]   | [AI_OFN_FILEPATH] | AI_OFN_FILEPATH

8. Build and run the project to test it. The Open File dialog will not display any filters, will use the default title ("Open") and the "File Name" Edit control will be empty. See the steps below for details on how to specify some or all of these.

Customizing the Open File dialog

You have the possibility to specify the dialog title, filters and file name that will be used to initialize the Open File dialog. However, these are optional.

Specifying these parameters is done using additional SetProperty control events that will be added before the DoAction control event. The Argument for a SetProperty event can be any Formatted value so you can include references to files or folders from your package or to Properties and environment variables.

The order of these additional SetProperty control events is irrelevant. However, it is very important that they are added before the DoAction event.

Specifying a title for the Open File dialog

Is done by defining a SetProperty control event that sets the Advanced Installer-predefined property "AI_OFN_DLG_TITLE" to the appropriate (Formatted) value. Make sure that you add this Event before the DoAction control event, as specified above. Configure the control event as follows:

     Event          |     Argument      |   Condition
--------------------|-------------------|-----------------
 [AI_OFN_DLG_TITLE] | Your dialog title | (leave default)

Specifying the dialog filters

Is done in a similar way as setting the dialog title. You need to set the Advanced Installer-predefined Property "AI_OFN_FILTERS" to the entire filter string using a SetProperty control event. The whole filter string is composed of pairs of individual filter strings. The separator is the pipe character ("|"). You do not need to include the separator at the end of the string.

The first string in each pair is a display string that describes the filter (for example, "Text Files"), while the second string specifies the filter pattern (for example, "*.TXT"). To specify multiple filter patterns for a single display string, use a semicolon to separate the patterns (for example, "*.H;*.C;*.CPP"). A pattern string can be a combination of valid file name characters and the asterisk ("*") wildcard character. You should not include spaces in the pattern string (the "BrowseForFile" custom action will remove them when parsing the string if you do).

Examples of filter string specifications:

• All files (*.*)|*.*
• License files (*.lic)|*.lic|Text files (*.txt)|*.txt
• Text files (*.txt)|*.txt|Source files (*.cpp; *.c; *.h)|*.cpp;*.c;*.h|All files (*.*)|*.*
• License files (*.lic)|*.lic|Old format license files (*.lnc; *.dat)|*.lnc;*.dat|All files (*.*)|*.*

Configure the SetProperty control event as shown below and add it before the DoAction Event. The Argument field is set to a filter string specification as described above:

     Event          |      Argument      |   Condition
--------------------|--------------------|-----------------
 [AI_OFN_FILTERS]   |   <Your filters>   | (leave default)

Specifying a file name (and optionally an initial directory)

Is done by defining a SetProperty control event that sets the Advanced Installer-predefined property "AI_OFN_FILEPATH" to the appropriate Formatted value. This value can include only a file name or a full file path (the directory contained by this path, if it exists, will be used as the initial directory for the Open File dialog).

For instance, considering the license file example, suppose that registered users of your application will usually copy the license ("license.lic") in a folder named "License" located in the root of the system drive. In this case you could configure the SetProperty control event as shown below:

      Event          |               Argument             |   Condition
---------------------|------------------------------------|-----------------
 [AI_OFN_FILEPATH]   | [WindowsVolume]License\license.lic | (leave default)

Recall that this Event must be added before the DoAction control event. For example, the published events for the "Browse" button could look as shown below. The first 3 events at the top of the list are optional while the other 2 are required.

The "AI_OFN_DLG_TITLE" and "AI_OFN_FILTERS" properties will be reset (set to null) when the "BrowseForFile" custom action returns because if there is more than 1 "Browse" button used the filters and dialog title defined for one of the buttons will be used for the other buttons if no explicit definition exists for these other buttons. The "AI_OFN_FILEPATH" property will be empty (null) only if the user clicks "Cancel" or closes the Open File dialog.

The "BrowseForFile" custom action uses the following flags to create the Open File dialog: OFN_EXPLORER, OFN_HIDEREADONLY, OFN_FILEMUSTEXIST, OFN_PATHMUSTEXIST.

Sample project

Download and unzip the Browse For File example project to better understand how to configure your own package. An Enterprise version of Advanced Installer (version 5.0 or greater) is required in order to build and run the project.

The installer allows the user to select a license file which, for illustration purposes, is copied under "Application Data\Your Company\Browse For File Example" folder, using a custom action. A DoAction control event on the "Finish" button from the "ExitDialog" is used to open this folder after the user clicks "Finish".

A brief explanation regarding how the sample project is configured follows:

1. In the Install Parameters page the Application Folder is set to [AppDataFolder][Manufacturer]\[ProductName]. A Custom Action will copy the file selected by the user in this folder.

2. In the Files and Folders page there is defined a Remove File operation such that any files with a "lic" extension are removed from the Application Folder when the package is installed or uninstalled.

3. In the Dialogs page, a new dialog named "SelectLicenseDlg" has been created and both an Edit control and a Button control have been added to this dialog.

4. The property attached to the Edit control is called "THE_LICENSE" and it will contain the full path of the file selected by the user or it will be empty (not set) if no file is selected.

5. Notice how the published events for the "Browse" button have been configured. Refer to the above instructions for more details.

6. In the Custom Actions page, there are defined several custom actions:

a) The predefined "BrowseForFile" custom action is required in order to display the Open File dialog when the "Browse" button is clicked.

b) The other UI Custom Action ("OpenLicenseFolder") is a predefined Launch File or Open URL custom action which will open the folder where the file selected by the user is copied. This custom action is linked to the "Finish" button using a DoAction control event (see below).

c) The first custom action scheduled under "InstallFinalize" is a VBScript Inline custom action which will remove the trailing backslash from the destination folder. Windows Installer adds a trailing "\" to all folder paths and the only way to remove it is using a custom action. This is required in order to avoid problems with the copy operation on Win9x systems.

The Script Inline custom action will create a new property ("LICENSE_DEST_DIR") in which it will copy the full path of the destination folder minus the trailing "\".

d) The "CopyLicense" EXE with Working Dir custom action is used to copy the file selected by the user in the "SelectLicenseDlg" dialog to the destination folder designated by the "LICENSE_DEST_DIR" property (created by the above custom action).

Note how the "Full Path" field is set. For simplicity, it is used the "COPY" command of the command interpreter ("cmd.exe" on NT platforms and "command.com" on Win9x platforms) which is obtained from the "ComSpec" environment variable.

The Execution Condition of this CA ensures that the file is copied only if the "THE_LICENSE" property is not empty. Of course, there is no guarantee that the value of this property designates an existing file or even a valid file path and additional logic (in the "CopyLicense" custom action) is required in order to enforce this.

7. In the Dialogs page, note the DoAction control event for the "Finish" button (from the "ExitDialog") that invokes the "OpenLicenseFolder" custom action defined in the Custom Actions page.