Summary
This article discusses how to display a file open / browse dialog in a Basic MSI project.
Synopsis
This article discusses how to display a file open / browse dialog in a Basic MSI project.
Discussion
Launching a File Open / Browse Dialog
This information applies to Basic MSI projects.
InstallShield includes support for launching the Open dialog from one of the dialogs in your Basic MSI installation. End users click a browse button in one of your dialogs, and this launches the Open dialog. The Open dialog lets the end user browse for a file. When the end user selects the file and clicks the Open button, the Open dialog closes, and the installation writes the full path and file name in an edit field on the dialog. The installation also sets the value of the IS_BROWSE_FILEBROWSED property to the path and file name of the file that the end user selected.
When you incorporate support for the Open dialog in your installation, you can define several properties to specify the following functionality:
| | ? | You can specify the default path that is displayed in this dialog. |
| | ? | You can specify the string that should be displayed in the Files of type drop-down list on the Open dialog. |
| | ? | You can specify the file extensions of the files that should be displayed when the end user is browsing through folders to select a file. All files that have other file extensions are hidden and cannot be selected to open. |
| | ? | You can specify the default file extension that the Open dialog should use. If the end user does not type an extension, the Open dialog appends this default extension to the file name. |
Note the following requirements for this dialog:
| | ? | The Open dialog does not allow end users to create a new file. That is, if a file does not exist, an end user cannot manually type a new file name in the Open dialog. |
| | ? | If the dialog that launches the Open dialog has more than one edit field control, the edit field control that will contain the full path to the file must have the lowest value for the Tab Stop property. |
To add the Open dialog functionality to an end-user dialog:
| | 1. | Add to your project a new MSI DLL custom action called FileBrowse: |
| | a. | In the View List under Behavior and Logic, click Custom Actions and Sequences. |
| | b. | Right-click the Custom Actions explorer, point to New MSI DLL, and then click Stored in Binary table. InstallShield adds a new custom action called NewCustomActionN, where N is a successive number. |
| | c. | Change the name of the custom action to FileBrowse. |
| | d. | In the pane on the right, configure the following settings for this custom action: |
| | ? | DLL Filename: <ISRedistPlatformDependentFolder>\FileBrowse.dll |
| | ? | Function Name: FileBrowse |
| | ? | Return Processing: Synchronous (Ignores exit code) |
| | ? | In-Script Execution: Immediate Execution |
| | ? | Execution Scheduling: Always execute |
For all other settings, leave the default values. The value of the MSI Type Number setting should be 65.
| | 2. | Create or edit the dialog that should launch the Open dialog, and configure its behavior and layout: |
| | a. | In the View List under User Interface, click Dialogs. |
| | b. | In the Dialogs explorer, expand the All Dialogs folder. |
| | c. | Either select an existing dialog or create a new dialog. |
Note that if you select an existing dialog and it has more than one edit field control, the edit field control that will contain the full path to the file must have the lowest value for the Tab Stop property.
| | d. | Under this dialog, click the language whose layout you want to configure. |
| | e. | Add the edit field control that will contain the full path and file name that the end user selects at run time. When InstallShield prompts you for the property name associated with the control, enter IS_BROWSE_FILEBROWSED. |
| | f. | Next to the edit field control, add a push button control. This is the button that will launch the Open dialog. |
| | g. | Select the push button control and then edit its properties in the grid on the right as needed. For example, to specify the text that you want to be displayed on the button, add a value for the Text property. |
| | h. | In the Dialogs explorer, click the Behavior item under the dialog that you are configuring. |
| | i. | In the center pane that lists the dialog controls, click the push button control that you just created. Its settings are displayed in the right pane. |
| | j. | In the Events setting, click the New Event button, and then click DoAction. InstallShield adds a new set of rows under the Events setting. |
| | k. | In the DoAction setting, enter the following: 1 |
| | l. | In the Action subsetting, specify the following action name: FileBrowse |
| | m. | In the Events setting, click the New Event button, and then click SetProperty. InstallShield adds a new set of rows under the Events setting. |
| | n. | In the SetProperty setting, enter the following: 1 |
| | o. | In the Property subsetting, specify the following action name: IS_BROWSE_FILEBROWSED |
| | p. | In the Value subsetting, specify the following action name: [IS_BROWSE_FILEBROWSED] |
Note ? The SetProperty Event refreshes the MSI property value displayed in the Edit field control on the dialog, so that the displayed MSI property value is updated after selecting a file in the file browse window.
| | 3. | Configure several properties to specify behavior of the Open dialog and the dialog that launches the Open dialog: |
| | a. | In the View List under Behavior and Logic, click Property Manager. |
| | b. | Find the IS_BROWSE_FILEBROWSED property. Its default value is 0. Do one of the following: |
| | ? | To leave the edit field control blank in your dialog when the end user first displays it, right-click the row that has the IS_BROWSE_FILEBROWSED property and then click Delete Property. |
| | ? | To display a default path and file name in the edit field control, change the value of the IS_BROWSE_FILEBROWSED property to the path and file name. |
Note ? If you do not manually change the value of this property or delete this property, the default value for the edit field control on the dialog that launches the Open dialog is set to 0.
| | c. | Optionally, add a property called IS_BROWSE_FILEEXT, and set its value to a filter string that identifies the file extensions that should be displayed when the end user is browsing through folders to select a file. All files that have other file extensions are hidden and cannot be selected to open. |
A filter string can be a combination of valid file name characters and the asterisk (*) as a wild-card character.
To specify multiple file extensions, separate each with a semicolon. Do not include spaces. For example, to let end users select .exe and .dll files, enter the following string as the value of the IS_BROWSE_FILEEXT property: *.exe;*.dll
In this example, the Open dialog lets end users select .exe and .dll files. It hides all other file types.
If you do not set this property, the Open dialog lets end users select any file type.
| | d. | Optionally, add a property called IS_BROWSE_FILETYPE, and set its value to the string that you want to be displayed in the Files of type drop-down list on the Open dialog. Note that only one option can be displayed in this drop-down list. |
For example, if you want end users to be able to select .txt or .doc files, enter the following string as the value of the IS_BROWSE_FILETYPE property:
Text Files (*.txt); Word documents (*.doc)
If you do not set this property, the Files of type drop-down list in the Open dialog is blank.
| | e. | Optionally, add a property called IS_BROWSE_DEFAULTEXTENSION, and set its value to the default file extension that the Open dialog should use. If the end user does not type an extension, the Open dialog appends this default extension to the file name. For example, to use .exe as the default file extension, enter the following string as the value of the IS_BROWSE_DEFAULTEXTENSION property: exe |
| | f. | Optionally, add a property called IS_BROWSE_INITIALDIR, and set its value to the default path that the Open dialog should use. For example, to use C:\Program Files\My Product, enter the following string as the value of the IS_BROWSE_INITIALDIR property: C:\Program Files\My Product |
At run time, when the end user clicks the new push button control, the Open dialog opens. The end user can browse to and select a file. The installation sets the value of the IS_BROWSE_FILEBROWSED property to the path and file name of the file that the end user selected, and then it displays that path and file name in the edit field control on the dialog that launched the Open dialog.
Additional Information
HelpNet article: Launching a File Open Dialog
Case id: 00001065
Activity: Status change: 2 hours ago