| Argument | Description | Types / Required |
|---|
| target | The file path of an application or file that is the target of the shortcut. | string
required |
| label | A label describing the shortcut. If not defined, the target's filename (without an extension) is used. | string
not required |
| longLabel | A longer, more descriptive, label that may be used when space permits. | string
not required |
| icon | The file path of an icon to use for the shortcut. | string
not required |
The
System.createShortcut action creates a shortcut to a CSPro application or file. The way that the shortcut is created depends on the execution environment.
On Windows, a shortcut is added as a
Shell link. The shortcut is placed on the Desktop and is named based on the
label. If
longLabel is provided, it is used as the shortcut's
description.
On Android, a shortcut is added as a
pinned shortcut that can be added to the Android launcher (the home screen). The
label is used as the shortcut's
short label. If
longLabel is provided, it is used as the shortcut's
long label. Android guidance recommends maximum label lengths of 10 and 25 characters, respectively. A shortcut is not automatically created but instead Android displays a screen that allows the user to drag the shortcut to the home screen, or click a button to add it to the home screen automatically. Given this requirement for user intervention, it is not guaranteed that a shortcut is actually created.
An
icon can be associated with a shortcut. On Windows, icons can be specified in any format that the
Image.load function handles. On Android, icons can be specified in any format supported by Android's
BitmapFactory. Generally
ICO (.ico) files are used on Windows and
PNG (.png) files are used on Android. If designing an icon for cross-platform use, it is best to use the PNG format. On both platforms, the icon file will be copied to CSPro or system storage, so the icon can be a temporary file.
If an icon is not specified, the icon will default to the file type's icon on Windows, and the traffic light icon (representing
PFF files) on Android.
The action returns undefined.
The action throws an exception if any of its arguments are not specified in a valid form, or if:
- The target or icon file do not exist.
- The icon file cannot be read by the system.
- The Android version does not support pin shortcuts (a version lower than 8.0).
CS.System.createShortcut(target := "Congestion-Pricing-Survey.pff",
label := "Congestion",
longLabel := "Congestion Pricing Survey",
icon := "Images/Traffic-Icon.png");