---

AskPath

InstallShield 2009 » InstallScript Language Reference

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 to create the path.

Note

You cannot use the 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 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 function instead.

Syntax

AskPath ( szMsg, szDefPath, svResultPath );

Parameters

AskPath 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 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. 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

AskPath 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

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 Help Library 5 June 2008

|

 

 

 

 

 

 

 

 

 

 

 

 

---

AskPath Example

InstallShield 2009 » InstallScript Language Reference

Note

To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.

/*-----------------------------------------------------------*\

*

* InstallShield Example Script

*

* Demonstrates the AskPath function.

*

* This script obtains the path to a folder on the

* end user's computer.  If the path does not exist, it creates

* a folder at that location if indicated by the

* end user.  Finally, it displays the selected path.

*

\*-----------------------------------------------------------*/

// Include Ifx.h for built-in InstallScript function prototypes.

#include "Ifx.h"

export prototype ExFn_AskPath(HWND);

function ExFn_AskPath(hMSI)

    STRING szMsg, svResultPath[101];

    BOOL bTargetDirOk;

begin

    // Disable the Back button in installation dialogs.

    Disable (BACKBUTTON);

    // Create the message to display in the AskPath dialog.

    szMsg = "Specify a folder for the application.";

    // Initialize valid path indicator.

    bTargetDirOk = FALSE;

    repeat

        // Get a path from the user.  The default path is

        // the current value of the system variable INSTALLDIR.

        if (AskPath (szMsg, INSTALLDIR, svResultPath) = NEXT) then

            // Does the path entered by the user exist on the

            // target system?

            if (ExistsDir (svResultPath) = 0) then

                // If it exists, set indicator to exit the loop.

                bTargetDirOk = TRUE;

            else

                // If the path doesn't exists, ask if it should be created.

                 if (AskYesNo ("Folder does not exist. Create it?",YES) = YES) then

                    // Attempt to create the folder (directory).

                    if (CreateDir (svResultPath) = 0) then

                        // If the folder was created, set indicator to exit the loop.

                        bTargetDirOk = TRUE;

                    else

                        // Inform the end user that the folder was not created.

                        MessageBox ("Unable to create " + svResultPath, WARNING);

                    endif;

                endif;

            endif;

        endif;

    until bTargetDirOk;

    // Display the name of the target folder.

    MessageBox ("The target folder is " + svResultPath, INFORMATION);

    // You'd also enable the Back button for subsequent dialogs.

    Enable (BACKBUTTON);

end;

---

InstallShield Help Library 5 June 2008

|

		Popup

		Popup