SetShortcutProperty

InstallShield 2018 » InstallScript Language Reference

The SetShortcutProperty function sets one or more shortcut properties that you want the Windows Shell to set at installation run time. For example, SetShortcutProperty has built-in support for enabling you to set Shell properties that control the following behavior:

• Specify whether a shortcut should be pinned to the Windows 8 Start screen.
• Specify whether end users should be able to pin a shortcut to the taskbar or Start menu on Windows 7 or later systems.
• Prevent a shortcut on the Start menu from being highlighted as newly installed on Windows 7 or later systems.

SetShortcutProperty also lets you set additional properties that the Windows Shell supports.

Note • The shortcut and its target must be present on the target system before SetShortcutProperty can be called.

SetShortcutProperty does not support the configuration of Internet shortcuts.

Syntax

SetShortcutProperty (szShortcutFolder, szName, szPropertyKey, szValue);

Parameters

SetShortcutProperty Parameters

Parameter

Description

szShortcutFolder

Specify the path of the shortcut whose properties you want to configure.

To configure a shortcut that is in a specific folder, specify the fully qualified path—for example:

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

If the shortcut is on the Programs menu of 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 that you are configuring.

szPropertyKey

Specify the property key name that you want to set. The properties that can be set are defined in propkey.h, which is part of the Windows SDK.

You can pass any of the following constants for property keys that are predefined in InstallScript:

• SSP_PROPERTY_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.

To enable this property, set szValue to 1.

• SSP_PROPERTY_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.

To enable this property, set szValue to 1.

• SSP_PROPERTY_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.

To enable this property, set szValue to 1.

For more information on SSP_PROPERTY_PREVENT_PINNING and SSP_PROPERTY_NO_STARTSCREEN_PIN, see the Additional Information section.

szValue

Specify the value (represented as a string) of the property that you are setting. For information on the value to use with a given property, see propkey.h, which is part of the Windows SDK.

The InstallScript engine converts the string value into the appropriate data type that corresponds with the property that is specified in szPropertyKey.

Return Values

Table 1:  

Return Value

Description

>= ISERR_SUCCESS

Indicates that the function successfully set the shortcut property.

< ISERR_SUCCESS

Indicates that the function was unable to set the shortcut property.

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.

SSP_PROPERTY_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

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

SetShortcutProperty Example

Shell Functions

InstallShield 2018 Help Library

September 2018

 Copyright Information | Flexera

Open topic with navigation