CreateShortcut

InstallShield 2022 » InstallScript Language Reference

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

• Add a shortcut or program folder to locations such as the Start menu, the Programs menu, or the desktop. Use the szShortcutFolder parameter to specify the appropriate location for the shortcut.
• Create a cascading submenu on the Startup menu, and include a shortcut in the submenu.
• Set Windows Shell properties for a shortcut to configure behavior such as disabling the ability to pin the shortcut to the Start menu.

Note:The shortcut target must be present on the target system before CreateShortcut can be called.

CreateShortcut does not support the creation of Internet shortcuts.

Syntax

CreateShortcut (szShortcutFolder, szName, szCommandLine, szWorkingDir, szIconPath, nIcon, szShortCutKey, nFlag);

Parameters

CreateShortcut Parameters

Parameter

Description

szShortcutFolder

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, CreateShortcut 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"

szName

Specify the name of the shortcut. Calling CreateShortcut to add a shortcut to a program folder also creates a link file in the links directory that is specified by szCommandLine. Note that Windows Shell does not allow the following characters in 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 szName 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 szName is a subfolder, this parameter is not applicable.

CreateShortcut 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 szName 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 szName 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 ( | ).

• CS_OPTION_FLAG_REPLACE_EXISTING—Replace an existing shortcut.
• CS_OPTION_FLAG_RUN_MAXIMIZED—The target of the shortcut is maximized when launched.
• CS_OPTION_FLAG_RUN_MINIMIZED—The target of the shortcut is minimized when launched.
• CS_OPTION_FLAG_PREVENT_PINNING—Do not allow the shortcut to be pinned to the Start menu or taskbar on Windows 7 or later systems. This option hides the context menu commands that enable end users to pin the shortcut to the taskbar and to the Start menu.

You may want to prevent pinning for shortcuts that are for tools and secondary products that are part of your installation.

• CS_OPTION_FLAG_NO_NEW_INSTALL_HIGHLIGHT—Do not highlight the shortcut as newly installed after end users install your product on Windows 7 or later systems. This has the same effect as clearing the Highlight newly installed programs check box in the Customize Start Menu dialog box for an individual item on a target system.

You may want to use this option for shortcuts that are for tools and secondary products that are part of your installation.

• CS_OPTION_FLAG_NO_STARTSCREEN_PIN—Do not pin the shortcut to the Start screen by default on Windows 8 target systems. If you pass this constant, the installation sets a Windows Shell property that was introduced in Windows 8.

You may want to prevent pinning for shortcuts that are for tools and secondary products that are part of your installation.

• NULL—Indicates no options.

For more information on CS_OPTION_FLAG_PREVENT_PINNING and CS_OPTION_FLAG_NO_STARTSCREEN_PIN, see the Additional Information section.

Return Values

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

Additional Information

Note the following details about two of the nFlag constants.

CS_OPTION_FLAG_PREVENT_PINNING

If you configure the shortcut to prevent pinning to the taskbar and the Start menu, the target of the shortcut is ineligible for inclusion in the most frequently used list on the Start menu.

Shortcuts that contain certain strings cannot be pinned to the taskbar or the Start menu, and they cannot be displayed in the most frequently used list. Examples are:

• Documentation
• Help
• Install
• Remove
• Setup
• Support

CS_OPTION_FLAG_NO_STARTSCREEN_PIN

Note that Windows 8 maintains information about shortcut pinning to the Start screen after a shortcut is removed by uninstalling the application. Therefore, the CS_OPTION_FLAG_NO_STARTSCREEN_PIN constant has no effect on the target system if the shortcut has already been installed on it. Thus, when you are testing this functionality, ensure that you test on a clean machine—one on which this shortcut and its target have never been installed.

See Also

CreateShortcut Examples

Shell Functions