Shortcut Specification

Shortcut Specification

The specification for application shortcuts is provided to the Shortcut Panel in the XML file format. It must be referred in the <resources> section by a resource definition with the ID "shortcutSpec.xml":

<res id="shortcutSpec.xml" src="my-installer-files/shortcutSpec.xml/>

 All contents in the referred file must be nested to the following root element:

<izpack:shortcuts version="5.0"
                  xmlns:izpack="http://izpack.org/schema/shortcuts"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:schemaLocation="http://izpack.org/schema/shortcuts http://izpack.org/schema/5.0/izpack-shortcuts-5.0.xsd">

...
</izpack:shortcuts>


Nested Elements 

defaultCurrentUser

The <defaultCurrentUser/> tags has no attributes or content. Makes create shortcut for: current user the default selection on the Shortcut Panel. If not specified, then all users will be the default selection (if available).  

skipIfNotSupported

The <skipIfNotSupported/> tag has no attributes or content. It suppresses the default behavior on systems not supported by Shortcut Panel, forcing the installer to completely skip the display of Shortcut Panel. (The default behavior is to show an alternative UI, which displays the shortcut information that would have been created on a supported system.)

notSupported

The <notSupported/> tag has no attributes or content. Allows you to review what an end user would see if the target operating system is not supported by forcing the Shortcut Panel to behave as though running on an unsupported system. 

This tag is for testing purposes only. Be sure to remove this tag before preparing your installer for production.

lateShortcutInstall

The <lateShortcutInstall/> tag has no attributes or content.  Delays the creation of shortcuts until after all packs have been installed (instead of creating shortcuts as soon as 'Next' is clicked). Specify this if you want to show ShortcutPanel before InstallPanel.

previousDisabled

The <previousDisabled/> tag has no attributes or content. Specify this if you want to disable the previous navigation button for this panel. (Since: IzPack 5.1.3)

programGroup

Allows you to specify the name of the menu, or more precisely the folder, in which the shortcuts will be grouped. The exact location and appearance of the program group depends on the specific target system on which the application will be installed. This can be partially controlled by the location parameter.

AttributeDescriptionRequired
defaultNameSpecifies the name that the group menu should have on the target system. You should be aware that the Shortcut Panel will present this name to the user as a choice. The user can then edit this name, or select a group that already exists.No, but recommended; default is blank.
location

Specifies where the group menu should be displayed in the desktop menu. There are two choices:

  • applications: the group menu will be placed in the menu that is ordinarily used for application shortcuts
  • startMenu: the group menu will be placed at the top-most menu level available on the target system

On Unix-based systems, the applications location is already on the highest level, so setting any other value will have no effect. Depending on the target system, it might not be possible to honor this specification exactly. In such cases, the Shortcut Panel will map the choice to the location that most closely resembles your choice.

No; default is applications.
installGroupWhen using the Installation Group Panel, multiple programGroup elements can be specified, each defining this attribute with the name of the applicable installation group. A custom programGroup can be defined for each installation group, but Shortcut Panel will still only create one progam group folder. If no programGroup spec has an installGroup attribute matching the selected installation group name, the first defined programGroup will be used. If multiple programGroup tags with the same installGroup attribute are defined, the first will be used and all others ignored.No.

If more than one instance of <programGroup> is specified without the use of the Installation Group Panel and the installGroup parameter, only the first one will be used - all other <programGroup> tags will be ignored. 

shortcut

For each shortcut you want to create, you have to add one <shortcut> tag. The attributes can be divided into two groups:

  • attributes that describe properties of the shortcut
  • attributes that define the location(s) at which a copy of the shortcut should be placed.

The attributes listed in this table are mostly common to all platforms, but some are not valid or sensible on all operating systems. These cases are noted. Additional, OS-specific attributes, are listed below.

AttributeDescriptionRequired
nameThe name that the shortcut will have. This is the text that makes up the menu name if the shortcut is placed in a menu or the caption that is displayed with the shortcut if it is placed on the desktop.Yes
target

The application that should be launched when the shortcut is clicked. The value is translated through the variable substitutor, so variables such as $INSTALL_PATH can be used in the path.

 Use of this attribute may change once other operating systems are supported.

Yes
commandLineSpecifies command line arguments to pass to the target through the shortcut. Command line arguments are not supported by all operating systems. As a result, your applications will not be portable if they depend on command line arguments. Instead, consider using system properties or configuration files. See Shortcut Tips on command line arguments.No
workingDirectoryDefines the working directory for the application at the time it is launched. Exercise caution in relying on this too heavily if your application should be portable, since this might not be supported by all operating systems. The value is translated through the variable substitutor, so variables such as $INSTALL_PATH can be used to describe the directory.No
descriptionThe value of this attribute will be visible to the user when a brief description about associated application is requested. The form of the request and the way in which this description is displayed varies between operating systems. On Windows, the description is shown as a tool tip when the mouse cursor hovers over the icon for a few seconds. On some operating systems this feature might not be supported.No
iconFile

A file that holds the icon that should be displayed as a symbol for this shortcut. This value is translated through the variable substitutor, so variables such as $INSTALL_PATH can be used. If this attribute is omitted, no icon will be specified for the shortcut. Usually this causes the OS to display an OS-supplied default icon.

 Use of this attribute may change once other operating systems are supported. 

See Shortcut Tips on shortcut icons.

