We need you!

Icon

The IzPack documentation needs work, and you are invited to edit it!

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Shortcut Panel

Creates shortcuts to applications or resources on the desktop, or in the menu system, of the operating system GUI. Currently supports the following operating systems.

  • Microsoft Windows
  • Unix and Unix-based operating systems (like Linux), which use the X11 GUI-System and FreeDesktop.org-based shortcut handling (such as the KDE and Gnome desktop environments).

On unsupported systems, such as Mac OS X, the installers displays a variant UI that informs the user about the intended targets of your shortcuts and allows the user to save this information to a text file (see notSupported).

Add the Shortcut Panel to your installer by adding a <panel> tag with the name ShortcutPanel to the <panels> element: 

Code Block
<panel name="ShortcutPanel" id="shortcutpanel"/>

The Shortcut Panel executes its configuration immediately after the user performs the Next action, so is often placed after the Install Panel. To make IzPack display the Shortcut Panel before the Install Panel, but not actually create the shortcuts until after file installation, use in conjunction with the option <lateShortcutInstall/>.

Variables 

The following installer variables define or modify the behaviour of a shortcut panel.

VariableDescriptionRequired
ApplicationShortcutPathTo define the base path for the application shortcuts, absolute or relative to $INSTALL_PATH. If undefined, the application shortcuts will be directly written in the $INSTALL_PATH.No.
DesktopShortcutCheckboxEnabledWhen set to true, it automatically checks the "Create Desktop Shortcuts" button.No; defaults to false.

Required Configuration

The following tags in install.xml define the behaviour of a shortcut panel.

ShellLink.dll

Required native library for using Shortcut Panel for installers targetting Windows.

Code Block
titleHow to including native DLLs for ShortcutPanel
languagehtml/xml
<natives>
    <native type="izpack" name="ShellLink.dll"/>
    <native type="izpack" name="ShellLink_x64.dll"/>
<natives>

Both 32-bit and 64-bit versions are built-in to IzPack.

shortcutSpec.xml

Required XML resource file defining all shortcut options. The resource ID for the default spec file is shortcutSpec.xml. For details of shortcut spec options, see Shortcut Specification and the Shortcut Tips and Troubleshooting guide.

Code Block
<res src="resources/default_shortcut_spec.xml" id="shortcutSpec.xml"/>

This tag should be defined in the <resources> element.

OS-specific shortcuts

Take into account the following considerations when creating cross-platform installers.

  1. Target filenames/commands may be different (e.g. batch files on Windows vs. shell scripts on Unix).
  2. Target paths may be different. 
  3. Icon file formats are different (e.g. ICOs on Windows, PNGs on Unix).

Create OS-specific shortcut files using platform prefixes with the resource ID, in the form prefix_shortcutSpec.xml. Supported prefixes are:

  • Win
    Windows platforms
  • Unix
    Unix-based platforms (including Linux)
Code Block
<res src="resources/default_shortcut_spec.xml" id="shortcutSpec.xml"/>
<res src="resources/unix_shortcut_spec.xml" id="Unix_shortcutSpec.xml"/>

In this example, Unix installations would use the configuration defined in unix_shortcut_specification.xml, and Windows installations would fall back on the default configuration defined in default_shortcut_spec.xml.

Localizing shortcuts

Shortcut names, descriptions can be localized by defining alternative XML spec files using the ISO3 country code as a suffix to the resource ID. Even some paths can be different when an OS is localized (e.g. My Documents becomes Mes Documents on Windows in French).

Code Block
<res src="resources/default_shortcut_spec.xml" id="shortcutSpec.xml"/>
<res src="resources/default_shortcut_spec_fr.xml" id="shortcutSpec.xml_fra"/>
<res src="resources/unix_shortcut_spec_en.xml" id="Unix_shortcutSpec.xml"/>
<res src="resources/unix_shortcut_spec_fr.xml" id="Unix_shortcutSpec.xml_fra"/>

This examples defines English and French configurations for both the default shortcut spec, and for a Unix shortcut spec.