ReplaceShortcut

InstallShield 2019 » InstallScript Language Reference

The ReplaceShortcut function replaces a shortcut in a specified folder. You must specify an existing folder, either one that you have created with the CreateShortcutFolder function or one that already exists on the end user’s system.

Syntax

ReplaceShortcut (szShortcutFolder, szName, szNewItem, szCmdLine, szWorkingDir, szIconPath, nIcon, szShortCutKey, nFlag);

Parameters

ReplaceShortcut Parameters

Parameter

Description

szShortcutFolder

Specify the name of the folder that contains the shortcut that you want to replace.

szName

Specify the name of the shortcut that you want to replace.

szNewItem

Specify the name of the shortcut as it should appear after the replacement.

szCmdLine

Specify one of the following:

• The fully qualified name of the executable file that is associated with the icon, including any command-line parameters.
• The fully qualified path if szName is a subfolder.

szWorkingDir

If szName is not a subfolder, specify the directory that contains the product’s program files.

To make the directory that contains the product’s program files the working directory, pass a null string ("") in this parameter.

szIconPath

Specify the name of an alternate icon file or a valid executable file that contains the new icon.

nIcon

If you specified an executable file for szIconPath, specify the icon index in the executable file. Otherwise, enter the number 0 for nIcon.

szShortCutKey

Specify the string that contains the shortcut key sequence the end user can press to start the program. For example, if you want the end user to be able to open the application by pressing the “Ctrl,” the “Alt,” and then the “1” key, specify “Ctrl + Alt + 1” in this parameter.

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 Vista 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 Vista 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

ReplaceShortcut Return Values

Return Value

Description

0

Indicates that the function successfully replaced the shortcut.

< 0

Indicates that the function was unable to replace the shortcut.

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

ReplaceShortcut Example

Shell Functions

InstallShield 2019 Help Library

April 2019

 Copyright Information | Flexera

Open topic with navigation