AddFolderIcon

InstallShield 2018 » InstallScript Language Reference

The CreateShortcut function supersedes the AddFolderIcon function.

The AddFolderIcon function lets you perform tasks such as the following:

•

Create a shortcut or folder on the Start menu, the Programs menu, or the desktop. Use the szProgramFolder parameter to specify the appropriate location for the shortcut or folder.

•

Create a cascading submenu on the Startup menu, and include a shortcut in the submenu.

Note • The shortcut target must be present on the target system before AddFolderIcon can be called.

AddFolderIcon does not support the creation of Internet shortcuts.

Syntax

AddFolderIcon ( szProgramFolder, szItemName, szCommandLine, szWorkingDir, szIconPath, nIcon, szShortCutKey, nFlag );

Parameters

AddFolderIcon Parameters

Parameter

Description

szProgramFolder

Specify the name of the folder that should contain the shortcut, or specify the name of the program folder that you want to create. If the folder does not exist, the installation creates it. For this parameter, you can specify a subfolder in a multi-level cascading menu. If the subfolder does not exist, AddFolderIcon creates the subfolder and, if necessary, its parent folders.

To add the shortcut to a specific folder, specify the fully qualified path—for example:

C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs

To add a shortcut to the Programs menu on the Start menu, you can pass a null string ("") in this parameter.

You can pass one of the following InstallScript system variables in this parameter:

•

FOLDER_DESKTOP—Adds the shortcut to the desktop.

•

FOLDER_STARTUP—Adds the shortcut to the Startup menu.

•

FOLDER_STARTMENU—Adds the shortcut to the Start menu.

•

FOLDER_PROGRAMS—Adds the shortcut to the Start\Programs menu.

You can also specify a path relative to a folder that is identified by an InstallScript system variable—for example:

FOLDER_PROGRAMS ^ “ACCESSORIES\\GAMES”

szItemName

Specify the name of the shortcut. Calling AddFolderIcon to add a shortcut to a program folder also creates a link file in the links directory that is specified by szCommandLine. Note that Explorer shell does not allow the following characters in item names: /, \, :, ?, <, >, or |.

szCommandLine

Specify one of the following:

•

The fully qualified name of the executable file that is associated with the shortcut, including any command-line parameters. This is added to the Target value on the shortcut’s Properties dialog box. To add a shortcut to the Start Programs menu, enter the fully qualified path of the links directory, which is where your application stores its icon link files.

•

The fully qualified path if szItemName is a subfolder.

Caution • If the command line includes a long file name, it must be enclosed in quotes. Command-line parameters, however, should not be surrounded with quotation marks. For that reason, it is advisable to build the szCommandLine string from two separate strings.

szWorkingDir

Specify the working directory for the shortcut target.

If szItemName is a subfolder, this parameter is not applicable.

AddFolderIcon writes this directory in the Start In box on the Shortcut tab of the shortcut’s Properties dialog box. If you pass a null string ("") in this parameter, the function leaves this Start In box blank, and the path in the Target box is used.

Caution • Do not call LongPathToQuote to enclose this path in quotation marks. InstallShield automatically encloses these paths in quotation marks.

szIconPath

Specify the fully qualified path to the file that contains the icon that you want to be displayed for the shortcut.

If szItemName is a subfolder, this parameter is not applicable.

Caution • Do not call LongPathToQuote to enclose this path in quotation marks. InstallShield automatically encloses these paths in quotation marks.

nIcon

Specify the icon index in the executable file that is specified by szIconPath. An icon index of 0 refers to the first icon in the file, an icon index of 1 refers to the second icon, and so on. If you are not using an icon, specify 0 in this parameter.

If szItemName is a subfolder, this parameter is not applicable.

szShortCutKey

Specify the shortcut key (in the form of a string) that you want to be assigned to your shortcut. You can set szShortCutKey for the shortcut so that end users can press the appropriate hot keys to launch the shortcut.

For example, if you want end users to be able to launch the product by pressing the CTRL key, the ALT key, and then the 1 key on the numeric keyboard, pass “Ctrl + Alt + 1” in this parameter.

If szItemName is a subfolder, this parameter is not applicable.

nFlag

Pass one or more of the following predefined constants in this parameter. To pass two or more predefined constants in this parameter, combine those constants with the bitwise OR operator ( | ).

•

REPLACE—Indicates that the current icon or shortcut in the folder is to be replaced.

•

RUN_MAXIMIZED—Indicates that the program should be maximized when launched.

•

RUN_MINIMIZED—Indicates that the program should be minimized when launched.

•

NULL—Indicates no options.

Return Values

AddFolderIcon Return Values
Return Value	Description
0	Indicates that the function successfully added or replaced the shortcut in the specified folder and associated the executable file with it.
< 0	Indicates that the function was unable to add or replace the shortcut and associate the executable file with it. You can obtain the error message text associated with a large negative return value—for example, -2147024891 (0x80070005)—by calling FormatMessage.

AddFolderIcon

InstallShield 2018 Help Library

September 2018