InstallShield 2014 » InstallScript Language Reference
Project: This information applies to the following project types:
| • | InstallScript |
| • | InstallScript MSI |
The AskPath function displays a dialog that prompts the end user to enter the path to a destination location. The dialog contains a single-line edit field in which you can display a default path. The end user has three options:
| • | Accept the default path. |
| • | Edit the default path. |
| • | Display the Choose Folder dialog to select a folder. |
To open the Choose Folder dialog, the end user must click the Browse button. The Choose Folder dialog displays a list of all available folders. The end user can select an existing folder or enter a new folder name. If the end user enters the name of a folder that does not exist, the folder is created.
Caution: AskPath does not verify the existence of the path entered by the end user. After calling AskPath, call CreateDir to create the path.
Note: You cannot use the PlaceWindow function in conjunction with the AskPath function. By default, the dialog opens in the center of the desktop, unless the background window mode is enabled. If the installation is in window mode, the dialog opens in the center of the background window.
The default title for the dialog is Choose Destination Location. To change the title, call SetDialogTitle before calling AskPath.
The AskPath function accepts the name of a folder that exists but is not writable. To limit the end user's selection to writable folders, call the AskDestPath function instead.
Syntax
AskPath ( szMsg, szDefPath, svResultPath );
Parameters
|
Parameter |
Description |
|
szMsg |
Specifies the message to display in this dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter. |
|
szDefPath |
Specifies the default path to display in the edit field. The end user can modify this string. |
|
svResultPath |
Returns the resulting path, regardless of whether the user accepts the default path, modifies it, or selects an alternate path from the Choose Folder dialog. AskPath adds a backslash to the end of the path before placing it into svResultPath. If necessary, that backslash can be removed by calling StrRemoveLastSlash after AskPath returns. If the user clicks the Back button, the value of svResultPath will be unpredictable. Therefore, if you are using the same variable for both szDefPath and svResultPath, be sure to reinitialize that variable when the return value from AskPath is BACK. Note: The edit field displayed in the dialog scrolls to accommodate long strings. Because the number of characters that can be entered into the edit field is not limited, you should declare the variable passed in svResultPath without an explicit size. If the string variable is not large enough to store the text entered by the user, the string is truncated and an error message is displayed. Because this function appends a backslash and a NULL terminator to the end of the string, the size of the string must be at least two characters longer than the path entered by the user. |
Return Values
|
Return Value |
Description |
|
NEXT (1) |
Indicates that the end user clicked the Next button. |
|
BACK (12) |
Indicates that the end user clicked the Back button; svResultPath is set to a null string (""). |
Additional Information
AdminAskPath uses the AskPath dialog, and it uses the same dialog resources as AskPath. Therefore, any changes you make to the layout of AskPath in the Dialog Editor are reflected in AdminAskPath.
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.
See Also
InstallShield 2014 Help LibraryMay 2014 |
Copyright Information | Contact Us |