No
iconIndexIf the file type for the icon supports multiple icons in one file, then this attribute may be used to specify the correct index for the icon. In file formats that do not support multiple icons, this value is ignored. This is only likely to be useful for Windows shortcuts, if the icon is in a multiple-icon ICO, or embedded in a DLL or EXE file. See Shortcut Tips on shortcut icons.No
initialState

If the target operating system supports this feature, then this value will set the initial window state of the application. Valid options are:

  • normal
  • minimized (not valid on Unix
  • maximized (not valid on Unix)
  • noShow(not valid on Unix)

The noShow option is particularly useful when launching batch scripts on Windows, as no command window will be visible with this option. For instance, a shortcut to a batch file that launches a Java application has the less-than-pretty side effect that two windows show: the DOS command prompt and the Java application window. Even if the shortcut is configured to show minimized, there will be buttons for both windows in the task bar. Using noShow will completely eliminate this effect, only the Java application window will be visible.

No; default is normal

programGroupIf the value is true, then a copy of this shortcut will be placed in the group menu (see programGroup). On Unix (KDE) this will always be placed on the top level.At least one location attribute is required, as all default to false. If no location attribute is true, the shortcut will not be displayed anywhere. If multiple locations attributes are true, a copy of the shortcut will be displayed in all of those locations.




desktopIf the value is true, then a copy of the shortcut is placed on the desktop. On Unix the shortcuts will only be placed on the KDE desktop of the user currently running the installer. For Gnome the user can simply copy the .desktop files from */Desktop to /gnome-desktop.
applicationsIf the value is true, then a copy of the shortcut is placed in the applications menu (if the target operating system supports this). This is the same location as the applications choice for the programGroup element. Setting applications="true" is equivalent to setting programGroup="true" on Unix.
startMenuIf the value is true, then a copy of the shortcut is placed directly in the top most menu that is available for placing application shortcuts. This is not supported on Unix.  
startupIf the value is true, then a copy of the shortcut is placed in a location where all applications get automatically started at OS launch time, if this is available on the target OS. This is not supported on Unix.
subgroupSpecifies a sub-path (i.e. a sub-folder) of the main program group in which this shortcut will be placed. This is not supported on Unix.No; has no effect unless programGroup is true.
conditionSpecifies the name of an installer condition that must evaluate to true for this shortcut to be created. If the condition does not exist, the shortcut is created.No

Unix-specific attributes

These attributes apply only to Unix-based systems (including Linux).

AttributeDescriptionRequired
type

Specifies the type of shortcut. Valid values are:

  • Application
    Creates a shortcut to start any application (native, Java, or shell-script). The GUI-System will launch this Application through its native shell or application launcher. In this case, note that the right workingDirectory is always important on Unix platforms. If the user's PATH environment variable does not contain the application path, this application will not run unless workingDirectory specifies the application path. The "current path" placeholder (i.e. '.') must exist on the PATH, as is the case by default on most systems. Consult the Unix manuals for more details.
  • Link
    Creates a shortcut to open a URL in the user's default web browser. In this case, the url attribute must be set.
Yes
urlSpecifies a locally installed HTML file, other file with a known MIME type (e.g. plain text), or a WWW URL (e.g. http://izpack.org/). This value is translated through the variable substitutor, so variables such as $INSTALL_PATH (for local documents) can be used.Yes, if type=link
mimetype

Specifies the MIME type for links pointing to local files when using type=link.

No; recommended if type=link and url points to a local file.
encodingThis should always set to UTF-8.Yes
terminalSet to true to allow the user to see the console output of a program (e.g. in Java applications "System.out").No; defaults to false.
terminalOptions

Specifies attributes for terminal windows when terminal=true (see man pages for setterm).

No
KdeSubstUIDThis is the sudo option for a shortcut. If set to true, you will be asked for the password of the KdeUsername.

No; defaults to false

KdeUsernameThe username with correct sudo permissions where KdeSubstUID is true. This is root in most cases.No; defaults to root.
createForAllIf a user with administrative rights, such as root, performs the installation, set to true to make this shortcut appear to other users as well as root.No; defaults to false.
categories

The category in the Desktop Application Menu where the shortcut will be placed. Here are some sample categories and their apps. For more examples, examine the desktop files in /usr/share/applications in the target environment.

  • Categories="Application;Network;WebDevelopment;" - Nvu
  • Categories="Qt;Development;GUIDesigner;" - QtDesigner3
  • Categories="Application;System;" - VMwareServer-console
  • Categories="Network;WebBrowser;" - Opera
  • Categories="Development;Debugger;" - DDD debugger
  • Categories="Development;IDE;" - Eclipse IDE
  • Categories="SystemSetup;X-SuSE-Core-System;" - Yast2
  • Categories="System;Archiving;" - Sesam archiving
  • Categories="System;Database;" - MySQL Administrator
No; no default.
tryexecSpecifies a command to pass through 'raw' to the operating system.No; default is to use target and (where present) commandLine

Windows-specific attributes

These attributes apply only to Windows-based systems.

AttributeDescriptionRequired
runAsAdministrator

Determines if the target of the shortcut should be run with administrator privileges
(since 5.0.0-rc1)

No; defaults to false.


createForPack

This is an optional nested element, with one required attribute, name, specifying the name of a pack that must be selected for this shortcut to be created. Multiple <createForPack> elements can be nested in the same <shortcut>.

<createForPack name="Pack 1" />
<createForPack name="Pack 2"/>