How to select an external file during the installation
The following article uses options that are available starting
with the Enterprise edition and project
type.
There are projects that may need to be configured 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 requires at least an Enterprise license.
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. Display an Open File dialog during installation
The steps required for adding this functionality to your Enterprise or Architect project are presented below:
1.1 Switch to the Custom Actions page and add the predefined "BrowseForFile" custom action without sequence. You do not need to modify any settings for this custom action.
1.2 Switch to the Dialogs page and select the desired dialog in the tree control or create a new one.
1.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").
1.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.
1.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.
1.6 Now it is required to link the "BrowseForFile" custom action to the "Browse" button click event. This is done using an "Execute custom action" control event. Select the "Browse" button on your dialog, select the "Published Events" tab at the bottom and add an "Execute custom action" control event by clicking “New”. Configure the control event as follows:
| Event | Argument | Condition |
|---|---|---|
| Execute custom action | BrowseForFile | (leave default) |
1.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 "Set installer property value" control event to the "Browse" button and configure it as shown below. Make sure that this control event comes after the "Execute custom action" 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 |
1.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.
2. Customize 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 "Set installer property" value control events that will be added before the "Execute custom action" control event. The Argument for a "Set installer property value" 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 "Set installer property value" control events is irrelevant. However, it is very important that they are added before the "Execute custom action" event.
2.1 Specifying a title for the Open File dialog
Is done by defining a "Set installer property value" 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 "Execute custom action" control event, as specified above. Configure the control event as follows:
| Event | Argument | Condition |
|---|---|---|
| [AI_OFN_DLG_TITLE] | Your dialog title | (leave default) |
2.2 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 "Set installer property value" 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 "Set installer property value" control event as shown below and add it before the "Execute custom action" Event. The Argument field is set to a filter string specification as described above:
| Event | Argument | Condition |
|---|---|---|
| [AI_OFN_FILTERS] | <Your filters> | (leave default) |
2.3 Specifying a file name (and optionally an initial directory)
Is done by defining a "Set installer property value" 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 "Set installer property value" 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 "Execute custom action" 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.
3. Sample project
Download and unzip the Browse for file example project to better understand how to configure your own package. At least 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. An "Execute custom action" 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:
3.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.
3.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.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.
3.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.
3.5 Notice how the published events for the "Browse" button have been configured. Refer to the above instructions for more details.
3.6 In the Custom Actions page, there are defined several custom actions:
- The predefined "BrowseForFile" custom action is required in order to display the Open File dialog when the "Browse" button is clicked.
- The other custom action without sequence ("OpenLicenseFolder") is a predefined "Launch file" 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 an "Execute custom action" control event (see below).
- The "CopyLicense" Launch EXE with working directory custom action is used to copy the file selected by the user in the "SelectLicenseDlg" dialog to the destination folder designated by the "APPDIR" property.
Note how the "Command Line" field is set. For simplicity, it is used the "COPY" command of the command interpreter ("cmd.exe" on NT 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.
3.7 In the Dialogs page, note the "Execute custom action" control event for the "Finish" button (from the "ExitDialog") that invokes the "OpenLicenseFolder" custom action defined in the Custom Actions page.