In order to add a shortcut to a packaging project, go to the Shortcut view of the Visual Designer mode.
Click the Create new button, which is available in the upper left corner of the views content area.
The Add Shortcut wizard is displayed.
Work your way through the steps of the wizard to define all required properties for the new shortcut.
At any time, using the Next or Back buttons, which are displayed at the bottom of the wizard dialog, enables navigation within the already processed steps.
To exit the wizard without creating a new object, use the Cancel button, also located at the bottom of the wizard dialog.
Step 1: Target Type
Shortcuts within a package may not only point to an internal resource, which is brought to the target device during the installation of the package, but to any resource already available on the target device. In this first step, users have to make a primary decision regarding this shortcut property.
As the common target type actually is a file within this package, this option is preselected by default. The currently active option has a check mark in the upper right corner of its description box. Hover over the options and click anywhere inside the highlighted option value box to switch the active setting to that option. The check mark is immediately transferred to that description box.
Click Next to proceed or CANCEL to exit the shortcut creation.
Step 2: Target Selection
The interface of this step depends on the option selected in the previous one:
File within this package
RayPack displays the standard package file browser interface, which allows packagers to easily browse for the desired target file. Within the file management interface, users may not only pick one of the already added packaging project resource files, but also import one for direct usage.
As soon as a file is selected from within the display area on the right-hand side or the package file browser interface, the Next button becomes available.
|
Be aware: When files (or folders) are imported into the packaging project during this wizard step, using the CANCEL button at a later time does not automatically remove those files again. Please make sure to remove them via the controls of the Files & Folders view if required. |
File outside of this package
The shortcut target is specified by the path to its location and the name of the file that has to be invoked on the target machine.
The value given for the folder property may be a real path, such as C:\Program Files (x86)\RayPack\ or a dynamic reference defined by the identifier of a known directory on the target machine, such as INSTALLDIR. RayPack cannot know the local file system of the target device, thus the entered folder value is not checked for validity.
The second option is usually the more useful one, since hardcoded path values may become invalid due to the actual architecture or operating system on the target machine. Therefore, it is recommended to click on the browse button [...] placed at the right hand side of the Folder input field, and use the interface of the SELECT A FOLDER dialog to pick the matching folder identifier. This placeholder is replaced at Installer run time to point to the correct folder according to the actual properties of the target device.
Please refer to the Select a folder topic within the Common Dialogs section for details regarding the interface handling of the SELECT A FOLDER dialog.
The file name value must contain the name of a file that is available on the target machine. If the given name does not point to a reachable file, the end user will not be able to successfully execute the shortcut.
Packagers should keep in mind that executable files need to be run in the context of the currently logged on user. Therefore pointing to files that are usually restricted from general access needs to be double-checked.
Folder and file name are automatically linked to build a command line that is actually executed when the end user clicks on the shortcut once it has been placed on the target machine. As soon as both values are given, the NEXT button becomes available.
Step 3: Advertising
Shortcuts may either be advertised or not.
Advertised shortcuts, which are the recommended ones to use within packaging projects, check if their target is actually usable before it is invoked. This means that the target of the shortcut is checked for the availability of all required critical files. If any of them is missing or corrupt, the MSI Repair functionality is executed on the shortcuts target component.
Advertisement will not work for resources that have simply been copied to the target machine, have been installed by non-MSI methods, or for those files that are no executables at all. In these cases a standard Windows shortcut is all that can be provided: If it cannot be accessed, the target is invoked and a standard Windows error is raised.
Step 4: Display and Location
The values for Display name and Shortcut description are mere information for the end-user, explaining where on the system the shortcut points to.
Selecting a location controls where the shortcut object will be put on the target system, meaning where the end user will find it on their Windows interface. If the packager does not change the default setting, RayPack automatically adds the shortcut to the Program Menu Folder on the target machine. Other typical locations would be the Start Menu or Desktop folder. Click on the browse button (displayed as a button with the label "...") right of the location input field to change the default setting.
Please refer to the Select a folder topic within the Common Dialogs section for details regarding the interface handling of the SELECT A FOLDER dialog, which is used for the definition of the shortcut location.
|
Note: According to Best Practices the Desktop folder is only populated with shortcuts if the installation description provided by the customer demands so. Even though many vendor packages create a desktop shortcut by default, it is not regarded to be very user friendly. Just imagine a device with 20 applications installed, and for every application there is a shortcut on the desktop - clean and clear orientation might be considered to look slightly different, agreed? |
Each shortcut may be visually augmented with an icon. Packagers may either pick one of the already existing icon resources from the current packaging project or add a new icon by loading it from the local disk.
To pick an existing icon resource:
1.Users expand the icon resource selector interface with a click on the downwards arrow icon next to the standard icon.
The list of icon resources stored within the packaging project is displayed.
2.Select the desired icon from the list on the left-hand side of the selector interface and if required, navigate to the icon index that should be used. Use the arrows pointing to the left and to the right to change the currently active icon index value.
3.Click somewhere outside the icon resource selector interface to save the current setting for the shortcut icon.
To load a new icon resource from disk:
1.Users click on the "load from disk" link at the right-hand side of the preview panel for the current shortcut icon state.
2.Within the system browser for icon selection, the desired icon resource has to be selected.
3.By clicking on the Open button the icon is loaded into the project and selected to be the icon for the new shortcut.
|
Be aware: When an icon resource is loaded into the packaging project during this wizard step, using the CANCEL button at a later time does not automatically remove that icon resource again. Please make sure to remove it via the controls of the Resources view if required. |
Step 5: Start-up
Command line arguments
The command-line arguments for the shortcut. Note that the resolution of properties in the Arguments column of the Shortcut database table is limited.
When properties are used within this column value, the actual value of the property must have been resolved already once the shortcut is created on the target machine.
Working directory
The folder selected for this value is displayed as the "Start in" setting within the properties dialog of a shortcut on the target system. The working directory is the default for file opening and saving operations, and the current directory used by the invoked application.
Please refer to the Select a folder topic within the Common Dialogs section for details regarding the interface handling of the SELECT A FOLDER dialog, which is used for the definition of the working directory.
Hot key
To define a hot key for the new shortcut, packagers click into the usually greyed out hot key input field. As soon as the background color of the input field has switched to white, the next combination of keys pressed on the keyboard is recorded as hot key for the shortcut object. It is possible to use a single keystroke or a combination such as Control + Shift + b.
|
Tip: Hot keys should only be added to shortcuts if the customers installation description demands to do so. Conflicts between already existing hot key settings on the target device may lead to the experience of inconvenient system behavior for the end user. |
Start-up mode
Decide the behavior of the target application window when the shortcut is executed. Select one of the available options for the Run property of the later Windows shortcut object:
•Normal window - the application is invoked with the standard settings saved for the application.
•Maximized window - if no (user-) specific settings override this command, the invoked application covers the whole screen.
•Minimized window - if no (user-) specific settings override this command, the invoked application resides minimized in the task bar.
|
Note: Some programs override the Run property injected by shortcuts. For those applications packagers have to check whether there is a way to alter this behavior. The Run property works for programs and shortcuts to programs, but not for other target file types. |
Use the summary page to check the correctness of the shortcut properties that were defined during the previous wizard steps.
•If all properties are set as required, click Process to finally create the shortcut
•If changes are necessary, click Back until the wizard step with the incorrect property definition(s) is displayed and make modifications as required.
Please note that changes in an early step may lead to different defaults or options in any later step. Therefore, please verify that all steps contain the desired settings whilst Next-ing to the summary page again.
Step 7: Finished
Once the new shortcut object has been created, the wizard can be closed by using the Finish button at its lower right corner. The Shortcut view is updated, and the list of existing shortcuts contains the newly created object.