[izpack-changes] r1911 - in izpack-src/trunk: . src/doc-reST src/lib/com/izforge/izpack/panels src/lib/com/izforge/izpack/util
noreply at berlios.de
noreply at berlios.de
Wed Nov 21 18:00:37 CET 2007
Author: jponge
Date: 2007-11-21 18:00:22 +0100 (Wed, 21 Nov 2007)
New Revision: 1911
Modified:
izpack-src/trunk/Versions.txt
izpack-src/trunk/src/doc-reST/desktop-shortcuts.txt
izpack-src/trunk/src/doc-reST/installation-files.txt
izpack-src/trunk/src/lib/com/izforge/izpack/panels/InstallationGroupPanel.java
izpack-src/trunk/src/lib/com/izforge/izpack/panels/ShortcutPanel.java
izpack-src/trunk/src/lib/com/izforge/izpack/util/FileExecutor.java
izpack-src/trunk/src/lib/com/izforge/izpack/util/OsVersion.java
Log:
Various fixes (Loic via Julien Ponge)
Modified: izpack-src/trunk/Versions.txt
===================================================================
--- izpack-src/trunk/Versions.txt 2007-11-20 14:32:36 UTC (rev 1910)
+++ izpack-src/trunk/Versions.txt 2007-11-21 17:00:22 UTC (rev 1911)
@@ -57,6 +57,7 @@
- Fixed wrong required size of packs (Dennis Reil)
- Added condition-attribute to pack element in installer.xml (Dennis Reil)
- Spanish langpack update (Sergio Banos Calvo via Julien Ponge)
+- Various fixes (Loic via Julien Ponge)
> 3.10.2 (build 2007.05.11)
Modified: izpack-src/trunk/src/doc-reST/desktop-shortcuts.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/desktop-shortcuts.txt 2007-11-20 14:32:36 UTC (rev 1910)
+++ izpack-src/trunk/src/doc-reST/desktop-shortcuts.txt 2007-11-21 17:00:22 UTC (rev 1911)
@@ -1,1027 +1,1073 @@
-Desktop Shortcuts
-=================
-
-(by Elmar GROM and Marc EPPELMANN)
-
-Defining Shortcuts
-------------------
-
-
-Introduction
-'''''''''''''
-
-On todays GUI oriented operating systems, users are used to launching
-applications, view web sites, look at documentation and perform a variety of
-other tasks, by simply clicking on an icon on the desktop or in a menu system
-located on the desktop. Depending on the operating system these icons have
-different names. In this context we will refer to them collectively as
-shortcuts.
-
-
-Apart from actually placing an application on the target system, users
-routinely expect an installer to create the necessary shortcuts for the
-application as well. For you as application developer, this means that for a
-professional appearance of your product you should also consider creating
-shortcuts.
-
-
-In contrast to the general specification of an IzPack installer, the
-specification of shortcuts in IzPack requires a little more effort. In
-addition, some of the concepts are a bit more complex and there are some
-operating system specific issues to observe. Fortunately, you only need to
-worry about operating system specifics if you want to deploy your application
-to multiple different operating systems. In any case, it will pay off to
-spend some time to study this documentation and the example spec files before
-you start to implement your own shortcuts.
-
-
-At the time of writing this Chapter the current IzPack Version 3.7.0-M3 is
-only capable to creating shortcuts on
-
-1. Microsoft Windows, and
-2. Unix and Unix-based operating systems (like Linux), which use the
- `X11` GUI-System and ` FreeDesktop.org` based shortcut handling (such
- as `KDE` and `Gnome`).
-
-Other operating or GUI systems, such as MacOS X are not
-supported. However, there is a special UI-variant that automatically pops up
-on unsupported systems. It informs the user about the intended targets of
-your shortcuts and allows the user to save this information to a text file.
-While this is not an elegant solution, at least it aids the user in the
-manual creation of the shortcuts.
-
-
-If you would like to review what an end user would see if the target
-operating system is not supported, you can do the following. Simply place the
-tag ``<notSupported/>`` in the spec file. This tag requires no attributes or
-other data. It must be placed under ``<shortcuts>``, just like the individual
-shortcut specifications. Be sure to remove this tag before getting your
-application ready for shipment.
-
-
-We expect other operating systems to be supported in the near future and as
-always, contributions are very welcome. At present someone is actively
-working on Mac support.
-
-
-What to Add to the Installer
-'''''''''''''''''''''''''''''
-
-There are some things that you have to add to your installer to enable
-shortcut creation. Obviously you need to add the panel responsible for
-creating shortcuts. This panel is aptly enough called ShortcutPanel. However,
-in order for the ShortcutPanel to work properly a number of additional items
-are required. These must be added manually to the installer, as all other
-resourcs, since the front-end will be rewritten. In this chapter we will
-explain which of these items are required and for what reason.
-
-
-First, we would like to discuss items that are supplied with IzPack and only
-need to be added to the installer. After that, we move on to the things you
-have to prepare yourself before you can add them. The way in which shortcuts
-are created varies widely among operating systems. In some cases it is
-possible to do this with pure Java code, while other systems -such as MS-
-Windows- require native code to accomplish this task. On the other side, the
-current implementation, which creates shortcuts on Unix based systems needs
-no native library at all, since it works with 'these' pure Java code. The
-native library required for the Windows operating systems are supplied with
-IzPack is called ``ShellLink.dll``. Note: They will not be automatically
-added to your installer file. You need to list them yourself in the XML file
-for the installer. A describtion how to do this follows in the next section.
-
-
-Native libraries can be added to the installer by using the ``<native>`` tag.
-To add the ``ShellLink.dll``, you just have to add the following line to the
-installer XML file:
-``<native type="izpack" name="ShellLink.dll"/>``
-For more details about the use of the ``<native>`` tag see the chapter about
-the format of the XML file.
-
-
-You have also to add an extra specification file for each platform family to
-enable shortcut creation on these platforms. At least one (the default file)
-is required by the shortcut panel. The format of all spec files is XML and
-they must be added to the installer as a resource. The source name of this
-specification does not matter, however its resource name (also called id or
-alias) when added to the installer must be ``(prefix)+shortcutSpec.xml``.
-At this release, there are only two prefixes supported: "Win" for the
-Windows family and "Unix" for all Unixes. If the prefix is ommited the
-shortcut panel searches for a named resource: `` shortcutSpec.xml``. This is
-the default resource name. As the default resource name will be used on
-Windows platforms, the ``"Win_shortcutSpec.xml"`` can be ommited.
-Hint: If the shortcut panel does not find one of these named resources, it
-will never appears. So, do not use different resource names and do not add a
-path to these.
-
-
-**Example**
-
-
-::
-
- <res src="C:\MyDocuments\Installer\default_shortcut_specification.xml"
- id="shortcutSpec.xml"/>
- <res src="C:\MyDocuments\Installer\unix_shortcut_specification.xml"
- id="Unix_shortcutSpec.xml"/>
-
-
-Why use different shortcut spec files?
-
-
-1. The Target filenames are most different.(batch files on Windows vs.
- shell scripts on Unix.)
-2. The Icon file formats are different. ICOs on Windows-, PNGs on Unix-
- platforms.
-3. The Target locations can be different.
-
-This is the simple reason.
-
-
-
-Why Native Code to do the Job on Windows?
------------------------------------------
-
-by Elmar
-
-
-This little chapter is not strictly part of the documentation but i have been
-asked this question sufficiently often that i think it's worth explaining
-right here. It is certainly a natural question to ask. After all IzPack is an
-application completely written in Java and primarily targeted for the
-installation of Java based programs. So why wouldn't we try to keep
-everything pure Java and avoid the use of native code altogether? There must
-be some personal preference of the developer hidden behind this approach you
-might think. Well, not really, but i admit at first it seems quite feasible
-to write it all in Java. On virtually any operating system or GUI surface
-around, Shortcuts are simply files on the local file system. Files can be
-created and accessed directly from within Java, so why should there be a need
-for using native code?
-
-
-Well, it turns out that just creating a file is not good enough, it also
-needs to have the right content. Shell Links as they are called in Windows
-land are binary files. i actually managed to find documentation on the
-format. Naturally this was hacker data, you won't get this sort of thing from
-Microsoft (by the way: thanks a lot to Jesse Hager for a smash job!). Armed
-with this information i tried to create these files myself in Java. The
-problem was that the documentation was not entirely accurate and had some
-gaps as well. i tried for over a month to get this to work but finally i had
-to give up. Even if i would have succeeded, it would have been a hack, since
-a shell link requires some information that is impossible to obtain from
-within Java. Usually you can successfully create a shell link by only filling
-in the bare minimum information and then ask Windows to resolve the link.
-Windows then repairs the shell link. Unfortunately this was only the
-beginning, soon i encountered a host of other problems. For one thing, the
-installer needs to know the correct directories for placing the links and it
-turns out they are named differently in different countries. In addition,
-there are ways of manually modifying them, which some people might actually
-have done. The only way to place the shortcut files reliably is through
-accessing the Windows Registry. Naturally, this operation also required
-native code. Same thing with asking Windows to resolve the link... On the
-bottom line, at every step and turn you run into an issue where you just need
-to use native code to do the trick. So i decided that i would do it the
-proper way all the way through. That is in a nutshell the reason why i used
-native code to create shortcuts on MS-Windows.
-
-
-As i am writing this i am at work with a friend to replicate this work for
-the Mac and it looks very much like we need to take the same approach there
-as well. On the various Unix GUIs on the other hand, we are lucky that we can
-do the job without native libraries.
-
-
-
-The Shortcut Specification
---------------------------
-
-As we say above, the specification for shortcuts is provided to the
-ShortcutPanel in the XML fileformat. At the time of this writing (for IzPack
-version 3.7.0-M3) the front-end will be rewritten. Until these work is in
-progress you have to write the specification files manually. For your
-convenience, there are two annotated sample specification files in the sample
-subdirectory of your IzPack installation. At the beginning you might want to
-experiment with these files.
-
-
-Both specification files have one root element called ``<shortcuts>``. This
-root elements recognizes 3 different child elements:
-``<programGroup>``, ``<skipIfNotSupported/>`` and ``<shortcut>``.
-
-
-``<skipIfNotSupported/>`` can be used to avoid the panel to show the
-alternative UI which shows the shortcut information that would have been
-created on a system that supports it. In other words, using this tag will
-make the panel be silent on non-supported systems. The default is to show the
-alternative UI.
-
-
-The ``<programGroup>`` tag allows you to specify the name of the menu, or
-more precise, 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, however you can partially
-control it. Please note that ``<programGroup>`` may only appear once in the
-specification. If more than one instance occurs, only the first one will be
-used. This tag requires two attributes: ``defaultName`` and ``location``.
-``defaultName`` specifies the name that the group menu should have on the
-target system. You should be aware that the ShortcutPanel will present this
-name to the user as a choice. The user can then edit this name or select a
-group that already exists. As a result, there is no guarantee that the actual
-name of the program group on the target system is identical with your
-specification. ``location`` specifies where the group menu should show up.
-There are two choices: ``applications`` and ``startMenu``. If you use
-``applications``, then the menu will be placed in the menu that is ordinarily
-used for application shortcuts. ``applications`` is recommended for Unix
-shortcuts. If you use ``startMenu``, the group menu will be placed at the top
-most menu level available on the target system. Depending on the target
-system, it might not be possible to honor this specification exactly. In such
-cases, the ShortcutPanel will map the choice to the location that most
-closely resembles your choice. Unix shortcuts do not need to support the
-``startMenu``, because the ``applications`` menu is already on the highest
-level. This means this has no affect on thess platform.
-
-
-For each shortcut you want to create, you have to add one ``<shortcut>`` tag.
-Most details about the shortcut are listed as attributes with this tag. The
-following sections describe what each attribute does, which attributes are
-optional and which ones are required and what the values are that are
-accepted for each of the attributes. Note that all attributes that have a
-yes/no choice can also be omitted. Doing so has the same effect as using a
-value of no. The shortcut 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 following attributes are used to define location:
-
-- ``programGroup``
-- ``desktop``
-- ``applications``
-- ``startMenu``
-- ``startup``
-
-
-Shortcut Attributes
--------------------
-
-There are three classes of attributes. Some are required, most are completely
-optional and some are semi-optional. The set of semi-optional attributes are
-all the attributes used to define the location of a shortcut. These are semi-
-optional because for any individual one it is your choice if you want to
-include it or not. However they are not completely optional. You must specify
-at least one location. If all were omitted, the instruction would essentially
-tell the panel that a copy of this shortcut is to be placed at no location.
-In other words no copy is to be placed anywhere.
-
-**name** ``- required``
-
-
-The value of this attribute defines the 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.
-
-
-**target** ``- required``
-
-
-The value of this attribute points to the application that should be launched
-when the shortcut is clicked. The value is translated through the variable
-substitutor. Therefore variables such as ``$INSTALL_PATH`` can be used to
-describe the location. **You should be aware that the use of this tag is
-likely to change once other operating systems are supported**.
-
-
-**commandLine** ``- optional``
-
-
-The value of this attribute will be passed to the application as command
-line. i recommend to work without command line arguments, since these 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.
-
-
-**workingDirectory** ``- optional``
-
-
-This attribute defines the working directory for the application at the time
-it is launched. i would recommend some caution in relying on this too heavily
-if your application should be portable, since this might not be supported by
-all operating systems. At this time i don't have enough information to make a
-definite statement one way or the other. The value is translated through the
-variable substitutor. Therefore variables such as ``$INSTALL_PATH`` can be
-used to describe the directory.
-
-
-**description** ``- optional``
-
-
-The 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 MS-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 but i think it is always a good
-idea to include a brief description.
-
-
-**iconFile** ``- optional``
-
-
-The value of this attribute points to the file that holds the icon that
-should be displayed as a symbol for this shortcut. This value is also
-translated through the variable substitutor and consequently can contain
-variables such as $INSTALL_PATH. 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. **The use of this attribute is also likely to change
-once other operating systems are supported. Read the Section about Icons
-below, for more information.**
-
-
-**iconIndex** ``- optional``
-
-
-If 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. i would also
-advise against using this feature, because of operating system
-incompatibilities in this area. In file formats that do not support multiple
-icons, this values is ignored.
-
-
-**initialState** ``- optional``
-
-
-There are four values accepted for this attribute: ``noShow``, ``normal``,
-``maximized`` and ``minimized``. If the target operating system supports this
-feature, then this value will have the appropriate influence on the initial
-window state of the application. ``noShow`` is particularly useful when
-launch scripts are used that cause a command window to open, because the
-command window will not be visible with this option. For instance on MS-
-Windows starting 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 are buttons for both windows in the task bar. Using
-``noShow`` will completely eliminate this effect, only the Java application
-window will be visible. *On Unix use* ``normal`` *, because this is not
-supported*.
-
-
-**programGroup** ``- semi-optional``
-
-
-The value for this attribute can be either yes or no. Any other value will be
-interpreted as no. If the value is yes, then a copy of this shortcut will be
-placed in the group menu. *On Unix (KDE) this will always be placed on the
-top level.*
-
-
-**desktop** ``- semi-optional``
-
-
-For this attribute the value should also be yes or no. If the value is yes,
-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, who currently runs the
-installer. For Gnome the user can simply copy the *.desktop files from*
-``/Desktop`` *to* ``/gnome-desktop``. (This is already a TODO for the Unix-
-shortcut implementation.)
-
-
-**applications** ``- semi-optional``
-
-
-This is also a yes/no attribute. If the value is yes, 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
-program group. *This makes no sense on Unix.*
-
-
-**startMenu** ``- semi-optional``
-
-
-This is a yes/no attribute as well. If the value is yes, 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. see above.*
-
-
-**startup** ``- semi-optional``
-
-
-This is also a yes/no attribute. If the value is yes, 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
-also not supported on Unix.*
-
-
-
-Unix specific shortcut attributes
-----------------------------------
-
-This extension was programmed by MARC EPPELMANN. This is still in development
-and may be changed in one of the next releases of IzPack.
-
-
-**type** ``- required``
-
-
-This must be one of ``Application`` or ``Link``
-
-
-- Application: To start any application, native, Java or shell-script
- based, the **type** has to be ``Application``. The GUI-System will launch
- this Application, so as is, thru their native shell or application
- launcher. In this case, note that the right ``workingDirectory`` is
- always important on Unix platforms. If the users PATH environment
- variable does not contain the path, where the application is located,
- this can never be run, until the ``workingDirectory`` does not contain
- these path. The needed current path: ".", this is the case on most
- systems, should be in the users PATH environment variable. Consult the
- Unix manuals for more details.
-- Link: If you want to open a URL in the users default Webbrowser, you
- have to set the **type** to ``Link``. Note: The ``url`` attribute must be
- set to work properly.
-- Other: There are more supported types on KDE, like FSDevice, but
- these types makes no sense for IzPack, in my opinion.
-
-Without the type the Unix shortcut does not work.
-
-
-**url** ``- semi-optional``
-
-
-If you want to create a shortcut as type *Link*, then you have to set the
-``url`` attribute. The value can be a locally installed html or another
-document, with a known MIME type, like plain text, or a WWW Url i.e.
-'https://izpack.github.io/'.
-
-
-A local document can be referenced by i.e. "$INSTALL_PATH/doc/index.html".
-
-
-The IzPack variable substitution system is supported by the **url**.
-
-
-**encoding** ``- required``
-
-
-This should always set to **UTF-8**.
-
-
-**terminal** ``- optional``
-
-
-If you want, the user can see the console output of a program (in Java
-applications "System.outs"), set the ``terminal`` attribute to **true**.
-
-
-**KdeSubstUID** ``- unused``
-
-
-This is not fully implemented by IzPack. i the future this is the sudo option
-for a shortcut.
-
-
-
-Selective Creation of Shortcuts
--------------------------------
-
-Usually all shortcuts that are listed will be created when the user clicks
-the 'Next' button. However it is possible to control to some degree if
-specific shortcuts should be created or not. This is based on install
-conditions. By including one or more ``<createForPack name=''a pack name''
-/>`` tags in the specification for a shortcut, you can direct the
-ShortcutPanel to create the shortcut only if any of the listed packs are
-actually installed. The 'name' attribute is used to define the name of one of
-the packs for which the shortcut should be created. You do not need to list
-all packs if a shortcut should always be created. In this case simply omit
-this tag altogether.
-
-
-**A word of caution**
-
-
-For any shortcut that is always created, i would recommend to omit this tag,
-since i have seen a number of problems related to changing pack names. You
-can save yourself some troubleshooting and some Aspirin by not using this
-feature if it's not required. On the other hand if you need it i would advise
-to be very careful about changing pack names.
-
-
-
-DesktopShortcutCheckboxEnabled Builtin Variable
------------------------------------------------
-
-``$DesktopShortcutCheckboxEnabled`` : When set to true, it automatically
-checks the "Create Desktop Shortcuts" button. To see how to use it, go to
-`The Variables Element ``<variables>``
-
-Be careful this variable is case sensitve !
-
-
-Summary
--------
-
-**Native Libraries**
-
-- ShellLink.dll ``- required by Microsoft Windows``
-- 'Nothing' ``- for KDE/Gnome shortcuts``
-
-**Names of the Specification Files**
-``shortcutSpec.xml`` for Windows and as default.
-``Unix_shortcutSpec.xml`` for Unix.
-
-
-**Specification File Layout - Windows**
-
-::
-
- <shortcuts>
- <skipIfNotSupported/>
- <programGroup defaultName="MyOrganization\MyApplication"
- location="applications||startMenu"/>
- <shortcut
- name="Start MyApplication"
- target="$INSTALL_PATH\Path\to\MyApplication\launcher.bat"
- commandLine=""
- workingDirectory="$INSTALL_PATH\Path\to\MyApplication"
- description="This starts MyApplication"
- iconFile="$INSTALL_PATH\Path\to\MyApplication\Icons\start.ico"
- iconIndex="0"
- initialState="noShow||normal||maximized||minimized"
- programGroup="yes||no"
- desktop="yes||no"
- applications="yes||no"
- startMenu="yes||no"
- startup="yes||no">
-
- <createForPack name="MyApplication Binaries"/>
- <createForPack name="MyApplication Batchfiles"/>
- </shortcut>
- </shortcuts>
-
-
-**A sample Specification File for Unix is at the end of this chapter**
-
-
-Shortcut Tips
--------------
-
-I wrote this section to provide additional information about issues
-surrounding the creation of shortcuts. Reading this section is not necessary
-to successfully create shortcuts, but it might help you creating an
-installation that works more smoothly. In addition, it might give you some
-knowledge about operating systems that you don't know so well. In fact most
-of the issues described in this section are focused on differences in
-operating system specifics.
-
-
-The Desktop
-'''''''''''
-
-You should recognize that the desktop is precious real estate for many
-people. They like to keep it uncluttered and keep only the things there that
-they use on a regular basis. This is not true for everybody and you might
-personally think different about this. Still, the fact remains that a lot of
-people might have different feelings about it, so you should not
-automatically assume that it is ok to place all of your shortcuts on the
-desktop proper. While your application is certainly one of the most important
-things for you, for your customers it is probably one of many applications
-they use and maybe not even the most important one. Accordingly, placing more
-shortcut icons there than they feel they will use on a regular basis and
-especially doing this without asking for permission might trigger some bad
-temper.
-
-
-Annotation: But even the experienced user should be able to organize their
-Desktop. On Linux the users desktop is the only place, which supports any
-kind of shortcuts.
-
-
-It is common practice to create a program group in the application menu
-system of the OS and place all shortcuts that go with an application in that
-program group. In addition, only one shortcut to the key access point of the
-application is placed directly on the desktop. Many installers first ask for
-permission to do so, as does the ShortcutPanel in IzPack.
-
-
-I would like to recommend that you always create a shortcut in the menu
-system, even if your application has only one access point and you are
-placing this on the desktop. Note that shortcuts can also be placed directly
-in the menu, they don't need to be in a program group. There are two reasons
-for doing so.
-
-
-- If the user elects not to create shortcuts on the desktop, they will
- end up with no access point to your application
-- Even if this works fine, occasionally people 'clean up' their
- desktop. They might later find that they accidentally deleted the only
- access point to your application. For the less technology savvy users,
- recreating the shortcut might be a rough experience.
-
-
-Icons
-''''''
-
-Icons are supplied in image files, usually in some kind of bitmap format.
-Unfortunately there is no format that is universally recognized by all
-operating systems. If you would like to create shortcuts on a variety of
-operating systems that use your own icons, you must supply each icon in a
-number of different formats. This chapter discusses icon file formats used on
-various operating systems. Fortunately there are good programs available that
-allow you to convert between these formats, so that creating the different
-files is not much of a problem once the icons themselves are created.
-
-
-**Microsoft Windows**
-
-
-Windows prefers to use its native icon file format. Files of this type
-usually use the extension .ico. These so called ICO files can hold multiple
-icons in one file, which can be useful if the same icon is to be provided in
-a number of sizes and color-depths.
-
-Windows itself selects the icon with the most matching dimensions and
-displays it. While the Start menu displays the icon with 16x16 pixel if
-available, the desktop displays the 32x32 pixel resolution of the same ICO if
-this is in.
-
-In other words, a ICO file has embedded one or more dimensions of the same
-Icon. We recommend to play with `microangelo`.
-
-Dlls and Exe files on the other side, can store, amongst other things, a
-collection of different Icons. You can select your desired Icon by its index.
-The lowest index is 0. Use the iconIndex attribute in the spec file to
-specify this index.
-
-
-As a sample look into
-
-::
-
- %SystemRoot%\system32\shell32.dll
-
-
-These contains a lot of Windows own icons. You can use the `PE Explorer` or
-another Resource Editor to extract or modify Icons in dlls or exe files. But
-be warned. You can also destroy a working application with these kind of
-tools.
-
-At least Windows also supports the use of bitmap files in the .bmp format as
-icons. Note that this format does not support multiple icons.
-
-
-We might have overlooked other file formats that are supported by Windows.
-However, we suggest to test other formats for compatibility as they might not
-work all the way back to Windows 95 or on the NT/non-NT strain. Sticking with
-one of these two formats should keep you out of trouble.
-
-
-**Apple**
-
-
-Apple Macintosh systems use the Macintosh PICT format, extension .pct. If
-you are working with an apple system you know a whole lot more about this
-format than i do. If you don't but would like to be able to install your
-application on a Mac, simply start with any bitmap format that you feel
-comfortable to work with. Then find an application that is capable of
-converting this format into a .pct file. i like to use Paint Shop Pro (PC
-based), because it provides conversion capabilities among several dozen
-different file formats.
-
-
-**UNIX flavors**
-
-
-by Marc Eppelmann
-
-
-As my knowledge, all X based Unix Window systems supports the (ASCII-) XBM
-(X-Bitmap ) and the better XPM (X-PixMap) format. The modern GUI systems like
-KDE and Gnome can display additionally a lot of other ImageIcon formats, such
-as GIF, JPG, and PNG.
-
-
-i suggest to use PNG, because this can lossless compress like the GIF format,
-however this format is absolutely free. And not least, this can store true
-transparency informations (It has an alpha channel).
-
-
-Targets
-''''''''
-
-So, you thought you could escape the ugly mess of operating system
-dependencies at least with the way how your Java application is started?
-Sorry but i have just another bad message. The one positive thing is that
-here you have a way of escaping, even if doing so has a few less pretty side
-effects. At first, i would like to discuss various launching options you have
-available on different operating systems. At the end of the chapter i write
-about a way to make launching your application OS independent.
-
-
-**Microsoft Windows**
-
-
-On Microsoft Windows you have a variety of options for launching your
-application. Probably the most simple case is directly starting the Java VM
-from the command line and typing out all parameters, such as class path, the
-class name etc. In principle, this can be placed right in a shortcut and
-should work.
-
-
-A little more elegant solution is to place this in a batch file and have the
-shortcut point to this batch file. This will also make it more likely that
-users can repair or recreate shortcuts. Recreating shortcuts with
-sophisticated command lines is practically impossible.
-
-
-Another method is less commonly used but just as possible. Implement a native
-executable that launches the VM with your Java application. The VM comes as
-DLL and is used by java.exe in just the same way. As a sample look at the
-exlipse.exe provided by the `Eclipse-IDE`
-
-
-Clearly, even though the first option is a bit ugly and has some
-restrictionss, it is the most portable solution among the three.
-
-
-**Apple**
-
-
-We hope, there is a IzPack developer currently researching for the details
-for the Mac environment. We expect an updated chapter in one of the next
-releases.
-
-
-**UNIX**
-
-
-UNIX provides essentially the same options as Windows. You can simply use the
-command line option, you can write a shell script and you can write a native
-launcher. Naturally this stuff is in no way compatible with the equivalent
-Windows implementations. The native option is even more problematic in this
-environment, since the code can not even be moved from one UNIX platform to
-another, without recompilation.
-
-
-**OS Independent Launching**
-
-
-So, after all this rather discouraging news, there is actually a portable way
-to launch Java applications? You bet! although i have to admit that it is not
-necessarily the most pretty way of doing things.
-
-
-This approach is currently used by IzPack. Package your application in a
-.jar file if you don't already do so and make it executable by including the
-necessary metaINF/MANIFEST.MF information file. i am not going into all the
-details on how exactly to do this, the Java documentation will have to do.
-You might have noticed that even though the instructions to install IzPack
-say to type :
-
-::
-
- java -jar IzPack-install.jar
-
-
-You can just as well double click on IzPack-install.jar and it will start up.
-This procedure will work on all GUI based Java supported operating systems
--though you might have to replace double clicking with dropping the file on
-the VM. In just the same way, you can make the .jar file itself the target
-of a shortcut. Note: This works only, if jars are registered as files, which
-have to launch by the installed JRE (with: javaw.exe -jar)
-
-
-The one restriction with this approach is that a .jar file can only have one
-main file. So, if you have multiple targets, they need to be packaged each
-into a different .jar file. They can be in one .jar file but then you have
-to start them explicitly, which gets you back to the problems that i
-mentioned before. This brings me to the ugly part. If you have just one
-target, then you are all set. If you have multiple targets, you need to
-create a .jar file for each of them. In addition, you have a much harder
-time setting the classpath, because each of the .jar files that contain
-supporting code must be listed. In fact, at present there is no way of
-setting this during the installation, because IzPack does not yet (version
-3.0) support the setting and modification of environment variables.
-
-
-
-Command Line
-------------
-
-Before i start to write a lot about the use of command line arguments let me
-state this: If you can avoid using them, do it! Not that there is anything
-wrong with command line arguments as such. The issue is simply that if you
-want your application to be usable cross platform (the big Java promise) you
-should shy away from using command line arguments. The problem here is that
-not all operating systems actually support command line arguments. To be more
-precise, to my knowledge only Apple operating systems do not support command
-line parameters. If you don't care for running your application on a Mac,
-then you might not worry about his at all. If you are interested to support
-the Mac as well, read on.
-
-
-In fact the Mac lower than MacOSX supports command line parameters in a way.
-More to the point, it supports a single parameter that your application
-should interpret as the name of a data file to open. You have no way of
-supplying this to your application through the command line attribute. The
-operating system generates this when the user drops the file on your
-application and then passes it as command line argument. That's it. This same
-behavior will probably fly well on pretty much any system and should
-therefore be an ok implementation.
-
-
-So what to do if you want to modify program behavior based on runtime
-switches? For one thing, you could set system properties accordingly. The
-disadvantage here is the same as with the command line parameters: the way of
-setting these might vary between operating systems. The best way seems to be
-using a property file that contains the configuration data.
-
-
-
-Trouble Shooting
------------------
-
-by Elmar
-
-It has been some time since i wrote this chapter during which a good number
-of users had a chance to gather experience. Unfortunately i never know how
-many have used it successfully without much difficulty. i only hear from
-those that have encountered one problem or another. The type of problems that
-i have seen prompted me to write this section, because i think it will help
-you in locating most problems that you might encounter or at least give you
-some idea where the problem might be located.
-
-
-
-Problems You Can Solve
-'''''''''''''''''''''''
-
-If you see an exception that essentially says that a library can not be
-loaded (ShellLink.dll) you have an easy problem to deal with. Your installer
-file is probably missing the native tag that adds the Windows dll to the
-installer or something with this tag is no quite right. Read 'What to Add to
-the Installer' for all details on this topic.
-
-
-Most other problems cause the ShortcutPanel not to show at all during the
-installation process. The reason is simply that the ShortcutPanel skips if it
-does not know what to do or if it has nothing to do (no point showing then
-and confusing the user). The problem is that this is not always what you
-intended. The most simple but not so uncommon case is, that the ShortcutPanel
-cannot find their spec file. This can be caused by a number of reasons. The
-associated resource tag might be missing in the installer specification file,
-the target file name might be misspelled (the name you specify for the ``id``
-attribute) or the target file name has a path or package name pre-pended. You
-have only to use ``shortcutSpec.xml`` or ``Unix_shortcutSpec.xml`` and
-nothing else, just as described in 'What to Add to the Installer'. You can
-always verify if this part is ok by inspecting the content of the installer
-.jar file. The file shortcutSpec.xml should be located in the directory
-``res``. This inspection can be performed with any zip tool. If the file is
-not there, first correct this before proceeding.
-
-
-If the file is there and the panel does not appear, you have a problem within
-the specification file. In most cases that i have seen, it comes down to a
-spelling mistake of an attribute or tag name. You just have to carefully make
-sure that everything is spelled correctly. Don't forget that all names are
-case sensitive! In a few cases it is also happend, that required or semi-
-optional attributes are omitted, so you might want to verify if all
-attributes that you need are actually supplied.
-
-
-If everything is correct up to this point the problem becomes more elusive.
-Most likely the panel will not be displayed, because it is instructed not to
-show. There are be several reasons for this. The simple case is that no
-location has been specified for the shortcuts in your installation. This can
-happen if all five location attributes are omitted or if all the ones that
-are listed are set to ``no``. Remember, you have to specify at least one
-location for every shortcut. If this is also correct, you might have used the
-``<createForPack>`` tag. Review the details in 'Selective Creation of
-Shortcuts'. One possibility for the panel not to show is that based on the
-packs that are currently selected for installation no shortcut qualifies for
-creation. In this case the panel will not show, this is perfectly normal
-behavior. More likely this condition is true because of some accident and not
-because it's intended. Make sure the packs that you list for the shortcut are
-actually defined in your installation and verify that they are all spelled
-correctly. Remember: case matters! Did the ShortcutPanel use to work in your
-installation and all of a sudden stopped working? Very likely you are dealing
-with the last problem. A package name might have been modified and the
-shortcut spec was not adjusted to stay in sync.
-
-
-
-Problems That Have No Solution (yet)
-'''''''''''''''''''''''''''''''''''''''
-
-Unfortunately one problem has been very persistent and only recently one user
-found the reason. The problem occurs when installing on some target systems
-where non-English characters are used in the storage path for the shortcuts.
-The problem is that these characters don't seem to be properly translated
-across the Java Native Interface. This leads to a situation where the proper
-path can not be located and the shortcut creation fails. i write 'some target
-systems' because it does not fail everywhere. After much agonizing over this
-problem, one user found the solution: The shortcut creation works fine if a
-Sun virtual machine is installed, but fails if a version from IBM happens to
-be installed. So far i have no solution for this problem but i am trying to
-find a workaround the problem.
-
-
-
-A sample shortcut specification file for Unix
-----------------------------------------------
-
-::
-
- <?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
-
- <shortcuts>
-
- <programGroup defaultName="IzForge/IzPack"
- location="applications"/>
-
- <!-- Disabled since there is no Frontend
- shortcut
- name="IzPack"
- programGroup="yes"
- desktop="yes"
- applications="no"
- startMenu="yes"
- startup="no"
- target="$INSTALL_PATH/bin/izpack-fe.sh"
- commandLine=""
- workingDirectory="$INSTALL_PATH/bin"
- description="Front-End for IzPack installation tool"
- iconFile="$INSTALL_PATH/bin/icons/izpack.png"
- iconIndex="0"
- type="Application"
- encoding="UTF-8"
- terminal="true"
- KdeSubstUID="false"
- initialState="normal">
- <createForPack name="Core"/>
- </shortcut -->
-
- <shortcut
- name="IzPack Documentation"
- programGroup="yes"
- desktop="yes"
- applications="no"
- startMenu="yes"
- startup="no"
- target="konqueror"
- workingDirectory=""
- commandLine=""
- initialState="noShow"
- iconFile="help"
- iconIndex="0"
- url="$INSTALL_PATH/doc/izpack/html/izpack-doc.html"
- type="Link"
- encoding="UTF-8"
- description="IzPack user documentation (html format)">
-
- <createForPack name="Documentation-html"/>
- </shortcut>
-
- <shortcut
- name="Documentation"
- programGroup="yes"
- desktop="yes"
- applications="no"
- startMenu="yes"
- startup="no"
- target="acroread"
- workingDirectory=""
- commandLine="$INSTALL_PATH/doc/izpack/pdf/izpack-doc.pdf"
- initialState="noShow"
- iconFile="acroread"
- iconIndex="0"
- url="$INSTALL_PATH/doc/izpack/pdf/izpack-doc.pdf"
- type="Application"
- encoding="UTF-8"
- description="IzPack user documentation (PDF format)">
-
- <createForPack name="Documentation-PDF"/>
- </shortcut>
-
- <shortcut
- name="Uninstaller"
- programGroup="yes"
- desktop="yes"
- applications="no"
- startMenu="no"
- startup="no"
- target="/usr/lib/java/bin/java"
- commandLine="-jar
- "$INSTALL_PATH/Uninstaller/uninstaller.jar""
- initialState="noShow"
- iconFile="trashcan_full"
- iconIndex="0"
- workingDirectory=""
- type="Application"
- encoding="UTF-8"
- description="IzPack uninstaller">
- <createForPack name="Core" />
- </shortcut>
-
- </shortcuts>
+Desktop Shortcuts
+=================
+
+(by Elmar GROM and Marc EPPELMANN)
+
+Defining Shortcuts
+------------------
+
+
+Introduction
+'''''''''''''
+
+On todays GUI oriented operating systems, users are used to launching
+applications, view web sites, look at documentation and perform a variety of
+other tasks, by simply clicking on an icon on the desktop or in a menu system
+located on the desktop. Depending on the operating system these icons have
+different names. In this context we will refer to them collectively as
+shortcuts.
+
+
+Apart from actually placing an application on the target system, users
+routinely expect an installer to create the necessary shortcuts for the
+application as well. For you as application developer, this means that for a
+professional appearance of your product you should also consider creating
+shortcuts.
+
+
+In contrast to the general specification of an IzPack installer, the
+specification of shortcuts in IzPack requires a little more effort. In
+addition, some of the concepts are a bit more complex and there are some
+operating system specific issues to observe. Fortunately, you only need to
+worry about operating system specifics if you want to deploy your application
+to multiple different operating systems. In any case, it will pay off to
+spend some time to study this documentation and the example spec files before
+you start to implement your own shortcuts.
+
+
+At the time of writing this Chapter the current IzPack Version 3.7.0-M3 is
+only capable to creating shortcuts on
+
+1. Microsoft Windows, and
+2. Unix and Unix-based operating systems (like Linux), which use the
+ `X11` GUI-System and ` FreeDesktop.org` based shortcut handling (such
+ as `KDE` and `Gnome`).
+
+Other operating or GUI systems, such as MacOS X are not
+supported. However, there is a special UI-variant that automatically pops up
+on unsupported systems. It informs the user about the intended targets of
+your shortcuts and allows the user to save this information to a text file.
+While this is not an elegant solution, at least it aids the user in the
+manual creation of the shortcuts.
+
+
+If you would like to review what an end user would see if the target
+operating system is not supported, you can do the following. Simply place the
+tag ``<notSupported/>`` in the spec file. This tag requires no attributes or
+other data. It must be placed under ``<shortcuts>``, just like the individual
+shortcut specifications. Be sure to remove this tag before getting your
+application ready for shipment.
+
+
+We expect other operating systems to be supported in the near future and as
+always, contributions are very welcome. At present someone is actively
+working on Mac support.
+
+
+What to Add to the Installer
+'''''''''''''''''''''''''''''
+
+There are some things that you have to add to your installer to enable
+shortcut creation. Obviously you need to add the panel responsible for
+creating shortcuts. This panel is aptly enough called ShortcutPanel. However,
+in order for the ShortcutPanel to work properly a number of additional items
+are required. These must be added manually to the installer, as all other
+resourcs, since the front-end will be rewritten. In this chapter we will
+explain which of these items are required and for what reason.
+
+
+First, we would like to discuss items that are supplied with IzPack and only
+need to be added to the installer. After that, we move on to the things you
+have to prepare yourself before you can add them. The way in which shortcuts
+are created varies widely among operating systems. In some cases it is
+possible to do this with pure Java code, while other systems -such as MS-
+Windows- require native code to accomplish this task. On the other side, the
+current implementation, which creates shortcuts on Unix based systems needs
+no native library at all, since it works with 'these' pure Java code. The
+native library required for the Windows operating systems are supplied with
+IzPack is called ``ShellLink.dll``. Note: They will not be automatically
+added to your installer file. You need to list them yourself in the XML file
+for the installer. A describtion how to do this follows in the next section.
+
+
+Native libraries can be added to the installer by using the ``<native>`` tag.
+To add the ``ShellLink.dll``, you just have to add the following line to the
+installer XML file:
+``<native type="izpack" name="ShellLink.dll"/>``
+For more details about the use of the ``<native>`` tag see the chapter about
+the format of the XML file.
+
+
+You have also to add an extra specification file for each platform family to
+enable shortcut creation on these platforms. At least one (the default file)
+is required by the shortcut panel. The format of all spec files is XML and
+they must be added to the installer as a resource. The source name of this
+specification does not matter, however its resource name (also called id or
+alias) when added to the installer must be ``(prefix)+shortcutSpec.xml``.
+At this release, there are only two prefixes supported: "Win" for the
+Windows family and "Unix" for all Unixes. If the prefix is ommited the
+shortcut panel searches for a named resource: `` shortcutSpec.xml``. This is
+the default resource name. As the default resource name will be used on
+Windows platforms, the ``"Win_shortcutSpec.xml"`` can be ommited.
+Hint: If the shortcut panel does not find one of these named resources, it
+will never appears. So, do not use different resource names and do not add a
+path to these.
+
+ShortcutSpecs can be localized, see "Localizing shortcuts" below.
+
+**Example**
+
+
+::
+
+ <res src="C:\MyDocuments\Installer\default_shortcut_specification.xml"
+ id="shortcutSpec.xml"/>
+ <res src="C:\MyDocuments\Installer\unix_shortcut_specification.xml"
+ id="Unix_shortcutSpec.xml"/>
+
+
+Why use different shortcut spec files?
+
+
+1. The Target filenames are most different.(batch files on Windows vs.
+ shell scripts on Unix.)
+2. The Icon file formats are different. ICOs on Windows-, PNGs on Unix-
+ platforms.
+3. The Target locations can be different.
+4. If your installer is localized, your users sure will expect their
+ shortcuts names and descriptions to be as well. Moreover, some paths
+ can be different when OS are localized (``My Documents`` becomes
+ ``Mes Documents`` on Windows in french for example). See "Localizing
+ shortcuts" below.
+
+This is the simple reason.
+
+
+
+Why Native Code to do the Job on Windows?
+-----------------------------------------
+
+by Elmar
+
+
+This little chapter is not strictly part of the documentation but i have been
+asked this question sufficiently often that i think it's worth explaining
+right here. It is certainly a natural question to ask. After all IzPack is an
+application completely written in Java and primarily targeted for the
+installation of Java based programs. So why wouldn't we try to keep
+everything pure Java and avoid the use of native code altogether? There must
+be some personal preference of the developer hidden behind this approach you
+might think. Well, not really, but i admit at first it seems quite feasible
+to write it all in Java. On virtually any operating system or GUI surface
+around, Shortcuts are simply files on the local file system. Files can be
+created and accessed directly from within Java, so why should there be a need
+for using native code?
+
+
+Well, it turns out that just creating a file is not good enough, it also
+needs to have the right content. Shell Links as they are called in Windows
+land are binary files. i actually managed to find documentation on the
+format. Naturally this was hacker data, you won't get this sort of thing from
+Microsoft (by the way: thanks a lot to Jesse Hager for a smash job!). Armed
+with this information i tried to create these files myself in Java. The
+problem was that the documentation was not entirely accurate and had some
+gaps as well. i tried for over a month to get this to work but finally i had
+to give up. Even if i would have succeeded, it would have been a hack, since
+a shell link requires some information that is impossible to obtain from
+within Java. Usually you can successfully create a shell link by only filling
+in the bare minimum information and then ask Windows to resolve the link.
+Windows then repairs the shell link. Unfortunately this was only the
+beginning, soon i encountered a host of other problems. For one thing, the
+installer needs to know the correct directories for placing the links and it
+turns out they are named differently in different countries. In addition,
+there are ways of manually modifying them, which some people might actually
+have done. The only way to place the shortcut files reliably is through
+accessing the Windows Registry. Naturally, this operation also required
+native code. Same thing with asking Windows to resolve the link... On the
+bottom line, at every step and turn you run into an issue where you just need
+to use native code to do the trick. So i decided that i would do it the
+proper way all the way through. That is in a nutshell the reason why i used
+native code to create shortcuts on MS-Windows.
+
+
+As i am writing this i am at work with a friend to replicate this work for
+the Mac and it looks very much like we need to take the same approach there
+as well. On the various Unix GUIs on the other hand, we are lucky that we can
+do the job without native libraries.
+
+
+
+The Shortcut Specification
+--------------------------
+
+As we say above, the specification for shortcuts is provided to the
+ShortcutPanel in the XML fileformat. At the time of this writing (for IzPack
+version 3.7.0-M3) the front-end will be rewritten. Until these work is in
+progress you have to write the specification files manually. For your
+convenience, there are two annotated sample specification files in the sample
+subdirectory of your IzPack installation. At the beginning you might want to
+experiment with these files.
+
+
+Both specification files have one root element called ``<shortcuts>``. This
+root elements recognizes 3 different child elements:
+``<programGroup>``, ``<skipIfNotSupported/>`` and ``<shortcut>``.
+
+
+``<skipIfNotSupported/>`` can be used to avoid the panel to show the
+alternative UI which shows the shortcut information that would have been
+created on a system that supports it. In other words, using this tag will
+make the panel be silent on non-supported systems. The default is to show the
+alternative UI.
+
+
+The ``<programGroup>`` tag allows you to specify the name of the menu, or
+more precise, 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, however you can partially
+control it. Please note that ``<programGroup>`` may only appear once in the
+specification. If more than one instance occurs, only the first one will be
+used. This tag requires two attributes: ``defaultName`` and ``location``.
+``defaultName`` specifies the name that the group menu should have on the
+target system. You should be aware that the ShortcutPanel will present this
+name to the user as a choice. The user can then edit this name or select a
+group that already exists. As a result, there is no guarantee that the actual
+name of the program group on the target system is identical with your
+specification. ``location`` specifies where the group menu should show up.
+There are two choices: ``applications`` and ``startMenu``. If you use
+``applications``, then the menu will be placed in the menu that is ordinarily
+used for application shortcuts. ``applications`` is recommended for Unix
+shortcuts. If you use ``startMenu``, the group menu will be placed at the top
+most menu level available on the target system. Depending on the target
+system, it might not be possible to honor this specification exactly. In such
+cases, the ShortcutPanel will map the choice to the location that most
+closely resembles your choice. Unix shortcuts do not need to support the
+``startMenu``, because the ``applications`` menu is already on the highest
+level. This means this has no affect on thess platform.
+
+
+For each shortcut you want to create, you have to add one ``<shortcut>`` tag.
+Most details about the shortcut are listed as attributes with this tag. The
+following sections describe what each attribute does, which attributes are
+optional and which ones are required and what the values are that are
+accepted for each of the attributes. Note that all attributes that have a
+yes/no choice can also be omitted. Doing so has the same effect as using a
+value of no. The shortcut 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 following attributes are used to define location:
+
+- ``programGroup``
+- ``desktop``
+- ``applications``
+- ``startMenu``
+- ``startup``
+
+
+Shortcut Attributes
+-------------------
+
+There are three classes of attributes. Some are required, most are completely
+optional and some are semi-optional. The set of semi-optional attributes are
+all the attributes used to define the location of a shortcut. These are semi-
+optional because for any individual one it is your choice if you want to
+include it or not. However they are not completely optional. You must specify
+at least one location. If all were omitted, the instruction would essentially
+tell the panel that a copy of this shortcut is to be placed at no location.
+In other words no copy is to be placed anywhere.
+
+**name** ``- required``
+
+
+The value of this attribute defines the 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.
+
+
+**target** ``- required``
+
+
+The value of this attribute points to the application that should be launched
+when the shortcut is clicked. The value is translated through the variable
+substitutor. Therefore variables such as ``$INSTALL_PATH`` can be used to
+describe the location. **You should be aware that the use of this tag is
+likely to change once other operating systems are supported**.
+
+
+**commandLine** ``- optional``
+
+
+The value of this attribute will be passed to the application as command
+line. i recommend to work without command line arguments, since these 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.
+
+
+**workingDirectory** ``- optional``
+
+
+This attribute defines the working directory for the application at the time
+it is launched. i would recommend some caution in relying on this too heavily
+if your application should be portable, since this might not be supported by
+all operating systems. At this time i don't have enough information to make a
+definite statement one way or the other. The value is translated through the
+variable substitutor. Therefore variables such as ``$INSTALL_PATH`` can be
+used to describe the directory.
+
+
+**description** ``- optional``
+
+
+The 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 MS-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 but i think it is always a good
+idea to include a brief description.
+
+
+**iconFile** ``- optional``
+
+
+The value of this attribute points to the file that holds the icon that
+should be displayed as a symbol for this shortcut. This value is also
+translated through the variable substitutor and consequently can contain
+variables such as $INSTALL_PATH. 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. **The use of this attribute is also likely to change
+once other operating systems are supported. Read the Section about Icons
+below, for more information.**
+
+
+**iconIndex** ``- optional``
+
+
+If 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. i would also
+advise against using this feature, because of operating system
+incompatibilities in this area. In file formats that do not support multiple
+icons, this values is ignored.
+
+
+**initialState** ``- optional``
+
+
+There are four values accepted for this attribute: ``noShow``, ``normal``,
+``maximized`` and ``minimized``. If the target operating system supports this
+feature, then this value will have the appropriate influence on the initial
+window state of the application. ``noShow`` is particularly useful when
+launch scripts are used that cause a command window to open, because the
+command window will not be visible with this option. For instance on MS-
+Windows starting 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 are buttons for both windows in the task bar. Using
+``noShow`` will completely eliminate this effect, only the Java application
+window will be visible. *On Unix use* ``normal`` *, because this is not
+supported*.
+
+
+**programGroup** ``- semi-optional``
+
+
+The value for this attribute can be either yes or no. Any other value will be
+interpreted as no. If the value is yes, then a copy of this shortcut will be
+placed in the group menu. *On Unix (KDE) this will always be placed on the
+top level.*
+
+
+**desktop** ``- semi-optional``
+
+
+For this attribute the value should also be yes or no. If the value is yes,
+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, who currently runs the
+installer. For Gnome the user can simply copy the *.desktop files from*
+``/Desktop`` *to* ``/gnome-desktop``. (This is already a TODO for the Unix-
+shortcut implementation.)
+
+
+**applications** ``- semi-optional``
+
+
+This is also a yes/no attribute. If the value is yes, 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
+program group. *This makes no sense on Unix.*
+
+
+**startMenu** ``- semi-optional``
+
+
+This is a yes/no attribute as well. If the value is yes, 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. see above.*
+
+
+**startup** ``- semi-optional``
+
+
+This is also a yes/no attribute. If the value is yes, 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
+also not supported on Unix.*
+
+
+
+Unix specific shortcut attributes
+----------------------------------
+
+This extension was programmed by MARC EPPELMANN. This is still in development
+and may be changed in one of the next releases of IzPack.
+
+
+**type** ``- required``
+
+
+This must be one of ``Application`` or ``Link``
+
+
+- Application: To start any application, native, Java or shell-script
+ based, the **type** has to be ``Application``. The GUI-System will launch
+ this Application, so as is, thru their native shell or application
+ launcher. In this case, note that the right ``workingDirectory`` is
+ always important on Unix platforms. If the users PATH environment
+ variable does not contain the path, where the application is located,
+ this can never be run, until the ``workingDirectory`` does not contain
+ these path. The needed current path: ".", this is the case on most
+ systems, should be in the users PATH environment variable. Consult the
+ Unix manuals for more details.
+- Link: If you want to open a URL in the users default Webbrowser, you
+ have to set the **type** to ``Link``. Note: The ``url`` attribute must be
+ set to work properly.
+- Other: There are more supported types on KDE, like FSDevice, but
+ these types makes no sense for IzPack, in my opinion.
+
+Without the type the Unix shortcut does not work.
+
+
+**url** ``- semi-optional``
+
+
+If you want to create a shortcut as type *Link*, then you have to set the
+``url`` attribute. The value can be a locally installed html or another
+document, with a known MIME type, like plain text, or a WWW Url i.e.
+'https://izpack.github.io/'.
+
+
+A local document can be referenced by i.e. "$INSTALL_PATH/doc/index.html".
+
+
+The IzPack variable substitution system is supported by the **url**.
+
+
+**encoding** ``- required``
+
+
+This should always set to **UTF-8**.
+
+
+**terminal** ``- optional``
+
+
+If you want, the user can see the console output of a program (in Java
+applications "System.outs"), set the ``terminal`` attribute to **true**.
+
+
+**KdeSubstUID** ``- unused``
+
+
+This is not fully implemented by IzPack. i the future this is the sudo option
+for a shortcut.
+
+
+
+Selective Creation of Shortcuts
+-------------------------------
+
+Usually all shortcuts that are listed will be created when the user clicks
+the 'Next' button. However it is possible to control to some degree if
+specific shortcuts should be created or not. This is based on install
+conditions. By including one or more ``<createForPack name=''a pack name''
+/>`` tags in the specification for a shortcut, you can direct the
+ShortcutPanel to create the shortcut only if any of the listed packs are
+actually installed. The 'name' attribute is used to define the name of one of
+the packs for which the shortcut should be created. You do not need to list
+all packs if a shortcut should always be created. In this case simply omit
+this tag altogether.
+
+
+**A word of caution**
+
+
+For any shortcut that is always created, i would recommend to omit this tag,
+since i have seen a number of problems related to changing pack names. You
+can save yourself some troubleshooting and some Aspirin by not using this
+feature if it's not required. On the other hand if you need it i would advise
+to be very careful about changing pack names.
+
+
+Localizing shortcuts
+---------------------
+
+The izPack installer allows localization of your installer. Obviously, you will
+want your shortcuts labels to be localized, too. Thus, you can provide
+shortcutSpec files for each language you support.
+
+This works just like localizing other specs for other panels : add an
+underscore and the iso3 language code to the end of the resource name, and set
+the source name to the appropriate localized spec file.
+As for the platforms, if a specific spec file is not declared for the current
+language, the installer will revert to the default ``shortcutSpec.xml`` resource.
+This way, you can for example have a resource ``shortcutSpec.xml_fra`` for
+french installs and have the default resource ``shortcutSpec.xml`` (maybe
+containing strings in english) be used for other languages.
+
+The platform prefix and language suffix are combined like in this example :
+ ``Unix_shortcutSpec.xml_fra``.
+When the installer can't find such a platform-and-language-specific resource,
+it will fallback to a suitable default using the following search order :
+ ``shortcutSpec.xml_<iso3>`` (default platform, language-specific)
+ ``<platform>_shortcutSpec.xml`` (default language, platform-specific)
+ ``shortcutSpec.xml`` (default platform and language)
+
+Reminder: If the shortcut panel does not find one of these named resources,
+it will never appear. So, do not use different resource names and do not add
+a path to these.
+
+**Example**
+
+::
+ <res src="C:\MyDocuments\Installer\default_shortcut_specification.xml"
+ id="shortcutSpec.xml"/>
+ <res src="C:\MyDocuments\Installer\default_shortcut_specification_fr.xml"
+ id="shortcutSpec.xml_fra"/>
+ <res src="C:\MyDocuments\Installer\unix_shortcut_specification_en.xml"
+ id="Unix_shortcutSpec.xml"/>
+ <res src="C:\MyDocuments\Installer\unix_shortcut_specification_fr.xml"
+ id="Unix_shortcutSpec.xml_fra"/>
+
+
+DesktopShortcutCheckboxEnabled Builtin Variable
+-----------------------------------------------
+
+``$DesktopShortcutCheckboxEnabled`` : When set to true, it automatically
+checks the "Create Desktop Shortcuts" button. To see how to use it, go to
+`The Variables Element ``<variables>``
+
+Be careful this variable is case sensitve !
+
+
+Summary
+-------
+
+**Native Libraries**
+
+- ShellLink.dll ``- required by Microsoft Windows``
+- 'Nothing' ``- for KDE/Gnome shortcuts``
+
+**Names of the Specification Files**
+``shortcutSpec.xml`` for Windows and as default.
+``Unix_shortcutSpec.xml`` for Unix.
+
+
+**Specification File Layout - Windows**
+
+::
+
+ <shortcuts>
+ <skipIfNotSupported/>
+ <programGroup defaultName="MyOrganization\MyApplication"
+ location="applications||startMenu"/>
+ <shortcut
+ name="Start MyApplication"
+ target="$INSTALL_PATH\Path\to\MyApplication\launcher.bat"
+ commandLine=""
+ workingDirectory="$INSTALL_PATH\Path\to\MyApplication"
+ description="This starts MyApplication"
+ iconFile="$INSTALL_PATH\Path\to\MyApplication\Icons\start.ico"
+ iconIndex="0"
+ initialState="noShow||normal||maximized||minimized"
+ programGroup="yes||no"
+ desktop="yes||no"
+ applications="yes||no"
+ startMenu="yes||no"
+ startup="yes||no">
+
+ <createForPack name="MyApplication Binaries"/>
+ <createForPack name="MyApplication Batchfiles"/>
+ </shortcut>
+ </shortcuts>
+
+
+**A sample Specification File for Unix is at the end of this chapter**
+
+
+Shortcut Tips
+-------------
+
+I wrote this section to provide additional information about issues
+surrounding the creation of shortcuts. Reading this section is not necessary
+to successfully create shortcuts, but it might help you creating an
+installation that works more smoothly. In addition, it might give you some
+knowledge about operating systems that you don't know so well. In fact most
+of the issues described in this section are focused on differences in
+operating system specifics.
+
+
+The Desktop
+'''''''''''
+
+You should recognize that the desktop is precious real estate for many
+people. They like to keep it uncluttered and keep only the things there that
+they use on a regular basis. This is not true for everybody and you might
+personally think different about this. Still, the fact remains that a lot of
+people might have different feelings about it, so you should not
+automatically assume that it is ok to place all of your shortcuts on the
+desktop proper. While your application is certainly one of the most important
+things for you, for your customers it is probably one of many applications
+they use and maybe not even the most important one. Accordingly, placing more
+shortcut icons there than they feel they will use on a regular basis and
+especially doing this without asking for permission might trigger some bad
+temper.
+
+
+Annotation: But even the experienced user should be able to organize their
+Desktop. On Linux the users desktop is the only place, which supports any
+kind of shortcuts.
+
+
+It is common practice to create a program group in the application menu
+system of the OS and place all shortcuts that go with an application in that
+program group. In addition, only one shortcut to the key access point of the
+application is placed directly on the desktop. Many installers first ask for
+permission to do so, as does the ShortcutPanel in IzPack.
+
+
+I would like to recommend that you always create a shortcut in the menu
+system, even if your application has only one access point and you are
+placing this on the desktop. Note that shortcuts can also be placed directly
+in the menu, they don't need to be in a program group. There are two reasons
+for doing so.
+
+
+- If the user elects not to create shortcuts on the desktop, they will
+ end up with no access point to your application
+- Even if this works fine, occasionally people 'clean up' their
+ desktop. They might later find that they accidentally deleted the only
+ access point to your application. For the less technology savvy users,
+ recreating the shortcut might be a rough experience.
+
+
+Icons
+''''''
+
+Icons are supplied in image files, usually in some kind of bitmap format.
+Unfortunately there is no format that is universally recognized by all
+operating systems. If you would like to create shortcuts on a variety of
+operating systems that use your own icons, you must supply each icon in a
+number of different formats. This chapter discusses icon file formats used on
+various operating systems. Fortunately there are good programs available that
+allow you to convert between these formats, so that creating the different
+files is not much of a problem once the icons themselves are created.
+
+
+**Microsoft Windows**
+
+
+Windows prefers to use its native icon file format. Files of this type
+usually use the extension .ico. These so called ICO files can hold multiple
+icons in one file, which can be useful if the same icon is to be provided in
+a number of sizes and color-depths.
+
+Windows itself selects the icon with the most matching dimensions and
+displays it. While the Start menu displays the icon with 16x16 pixel if
+available, the desktop displays the 32x32 pixel resolution of the same ICO if
+this is in.
+
+In other words, a ICO file has embedded one or more dimensions of the same
+Icon. We recommend to play with `microangelo`.
+
+Dlls and Exe files on the other side, can store, amongst other things, a
+collection of different Icons. You can select your desired Icon by its index.
+The lowest index is 0. Use the iconIndex attribute in the spec file to
+specify this index.
+
+
+As a sample look into
+
+::
+
+ %SystemRoot%\system32\shell32.dll
+
+
+These contains a lot of Windows own icons. You can use the `PE Explorer` or
+another Resource Editor to extract or modify Icons in dlls or exe files. But
+be warned. You can also destroy a working application with these kind of
+tools.
+
+At least Windows also supports the use of bitmap files in the .bmp format as
+icons. Note that this format does not support multiple icons.
+
+
+We might have overlooked other file formats that are supported by Windows.
+However, we suggest to test other formats for compatibility as they might not
+work all the way back to Windows 95 or on the NT/non-NT strain. Sticking with
+one of these two formats should keep you out of trouble.
+
+
+**Apple**
+
+
+Apple Macintosh systems use the Macintosh PICT format, extension .pct. If
+you are working with an apple system you know a whole lot more about this
+format than i do. If you don't but would like to be able to install your
+application on a Mac, simply start with any bitmap format that you feel
+comfortable to work with. Then find an application that is capable of
+converting this format into a .pct file. i like to use Paint Shop Pro (PC
+based), because it provides conversion capabilities among several dozen
+different file formats.
+
+
+**UNIX flavors**
+
+
+by Marc Eppelmann
+
+
+As my knowledge, all X based Unix Window systems supports the (ASCII-) XBM
+(X-Bitmap ) and the better XPM (X-PixMap) format. The modern GUI systems like
+KDE and Gnome can display additionally a lot of other ImageIcon formats, such
+as GIF, JPG, and PNG.
+
+
+i suggest to use PNG, because this can lossless compress like the GIF format,
+however this format is absolutely free. And not least, this can store true
+transparency informations (It has an alpha channel).
+
+
+Targets
+''''''''
+
+So, you thought you could escape the ugly mess of operating system
+dependencies at least with the way how your Java application is started?
+Sorry but i have just another bad message. The one positive thing is that
+here you have a way of escaping, even if doing so has a few less pretty side
+effects. At first, i would like to discuss various launching options you have
+available on different operating systems. At the end of the chapter i write
+about a way to make launching your application OS independent.
+
+
+**Microsoft Windows**
+
+
+On Microsoft Windows you have a variety of options for launching your
+application. Probably the most simple case is directly starting the Java VM
+from the command line and typing out all parameters, such as class path, the
+class name etc. In principle, this can be placed right in a shortcut and
+should work.
+
+
+A little more elegant solution is to place this in a batch file and have the
+shortcut point to this batch file. This will also make it more likely that
+users can repair or recreate shortcuts. Recreating shortcuts with
+sophisticated command lines is practically impossible.
+
+
+Another method is less commonly used but just as possible. Implement a native
+executable that launches the VM with your Java application. The VM comes as
+DLL and is used by java.exe in just the same way. As a sample look at the
+exlipse.exe provided by the `Eclipse-IDE`
+
+
+Clearly, even though the first option is a bit ugly and has some
+restrictionss, it is the most portable solution among the three.
+
+
+**Apple**
+
+
+We hope, there is a IzPack developer currently researching for the details
+for the Mac environment. We expect an updated chapter in one of the next
+releases.
+
+
+**UNIX**
+
+
+UNIX provides essentially the same options as Windows. You can simply use the
+command line option, you can write a shell script and you can write a native
+launcher. Naturally this stuff is in no way compatible with the equivalent
+Windows implementations. The native option is even more problematic in this
+environment, since the code can not even be moved from one UNIX platform to
+another, without recompilation.
+
+
+**OS Independent Launching**
+
+
+So, after all this rather discouraging news, there is actually a portable way
+to launch Java applications? You bet! although i have to admit that it is not
+necessarily the most pretty way of doing things.
+
+
+This approach is currently used by IzPack. Package your application in a
+.jar file if you don't already do so and make it executable by including the
+necessary metaINF/MANIFEST.MF information file. i am not going into all the
+details on how exactly to do this, the Java documentation will have to do.
+You might have noticed that even though the instructions to install IzPack
+say to type :
+
+::
+
+ java -jar IzPack-install.jar
+
+
+You can just as well double click on IzPack-install.jar and it will start up.
+This procedure will work on all GUI based Java supported operating systems
+-though you might have to replace double clicking with dropping the file on
+the VM. In just the same way, you can make the .jar file itself the target
+of a shortcut. Note: This works only, if jars are registered as files, which
+have to launch by the installed JRE (with: javaw.exe -jar)
+
+
+The one restriction with this approach is that a .jar file can only have one
+main file. So, if you have multiple targets, they need to be packaged each
+into a different .jar file. They can be in one .jar file but then you have
+to start them explicitly, which gets you back to the problems that i
+mentioned before. This brings me to the ugly part. If you have just one
+target, then you are all set. If you have multiple targets, you need to
+create a .jar file for each of them. In addition, you have a much harder
+time setting the classpath, because each of the .jar files that contain
+supporting code must be listed. In fact, at present there is no way of
+setting this during the installation, because IzPack does not yet (version
+3.0) support the setting and modification of environment variables.
+
+
+
+Command Line
+------------
+
+Before i start to write a lot about the use of command line arguments let me
+state this: If you can avoid using them, do it! Not that there is anything
+wrong with command line arguments as such. The issue is simply that if you
+want your application to be usable cross platform (the big Java promise) you
+should shy away from using command line arguments. The problem here is that
+not all operating systems actually support command line arguments. To be more
+precise, to my knowledge only Apple operating systems do not support command
+line parameters. If you don't care for running your application on a Mac,
+then you might not worry about his at all. If you are interested to support
+the Mac as well, read on.
+
+
+In fact the Mac lower than MacOSX supports command line parameters in a way.
+More to the point, it supports a single parameter that your application
+should interpret as the name of a data file to open. You have no way of
+supplying this to your application through the command line attribute. The
+operating system generates this when the user drops the file on your
+application and then passes it as command line argument. That's it. This same
+behavior will probably fly well on pretty much any system and should
+therefore be an ok implementation.
+
+
+So what to do if you want to modify program behavior based on runtime
+switches? For one thing, you could set system properties accordingly. The
+disadvantage here is the same as with the command line parameters: the way of
+setting these might vary between operating systems. The best way seems to be
+using a property file that contains the configuration data.
+
+
+
+Trouble Shooting
+-----------------
+
+by Elmar
+
+It has been some time since i wrote this chapter during which a good number
+of users had a chance to gather experience. Unfortunately i never know how
+many have used it successfully without much difficulty. i only hear from
+those that have encountered one problem or another. The type of problems that
+i have seen prompted me to write this section, because i think it will help
+you in locating most problems that you might encounter or at least give you
+some idea where the problem might be located.
+
+
+
+Problems You Can Solve
+'''''''''''''''''''''''
+
+If you see an exception that essentially says that a library can not be
+loaded (ShellLink.dll) you have an easy problem to deal with. Your installer
+file is probably missing the native tag that adds the Windows dll to the
+installer or something with this tag is no quite right. Read 'What to Add to
+the Installer' for all details on this topic.
+
+
+Most other problems cause the ShortcutPanel not to show at all during the
+installation process. The reason is simply that the ShortcutPanel skips if it
+does not know what to do or if it has nothing to do (no point showing then
+and confusing the user). The problem is that this is not always what you
+intended. The most simple but not so uncommon case is, that the ShortcutPanel
+cannot find their spec file. This can be caused by a number of reasons. The
+associated resource tag might be missing in the installer specification file,
+the target file name might be misspelled (the name you specify for the ``id``
+attribute) or the target file name has a path or package name pre-pended. You
+have only to use ``shortcutSpec.xml`` or ``Unix_shortcutSpec.xml`` and
+nothing else, just as described in 'What to Add to the Installer'. You can
+always verify if this part is ok by inspecting the content of the installer
+.jar file. The file shortcutSpec.xml should be located in the directory
+``res``. This inspection can be performed with any zip tool. If the file is
+not there, first correct this before proceeding.
+
+
+If the file is there and the panel does not appear, you have a problem within
+the specification file. In most cases that i have seen, it comes down to a
+spelling mistake of an attribute or tag name. You just have to carefully make
+sure that everything is spelled correctly. Don't forget that all names are
+case sensitive! In a few cases it is also happend, that required or semi-
+optional attributes are omitted, so you might want to verify if all
+attributes that you need are actually supplied.
+
+
+If everything is correct up to this point the problem becomes more elusive.
+Most likely the panel will not be displayed, because it is instructed not to
+show. There are be several reasons for this. The simple case is that no
+location has been specified for the shortcuts in your installation. This can
+happen if all five location attributes are omitted or if all the ones that
+are listed are set to ``no``. Remember, you have to specify at least one
+location for every shortcut. If this is also correct, you might have used the
+``<createForPack>`` tag. Review the details in 'Selective Creation of
+Shortcuts'. One possibility for the panel not to show is that based on the
+packs that are currently selected for installation no shortcut qualifies for
+creation. In this case the panel will not show, this is perfectly normal
+behavior. More likely this condition is true because of some accident and not
+because it's intended. Make sure the packs that you list for the shortcut are
+actually defined in your installation and verify that they are all spelled
+correctly. Remember: case matters! Did the ShortcutPanel use to work in your
+installation and all of a sudden stopped working? Very likely you are dealing
+with the last problem. A package name might have been modified and the
+shortcut spec was not adjusted to stay in sync.
+
+
+
+Problems That Have No Solution (yet)
+'''''''''''''''''''''''''''''''''''''''
+
+Unfortunately one problem has been very persistent and only recently one user
+found the reason. The problem occurs when installing on some target systems
+where non-English characters are used in the storage path for the shortcuts.
+The problem is that these characters don't seem to be properly translated
+across the Java Native Interface. This leads to a situation where the proper
+path can not be located and the shortcut creation fails. i write 'some target
+systems' because it does not fail everywhere. After much agonizing over this
+problem, one user found the solution: The shortcut creation works fine if a
+Sun virtual machine is installed, but fails if a version from IBM happens to
+be installed. So far i have no solution for this problem but i am trying to
+find a workaround the problem.
+
+
+
+A sample shortcut specification file for Unix
+----------------------------------------------
+
+::
+
+ <?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
+
+ <shortcuts>
+
+ <programGroup defaultName="IzForge/IzPack"
+ location="applications"/>
+
+ <!-- Disabled since there is no Frontend
+ shortcut
+ name="IzPack"
+ programGroup="yes"
+ desktop="yes"
+ applications="no"
+ startMenu="yes"
+ startup="no"
+ target="$INSTALL_PATH/bin/izpack-fe.sh"
+ commandLine=""
+ workingDirectory="$INSTALL_PATH/bin"
+ description="Front-End for IzPack installation tool"
+ iconFile="$INSTALL_PATH/bin/icons/izpack.png"
+ iconIndex="0"
+ type="Application"
+ encoding="UTF-8"
+ terminal="true"
+ KdeSubstUID="false"
+ initialState="normal">
+ <createForPack name="Core"/>
+ </shortcut -->
+
+ <shortcut
+ name="IzPack Documentation"
+ programGroup="yes"
+ desktop="yes"
+ applications="no"
+ startMenu="yes"
+ startup="no"
+ target="konqueror"
+ workingDirectory=""
+ commandLine=""
+ initialState="noShow"
+ iconFile="help"
+ iconIndex="0"
+ url="$INSTALL_PATH/doc/izpack/html/izpack-doc.html"
+ type="Link"
+ encoding="UTF-8"
+ description="IzPack user documentation (html format)">
+
+ <createForPack name="Documentation-html"/>
+ </shortcut>
+
+ <shortcut
+ name="Documentation"
+ programGroup="yes"
+ desktop="yes"
+ applications="no"
+ startMenu="yes"
+ startup="no"
+ target="acroread"
+ workingDirectory=""
+ commandLine="$INSTALL_PATH/doc/izpack/pdf/izpack-doc.pdf"
+ initialState="noShow"
+ iconFile="acroread"
+ iconIndex="0"
+ url="$INSTALL_PATH/doc/izpack/pdf/izpack-doc.pdf"
+ type="Application"
+ encoding="UTF-8"
+ description="IzPack user documentation (PDF format)">
+
+ <createForPack name="Documentation-PDF"/>
+ </shortcut>
+
+ <shortcut
+ name="Uninstaller"
+ programGroup="yes"
+ desktop="yes"
+ applications="no"
+ startMenu="no"
+ startup="no"
+ target="/usr/lib/java/bin/java"
+ commandLine="-jar
+ "$INSTALL_PATH/Uninstaller/uninstaller.jar""
+ initialState="noShow"
+ iconFile="trashcan_full"
+ iconIndex="0"
+ workingDirectory=""
+ type="Application"
+ encoding="UTF-8"
+ description="IzPack uninstaller">
+ <createForPack name="Core" />
+ </shortcut>
+
+ </shortcuts>
Modified: izpack-src/trunk/src/doc-reST/installation-files.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/installation-files.txt 2007-11-20 14:32:36 UTC (rev 1910)
+++ izpack-src/trunk/src/doc-reST/installation-files.txt 2007-11-21 17:00:22 UTC (rev 1911)
@@ -1,1453 +1,1470 @@
-Writing Installation XML Files
-==============================
-
-
-What You Need
--------------
-
-
-Your editor
-'''''''''''
-
-In order to write your XML installation files, you just need a plain text
-editor. Of course it's always easier to work with color coded text, so you
-might rather want to work with a text editor having such a feature. Here is a
-list of free editors that work well :
-
-- Jext : http://www.jext.org/
-- JEdit : http://www.jedit.org/
-- classics like Vim and (X)Emacs.
-
-If you are a developer and tend to write your own patches, extension or
-features to IzPack sources, or, if you wish to debug your compilation,
-installation and uninstallation, we recommend these IDE:
-
-- IntelliJ IDEA : http://www.jetbrains.com/idea/
-- Eclipse : http://www.eclipse.org/
-- Netbeans : http://www.netbeans.org/
-
-For the first one, JetBrains has granted us an Open Source License. All
-project members can ask the Licence Key to one of the project manager.
-
-The other ones are well know open source projects (Just like us :-)). We provide
-a tutorial on how to develop/debug IzPack using Eclipse in the chapter
-''Getting Started > How to develop and debug IpPack using Eclipse''
-
-
-Writing XML
-'''''''''''
-
-Though you might not know much about XML, you have certainly heard about it.
-If you know XML you can skip this subsection as we will briefly present how
-to use XML.
-
-
-XML is a markup language, really close to HTML. If you've ever worked with
-HTML the transition will be fast. However there are a few little things to
-know. The markups used in XML have the following form : ``<markup>``. Each
-markup has to be closed somewhere with its ending tag : ``</markup>``. Each
-tag can contain text and other markups. If a markup does not contain
-anything, it is just reported once : ``<markup/>``. A markup can contain
-attributes like : ``<markup attr1="123" attr2="hello !"/>``. Here is a sample
-of a valid XML structure :
-
-::
-
- <chapter title="Chapter 1">
- <section name="Introduction">
- <paragraph>
- This is the text of the paragraph number 1. It is available
- for the very low
- price of <price currency="dollar">1 000 000</price>.
- </paragraph>
- </section>
- <section name="xxx">
- xxx
- </section>
- </chapter>
-
-
-You should be aware of the following common mistakes :
-
-- markups **are** case sensitive : ``<markup>`` is different from
- ``<Markup>``.
-- you **must** close the markups in the same order as you create them :
- ``<m1><m2>(...)</m2></m1>`` is right but `` <m1><m2>(...)</m1></m2>`` is
- not.
-
-Also, an XML file must start with the following header :
-``<?xml version="1.0" encoding="iso-8859-1 standalone="yes" ?>``. The only
-thing you should modify is the encoding (put here the one your text editor
-saves your files to). The `` standalone`` attribute is not very important for
-us.
-
-
-This (brief !) introduction to XML was just meant to enable you to write your
-installation specification. For a better introduction there are plenty of
-books and articles/tutorials dealing with XML on the Internet, in book
-stores, in magazines and so on.
-
-Variable Substitution
----------------------
-
-During the installation process IzPack can substitute variables in various
-places with real values. Obvious targets for variable substitution are
-resource files and launch scripts, however you will notice many more places
-where it is more powerful to use variables rather then hard coded values.
-Wherever variables can be used it will be explained in the documentation.
-
-
-There are three types of variables:
-
-- Built-In variables. These are implemented in IzPack and are all
- dynamic in nature. This means that the value of each variable depends on
- local conditions on the target system.
-- Environment variables. These are provided by the operating system the
- installer is run on.
-- Variables that you can define. You also define the value, which is
- fixed for a given installation file.
-
-You define your own variables in the installation XML file with the
-``<variable>`` tag. How to do this is explained in detail later in this
-chapter.
-
-
-**Please note** that when using variables they must always appear with a
-'``$``' sign as the first character, even though they are not defined this
-way.
-
-
-
-The Built-In Variables
-----------------------
-
-The following variables are built-in :
-
-- ``$INSTALL_PATH`` : the installation path on the target system, as
- chosen by the user
-- ``$APPLICATIONS_DEFAULT_ROOT`` : the default path for applications
-- ``$JAVA_HOME`` : the JavaTM virtual machine home path
-- ``$CLASS_PATH`` : the Class Path used mainly for Java Applications
-- ``$USER_HOME`` : the user's home directory path
-- ``$USER_name`` : the user name
-- ``$APP_name`` : the application name
-- ``$APP_URL`` : the application URL
-- ``$APP_VER`` : the application version
-- ``$ISO3_LANG`` : the ISO3 language code of the selected langpack.
-- ``$IP_ADDRESS`` : the IP Address of the local machine.
-- ``$HOST_NAME`` : the HostName of the local machine.
-- ``$FILE_SEPARATOR`` : the file separator on the installation system
-- ``$DesktopShortcutCheckboxEnabled`` : When set to true, it
- automatically checks the "Create Desktop Shortcuts" button. To see how to
- use it, go to `The Variables Element ``<variables>`` Be careful this
- variable is case sensitve !
-- ``$InstallerFrame.logfilePath`` : The path to the install log. This
- file contains the paths of all installed files. If set to "default" then
- the "$INSTALL_PATH/Uninstaller/install.log" path will be used. To see how
- to use it, go to `The Variables Element ``<variables>``. If this
- variable is not set, no install.log will be created.
-
-
-Environment Variables
----------------------
-
-Environment variables can be accessed via the syntax ``${ENV[variable]}``.
-The curly braces are mandatory. Note that variable names are case-sensitive
-and usually in UPPER CASE.
-
-Example: To get the value of the OS environment variable "CATALINA_HOME", use
-``${ENV[CATALINA_HOME]}``.
-
-
-Parse Types
------------
-
-Parse types apply only when replacing variables in text files. At places
-where it might be necessary to specify a parse type, the documentation will
-mention this. Depending on the parse type, IzPack will handle special cases
--such as escaping control characters- correctly. The following parse types
-are available:
-
-- ``plain`` - use this type for plain text files, where no special
- substitution rules apply. All variables will be replaced with their
- respective values as is.
-- ``javaprop`` - use this type if the substitution happens in a Java
- properties file. Individual variables might be modified to function
- properly within the context of Java property files.
-- ``xml`` - use this type if the substitution happens in a XML file.
- Individual variables might be modified to function properly within the
- context of XML files.
-- ``shell`` - use this type if the substitution happens in a shell
- script. Because shell scripts use ``$variable`` themselves, an
- alternative variable marker is used: ``%variable`` or ``%{variable}``.
-
-
-The IzPack Elements
--------------------
-
-*When writing your installer XML files, it's a good idea to have a look at
-the iZPACK installation DTD*.
-
-
-
-
-The Root Element ``<installation>``
-''''''''''''''''''''''''''''''''''''
-
-The root element of an installation is ``<installation>``. It takes one
-required attribute : ``version``. The attribute defines the version of the
-XML file layout and is used by the compiler to identify if it is compatible
-with the XML file. This should be set to **1.0** for the moment.
-
-
-The Information Element ``<info>``
-'''''''''''''''''''''''''''''''''''
-
-This element is used to specify some general information for the installer.
-It contains the following elements :
-
-- ``<appname>`` : the application name
-- ``<appversion>`` : the application version
-- ``<appsubpath>`` : the subpath for the default of the installation
- path. A variable substitution and a maskable slash-backslash conversion
- will be done. If this tag is not defined, the application name will be
- used instead.
-- ``<url>`` : the application official website url
-- ``<authors>`` : specifies the author(s) of the application. It must
- contain at least one ``<author>`` element whose attributes are :
-
- - ``name`` : the author's name
- - ``email`` : the author's email
-
-- ``<uninstaller>`` : specifies whether to create an uninstaller after
- installation, and which name to use for it. This tag has the ``write``
- attribute, with default value `` yes``. If this tag is not specified, the
- uninstaller will still be written. The ``name`` attribute can be used to
- change the default name of the generated uninstaller, *i.e.* ``
- uninstaller.jar``.
-- ``<javaversion>`` : specifies the minimum version of Java required to
- install your program. Values can be ``1.2``, ``1.2.2``, ``1.4``, etc. The
- test is a lexical comparison against the ``java.version`` System property
- on the install machine.
-- ``<webdir>`` : Causes a ''web installer'' to be created, and
- specifies the URL packages are retrieved from at install time. The
- content of the tag must be a properly formed URL.
-- ``<summarylogfilepath>`` : specifies the path for the logfile of the
- `SummaryLoggerInstallerListener`.
-
-Here is an example of a typical ``<info>`` section :
-
-
-::
-
- <info>
- <appname>Super extractor</appname>
- <appversion>2.1 beta 6</appversion>
- <appsubpath>myCompany/SExtractor</appsubpath>
- <url>http://www.superextractor.com/</url>
- <authors>
- <author name="John John Doo" email="jjd at jjd-mail.com"/>
- <author name="El Goyo" email="goyoman at mymail.org"/>
- </authors>
- <javaversion>1.2</javaversion>
- </info>
-
-The Packaging Element ``<packaging>``
-''''''''''''''''''''''''''''''''''''''
-
-This element allows to specify packaging options. If not specified, the default will be to create an all in one
-installer. This element will usually be used to create an installer which spans over multiple volumes,
-e.g. the output will be two CDs. The packaging-element contains the following elements:
-
-- ``<packager>`` : specifies options used by the packager. The packager tag has the ``class`` attribute,
- which specifys the class to use for packaging. Currently two implementations
- are available (com.izforge.izpack.compiler.Packager, com.izforge.izpack.compiler.MultiVolumePackager).
- The packager-element can contain the ``<options>`` element which can have different attributes for the different
- implementations of packagers. For the MultiVolumePackager, it can have the following attributes:
-
- - ``volumesize``: the size of the volumes
- - ``firstvolumefreespace``: free space on the first volume used for the installer jar and additional resources like
- readme-files etc.
-
-
-- ``<unpacker>`` : specifies which unpacker class should be used. Currently there are two unpacker implementations
- (com.izforge.izpack.compiler.UnPacker, com.izforge.izpack.compiler.MultiVolumeUnPacker).
-
-Here's an example how to specify an installer which will create multiple volumes. In this example the volumes shall be
-CDs with 650 megabytes. There will be an additional free space of 150 megabytes on the first volume. This will result in
-the creation of an installer.jar and multiple installer.pak* files. The installer.jar plus installer.pak plus the additional
-resources have to be copied on the first volume, each installer.pak.<number> on several volumes.
-
-::
-
- <packaging>
- <packager class="com.izforge.izpack.compiler.MultiVolumePackager">
- <!-- 650 MB volumes, 150 MB space on the first volume -->
- <options volumesize="681574400" firstvolumefreespace="157286400"/>
- </packager>
- <unpacker class="com.izforge.izpack.installer.MultiVolumeUnpacker" />
- </packaging>
-
-The Variables Element ``<variables>``
-''''''''''''''''''''''''''''''''''''''
-
-This element allows you to define variables for the variables substitution
-system. Some variables are built-in, such as ``$INSTALL_PATH`` (which is the
-installation path chosen by the user). When you define a set of variables,
-you just have to place as many ``<variable>`` tags in the file as needed. If
-you define a variable named ``VERSION`` you need to type $VERSION in the
-files to parse. The variable substitutor will then replace it with the
-correct value. One ``<variable>`` tag take the following attributes :
-
-- ``name`` : the variable name
-- ``value`` : the variable value
-
-Here's a sample ``<variables>`` section :
-
-
-::
-
- <variables>
- <variable name="app-version" value="1.4"/>
- <variable name="released-on" value="08/03/2002"/>
- </variables>
-
-
-Here's a precise sample on how to use desktopshortcutcheckboxenabled and
-InstallerFrame.logfilePath variables:
-
-
-::
-
- <variables>
- <variable name="InstallerFrame.logfilePath" value="$INSTALL_PATH
- /My-install.log"/>
- <!-- This means that the log name will be My-install and that
- it will be stored at the root of the installation. -->
- <!-- Any path is fine. If value is set to "Default" then
- "$INSTALL_PATH/uninstall/install.log" is used. -->
- <!-- And if variable isn't defined then no log is written. -->
- <variable name="desktopshortcutcheckboxenabled" value="true"/>
- <!-- This automatically checks the "Create Desktop Shortcuts"
- button. Default value is "False". -->
- </variables>
-
-
-The GUI Preferences Element ``<guiprefs>``
-'''''''''''''''''''''''''''''''''''''''''''
-
-This element allows you to set the behavior of your installer GUI. This
-information will not have any effect on the command-line installers that will
-be available in future versions of iZPACK . The arguments to specify are :
-
-- ``resizable`` : takes ``yes`` or ``no`` and indicates whether the
- window size can be changed or not.
-- ``width`` : sets the initial window width
-- ``height`` : sets the initial window height.
-
-Here's a sample :
-
-::
-
- <guiprefs resizable="no" width="800" height="600"/>
-
-
-Starting from IzPack 3.6, the look and feel can be specified in this section
-on a per-OS basis. For instance you can use the native look and feels on
-Win32 and OS X but use a third-party one on Unix-like platforms. To do that,
-you have to add some children to the ``guiprefs`` tag:
-
-- ``laf``: the tag that specifies a look and feel. It has a ``name``
- parameter that defines the look and feel name.
-- Each ``laf`` element needs at least one ``os`` tag, specified like in
- the other parts of the specification that support this tag.
-- Like you can add ``os`` elements, you can add any number of ``param``
- elements to customize a look and feel. A ``param`` elements has two
- attribues: ``name`` and `` value``.
-
-The available look and feels are:
-
-- Kunststoff: ``kunststoff``
-- Liquid: ``liquid``
-- Metouia: ``metouia``
-- JGoodies Looks: ``looks``
-- Substance: ``substance``
-
-If you don't specify a look and feel for a particular operating system, then
-the default native one will be used: Windows on Windows, Aqua on Mac OS X and
-Metal on the Unix-like variants.
-
-
-The *Liquid Look and Feel* supports the following parameters:
-
-- ``decorate.frames``: ``yes`` means that it will render the frames in
- Liquid style
-- ``decorate.dialogs``: ``yes`` means that it will render the dialogs
- in Liquid style
-
-The *JGoodies Looks* look and feel can be specified by using the ``variant``
-parameters. The values can be one of:
-
-- ``windows``: use the Windows look
-- ``plastic``: use the basic Plastic look
-- ``plastic3D``: use the Plastic 3D look
-- ``plasticXP``: use the Plastic XP look (default).
-
-Here is a small sample:
-
-::
-
- <guiprefs height="600" resizable="yes" width="800">
- <laf name="metouia">
- <os family="unix" />
- </laf>
- <laf name="looks">
- <os family="windows" />
- <param name="variant" value="extwin" />
- </laf>
- </guiprefs>
-
-
-The *Substance* look and feel *toned-down* themes can be specified using the
-``variant`` parameter, with the value being one of: ``business, business-
-blue, business-black, creme, sahara, moderate, officesilver``. We have
-reduced the choice to the toned-down themes since they are the only ones to
-actually look decent (the other families colors are way too saturated).
-Please consult https://substance.dev.java.net/docs/skins/toneddown.html
-for a gallery of the different toned-down themes.
-
-Starting from IzPack 3.7, some characteristics can be customized with the
-``<modifier>`` tag. There is a separate description in the `Advanced
-Features` chapter paragraph `Modifying the GUI`.
-
-
-
-The Localization Element ``<locale>``
-''''''''''''''''''''''''''''''''''''''
-
-This element is used to specify the language packs (langpacks) that you want
-to use for your installer. You must set one ``<langpack>`` markup per
-language. This markup takes the `` iso3`` parameter which specifies the iso3
-language code.
-
-
-Here's a sample :
-
-
-::
-
- <locale>
- <langpack iso3="eng"/>
- <langpack iso3="fra"/>
- <langpack iso3="spa"/>
- </locale>
-
-
-The supported ISO3 codes are :
-
-========= ============================
-ISO3 code Language
-========= ============================
-cat Catalunyan
-chn Chinese
-cze Czech
-dan Danish
-deu German
-eng English
-fin Finnish
-fra French
-hun Hungarian
-ita Italian
-jpn Japanese
-mys Malaysian
-ned Nederlands
-nor Norwegian
-pol Polnish
-por Portuguese (Brazilian)
-rom Romanian
-rus Russian
-scg Serbian
-spa Spanish
-svk Slovakian
-swe Swedish
-ukr Ukrainian
-========= ============================
-
-
-
-The Resources Element ``<resources>``
-''''''''''''''''''''''''''''''''''''''
-
-Several panels, such as the license panel and the shortcut panel, require
-additional data to perform their task. This data is supplied in the form of
-resources. This section describes how to specify them. Take a look at each
-panel description to see if it might need any resources. Currently, no checks
-are made to ensure resources needed by any panel have been included. The ``
-<resources>`` element is not required, and no ``<res>`` elements are required
-within.
-The ``<resources>`` element is the only element besides the ``<packs>``
-element that is taken into consideration in referenced pack-files (see
-```<packs>`` element`_ for more info)
-
-
-You have to set one ``<res>`` markup for each resource. Here are the
-attributes to specify :
-
-- ``src`` : the path to the resource file which can be named freely of
- course (for instance ``my-picture.jpg``).
-- ``id`` : the resource id, depending on the needs of a particular
- panel
-- ``parse`` : takes ``yes`` or ``no`` (default is ``no``) - used to
- specify whether the resource must be parsed at the installer compilation
- time. For instance you could set the application version in a readme file
- used by ``InfoPanel``.
-- ``type`` : specifies the parse type. This makes sense only for a text
- resource - the default is ``plain``, other values are ``javaprop, xml``
- (Java properties file and XML files)
-- ``encoding`` : specifies the resource encoding if the receiver needs
- to know. This makes sense only for a text resource.
-
-Here's a sample :
-
-::
-
- <resources>
- <res id="InfoPanel.info" src="doc/readme.txt" parse="yes"/>
- <res id="LicencePanel.licence" src="legal/License.txt"/>
- </resources>
-
-
-The Panels Element ``<panels>``
-'''''''''''''''''''''''''''''''''
-
-Here you tell the compiler which panels you want to use. They will appear in
-the installer in the order in which they are listed in your XML installation
-file. Take a look at the different panels in order to find the ones you need.
-The ``<panel>`` markup takes a single attribute ``classname`` which is the
-classname of the panel.
-
-
-Here's a sample :
-
-::
-
- <panels>
- <panel classname="HelloPanel"/>
- <panel classname="LicencePanel"/>
- <panel classname="TargetPanel"/>
- <panel classname="InstallPanel"/>
- <panel classname="FinishPanel"/>
- </panels>
-
-
-The Packs Element ``<packs>``
-'''''''''''''''''''''''''''''''
-
-This is a crucial section as it is used to specify the files that need to be
-installed. The ``<packs>`` section consists of several ``<pack>`` and
-``<refpack>`` tags.
-
-The ``<pack>`` takes the following attributes :
-
-- ``name``: the pack name
-- ``required``: takes ``yes`` or ``no`` and specifies whether the pack
- is optional or not.
-- ``os``: optional attribute that lets you make the pack targeted to a
- specific *operating system*, for instance ``unix``, ``mac`` and so on.
-- ``preselected``: optional attribute that lets you choose whether the
- pack is by default selected for installation or not. Possible values are
- ``yes`` and ``no``. A pack which is not preselected needs to be
- explicitly selected by the user during installation to get installed.
-- ``loose``: can be used so that the files are not located in the
- installer Jar. The possible values are ``true`` or ``false``, the default
- beeing ``false``. The author of this feature needed to put his
- application on a CD so that the users could run it directly from this
- media. However, he also wanted to offer them the possibility to install
- the software localy. Enabling this feature will make IzPack take the
- files on disk instead of from the installer. *Please make sure that your
- relative files paths are correct !*
-- ``id``: this attribute is used to give a unique id to the pack to be
- used for internationalization.
-- ``packImgId``: this attribute is used to reference a unique resource
- that represents the pack's image for the ImgPacksPanel. The resource
- should be defined in the ``<resources>`` element of the installation XML
- using the same value for the ``id`` attribute of the ``<res>`` element.
-
-The ``<refpack>`` takes only one attribute ``file``, which contains the
-relative path (from the installation compiler) to an externally defined
-packs-definition. This external packs definition is a regular IzPack
-installation XML. However the only elements that are used from that XML file
-are the ``<packs>`` and the ``<resources>`` elements. This enables a model in
-which a single developer is responsible for maintaining the packs and
-resources related to the development-package assigned to him. The main
-install XML references these xml-files to avoid synchronization efforts
-between the central installation XML and the developer-maintained installer
-XMLs.
-
-Internationalization of the PacksPanel
-'''''''''''''''''''''''''''''''''''''''
-
-In order to provide internationalization for the PacksPanel, so that your
-users can be presented with a different name and description for each
-language you support, you have to create a file named ``packsLang.xml_xyz``
-where ``xyz`` is the ISO3 code of the language in lowercase. Please be aware
-that case is significant. This file has to be inserted in the resources
-section of `` install.xml`` with the ``id`` and ``src`` attributes set at the
-name of the file. The format of these files is identical with the
-distribution langpack files located at ``
-$IZPACK_HOME/bin/langpacks/installer``. For the name of the panel you just
-use the pack ``id`` as the txt ``id``. For the description you use the pack
-``id`` suffixed with ``.description``.
-
-The following sections describe the tags available for a ``<pack>`` section.
-
-
-``<description>`` - pack description
-'''''''''''''''''''''''''''''''''''''
-
-The contents of the ``<description>`` tag describe the pack contents. This
-description is displayed if the user highlights the pack during installation.
-
-
-``<depends>`` - pack dependencies
-''''''''''''''''''''''''''''''''''
-
-This can be used to make this pack selectable only to be installed only if
-some other is selected to be installed. The pack can depend on more than one
-by specifying more than one `` <depends>`` elements.
-Circular depedencies are not supported and the compiler reports an error if
-one occurs.
-
-This tag takes the following attribute:
-
-- ``packname``: The name of the pack that it depends on
-
-
-``<os>`` - OS restrictions
-'''''''''''''''''''''''''''
-
-It is possible to restrict a panel to a certain list of operating systems.
-This tag takes the following attributes:
-
-- ``family``: unix, windows or mac
-- ``name``: the exact OS name (ie Windows, Linux, ...)
-- ``version``: the exact OS version (see the JVM ``os.version``
- property)
-- ``arch``: the machine architecture (see the JVM ``os.arch``
- property).
-
-
-``<updatecheck>``
-''''''''''''''''''
-
-This feature can update an already installed package, therefore removing
-superfluous files after installation. Here's how this feature author (Tino
-Schwarze) described it on the IzPack development mailing-list:
-
-> Each pack can now specify an ``<updatecheck>`` tag. It supports a subset of
-ant fileset syntax, e.g.:
-
-::
-
- <updatecheck>
- <include name="lib/**" />
- <exclude name="config/local/** />
- </updatecheck>
-
-
-> If the paths are relative, they will be matched relative to
-``$INSTALL_PATH``. Update checks are only enabled if at least one
-``<include>`` is specified. See `` com.izforge.izpack.installer.Unpacker``
-for details.
-
-
-
-``<file>`` - add files or directories
-'''''''''''''''''''''''''''''''''''''''
-
-The ``<file>`` tag specifies a file (a directory is a file too) to include
-into the pack. It takes the following attributes:
-
-- ``src``: the file location (relative path) - if this is a directory
- its content will be added recursively
-- ``targetdir``: the destination directory, could be something like
- ``$INSTALL_PATH/subdirX``
-- ``os``: can optionally specify a target operating system (``unix,
- windows, mac``) - this means that the file will only be installed on its
- target operating system
-- ``override``: if ``true`` then if the file is already installed, it
- will be overwritten. Alternative values: ``asktrue`` and ``askfalse`` -
- ask the user what to do and supply default value for non-interactive use.
- Another possible values is ``update``. It means that the new file is only
- installed if it's modification time is newer than the modification time
- of the already existing file (note that this is not a reliable mechanism
- for updates - you cannot detect whether a file was altered after
- installation this way.) By default it is set to `` update``.
-- ``unpack``: if ``true`` and the file is an archive then its content
- will be unpacked and added as individual files
-
-
-
-``<additionaldata>``
-'''''''''''''''''''''
-
-This tag can also be specified in order to pass additional data related to a
-file tag for customizing.
-
-- ``<key>``: key to identify the data
-- ``<value>``: value which can be used by a custom action
-
-
-
-``<singlefile>`` - add a single file
-'''''''''''''''''''''''''''''''''''''
-
-Specifies a single file to include. The difference to ``<file>`` is that this
-tag allows the file to be renamed, therefore it has a ``target`` attribute
-instead of `` targetdir``.
-
-- ``src``: the file location (relative path)
-- ``target``: the destination file name, could be something like
- ``$INSTALL_PATH/subdirX/fileY``
-- ``os``: can optionally specify a target operating system (``unix,
- windows, mac``) - this means that the file will only be installed on its
- target operating system
-- ``override``: see ``<file>`` for description
-
-A ``<additionaldata>`` tag can also be specified for customizing.
-
-
-
-``<fileset>``: add a fileset
-'''''''''''''''''''''''''''''
-
-The ``<fileset>`` tag allows files to be specified using the powerful Jakarta
-Ant set syntax. It takes the following parameters:
-
-- ``dir``: the base directory for the fileset (relative path)
-- ``targetdir``: the destination path, works like for ``<file>``
-- ``casesensitive``: optionally lets you specify if the names are case-
- sensitive or not - takes ``yes`` or ``no``
-- ``defaultexcludes``: optionally lets you specify if the default
- excludes will be used - takes ``yes`` or ``no``.
-- ``os``: specifies the operating system, works like for ``<file>``
-- ``override``: see ``<file>`` for description
-- ``includes``: comma- or space-separated list of patterns of files
- that must be included; all files are included when omitted. This is an
- alternative for multiple include tags.
-- ``excludes``: comma- or space-separated list of patterns of files
- that must be excluded; no files (except default excludes) are excluded
- when omitted. This is an alternative for multiple exclude tags.
-
-You specify the files with ``<include>`` and ``<exclude>`` tags that take the
-``name`` parameter to specify the Ant-like pattern :
-
-- ``**`` : means any subdirectory
-- ``*`` : used as a wildcard.
-
-Here are some examples of Ant patterns :
-
-- ``<include name="lib"/>`` : will include ``lib`` and the
- subdirectories of ``lib``
-- ``<exclude name="**/*.java"/>`` : will exclude any file in any
- directory starting from the base path ending by ``.java``
-- ``<include name="lib/*.jar"/>`` : will include all the files ending
- by ``.jar`` in ``lib``
-- ``<exclude name="lib/**/*FOO*"/>`` : will exclude any file in any
- subdirectory starting from ``lib`` whose name contains ``FOO``.
-
-There area set of definitions that are excluded by default file-sets, just as
-in Ant. IzPack defaults to the Ant list of default excludes. There is
-currently no equivalent to the <defaultexcludes> task. Default excludes are:
-
-::
-
- **/*\~{}
- **/\#*\#
- **/.\#*
- **/%*%
- **/.\_*
- **/CVS
- **/CVS/**
- **/.cvsignore
- **/SCCS
- **/SCCS/**
- **/vssver.scc
- **/.svn
- **/.svn/**
- **/.DS\_Store
-
-
-A ``<additionaldata>`` tag can also be specified for customizing.
-
-
-``<parsable>`` - parse a file after installation
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-Files specified by ``<parsable>`` are parsed after installation and may have
-variables substituted.
-
-- ``targetfile`` : the file to parse, could be something like
- ``$INSTALL_PATH/bin/launch-script.sh``
- A slash will be changed to the system dependant path separator (e.g. to a
- backslash on Windows) only if no backslash masks the slash.
-- ``type`` : specifies the type (same as for the resources) - the
- default is ``plain``
-- ``encoding`` : specifies the file encoding
-- ``os``: specifies the operating system, works like for ``<file>``
-
-
-``<executable>`` - mark file executable or execute it
-'''''''''''''''''''''''''''''''''''''''''''''''''''''''
-
-The ``<executable>`` tag is a very useful thing if you need to execute
-something during the installation process. It can also be used to set the
-executable flag on Unix-like systems. Here are the attributes :
-
-- ``targetfile`` : the file to run, could be something like
- ``$INSTALL_PATH/bin/launch-script.sh``
- Slashes are handled special (see attribute ``targetfile`` of tag
- ``<parsable>``).
-- ``class`` : If the executable is a jar file, this is the class to run
- for a JavaTM program
-- ``type`` : ``bin`` or ``jar`` (the default is ``bin``)
-- ``stage`` : specifies when to launch : ``postinstall`` is just after
- the installation is done, ``never`` will never launch it (useful to set
- the +x flag on Unix). ``uninstall`` will launch the executable when the
- application is uninstalled. The executable is executed before any files
- are deleted. ``never`` is the default value.
-- ``failure`` : specifies what to do when an error occurs : ``abort``
- will abort the installation process, ``ask`` (default) will ask the user
- what to do and ``warn`` will just tell the user that something is wrong
-- ``os``: specifies the operating system, works like for ``<file>``
-- ``keep`` : specifies whether the file will be kept after execution.
- The default is to delete the file after is has been executed. This can be
- changed by specifying ``keep="true"``.
-
-A ``<args>`` tag can also be specified in order to pass arguments to the
-executable:
-
-- ``<arg>``: passes the argument specified in the ``value`` attribute.
- Slashes are handled special (see attribute ``targetfile`` of tag
- ``<parsable>``.
-
-
-
-``<os>`` - make a file OS-dependent
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-The ``<os>`` tag can be used inside the ``<file>``, ``<fileset>``,
-``<singlefile>``, ``<parsable>``, ``<executable>`` tags to restrict it's
-effect to a specific operating system family, architecture or version:
-
-- ``family``: ``unix, windows, mac`` to specify the operating system
- family
-- ``name``: the operating system name
-- ``version``: the operating system version
-- ``arch``: the operating system architecture (for instance the Linux
- kernel can run on i386, sparc, and so on)
-
-Here's an example installation file :
-
-::
-
- <packs>
- <!-- The core files -->
- <pack name="Core" required="yes">
- <description>The IzPack core files.</description>
- <file targetdir="$INSTALL_PATH" src="bin"/>
- <file targetdir="$INSTALL_PATH" src="lib"/>
- <file targetdir="$INSTALL_PATH" src="legal"/>
- <file targetdir="$INSTALL_PATH" src="Readme.txt"/>
- <file targetdir="$INSTALL_PATH" src="Versions.txt"/>
- <file targetdir="$INSTALL_PATH" src="Thanks.txt"/>
- <parsable targetfile="$INSTALL_PATH/bin/izpack-fe"/>
- <parsable targetfile="$INSTALL_PATH/bin/izpack-
- fe.bat"/>
- <parsable targetfile="$INSTALL_PATH/bin/compile"/>
- <parsable
- targetfile="$INSTALL_PATH/bin/compile.bat"/>
- <executable targetfile="$INSTALL_PATH/bin/compile"
- stage="never"/>
- <executable targetfile="$INSTALL_PATH/bin/izpack-fe"
- stage="never"/>
- </pack>
-
- <!-- The documentation (1 directory) -->
- <pack name="Documentation" required="no">
- <description>The IzPack documentation (HTML and
- PDF).</description>
- <file targetdir="$INSTALL_PATH" src="doc"/>
- </pack>
- </packs>
-
-
-The Native Element ``<native>``
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-Use this if you want to use a feature that requires a native library. The
-native libraries are placed under ``bin/native/..``. There are 2 kinds of
-native libraries : the iZPACK libraries and the third-party ones. The IzPack
-libraries are located at ``bin/native/izpack``, you can place your own
-libraries at `` bin/native/3rdparty``. It is possible to place a native
-library also into the uninstaller. It is useable from CustomActions.
-If one or more are referenced for it, the needed support classes are
-automatically placed into the uninstaller. To place it only on operating
-systems for which they are build, it is possible to define an OS restriction.
-This restriction will only be performed for the uninstaller. The markup takes
-the following attributes :
-
-- ``type`` : ``izpack`` or ``3rdparty``
-- ``name`` : the library filename
-- ``stage``: stage where to use the library (install|uninstall|both)
-
-
-``<os>`` - make a library OS-dependent
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-The ``<os>`` tag can be used to restrict the inclusion into the uninstaller
-to a specific operating system family, architecture or version. The inclusion
-into the installer will be always done.
-
-Here's a sample :
-
-::
-
- <native type="izpack" name="ShellLink.dll"/>
-
-
-The Jar Merging Element ``<jar>``
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-If you adapt iZPACK for your own needs, you might need to merge the content
-of another jar file into the jar installer. For instance, this could be a
-library that you need to merge. The ``<jar>`` markup allows you to merge the
-raw content of another jar file into the installer and the uninstaller. It is
-necessary that the paths in the jars are unique because only the contained
-files of the jar are added to the installer jar, not the jar file self. The
-attributes are:
-
-- ``src`` : the path at compile time
-- ``stage``: stage where to use the contents of the additional jar file
- (install|uninstall|both)
-
-A sample :
-
-::
-
- <jar src="../nicelibrary.jar"/>
-
-The Available Panels
----------------------
-
-In this section i will introduce the various panels available in IzPack. The
-usage for most is pretty simple and described right here. The more elaborate
-ones are explained in more detail in the *Advanced Features* chapter or in
-their own chapter. The panels are listed by their class name. This is the
-name that must be used with the ``classname`` attribute. Please be aware that
-the classname is Case-Sensitive, meaning that if the case from the
-install.xml and the founded class file differs the installation will break.
-In this last case, the installer will Throw an IllegalArgumentException in
-the compiler if the declared class name in the xml file differs in case from
-the founded class file.
-
-
-
-HelloPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This panel welcomes the user by displaying the project name, the version, the
-URL as well as the authors.
-
-
-
-CheckedHelloPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This panel welcomes the user also by displaying the project name, the
-version, the URL as well as the authors.
-
-
-Additonal on windows the registry will be scanned for an entry which
-determines that the product is already installed. If so, a dialog will be
-shown which ask whether to install a second version of the product or not. If
-you use this panel do not forget to add the `registry feature` into your
-installation.
-
-
-InfoPanel and HTMLInfoPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This is a kind of 'README' panel. It presents text of any length. The text is
-specified by the ``(HTML)InfoPanel.info`` resource. Starting from IzPack
-3.7.0, variables substitution is allowed.
-To add an image to the HTMLInfoPanel you simply need to add a ressource to
-your install.xml with an ID decided by you, then you can call this image by
-refering it by this same ID.
-
-In install.xml:
-
-::
-
- <resources>
- <res src="logo.jpg" id="GHGHGH"/>
- .....
-
-and in file.html:
-
-::
-
- <img src="GHGHGH" />
-
-
-LicencePanel and HTMLLicencePanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-Note:* There is a mistake in the name - it should be LicensePanel. In France
-the word is Licence ... and one of my diploma is a 'Licence' so ...:* -)
-
-
-Adding images to HTMLLicencePanel works exactly the same way as with
-HTMLInfoPanel.
-
-These panels can prompt the user to acknowledge a license agreement. They
-block unless the user selects the 'agree' option. To specify the license
-agreement text you have to use the `` (HTML)LicencePanel.licence`` resource.
-
-
-
-PacksPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-Allows the user to select the packs he wants to install.
-
-
-
-ImgPacksPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This is the same as above, but for each pack a different picture is shown to
-the user. The pictures are specified using the packImgId attribute for each
-pack in the installer XML. The initial image will be the image of the first
-pack that has a packImgId. The image is updated each time the user
-(de)selects a pack that has a packImgId. Of course it's up to you to specify
-an image for each pack in your installation with a unique packImgId. For
-instance if you have 2 packs ``core`` and ``documentation`` (in this order),
-and you assign both packs a packImgId that is identical to the pack's name
-then the resource for ``core`` will be ``core`` and the resource for
-``documentation`` will be ``documentation``. The initially shown image will
-be the resource ``core``. The supported image formats depend on what your
-client's JVM supports, but starting from J2SE 1.3, *GIF*, *JPEG* and *PNG*
-are supported.
-
-
-
-TargetPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This panel allows the user to select the installation path. It can be
-customized with the following resources (they are text files containing the
-path) :
-
-- ``TargetPanel.dir.f`` where f stands for the family (``mac, macosx,
- windows, unix``)
-- ``TargetPanel.dir`` : the directory name, instead of the software to
- install name
-- ``TargetPanel.dir.d`` where d is a "dynamic" name, as returned by the
- JavaTM virtual machine. You should write the name in lowercase and
- replace the spaces with underscores. For instance, you might want a
- different setting for Solaris and GNU/Linux which are both Unix-like
- systems. The resources would be ``TargetPanel.dir.sunos,
- TargetPanel.dir.linux``. You should have a Unix-resource in case it
- wouldn't work though.
-
-
-InstallPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-You should always have this one as it launches the installation process !
-
-
-
-XInfoPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-A panel showing text parsed by the variable substitutor. The text can be
-specified through the ``XInfoPanel.info`` resource. This panel can be useful
-when you have to show information after the installation process is completed
-(for instance if the text contains the target path).
-
-
-
-FinishPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-A ending panel, able to write automated installer information. For details
-see the chapter on 'Advanced Features'.
-
-
-
-SimpleFinishPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-Same as ``FinishPanel``, but without the automated installer features. It is
-aimed at making the life easier for end-users who will never encounter the
-automated installer extra feature.
-
-
-
-ShortcutPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This panel is used to create desktop shortcuts. For details on using the
-ShortcutPanel see the chapter 'Desktop Shortcuts'.
-
-
-UserInputPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This panel allows you to prompt the user for data. What the user is prompted
-for is specified using an XML file which is included as a resource to the
-installer.
-
-
-CompilePanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This panel allows you to compile just installed Java sourcecode. The details
-for the compilation are specified using the resource
-``CompilePanel.Spec.xml``. The XML file has the following format:
-
-::
-
- <compilation>
- <global>
- <compiler>
- <choice value="$JAVA_HOME/bin/javac" />
- <choice value="jikes" />
- </compiler>
- <arguments>
- <choice value="-O -g:none" />
- <choice value="-O" />
- <choice value="-g" />
- <choice value="" />
- </arguments>
- </global>
- <jobs>
- <classpath add="$INSTALL_PATH/src/classes/" />
- <job name="optional name">
- <directory name="$INSTALL_PATH/src/classes/xyz" />
- </job>
- <job name="another job">
- <packdepency name="some package name" />
- <classpath sub="$INSTALL_PATH/" />
- <directory name="$INSTALL_PATH/src/classes/abc" />
- <file name="$INSTALL_PATH/some/file.java" />
- </job>
- </jobs>
- </compilation>
-
-
-In theory, jobs can be nested but this has not been tested at all. A change
-to the classpath within a job only affects this job and nested jobs. The
-classpath should be specified before any files or directories.
-
-The user can change the compiler to use and choose from some default
-compilation options before compilation is started.
-
-.. image:: ./compilePanel.png
- :alt: CompilePanel
-
-
-
-ProcessPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This panel allows you to execute arbitrary files after installation. The
-details for the compilation are specified using the resource
-``ProcessPanel.Spec.xml``.
-
-The XML file has the following format:
-
-::
-
- <processing>
- <job name="do xyz">
- <os family="windows" />
- <executefile name="$INSTALL_PATH/scripts/xyz.bat">
- <arg>doit</arg><arg>$variable</arg>
- </executefile>
- </job>
- <job name="do xyz">
- <os family="unix" />
- <executefile name="$INSTALL_PATH/scripts/xyz.sh">
- <arg>doit</arg><arg>$variable</arg>
- </executefile>
- </job>
- </processing>
-
-
-Each job may have an ``<os>`` attribute.
-
-
-
-``<executeclass>`` - Execute Java Classes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-It is also possible to execute Java classes from this panel. Here's what this
-feature author (Alex Bradley) says:
-
-> i've been able to work around my requirements by extending the
-``ProcessPanelWorker`` functionality to run user-specified classes. i've
-extended the DTD of the `` ProcessPanel.Spec.xml`` to include a new element:
-
-::
-
- <executeclass name="classname">
- <args..../>
- </executeclass>
-
-
-> i've also added a new sub-class of ``Processable`` called ``executeclass``.
-This will run a user-specified class in the context of the installer JVM with
-a single method :
-
-::
-
- run( AbstractUIProcessHandler handler, String[] args]);
-
-
-> It can do everything i need and more. In particular, it allows me to write
-a process extension and still be able to provide feedback to the user through
-the feedback panel, and to add new functionality to the installer, after its
-been built.
-
-To use the executeclass facility, you will need to create a jar file with
-your class and then add it to the installer with the `The Jar Merging
-Element`.
-
-
-``<executeForPack>`` - Only execute the job for certain packs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This can be be used to run the job only if the pack is enabled. For example,
-the batch file will if either the ``Sources`` or ``Executables`` packs are
-selected at install time.
-
-::
-
- <processing>
- <job name="List files">
- <executeForPack name="Sources"/>
- <executeForPack name="Executables"/>
- <os family="windows" />
- <executefile name="$INSTALL_PATH\batch\ListFiles.bat" />
- </job>
- </processing>
-
-``<logfiledir>`` - Output of the processPanel saved to a log
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-New with version 3.7 is the possibility to tee output that is written to the
-ProcessPanel's textarea into an optional logfile. Using this feature is
-pretty much straightforward, you only have to add a line in
-``ProcessPanel.Spec.xml`` that will tell IzPack the location, where the
-logfile should be stored.
-
-Variable substitution is performed, so you can use ``$INSTALL_PATH`` as
-example.
-
-The name of the logfile is not (yet) configurable but should fit in most
-cases. It will be named
-
-::
-
- Install_V<$APP_VER>_<YYYY>-<MM>-<DD>_<hh>-<mm>-<ss>_<RandomId>.log
-
-
-Here's an example:
-
-::
-
- <processing>
- <logfiledir>$INSTALL_PATH</logfiledir>
- <job name="do xyz">
- <os family="windows" />
- <executefile name="$INSTALL_PATH/scripts/xyz.bat">
- <arg>doit</arg><arg>$variable</arg>
- </executefile>
- </processing>
-
-
-This will generate a logfile named e.g.
-``Install_V1.3_2004-11-08_19-22-20_43423.log`` located in ``$INSTALL_PATH``.
-
-``ProcessPanelWorker`` will write all output that is directed to ``stdout``
-and ``stderr`` to this file if ``ProcessPanel.Spec.xml`` contains the
-``logfiledir`` entry.
-
-Please note that this one file is used for storing the complete output of all
-jobs and not a file for each job that is run.
-
-
-JDKPathPanel
-'''''''''''''
-
-This panel allows the user to select a JDK path. The variable JAVA_HOME does
-not point to a JDK, else to a JRE also the environment variable points to a
-JDK. This is not a bug, this is the behavior of the VM. But some products
-needs a JDK, for that this panel can be used. There is not only a selection
-of the path else a validation. The validation will be done with the file
-JDKPath/lib/tools.jar. If JAVA_HOME points to the VM which is placed in the
-JDK, the directory will be used as default (JAVA_HOME/..). If there is the
-variable
-
-::
-
- JDKPathPanel.skipIfValid
-
-
-defined with the value "yes", the panel will be skiped if the path is valid.
-Additional it is possible to make a version control. If one or both variables
-
-::
-
- JDKPathPanel.minVersion
- JDKPathPanel.maxVersion
-
-
-are defined, only a JDK will be accepted which has a version in the range of
-it. The detection is a little bit pragmatically, therefor it is possible,
-that the detection can fail at some VMs. The values in the install.xml should
-be like
-
-::
-
- <variables>
- <variable name="JDKPathPanel.minVersion" value="1.4.1" />
- <variable name="JDKPathPanel.maxVersion" value="1.4.99" />
- <variable name="JDKPathPanel.skipIfValid" value="yes" />
- </variables>
-
-
-If all is valid, the panels isValidated method sets the variable
-
-::
-
- JDKPath
-
-
-to the chosen path. Be aware, this variable exist not until the JDKPanel was
-quitted once. At a secound activation, the default will be the last
-selection.
-
-
-SelectPrinterPanel
-''''''''''''''''''''''''''
-
-This panel will look at the local printers installed and propose a list box
-with all of them. Once chosen, the variable $SELECTED_PRINTER is set to the
-user choice.
-
-
-DataCheckPanel
-''''''''''''''''''''''''''
-
-DataCheckPanel is not for inclusion in an actuall install, but is a debugging
-resource for developers writing custom panels or code to be included in
-IzPack.
-It creates a list of all the variables in InstallData, their values and a
-list of all packs, indicating which are selected.
-This list is printed to the console and appears in a scrollable text area on
-the panel.
-Put the panel in wherever you want to see any variables in InstallData or a
-listing of the packs with a line like this in the <panels> section of
-install.xml:
-
-<panel classname="DataCheckPanel" />
-
-It will automatically give you a full list of all the variables and packs
-whenever the panel is made active.
-
-
-SummaryPanel
-'''''''''''''
-
-This panel gives a summary of all shown panels. The best place for it is just
-infront of the InstallPanel. Normaly it contains a warning that this is the
-last panel before installation. The panel contains a scrollable HTML text
-area to display the summary. The informations are collected from each panel
-by calling the methods ``getSummaryCaption`` and ``getSummaryBody``.
-``getSummaryCaption`` is implemented in ``IzPanel`` with a panel name default
-text. ``getSummaryBody`` has to be implemented in all panels which should be
-presented in the summary. If the secound method is not implemented, no
-summary of this panel will be shown.
-
-Additional it is possible to `log the contents` of the summary panel into a
-HTML file.
-
-
-InstallationGroupPanel
-''''''''''''''''''''''''''
-
-This Panel groups the pack together. A panel which displays the available
-*installGroups* found on the packs to allow the user to select a subset of
-the packs based on the pack *installGroups* attribute. This panel will be
-skipped if there are no pack elements with an *installGroups* attribute. For
-example ::
-
- <installation version="1.0">
- (...)
- <panels>
- (...)
- <panel classname="InstallationGroupPanel"/>
- <panel classname="PacksPanel"/>
- (...)
- </panels>
-
- <packs>
- <pack name="Base"
- installGroups="Group1"
- required="yes">
- (...)
- </pack>
- <pack name="Docs"
- installGroups="Group1,Group2"
- required="no">
- (...)
- </pack>
- <pack name="Sources"
- installGroups="Group3,Group2"
- required="no">
- (...)
- </pack>
- </packs>
- </installation>
-
-In above example when InstallationGroupPanel is displayed,
-it contains three radios named Group1, Group2 and Group3. Depending
-on what user selects, the respective Packs will be displayed in
-PacksPanel. InstallationGroupPanel will look for a description
-corresponding to the key
-"InstallationGroupPanel.description.Group1",
-"InstallationGroupPanel.description.Group2" etc in installation
-langpacks and variables and displays this description for each of
-the Group_i.
-
-You may also define a sortKey in the variables section of the installer.xml
-to define an alternative sorting. The default sorting is based on the Group
-Name.
-
-Here is an example for alternative sorting of groups: ::
-
- (...)
- <variables>
- (...)
- <variable
- name="InstallationGroupPanel.sortKey.Group2" value="A"/>
- <variable
- name="InstallationGroupPanel.sortKey.Group1" value="B"/>
- <variable
- name="InstallationGroupPanel.sortKey.Group3" value="C"/>
- </variables>
- (...)
+Writing Installation XML Files
+==============================
+
+
+What You Need
+-------------
+
+
+Your editor
+'''''''''''
+
+In order to write your XML installation files, you just need a plain text
+editor. Of course it's always easier to work with color coded text, so you
+might rather want to work with a text editor having such a feature. Here is a
+list of free editors that work well :
+
+- Jext : http://www.jext.org/
+- JEdit : http://www.jedit.org/
+- classics like Vim and (X)Emacs.
+
+If you are a developer and tend to write your own patches, extension or
+features to IzPack sources, or, if you wish to debug your compilation,
+installation and uninstallation, we recommend these IDE:
+
+- IntelliJ IDEA : http://www.jetbrains.com/idea/
+- Eclipse : http://www.eclipse.org/
+- Netbeans : http://www.netbeans.org/
+
+For the first one, JetBrains has granted us an Open Source License. All
+project members can ask the Licence Key to one of the project manager.
+
+The other ones are well know open source projects (Just like us :-)). We provide
+a tutorial on how to develop/debug IzPack using Eclipse in the chapter
+''Getting Started > How to develop and debug IpPack using Eclipse''
+
+
+Writing XML
+'''''''''''
+
+Though you might not know much about XML, you have certainly heard about it.
+If you know XML you can skip this subsection as we will briefly present how
+to use XML.
+
+
+XML is a markup language, really close to HTML. If you've ever worked with
+HTML the transition will be fast. However there are a few little things to
+know. The markups used in XML have the following form : ``<markup>``. Each
+markup has to be closed somewhere with its ending tag : ``</markup>``. Each
+tag can contain text and other markups. If a markup does not contain
+anything, it is just reported once : ``<markup/>``. A markup can contain
+attributes like : ``<markup attr1="123" attr2="hello !"/>``. Here is a sample
+of a valid XML structure :
+
+::
+
+ <chapter title="Chapter 1">
+ <section name="Introduction">
+ <paragraph>
+ This is the text of the paragraph number 1. It is available
+ for the very low
+ price of <price currency="dollar">1 000 000</price>.
+ </paragraph>
+ </section>
+ <section name="xxx">
+ xxx
+ </section>
+ </chapter>
+
+
+You should be aware of the following common mistakes :
+
+- markups **are** case sensitive : ``<markup>`` is different from
+ ``<Markup>``.
+- you **must** close the markups in the same order as you create them :
+ ``<m1><m2>(...)</m2></m1>`` is right but `` <m1><m2>(...)</m1></m2>`` is
+ not.
+
+Also, an XML file must start with the following header :
+``<?xml version="1.0" encoding="iso-8859-1 standalone="yes" ?>``. The only
+thing you should modify is the encoding (put here the one your text editor
+saves your files to). The `` standalone`` attribute is not very important for
+us.
+
+
+This (brief !) introduction to XML was just meant to enable you to write your
+installation specification. For a better introduction there are plenty of
+books and articles/tutorials dealing with XML on the Internet, in book
+stores, in magazines and so on.
+
+Variable Substitution
+---------------------
+
+During the installation process IzPack can substitute variables in various
+places with real values. Obvious targets for variable substitution are
+resource files and launch scripts, however you will notice many more places
+where it is more powerful to use variables rather then hard coded values.
+Wherever variables can be used it will be explained in the documentation.
+
+
+There are three types of variables:
+
+- Built-In variables. These are implemented in IzPack and are all
+ dynamic in nature. This means that the value of each variable depends on
+ local conditions on the target system.
+- Environment variables. These are provided by the operating system the
+ installer is run on.
+- Variables that you can define. You also define the value, which is
+ fixed for a given installation file.
+
+You define your own variables in the installation XML file with the
+``<variable>`` tag. How to do this is explained in detail later in this
+chapter.
+
+
+**Please note** that when using variables they must always appear with a
+'``$``' sign as the first character, even though they are not defined this
+way.
+
+
+
+The Built-In Variables
+----------------------
+
+The following variables are built-in :
+
+- ``$INSTALL_PATH`` : the installation path on the target system, as
+ chosen by the user
+- ``$APPLICATIONS_DEFAULT_ROOT`` : the default path for applications
+- ``$JAVA_HOME`` : the JavaTM virtual machine home path
+- ``$CLASS_PATH`` : the Class Path used mainly for Java Applications
+- ``$USER_HOME`` : the user's home directory path
+- ``$USER_name`` : the user name
+- ``$APP_name`` : the application name
+- ``$APP_URL`` : the application URL
+- ``$APP_VER`` : the application version
+- ``$ISO3_LANG`` : the ISO3 language code of the selected langpack.
+- ``$IP_ADDRESS`` : the IP Address of the local machine.
+- ``$HOST_NAME`` : the HostName of the local machine.
+- ``$FILE_SEPARATOR`` : the file separator on the installation system
+- ``$DesktopShortcutCheckboxEnabled`` : When set to true, it
+ automatically checks the "Create Desktop Shortcuts" button. To see how to
+ use it, go to `The Variables Element ``<variables>`` Be careful this
+ variable is case sensitve !
+- ``$InstallerFrame.logfilePath`` : The path to the install log. This
+ file contains the paths of all installed files. If set to "default" then
+ the "$INSTALL_PATH/Uninstaller/install.log" path will be used. To see how
+ to use it, go to `The Variables Element ``<variables>``. If this
+ variable is not set, no install.log will be created.
+
+
+Environment Variables
+---------------------
+
+Environment variables can be accessed via the syntax ``${ENV[variable]}``.
+The curly braces are mandatory. Note that variable names are case-sensitive
+and usually in UPPER CASE.
+
+Example: To get the value of the OS environment variable "CATALINA_HOME", use
+``${ENV[CATALINA_HOME]}``.
+
+
+Parse Types
+-----------
+
+Parse types apply only when replacing variables in text files. At places
+where it might be necessary to specify a parse type, the documentation will
+mention this. Depending on the parse type, IzPack will handle special cases
+-such as escaping control characters- correctly. The following parse types
+are available:
+
+- ``plain`` - use this type for plain text files, where no special
+ substitution rules apply. All variables will be replaced with their
+ respective values as is.
+- ``javaprop`` - use this type if the substitution happens in a Java
+ properties file. Individual variables might be modified to function
+ properly within the context of Java property files.
+- ``xml`` - use this type if the substitution happens in a XML file.
+ Individual variables might be modified to function properly within the
+ context of XML files.
+- ``shell`` - use this type if the substitution happens in a shell
+ script. Because shell scripts use ``$variable`` themselves, an
+ alternative variable marker is used: ``%variable`` or ``%{variable}``.
+
+
+The IzPack Elements
+-------------------
+
+*When writing your installer XML files, it's a good idea to have a look at
+the iZPACK installation DTD*.
+
+
+
+
+The Root Element ``<installation>``
+''''''''''''''''''''''''''''''''''''
+
+The root element of an installation is ``<installation>``. It takes one
+required attribute : ``version``. The attribute defines the version of the
+XML file layout and is used by the compiler to identify if it is compatible
+with the XML file. This should be set to **1.0** for the moment.
+
+
+The Information Element ``<info>``
+'''''''''''''''''''''''''''''''''''
+
+This element is used to specify some general information for the installer.
+It contains the following elements :
+
+- ``<appname>`` : the application name
+- ``<appversion>`` : the application version
+- ``<appsubpath>`` : the subpath for the default of the installation
+ path. A variable substitution and a maskable slash-backslash conversion
+ will be done. If this tag is not defined, the application name will be
+ used instead.
+- ``<url>`` : the application official website url
+- ``<authors>`` : specifies the author(s) of the application. It must
+ contain at least one ``<author>`` element whose attributes are :
+
+ - ``name`` : the author's name
+ - ``email`` : the author's email
+
+- ``<uninstaller>`` : specifies whether to create an uninstaller after
+ installation, and which name to use for it. This tag has the ``write``
+ attribute, with default value `` yes``. If this tag is not specified, the
+ uninstaller will still be written. The ``name`` attribute can be used to
+ change the default name of the generated uninstaller, *i.e.* ``
+ uninstaller.jar``.
+- ``<javaversion>`` : specifies the minimum version of Java required to
+ install your program. Values can be ``1.2``, ``1.2.2``, ``1.4``, etc. The
+ test is a lexical comparison against the ``java.version`` System property
+ on the install machine.
+- ``<webdir>`` : Causes a ''web installer'' to be created, and
+ specifies the URL packages are retrieved from at install time. The
+ content of the tag must be a properly formed URL.
+- ``<summarylogfilepath>`` : specifies the path for the logfile of the
+ `SummaryLoggerInstallerListener`.
+
+Here is an example of a typical ``<info>`` section :
+
+
+::
+
+ <info>
+ <appname>Super extractor</appname>
+ <appversion>2.1 beta 6</appversion>
+ <appsubpath>myCompany/SExtractor</appsubpath>
+ <url>http://www.superextractor.com/</url>
+ <authors>
+ <author name="John John Doo" email="jjd at jjd-mail.com"/>
+ <author name="El Goyo" email="goyoman at mymail.org"/>
+ </authors>
+ <javaversion>1.2</javaversion>
+ </info>
+
+The Packaging Element ``<packaging>``
+''''''''''''''''''''''''''''''''''''''
+
+This element allows to specify packaging options. If not specified, the default will be to create an all in one
+installer. This element will usually be used to create an installer which spans over multiple volumes,
+e.g. the output will be two CDs. The packaging-element contains the following elements:
+
+- ``<packager>`` : specifies options used by the packager. The packager tag has the ``class`` attribute,
+ which specifys the class to use for packaging. Currently two implementations
+ are available (com.izforge.izpack.compiler.Packager, com.izforge.izpack.compiler.MultiVolumePackager).
+ The packager-element can contain the ``<options>`` element which can have different attributes for the different
+ implementations of packagers. For the MultiVolumePackager, it can have the following attributes:
+
+ - ``volumesize``: the size of the volumes
+ - ``firstvolumefreespace``: free space on the first volume used for the installer jar and additional resources like
+ readme-files etc.
+
+
+- ``<unpacker>`` : specifies which unpacker class should be used. Currently there are two unpacker implementations
+ (com.izforge.izpack.compiler.UnPacker, com.izforge.izpack.compiler.MultiVolumeUnPacker).
+
+Here's an example how to specify an installer which will create multiple volumes. In this example the volumes shall be
+CDs with 650 megabytes. There will be an additional free space of 150 megabytes on the first volume. This will result in
+the creation of an installer.jar and multiple installer.pak* files. The installer.jar plus installer.pak plus the additional
+resources have to be copied on the first volume, each installer.pak.<number> on several volumes.
+
+::
+
+ <packaging>
+ <packager class="com.izforge.izpack.compiler.MultiVolumePackager">
+ <!-- 650 MB volumes, 150 MB space on the first volume -->
+ <options volumesize="681574400" firstvolumefreespace="157286400"/>
+ </packager>
+ <unpacker class="com.izforge.izpack.installer.MultiVolumeUnpacker" />
+ </packaging>
+
+The Variables Element ``<variables>``
+''''''''''''''''''''''''''''''''''''''
+
+This element allows you to define variables for the variables substitution
+system. Some variables are built-in, such as ``$INSTALL_PATH`` (which is the
+installation path chosen by the user). When you define a set of variables,
+you just have to place as many ``<variable>`` tags in the file as needed. If
+you define a variable named ``VERSION`` you need to type $VERSION in the
+files to parse. The variable substitutor will then replace it with the
+correct value. One ``<variable>`` tag take the following attributes :
+
+- ``name`` : the variable name
+- ``value`` : the variable value
+
+Here's a sample ``<variables>`` section :
+
+
+::
+
+ <variables>
+ <variable name="app-version" value="1.4"/>
+ <variable name="released-on" value="08/03/2002"/>
+ </variables>
+
+
+Here's a precise sample on how to use desktopshortcutcheckboxenabled and
+InstallerFrame.logfilePath variables:
+
+
+::
+
+ <variables>
+ <variable name="InstallerFrame.logfilePath" value="$INSTALL_PATH
+ /My-install.log"/>
+ <!-- This means that the log name will be My-install and that
+ it will be stored at the root of the installation. -->
+ <!-- Any path is fine. If value is set to "Default" then
+ "$INSTALL_PATH/uninstall/install.log" is used. -->
+ <!-- And if variable isn't defined then no log is written. -->
+ <variable name="desktopshortcutcheckboxenabled" value="true"/>
+ <!-- This automatically checks the "Create Desktop Shortcuts"
+ button. Default value is "False". -->
+ </variables>
+
+
+The GUI Preferences Element ``<guiprefs>``
+'''''''''''''''''''''''''''''''''''''''''''
+
+This element allows you to set the behavior of your installer GUI. This
+information will not have any effect on the command-line installers that will
+be available in future versions of iZPACK . The arguments to specify are :
+
+- ``resizable`` : takes ``yes`` or ``no`` and indicates whether the
+ window size can be changed or not.
+- ``width`` : sets the initial window width
+- ``height`` : sets the initial window height.
+
+Here's a sample :
+
+::
+
+ <guiprefs resizable="no" width="800" height="600"/>
+
+
+Starting from IzPack 3.6, the look and feel can be specified in this section
+on a per-OS basis. For instance you can use the native look and feels on
+Win32 and OS X but use a third-party one on Unix-like platforms. To do that,
+you have to add some children to the ``guiprefs`` tag:
+
+- ``laf``: the tag that specifies a look and feel. It has a ``name``
+ parameter that defines the look and feel name.
+- Each ``laf`` element needs at least one ``os`` tag, specified like in
+ the other parts of the specification that support this tag.
+- Like you can add ``os`` elements, you can add any number of ``param``
+ elements to customize a look and feel. A ``param`` elements has two
+ attribues: ``name`` and `` value``.
+
+The available look and feels are:
+
+- Kunststoff: ``kunststoff``
+- Liquid: ``liquid``
+- Metouia: ``metouia``
+- JGoodies Looks: ``looks``
+- Substance: ``substance``
+
+If you don't specify a look and feel for a particular operating system, then
+the default native one will be used: Windows on Windows, Aqua on Mac OS X and
+Metal on the Unix-like variants.
+
+
+The *Liquid Look and Feel* supports the following parameters:
+
+- ``decorate.frames``: ``yes`` means that it will render the frames in
+ Liquid style
+- ``decorate.dialogs``: ``yes`` means that it will render the dialogs
+ in Liquid style
+
+The *JGoodies Looks* look and feel can be specified by using the ``variant``
+parameters. The values can be one of:
+
+- ``windows``: use the Windows look
+- ``plastic``: use the basic Plastic look
+- ``plastic3D``: use the Plastic 3D look
+- ``plasticXP``: use the Plastic XP look (default).
+
+Here is a small sample:
+
+::
+
+ <guiprefs height="600" resizable="yes" width="800">
+ <laf name="metouia">
+ <os family="unix" />
+ </laf>
+ <laf name="looks">
+ <os family="windows" />
+ <param name="variant" value="extwin" />
+ </laf>
+ </guiprefs>
+
+
+The *Substance* look and feel *toned-down* themes can be specified using the
+``variant`` parameter, with the value being one of: ``business, business-
+blue, business-black, creme, sahara, moderate, officesilver``. We have
+reduced the choice to the toned-down themes since they are the only ones to
+actually look decent (the other families colors are way too saturated).
+Please consult https://substance.dev.java.net/docs/skins/toneddown.html
+for a gallery of the different toned-down themes.
+
+Starting from IzPack 3.7, some characteristics can be customized with the
+``<modifier>`` tag. There is a separate description in the `Advanced
+Features` chapter paragraph `Modifying the GUI`.
+
+
+
+The Localization Element ``<locale>``
+''''''''''''''''''''''''''''''''''''''
+
+This element is used to specify the language packs (langpacks) that you want
+to use for your installer. You must set one ``<langpack>`` markup per
+language. This markup takes the `` iso3`` parameter which specifies the iso3
+language code.
+
+
+Here's a sample :
+
+
+::
+
+ <locale>
+ <langpack iso3="eng"/>
+ <langpack iso3="fra"/>
+ <langpack iso3="spa"/>
+ </locale>
+
+
+The supported ISO3 codes are :
+
+========= ============================
+ISO3 code Language
+========= ============================
+cat Catalunyan
+chn Chinese
+cze Czech
+dan Danish
+deu German
+eng English
+fin Finnish
+fra French
+hun Hungarian
+ita Italian
+jpn Japanese
+mys Malaysian
+ned Nederlands
+nor Norwegian
+pol Polnish
+por Portuguese (Brazilian)
+rom Romanian
+rus Russian
+scg Serbian
+spa Spanish
+svk Slovakian
+swe Swedish
+ukr Ukrainian
+========= ============================
+
+
+
+The Resources Element ``<resources>``
+''''''''''''''''''''''''''''''''''''''
+
+Several panels, such as the license panel and the shortcut panel, require
+additional data to perform their task. This data is supplied in the form of
+resources. This section describes how to specify them. Take a look at each
+panel description to see if it might need any resources. Currently, no checks
+are made to ensure resources needed by any panel have been included. The ``
+<resources>`` element is not required, and no ``<res>`` elements are required
+within.
+The ``<resources>`` element is the only element besides the ``<packs>``
+element that is taken into consideration in referenced pack-files (see
+```<packs>`` element`_ for more info)
+
+
+You have to set one ``<res>`` markup for each resource. Here are the
+attributes to specify :
+
+- ``src`` : the path to the resource file which can be named freely of
+ course (for instance ``my-picture.jpg``).
+- ``id`` : the resource id, depending on the needs of a particular
+ panel
+- ``parse`` : takes ``yes`` or ``no`` (default is ``no``) - used to
+ specify whether the resource must be parsed at the installer compilation
+ time. For instance you could set the application version in a readme file
+ used by ``InfoPanel``.
+- ``type`` : specifies the parse type. This makes sense only for a text
+ resource - the default is ``plain``, other values are ``javaprop, xml``
+ (Java properties file and XML files)
+- ``encoding`` : specifies the resource encoding if the receiver needs
+ to know. This makes sense only for a text resource.
+
+Here's a sample :
+
+::
+
+ <resources>
+ <res id="InfoPanel.info" src="doc/readme.txt" parse="yes"/>
+ <res id="LicencePanel.licence" src="legal/License.txt"/>
+ </resources>
+
+
+The Panels Element ``<panels>``
+'''''''''''''''''''''''''''''''''
+
+Here you tell the compiler which panels you want to use. They will appear in
+the installer in the order in which they are listed in your XML installation
+file. Take a look at the different panels in order to find the ones you need.
+The ``<panel>`` markup takes a single attribute ``classname`` which is the
+classname of the panel.
+
+
+Here's a sample :
+
+::
+
+ <panels>
+ <panel classname="HelloPanel"/>
+ <panel classname="LicencePanel"/>
+ <panel classname="TargetPanel"/>
+ <panel classname="InstallPanel"/>
+ <panel classname="FinishPanel"/>
+ </panels>
+
+
+The Packs Element ``<packs>``
+'''''''''''''''''''''''''''''''
+
+This is a crucial section as it is used to specify the files that need to be
+installed. The ``<packs>`` section consists of several ``<pack>`` and
+``<refpack>`` tags.
+
+The ``<pack>`` takes the following attributes :
+
+- ``name``: the pack name
+- ``required``: takes ``yes`` or ``no`` and specifies whether the pack
+ is optional or not.
+- ``os``: optional attribute that lets you make the pack targeted to a
+ specific *operating system*, for instance ``unix``, ``mac`` and so on.
+- ``preselected``: optional attribute that lets you choose whether the
+ pack is by default selected for installation or not. Possible values are
+ ``yes`` and ``no``. A pack which is not preselected needs to be
+ explicitly selected by the user during installation to get installed.
+- ``loose``: can be used so that the files are not located in the
+ installer Jar. The possible values are ``true`` or ``false``, the default
+ beeing ``false``. The author of this feature needed to put his
+ application on a CD so that the users could run it directly from this
+ media. However, he also wanted to offer them the possibility to install
+ the software localy. Enabling this feature will make IzPack take the
+ files on disk instead of from the installer. *Please make sure that your
+ relative files paths are correct !*
+- ``id``: this attribute is used to give a unique id to the pack to be
+ used for internationalization.
+- ``packImgId``: this attribute is used to reference a unique resource
+ that represents the pack's image for the ImgPacksPanel. The resource
+ should be defined in the ``<resources>`` element of the installation XML
+ using the same value for the ``id`` attribute of the ``<res>`` element.
+
+The ``<refpack>`` takes only one attribute ``file``, which contains the
+relative path (from the installation compiler) to an externally defined
+packs-definition. This external packs definition is a regular IzPack
+installation XML. However the only elements that are used from that XML file
+are the ``<packs>`` and the ``<resources>`` elements. This enables a model in
+which a single developer is responsible for maintaining the packs and
+resources related to the development-package assigned to him. The main
+install XML references these xml-files to avoid synchronization efforts
+between the central installation XML and the developer-maintained installer
+XMLs.
+
+Internationalization of the PacksPanel
+'''''''''''''''''''''''''''''''''''''''
+
+In order to provide internationalization for the PacksPanel, so that your
+users can be presented with a different name and description for each
+language you support, you have to create a file named ``packsLang.xml_xyz``
+where ``xyz`` is the ISO3 code of the language in lowercase. Please be aware
+that case is significant. This file has to be inserted in the resources
+section of `` install.xml`` with the ``id`` and ``src`` attributes set at the
+name of the file. The format of these files is identical with the
+distribution langpack files located at ``
+$IZPACK_HOME/bin/langpacks/installer``. For the name of the panel you just
+use the pack ``id`` as the txt ``id``. For the description you use the pack
+``id`` suffixed with ``.description``.
+
+The following sections describe the tags available for a ``<pack>`` section.
+
+
+``<description>`` - pack description
+'''''''''''''''''''''''''''''''''''''
+
+The contents of the ``<description>`` tag describe the pack contents. This
+description is displayed if the user highlights the pack during installation.
+
+
+``<depends>`` - pack dependencies
+''''''''''''''''''''''''''''''''''
+
+This can be used to make this pack selectable only to be installed only if
+some other is selected to be installed. The pack can depend on more than one
+by specifying more than one `` <depends>`` elements.
+Circular depedencies are not supported and the compiler reports an error if
+one occurs.
+
+This tag takes the following attribute:
+
+- ``packname``: The name of the pack that it depends on
+
+
+``<os>`` - OS restrictions
+'''''''''''''''''''''''''''
+
+It is possible to restrict a panel to a certain list of operating systems.
+This tag takes the following attributes:
+
+- ``family``: unix, windows or mac
+- ``name``: the exact OS name (ie Windows, Linux, ...)
+- ``version``: the exact OS version (see the JVM ``os.version``
+ property)
+- ``arch``: the machine architecture (see the JVM ``os.arch``
+ property).
+
+
+``<updatecheck>``
+''''''''''''''''''
+
+This feature can update an already installed package, therefore removing
+superfluous files after installation. Here's how this feature author (Tino
+Schwarze) described it on the IzPack development mailing-list:
+
+> Each pack can now specify an ``<updatecheck>`` tag. It supports a subset of
+ant fileset syntax, e.g.:
+
+::
+
+ <updatecheck>
+ <include name="lib/**" />
+ <exclude name="config/local/** />
+ </updatecheck>
+
+
+> If the paths are relative, they will be matched relative to
+``$INSTALL_PATH``. Update checks are only enabled if at least one
+``<include>`` is specified. See `` com.izforge.izpack.installer.Unpacker``
+for details.
+
+
+
+``<file>`` - add files or directories
+'''''''''''''''''''''''''''''''''''''''
+
+The ``<file>`` tag specifies a file (a directory is a file too) to include
+into the pack. It takes the following attributes:
+
+- ``src``: the file location (relative path) - if this is a directory
+ its content will be added recursively
+- ``targetdir``: the destination directory, could be something like
+ ``$INSTALL_PATH/subdirX``
+- ``os``: can optionally specify a target operating system (``unix,
+ windows, mac``) - this means that the file will only be installed on its
+ target operating system
+- ``override``: if ``true`` then if the file is already installed, it
+ will be overwritten. Alternative values: ``asktrue`` and ``askfalse`` -
+ ask the user what to do and supply default value for non-interactive use.
+ Another possible values is ``update``. It means that the new file is only
+ installed if it's modification time is newer than the modification time
+ of the already existing file (note that this is not a reliable mechanism
+ for updates - you cannot detect whether a file was altered after
+ installation this way.) By default it is set to `` update``.
+- ``unpack``: if ``true`` and the file is an archive then its content
+ will be unpacked and added as individual files
+
+
+
+``<additionaldata>``
+'''''''''''''''''''''
+
+This tag can also be specified in order to pass additional data related to a
+file tag for customizing.
+
+- ``<key>``: key to identify the data
+- ``<value>``: value which can be used by a custom action
+
+
+
+``<singlefile>`` - add a single file
+'''''''''''''''''''''''''''''''''''''
+
+Specifies a single file to include. The difference to ``<file>`` is that this
+tag allows the file to be renamed, therefore it has a ``target`` attribute
+instead of `` targetdir``.
+
+- ``src``: the file location (relative path)
+- ``target``: the destination file name, could be something like
+ ``$INSTALL_PATH/subdirX/fileY``
+- ``os``: can optionally specify a target operating system (``unix,
+ windows, mac``) - this means that the file will only be installed on its
+ target operating system
+- ``override``: see ``<file>`` for description
+
+A ``<additionaldata>`` tag can also be specified for customizing.
+
+
+
+``<fileset>``: add a fileset
+'''''''''''''''''''''''''''''
+
+The ``<fileset>`` tag allows files to be specified using the powerful Jakarta
+Ant set syntax. It takes the following parameters:
+
+- ``dir``: the base directory for the fileset (relative path)
+- ``targetdir``: the destination path, works like for ``<file>``
+- ``casesensitive``: optionally lets you specify if the names are case-
+ sensitive or not - takes ``yes`` or ``no``
+- ``defaultexcludes``: optionally lets you specify if the default
+ excludes will be used - takes ``yes`` or ``no``.
+- ``os``: specifies the operating system, works like for ``<file>``
+- ``override``: see ``<file>`` for description
+- ``includes``: comma- or space-separated list of patterns of files
+ that must be included; all files are included when omitted. This is an
+ alternative for multiple include tags.
+- ``excludes``: comma- or space-separated list of patterns of files
+ that must be excluded; no files (except default excludes) are excluded
+ when omitted. This is an alternative for multiple exclude tags.
+
+You specify the files with ``<include>`` and ``<exclude>`` tags that take the
+``name`` parameter to specify the Ant-like pattern :
+
+- ``**`` : means any subdirectory
+- ``*`` : used as a wildcard.
+
+Here are some examples of Ant patterns :
+
+- ``<include name="lib"/>`` : will include ``lib`` and the
+ subdirectories of ``lib``
+- ``<exclude name="**/*.java"/>`` : will exclude any file in any
+ directory starting from the base path ending by ``.java``
+- ``<include name="lib/*.jar"/>`` : will include all the files ending
+ by ``.jar`` in ``lib``
+- ``<exclude name="lib/**/*FOO*"/>`` : will exclude any file in any
+ subdirectory starting from ``lib`` whose name contains ``FOO``.
+
+There area set of definitions that are excluded by default file-sets, just as
+in Ant. IzPack defaults to the Ant list of default excludes. There is
+currently no equivalent to the <defaultexcludes> task. Default excludes are:
+
+::
+
+ **/*\~{}
+ **/\#*\#
+ **/.\#*
+ **/%*%
+ **/.\_*
+ **/CVS
+ **/CVS/**
+ **/.cvsignore
+ **/SCCS
+ **/SCCS/**
+ **/vssver.scc
+ **/.svn
+ **/.svn/**
+ **/.DS\_Store
+
+
+A ``<additionaldata>`` tag can also be specified for customizing.
+
+
+``<parsable>`` - parse a file after installation
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Files specified by ``<parsable>`` are parsed after installation and may have
+variables substituted.
+
+- ``targetfile`` : the file to parse, could be something like
+ ``$INSTALL_PATH/bin/launch-script.sh``
+ A slash will be changed to the system dependant path separator (e.g. to a
+ backslash on Windows) only if no backslash masks the slash.
+- ``type`` : specifies the type (same as for the resources) - the
+ default is ``plain``
+- ``encoding`` : specifies the file encoding
+- ``os``: specifies the operating system, works like for ``<file>``
+
+
+``<executable>`` - mark file executable or execute it
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``<executable>`` tag is a very useful thing if you need to execute
+something during the installation process. It can also be used to set the
+executable flag on Unix-like systems. Here are the attributes :
+
+- ``targetfile`` : the file to run, could be something like
+ ``$INSTALL_PATH/bin/launch-script.sh``
+ Slashes are handled special (see attribute ``targetfile`` of tag
+ ``<parsable>``).
+- ``class`` : If the executable is a jar file, this is the class to run
+ for a JavaTM program
+- ``type`` : ``bin`` or ``jar`` (the default is ``bin``)
+- ``stage`` : specifies when to launch : ``postinstall`` is just after
+ the installation is done, ``never`` will never launch it (useful to set
+ the +x flag on Unix). ``uninstall`` will launch the executable when the
+ application is uninstalled. The executable is executed before any files
+ are deleted. ``never`` is the default value.
+- ``failure`` : specifies what to do when an error occurs : ``abort``
+ will abort the installation process, ``ask`` (default) will ask the user
+ what to do and ``warn`` will just tell the user that something is wrong
+- ``os``: specifies the operating system, works like for ``<file>``
+- ``keep`` : specifies whether the file will be kept after execution.
+ The default is to delete the file after is has been executed. This can be
+ changed by specifying ``keep="true"``.
+
+A ``<args>`` tag can also be specified in order to pass arguments to the
+executable:
+
+- ``<arg>``: passes the argument specified in the ``value`` attribute.
+ Slashes are handled special (see attribute ``targetfile`` of tag
+ ``<parsable>``.
+
+
+
+``<os>`` - make a file OS-dependent
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``<os>`` tag can be used inside the ``<file>``, ``<fileset>``,
+``<singlefile>``, ``<parsable>``, ``<executable>`` tags to restrict it's
+effect to a specific operating system family, architecture or version:
+
+- ``family``: ``unix, windows, mac`` to specify the operating system
+ family
+- ``name``: the operating system name
+- ``version``: the operating system version
+- ``arch``: the operating system architecture (for instance the Linux
+ kernel can run on i386, sparc, and so on)
+
+Here's an example installation file :
+
+::
+
+ <packs>
+ <!-- The core files -->
+ <pack name="Core" required="yes">
+ <description>The IzPack core files.</description>
+ <file targetdir="$INSTALL_PATH" src="bin"/>
+ <file targetdir="$INSTALL_PATH" src="lib"/>
+ <file targetdir="$INSTALL_PATH" src="legal"/>
+ <file targetdir="$INSTALL_PATH" src="Readme.txt"/>
+ <file targetdir="$INSTALL_PATH" src="Versions.txt"/>
+ <file targetdir="$INSTALL_PATH" src="Thanks.txt"/>
+ <parsable targetfile="$INSTALL_PATH/bin/izpack-fe"/>
+ <parsable targetfile="$INSTALL_PATH/bin/izpack-
+ fe.bat"/>
+ <parsable targetfile="$INSTALL_PATH/bin/compile"/>
+ <parsable
+ targetfile="$INSTALL_PATH/bin/compile.bat"/>
+ <executable targetfile="$INSTALL_PATH/bin/compile"
+ stage="never"/>
+ <executable targetfile="$INSTALL_PATH/bin/izpack-fe"
+ stage="never"/>
+ </pack>
+
+ <!-- The documentation (1 directory) -->
+ <pack name="Documentation" required="no">
+ <description>The IzPack documentation (HTML and
+ PDF).</description>
+ <file targetdir="$INSTALL_PATH" src="doc"/>
+ </pack>
+ </packs>
+
+
+The Native Element ``<native>``
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Use this if you want to use a feature that requires a native library. The
+native libraries are placed under ``bin/native/..``. There are 2 kinds of
+native libraries : the iZPACK libraries and the third-party ones. The IzPack
+libraries are located at ``bin/native/izpack``, you can place your own
+libraries at `` bin/native/3rdparty``. It is possible to place a native
+library also into the uninstaller. It is useable from CustomActions.
+If one or more are referenced for it, the needed support classes are
+automatically placed into the uninstaller. To place it only on operating
+systems for which they are build, it is possible to define an OS restriction.
+This restriction will only be performed for the uninstaller. The markup takes
+the following attributes :
+
+- ``type`` : ``izpack`` or ``3rdparty``
+- ``name`` : the library filename
+- ``stage``: stage where to use the library (install|uninstall|both)
+
+
+``<os>`` - make a library OS-dependent
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``<os>`` tag can be used to restrict the inclusion into the uninstaller
+to a specific operating system family, architecture or version. The inclusion
+into the installer will be always done.
+
+Here's a sample :
+
+::
+
+ <native type="izpack" name="ShellLink.dll"/>
+
+
+The Jar Merging Element ``<jar>``
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+If you adapt iZPACK for your own needs, you might need to merge the content
+of another jar file into the jar installer. For instance, this could be a
+library that you need to merge. The ``<jar>`` markup allows you to merge the
+raw content of another jar file into the installer and the uninstaller. It is
+necessary that the paths in the jars are unique because only the contained
+files of the jar are added to the installer jar, not the jar file self. The
+attributes are:
+
+- ``src`` : the path at compile time
+- ``stage``: stage where to use the contents of the additional jar file
+ (install|uninstall|both)
+
+A sample :
+
+::
+
+ <jar src="../nicelibrary.jar"/>
+
+The Available Panels
+---------------------
+
+In this section i will introduce the various panels available in IzPack. The
+usage for most is pretty simple and described right here. The more elaborate
+ones are explained in more detail in the *Advanced Features* chapter or in
+their own chapter. The panels are listed by their class name. This is the
+name that must be used with the ``classname`` attribute. Please be aware that
+the classname is Case-Sensitive, meaning that if the case from the
+install.xml and the founded class file differs the installation will break.
+In this last case, the installer will Throw an IllegalArgumentException in
+the compiler if the declared class name in the xml file differs in case from
+the founded class file.
+
+
+
+HelloPanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+This panel welcomes the user by displaying the project name, the version, the
+URL as well as the authors.
+
+
+
+CheckedHelloPanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+This panel welcomes the user also by displaying the project name, the
+version, the URL as well as the authors.
+
+
+Additonal on windows the registry will be scanned for an entry which
+determines that the product is already installed. If so, a dialog will be
+shown which ask whether to install a second version of the product or not. If
+you use this panel do not forget to add the `registry feature` into your
+installation.
+
+
+InfoPanel and HTMLInfoPanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+This is a kind of 'README' panel. It presents text of any length. The text is
+specified by the ``(HTML)InfoPanel.info`` resource. Starting from IzPack
+3.7.0, variables substitution is allowed.
+To add an image to the HTMLInfoPanel you simply need to add a ressource to
+your install.xml with an ID decided by you, then you can call this image by
+refering it by this same ID.
+
+In install.xml:
+
+::
+
+ <resources>
+ <res src="logo.jpg" id="GHGHGH"/>
+ .....
+
+and in file.html:
+
+::
+
+ <img src="GHGHGH" />
+
+
+LicencePanel and HTMLLicencePanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Note:* There is a mistake in the name - it should be LicensePanel. In France
+the word is Licence ... and one of my diploma is a 'Licence' so ...:* -)
+
+
+Adding images to HTMLLicencePanel works exactly the same way as with
+HTMLInfoPanel.
+
+These panels can prompt the user to acknowledge a license agreement. They
+block unless the user selects the 'agree' option. To specify the license
+agreement text you have to use the `` (HTML)LicencePanel.licence`` resource.
+
+
+
+PacksPanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Allows the user to select the packs he wants to install.
+
+
+
+ImgPacksPanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+This is the same as above, but for each pack a different picture is shown to
+the user. The pictures are specified using the packImgId attribute for each
+pack in the installer XML. The initial image will be the image of the first
+pack that has a packImgId. The image is updated each time the user
+(de)selects a pack that has a packImgId. Of course it's up to you to specify
+an image for each pack in your installation with a unique packImgId. For
+instance if you have 2 packs ``core`` and ``documentation`` (in this order),
+and you assign both packs a packImgId that is identical to the pack's name
+then the resource for ``core`` will be ``core`` and the resource for
+``documentation`` will be ``documentation``. The initially shown image will
+be the resource ``core``. The supported image formats depend on what your
+client's JVM supports, but starting from J2SE 1.3, *GIF*, *JPEG* and *PNG*
+are supported.
+
+
+
+TargetPanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+This panel allows the user to select the installation path. It can be
+customized with the following resources (they are text files containing the
+path) :
+
+- ``TargetPanel.dir.f`` where f stands for the family (``mac, macosx,
+ windows, unix``)
+- ``TargetPanel.dir`` : the directory name, instead of the software to
+ install name
+- ``TargetPanel.dir.d`` where d is a "dynamic" name, as returned by the
+ JavaTM virtual machine. You should write the name in lowercase and
+ replace the spaces with underscores. For instance, you might want a
+ different setting for Solaris and GNU/Linux which are both Unix-like
+ systems. The resources would be ``TargetPanel.dir.sunos,
+ TargetPanel.dir.linux``. You should have a Unix-resource in case it
+ wouldn't work though.
+
+
+InstallPanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+You should always have this one as it launches the installation process !
+
+
+
+XInfoPanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+A panel showing text parsed by the variable substitutor. The text can be
+specified through the ``XInfoPanel.info`` resource. This panel can be useful
+when you have to show information after the installation process is completed
+(for instance if the text contains the target path).
+
+
+
+FinishPanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+A ending panel, able to write automated installer information. For details
+see the chapter on 'Advanced Features'.
+
+
+
+SimpleFinishPanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Same as ``FinishPanel``, but without the automated installer features. It is
+aimed at making the life easier for end-users who will never encounter the
+automated installer extra feature.
+
+
+
+ShortcutPanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+This panel is used to create desktop shortcuts. For details on using the
+ShortcutPanel see the chapter 'Desktop Shortcuts'.
+
+
+UserInputPanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+This panel allows you to prompt the user for data. What the user is prompted
+for is specified using an XML file which is included as a resource to the
+installer.
+
+
+CompilePanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+This panel allows you to compile just installed Java sourcecode. The details
+for the compilation are specified using the resource
+``CompilePanel.Spec.xml``. The XML file has the following format:
+
+::
+
+ <compilation>
+ <global>
+ <compiler>
+ <choice value="$JAVA_HOME/bin/javac" />
+ <choice value="jikes" />
+ </compiler>
+ <arguments>
+ <choice value="-O -g:none" />
+ <choice value="-O" />
+ <choice value="-g" />
+ <choice value="" />
+ </arguments>
+ </global>
+ <jobs>
+ <classpath add="$INSTALL_PATH/src/classes/" />
+ <job name="optional name">
+ <directory name="$INSTALL_PATH/src/classes/xyz" />
+ </job>
+ <job name="another job">
+ <packdepency name="some package name" />
+ <classpath sub="$INSTALL_PATH/" />
+ <directory name="$INSTALL_PATH/src/classes/abc" />
+ <file name="$INSTALL_PATH/some/file.java" />
+ </job>
+ </jobs>
+ </compilation>
+
+
+In theory, jobs can be nested but this has not been tested at all. A change
+to the classpath within a job only affects this job and nested jobs. The
+classpath should be specified before any files or directories.
+
+The user can change the compiler to use and choose from some default
+compilation options before compilation is started.
+
+.. image:: ./compilePanel.png
+ :alt: CompilePanel
+
+
+
+ProcessPanel
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+This panel allows you to execute arbitrary files after installation. The
+details for the compilation are specified using the resource
+``ProcessPanel.Spec.xml``.
+
+The XML file has the following format:
+
+::
+
+ <processing>
+ <job name="do xyz">
+ <os family="windows" />
+ <executefile name="$INSTALL_PATH/scripts/xyz.bat">
+ <arg>doit</arg><arg>$variable</arg>
+ </executefile>
+ </job>
+ <job name="do xyz">
+ <os family="unix" />
+ <executefile name="$INSTALL_PATH/scripts/xyz.sh">
+ <arg>doit</arg><arg>$variable</arg>
+ </executefile>
+ </job>
+ </processing>
+
+
+Each job may have an ``<os>`` attribute.
+
+
+
+``<executeclass>`` - Execute Java Classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is also possible to execute Java classes from this panel. Here's what this
+feature author (Alex Bradley) says:
+
+> i've been able to work around my requirements by extending the
+``ProcessPanelWorker`` functionality to run user-specified classes. i've
+extended the DTD of the `` ProcessPanel.Spec.xml`` to include a new element:
+
+::
+
+ <executeclass name="classname">
+ <args..../>
+ </executeclass>
+
+
+> i've also added a new sub-class of ``Processable`` called ``executeclass``.
+This will run a user-specified class in the context of the installer JVM with
+a single method :
+
+::
+
+ run( AbstractUIProcessHandler handler, String[] args]);
+
+
+> It can do everything i need and more. In particular, it allows me to write
+a process extension and still be able to provide feedback to the user through
+the feedback panel, and to add new functionality to the installer, after its
+been built.
+
+To use the executeclass facility, you will need to create a jar file with
+your class and then add it to the installer with the `The Jar Merging
+Element`.
+
+
+``<executeForPack>`` - Only execute the job for certain packs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This can be be used to run the job only if the pack is enabled. For example,
+the batch file will if either the ``Sources`` or ``Executables`` packs are
+selected at install time.
+
+::
+
+ <processing>
+ <job name="List files">
+ <executeForPack name="Sources"/>
+ <executeForPack name="Executables"/>
+ <os family="windows" />
+ <executefile name="$INSTALL_PATH\batch\ListFiles.bat" />
+ </job>
+ </processing>
+
+``<logfiledir>`` - Output of the processPanel saved to a log
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+New with version 3.7 is the possibility to tee output that is written to the
+ProcessPanel's textarea into an optional logfile. Using this feature is
+pretty much straightforward, you only have to add a line in
+``ProcessPanel.Spec.xml`` that will tell IzPack the location, where the
+logfile should be stored.
+
+Variable substitution is performed, so you can use ``$INSTALL_PATH`` as
+example.
+
+The name of the logfile is not (yet) configurable but should fit in most
+cases. It will be named
+
+::
+
+ Install_V<$APP_VER>_<YYYY>-<MM>-<DD>_<hh>-<mm>-<ss>_<RandomId>.log
+
+
+Here's an example:
+
+::
+
+ <processing>
+ <logfiledir>$INSTALL_PATH</logfiledir>
+ <job name="do xyz">
+ <os family="windows" />
+ <executefile name="$INSTALL_PATH/scripts/xyz.bat">
+ <arg>doit</arg><arg>$variable</arg>
+ </executefile>
+ </processing>
+
+
+This will generate a logfile named e.g.
+``Install_V1.3_2004-11-08_19-22-20_43423.log`` located in ``$INSTALL_PATH``.
+
+``ProcessPanelWorker`` will write all output that is directed to ``stdout``
+and ``stderr`` to this file if ``ProcessPanel.Spec.xml`` contains the
+``logfiledir`` entry.
+
+Please note that this one file is used for storing the complete output of all
+jobs and not a file for each job that is run.
+
+
+JDKPathPanel
+'''''''''''''
+
+This panel allows the user to select a JDK path. The variable JAVA_HOME does
+not point to a JDK, else to a JRE also the environment variable points to a
+JDK. This is not a bug, this is the behavior of the VM. But some products
+needs a JDK, for that this panel can be used. There is not only a selection
+of the path else a validation. The validation will be done with the file
+JDKPath/lib/tools.jar. If JAVA_HOME points to the VM which is placed in the
+JDK, the directory will be used as default (JAVA_HOME/..). If there is the
+variable
+
+::
+
+ JDKPathPanel.skipIfValid
+
+
+defined with the value "yes", the panel will be skiped if the path is valid.
+Additional it is possible to make a version control. If one or both variables
+
+::
+
+ JDKPathPanel.minVersion
+ JDKPathPanel.maxVersion
+
+
+are defined, only a JDK will be accepted which has a version in the range of
+it. The detection is a little bit pragmatically, therefor it is possible,
+that the detection can fail at some VMs. The values in the install.xml should
+be like
+
+::
+
+ <variables>
+ <variable name="JDKPathPanel.minVersion" value="1.4.1" />
+ <variable name="JDKPathPanel.maxVersion" value="1.4.99" />
+ <variable name="JDKPathPanel.skipIfValid" value="yes" />
+ </variables>
+
+
+If all is valid, the panels isValidated method sets the variable
+
+::
+
+ JDKPath
+
+
+to the chosen path. Be aware, this variable exist not until the JDKPanel was
+quitted once. At a secound activation, the default will be the last
+selection.
+
+
+SelectPrinterPanel
+''''''''''''''''''''''''''
+
+This panel will look at the local printers installed and propose a list box
+with all of them. Once chosen, the variable $SELECTED_PRINTER is set to the
+user choice.
+
+
+DataCheckPanel
+''''''''''''''''''''''''''
+
+DataCheckPanel is not for inclusion in an actuall install, but is a debugging
+resource for developers writing custom panels or code to be included in
+IzPack.
+It creates a list of all the variables in InstallData, their values and a
+list of all packs, indicating which are selected.
+This list is printed to the console and appears in a scrollable text area on
+the panel.
+Put the panel in wherever you want to see any variables in InstallData or a
+listing of the packs with a line like this in the <panels> section of
+install.xml:
+
+<panel classname="DataCheckPanel" />
+
+It will automatically give you a full list of all the variables and packs
+whenever the panel is made active.
+
+
+SummaryPanel
+'''''''''''''
+
+This panel gives a summary of all shown panels. The best place for it is just
+infront of the InstallPanel. Normaly it contains a warning that this is the
+last panel before installation. The panel contains a scrollable HTML text
+area to display the summary. The informations are collected from each panel
+by calling the methods ``getSummaryCaption`` and ``getSummaryBody``.
+``getSummaryCaption`` is implemented in ``IzPanel`` with a panel name default
+text. ``getSummaryBody`` has to be implemented in all panels which should be
+presented in the summary. If the secound method is not implemented, no
+summary of this panel will be shown.
+
+Additional it is possible to `log the contents` of the summary panel into a
+HTML file.
+
+
+InstallationGroupPanel
+''''''''''''''''''''''''''
+
+This Panel groups the pack together. A panel which displays the available
+*installGroups* found on the packs to allow the user to select a subset of
+the packs based on the pack *installGroups* attribute. This panel will be
+skipped if there are no pack elements with an *installGroups* attribute. For
+example ::
+
+ <installation version="1.0">
+ (...)
+ <panels>
+ (...)
+ <panel classname="InstallationGroupPanel"/>
+ <panel classname="PacksPanel"/>
+ (...)
+ </panels>
+
+ <packs>
+ <pack name="Base"
+ installGroups="Group1"
+ required="yes">
+ (...)
+ </pack>
+ <pack name="Docs"
+ installGroups="Group1,Group2"
+ required="no">
+ (...)
+ </pack>
+ <pack name="Sources"
+ installGroups="Group3,Group2"
+ required="no">
+ (...)
+ </pack>
+ </packs>
+ </installation>
+
+In above example when InstallationGroupPanel is displayed,
+it contains three radios named Group1, Group2 and Group3. Depending
+on what user selects, the respective Packs will be displayed in
+PacksPanel. InstallationGroupPanel will look for a description
+corresponding to the key
+"InstallationGroupPanel.description.Group1",
+"InstallationGroupPanel.description.Group2" etc in installation
+langpacks and variables and displays this description for each of
+the Group_i.
+
+You may also define a sortKey in the variables section of the installer.xml
+to define an alternative sorting. The default sorting is based on the Group
+Name.
+
+Here is an example for alternative sorting of groups: ::
+
+ (...)
+ <variables>
+ (...)
+ <variable
+ name="InstallationGroupPanel.sortKey.Group2" value="A"/>
+ <variable
+ name="InstallationGroupPanel.sortKey.Group1" value="B"/>
+ <variable
+ name="InstallationGroupPanel.sortKey.Group3" value="C"/>
+ </variables>
+ (...)
+
+By default, your group name (and description) are displayed as-is in the
+installer. If you want them to be localized, add localized names to your
+``packsLang.xml`` resources. The string ID has to be
+InstallationGroupPanel.group.```group_name``.
+
+Here is an example to localize groups into French (these lines have to be put
+in your ``packsLang.xml_fra`` resource) :
+::
+
+<str id="InstallationGroupPanel.group.Core" txt="Noyau de l'application" />
+<str id="InstallationGroupPanel.description.Core" txt="Fichiers principaux, indispensables au fonctionnement de l'application" />
+<str id="InstallationGroupPanel.group.Samples" txt="Fichiers d'exemple" />
+<str id="InstallationGroupPanel.description.Samples" txt="Fichiers d'exemples" />
+
+If you want to add html markup to those strings, add ``.html`` at the end
+of the string id (after the group name).
Modified: izpack-src/trunk/src/lib/com/izforge/izpack/panels/InstallationGroupPanel.java
===================================================================
--- izpack-src/trunk/src/lib/com/izforge/izpack/panels/InstallationGroupPanel.java 2007-11-20 14:32:36 UTC (rev 1910)
+++ izpack-src/trunk/src/lib/com/izforge/izpack/panels/InstallationGroupPanel.java 2007-11-21 17:00:22 UTC (rev 1911)
@@ -1,601 +1,636 @@
-/*
- * IzPack - Copyright 2001-2007 Julien Ponge, All Rights Reserved.
- *
- * https://izpack.github.io/
- * http://developer.berlios.de/projects/izpack/
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-package com.izforge.izpack.panels;
-
-import java.awt.Component;
-import java.awt.Dimension;
-import java.awt.GridBagConstraints;
-import java.awt.GridBagLayout;
-import java.awt.Insets;
-import java.awt.event.ItemEvent;
-import java.awt.event.ItemListener;
-import java.util.Collections;
-import java.util.Comparator;
-import java.util.HashMap;
-import java.util.Iterator;
-import java.util.Set;
-import java.util.List;
-import java.util.HashSet;
-
-import javax.swing.AbstractCellEditor;
-import javax.swing.BorderFactory;
-import javax.swing.ButtonGroup;
-import javax.swing.JRadioButton;
-import javax.swing.JScrollPane;
-import javax.swing.JTable;
-import javax.swing.ListSelectionModel;
-import javax.swing.JTextPane;
-import javax.swing.border.EmptyBorder;
-import javax.swing.border.TitledBorder;
-import javax.swing.event.ListSelectionEvent;
-import javax.swing.event.ListSelectionListener;
-import javax.swing.table.DefaultTableModel;
-import javax.swing.table.TableCellEditor;
-import javax.swing.table.TableCellRenderer;
-import javax.swing.table.TableColumnModel;
-import javax.swing.table.TableModel;
-
-import net.n3.nanoxml.XMLElement;
-
-import com.izforge.izpack.Pack;
-import com.izforge.izpack.installer.InstallData;
-import com.izforge.izpack.installer.InstallerFrame;
-import com.izforge.izpack.installer.IzPanel;
-import com.izforge.izpack.util.Debug;
-import com.izforge.izpack.util.AbstractUIHandler;
-import com.izforge.izpack.util.OsConstraint;
-
-import java.util.ArrayList;
-import java.net.URLDecoder;
-import java.io.UnsupportedEncodingException;
-
-
-/**
- * A panel which displays the available installGroups found on the packs to
- * allow the user to select a subset of the packs based on the pack
- * installGroups attribute. This panel will be skipped if there are no
- * pack elements with an installGroups attribute.
- *
- * @author Scott.Stark at jboss.org
- * @version $Revision: 1.1.1.1 $
- */
-public class InstallationGroupPanel extends IzPanel
- implements ListSelectionListener
-{
- private static final long serialVersionUID = 1L;
-
- /** HashMap<String, Pack> of the InstallData.availablePacks */
- private HashMap packsByName;
- private TableModel groupTableModel;
- private JTextPane descriptionField;
- private JScrollPane groupScrollPane;
- private JTable groupsTable;
- private GroupData[] rows;
- private int selectedGroup = -1;
-
- public InstallationGroupPanel(InstallerFrame parent, InstallData idata)
- {
- super(parent, idata);
- buildLayout();
- }
-
- /**
- * If there are no packs with an installGroups attribute, this panel is
- * skipped. Otherwise, the unique installGroups are displayed in a table.
- */
- public void panelActivate()
- {
- // Set/restore availablePacks from allPacks; consider OS constraints
- idata.availablePacks = new ArrayList();
- for (Iterator i = idata.allPacks.iterator(); i.hasNext(); ) {
- Pack p = (Pack)i.next();
- if (OsConstraint.oneMatchesCurrentSystem(p.osConstraints)) idata.availablePacks.add(p);
- }
-
- Debug.trace("InstallationGroupPanel.panelActivate, selectedGroup="+selectedGroup);
- // If there are no groups, skip this panel
- HashMap installGroups = getInstallGroups(idata);
- if (installGroups.size() == 0)
- {
- super.askQuestion("Skip InstallGroup selection",
- "Skip InstallGroup selection", AbstractUIHandler.CHOICES_YES_NO);
- parent.skipPanel();
- return;
- }
-
- // Build the table model from the unique groups
- groupTableModel = getModel(installGroups);
- groupsTable.setModel(groupTableModel);
- TableColumnModel tcm = groupsTable.getColumnModel();
-
- // renders the radio buttons and adjusts their state
- TableCellRenderer radioButtonRenderer = new TableCellRenderer() {
- public Component getTableCellRendererComponent(JTable table, Object value,
- boolean isSelected, boolean hasFocus,
- int row, int column) {
- if (value==null) return null;
-
- int selectedRow = table.getSelectedRow();
-
- if (selectedRow != -1) {
- JRadioButton selectedButton = (JRadioButton)table.getValueAt(selectedRow, 0);
- if (!selectedButton.isSelected()) {
- selectedButton.doClick();
- }
- }
-
- JRadioButton button = (JRadioButton) value;
- button.setForeground(isSelected ?
- table.getSelectionForeground() : table.getForeground());
- button.setBackground(isSelected ?
- table.getSelectionBackground() : table.getBackground());
-
- // long millis = System.currentTimeMillis() % 100000;
- // System.out.printf("%1$5d: row: %2$d; isSelected: %3$5b; buttonSelected: %4$5b; selectedRow: %5$d%n", millis, row, isSelected, button.isSelected(), selectedRow);
-
- return button;
- }
- };
- tcm.getColumn(0).setCellRenderer(radioButtonRenderer);
-
- //groupsTable.setColumnSelectionAllowed(false);
- //groupsTable.setRowSelectionAllowed(true);
- groupsTable.setSelectionMode(ListSelectionModel.SINGLE_SELECTION);
- groupsTable.getSelectionModel().addListSelectionListener (this);
- groupsTable.setBorder(BorderFactory.createEmptyBorder(0, 2, 0, 2));
- groupsTable.setIntercellSpacing(new Dimension(0, 0));
- groupsTable.setShowGrid(false);
- if( selectedGroup >= 0 )
- {
- groupsTable.getSelectionModel().setSelectionInterval(selectedGroup, selectedGroup);
- descriptionField.setText(rows[selectedGroup].description);
- }
- else
- {
- descriptionField.setText(rows[0].description);
- }
- }
-
- /**
- * Remove all packs from the InstallData availablePacks and selectedPacks
- * that do not list the selected installation group. Packs without any
- * installGroups are always included.
- */
- public void panelDeactivate()
- {
-
- Debug.trace("InstallationGroupPanel.panelDeactivate, selectedGroup="+selectedGroup);
- if( selectedGroup >= 0 )
- {
- removeUnusedPacks();
- GroupData group = this.rows[selectedGroup];
- idata.setVariable("INSTALL_GROUP", group.name);
- Debug.trace("Added variable INSTALL_GROUP="+group.name);
- }
- }
-
- /**
- * There needs to be a valid selectedGroup to go to the next panel
- * @return true if selectedGroup >= 0, false otherwise
- */
- public boolean isValidated()
- {
- Debug.trace("InstallationGroupPanel.isValidated, selectedGroup="+selectedGroup);
- return selectedGroup >= 0;
- }
-
- /**
- * Update the current selected install group index.
- * @param e
- */
- public void valueChanged(ListSelectionEvent e)
- {
- Debug.trace("valueChanged: " + e);
- if (e.getValueIsAdjusting() == false)
- {
- ListSelectionModel lsm = (ListSelectionModel) e.getSource();
- if( lsm.isSelectionEmpty() )
- {
- descriptionField.setText("");
- }
- else
- {
- selectedGroup = lsm.getMinSelectionIndex();
- if( selectedGroup >= 0 )
- {
- GroupData data = rows[selectedGroup];
- descriptionField.setText(data.description);
- ((JRadioButton)groupTableModel.getValueAt(selectedGroup, 0)).setSelected(true);
- }
- Debug.trace("selectedGroup set to: "+selectedGroup);
- }
- }
- }
-
- /* Add the installation group to pack mappings
- * @see com.izforge.izpack.installer.IzPanel#makeXMLData(net.n3.nanoxml.XMLElement)
- */
- public void makeXMLData(XMLElement panelRoot)
- {
- InstallationGroupPanelAutomationHelper helper = new InstallationGroupPanelAutomationHelper();
- idata.setAttribute("GroupData", rows);
- idata.setAttribute("packsByName", packsByName);
- helper.makeXMLData(idata, panelRoot);
- }
-
- /**
- * Create the panel ui.
- */
- protected void buildLayout()
- {
- GridBagConstraints gridBagConstraints;
-
- descriptionField = new JTextPane();
- groupScrollPane = new JScrollPane();
- groupsTable = new JTable();
-
- setLayout(new GridBagLayout());
-
- descriptionField.setMargin(new Insets(2, 2, 2, 2));
- descriptionField.setAlignmentX(LEFT_ALIGNMENT);
- descriptionField.setCaretPosition(0);
- descriptionField.setEditable(false);
- descriptionField.setOpaque(false);
- descriptionField.setText("<b>Install group description text</b>");
- descriptionField.setContentType("text/html");
- descriptionField.setBorder(new TitledBorder(idata.langpack.getString("PacksPanel.description")));
- gridBagConstraints = new java.awt.GridBagConstraints();
- gridBagConstraints.gridy = 2;
- gridBagConstraints.fill = java.awt.GridBagConstraints.BOTH;
- gridBagConstraints.weightx = 1.0;
- gridBagConstraints.weighty = 0.3;
- add(descriptionField, gridBagConstraints);
-
- groupScrollPane.setBorder(new EmptyBorder(1, 1, 1, 1));
- groupScrollPane.setViewportView(groupsTable);
-
- gridBagConstraints = new java.awt.GridBagConstraints();
- gridBagConstraints.fill = java.awt.GridBagConstraints.BOTH;
- gridBagConstraints.weightx = 1.0;
- gridBagConstraints.weighty = 1.0;
- add(groupScrollPane, gridBagConstraints);
- }
-
- protected void removeUnusedPacks()
- {
- GroupData data = rows[selectedGroup];
- Debug.trace("InstallationGroupPanel.removeUnusedPacks, GroupData="+data.name);
-
- // Now remove the packs not in groupPackNames
- Iterator iter = idata.availablePacks.iterator();
- while( iter.hasNext() )
- {
- Pack p = (Pack) iter.next();
-
- //reverse dependencies must be reset in case the user is going
- //back and forth between the group selection panel and the packs selection panel
- p.revDependencies = null;
-
- if( data.packNames.contains(p.name) == false )
- {
- iter.remove();
- Debug.trace("Removed AvailablePack: "+p.name);
- }
- }
-
- idata.selectedPacks.clear();
- if (!"no".equals(idata.getVariable("InstallationGroupPanel.selectPacks"))) {
- idata.selectedPacks.addAll(idata.availablePacks);
- } else {
- for (Iterator i = idata.availablePacks.iterator(); i.hasNext(); ) {
- Pack p = (Pack)i.next();
- if (p.preselected) idata.selectedPacks.add(p);
- }
- }
- }
- protected void addDependents(Pack p, HashMap packsByName, GroupData data)
- {
- data.packNames.add(p.name);
- data.size += p.nbytes;
- Debug.trace("addDependents, added pack: "+p.name);
- if( p.dependencies == null || p.dependencies.size() == 0 )
- return;
-
- Iterator iter = p.dependencies.iterator();
- Debug.trace(p.name+" dependencies: "+p.dependencies);
- while( iter.hasNext() )
- {
- String dependent = (String) iter.next();
- if( data.packNames.contains(dependent) == false )
- {
- Debug.trace("Need dependent: "+dependent);
- Pack dependentPack = (Pack) packsByName.get(dependent);
- addDependents(dependentPack, packsByName, data);
- }
- }
- }
-
- /**
- * Build the set of unique installGroups data. The GroupData description
- * is taken from the InstallationGroupPanel.description.[name] property
- * where [name] is the installGroup name. The GroupData size is built
- * from the Pack.nbytes sum.
- *
- * @param idata - the panel install data
- * @return HashMap<String, GroupData> of unique install group names
- */
- protected HashMap getInstallGroups(InstallData idata)
- {
- /* First create a packsByName<String, Pack> of all packs and identify
- the unique install group names.
- */
- packsByName = new HashMap();
- HashMap installGroups = new HashMap();
- for (int n = 0; n < idata.availablePacks.size(); n++)
- {
- Pack p = (Pack) idata.availablePacks.get(n);
- packsByName.put(p.name, p);
- Set groups = p.installGroups;
- Iterator iter = groups.iterator();
- Debug.trace("Pack: "+p.name+", installGroups: "+groups);
- while (iter.hasNext())
- {
- String group = (String) iter.next();
- GroupData data = (GroupData) installGroups.get(group);
- if (data == null)
- {
- String description = getGroupDescription(group);
- String sortKey = getGroupSortKey(group);
- data = new GroupData(group, description, sortKey);
- installGroups.put(group, data);
- }
- }
- }
- Debug.trace("Found installGroups: " + installGroups.keySet());
-
- /* Build up a set of the packs to include in the installation by finding
- all packs in the selected group, and then include their dependencies.
- */
- Iterator gditer = installGroups.values().iterator();
- while( gditer.hasNext() )
- {
- GroupData data = (GroupData) gditer.next();
- Debug.trace("Adding dependents for: "+data.name);
- Iterator iter = idata.availablePacks.iterator();
- while( iter.hasNext() )
- {
- Pack p = (Pack) iter.next();
- Set groups = p.installGroups;
- if( groups.size() == 0 || groups.contains(data.name) == true )
- {
- // The pack may have already been added while traversing dependencies
- if( data.packNames.contains(p.name) == false )
- addDependents(p, packsByName, data);
- }
- }
- Debug.trace("Completed dependents for: "+data);
- if( Debug.tracing() )
- Debug.trace(data);
- }
-
- return installGroups;
- }
-
- /**
- * Look for a key = InstallationGroupPanel.description.[group] entry:
- * first using idata.langpack.getString(key+".html")
- * next using idata.langpack.getString(key)
- * next using idata.getVariable(key)
- * lastly, defaulting to group + " installation"
- * @param group - the installation group name
- * @return the group description
- */
- protected String getGroupDescription(String group)
- {
- String description = null;
- String key = "InstallationGroupPanel.description." + group;
- if( idata.langpack != null )
- {
- String htmlKey = key+".html";
- String html = idata.langpack.getString(htmlKey);
- // This will equal the key if there is no entry
- if( htmlKey.equalsIgnoreCase(html) )
- description = idata.langpack.getString(key);
- else
- description = html;
- }
- if (description == null || key.equalsIgnoreCase(description))
- description = idata.getVariable(key);
- if (description == null)
- description = group + " installation";
- try
- {
- description = URLDecoder.decode(description, "UTF-8");
- }
- catch (UnsupportedEncodingException e)
- {
- emitWarning("Failed to convert description", e.getMessage());
- }
-
- return description;
- }
-
- /**
- * Look for a key = InstallationGroupPanel.sortKey.[group] entry:
- * by using idata.getVariable(key)
- * if this variable is not defined, defaults to group
- * @param group - the installation group name
- * @return the group sortkey
- */
- protected String getGroupSortKey(String group)
- {
- String key = "InstallationGroupPanel.sortKey." + group;
- String sortKey = idata.getVariable(key);
- if (sortKey == null)
- sortKey = group;
- try
- {
- sortKey = URLDecoder.decode(sortKey, "UTF-8");
- }
- catch (UnsupportedEncodingException e)
- {
- emitWarning("Failed to convert sortKey", e.getMessage());
- }
-
- return sortKey;
- }
-
- protected TableModel getModel(HashMap groupData)
- {
- String c1 = parent.langpack.getString("InstallationGroupPanel.colNameSelected");
- String c2 = parent.langpack.getString("InstallationGroupPanel.colNameInstallType");
- String c3 = parent.langpack.getString("InstallationGroupPanel.colNameSize");
- String[] columns = {c1, c2, c3};
- DefaultTableModel model = new DefaultTableModel (columns, 0)
- {
- public boolean isCellEditable (int row, int column)
- {
- return false;
- }
- };
- rows = new GroupData[groupData.size()];
- // The name of the group to select if there is no current selection
- String defaultGroup = idata.getVariable("InstallationGroupPanel.defaultGroup");
- Debug.trace("InstallationGroupPanel.defaultGroup="+defaultGroup+", selectedGroup="+selectedGroup);
- List values = new ArrayList(groupData.values());
- Collections.sort(values, new Comparator()
- {
- public int compare(Object o1, Object o2)
- {
- GroupData g1 = (GroupData) o1;
- GroupData g2 = (GroupData) o2;
-
- if (g1.sortKey == null || g2.sortKey==null)
- {
- return 0;
- }
-
- return g1.sortKey.compareTo(g2.sortKey);
- }
- });
-
- Iterator iter = values.iterator();
- ButtonGroup buttonGroup = new ButtonGroup();
- boolean madeSelection = false;
- int count = 0;
- while (iter.hasNext())
- {
- GroupData gd = (GroupData) iter.next();
- rows[count] = gd;
- Debug.trace("Creating button#"+count+", group="+gd.name);
- JRadioButton btn = new JRadioButton(gd.name);
- if( selectedGroup == count )
- {
- btn.setSelected(true);
- Debug.trace("Selected button#"+count);
- }
- else if ( selectedGroup < 0 && madeSelection == false )
- {
- if( defaultGroup != null )
- {
- if( defaultGroup.equals(gd.name) )
- madeSelection = true;
- }
- else if( count == 0 )
- madeSelection = true;
- if( madeSelection )
- {
- btn.setSelected(true);
- Debug.trace("Selected button#"+count);
- selectedGroup = count;
- }
- }
- else
- {
- btn.setSelected(false);
- }
- buttonGroup.add(btn);
- String sizeText = gd.getSizeString();
- Object[] data = { btn, gd.description, sizeText};
- model.addRow(data);
- count ++;
- }
- return model;
- }
-
- protected static class GroupData
- {
- static final long ONEK = 1024;
- static final long ONEM = 1024 * 1024;
- static final long ONEG = 1024 * 1024 * 1024;
-
- String name;
- String description;
- String sortKey;
- long size;
- HashSet packNames = new HashSet();
-
- GroupData(String name, String description, String sortKey)
- {
- this.name = name;
- this.description = description;
- this.sortKey = sortKey;
- }
-
- String getSizeString()
- {
- String s;
- if (size < ONEK)
- {
- s = size + " bytes";
- }
- else if (size < ONEM)
- {
- s = size / ONEK + " KBytes";
- }
- else if (size < ONEG)
- {
- s = size / ONEM + " MBytes";
- }
- else
- {
- s = size / ONEG + " GBytes";
- }
- return s;
- }
- public String toString()
- {
- StringBuffer tmp = new StringBuffer("GroupData(");
- tmp.append(name);
- tmp.append("){description=");
- tmp.append(description);
- tmp.append(", sortKey=");
- tmp.append(sortKey);
- tmp.append(", size=");
- tmp.append(size);
- tmp.append(", sizeString=");
- tmp.append(getSizeString());
- tmp.append(", packNames=");
- tmp.append(packNames);
- tmp.append("}");
- return tmp.toString();
- }
- }
-
-}
+/*
+ * IzPack - Copyright 2001-2007 Julien Ponge, All Rights Reserved.
+ *
+ * https://izpack.github.io/
+ * http://developer.berlios.de/projects/izpack/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.izforge.izpack.panels;
+
+import java.awt.Component;
+import java.awt.Dimension;
+import java.awt.GridBagConstraints;
+import java.awt.GridBagLayout;
+import java.awt.Insets;
+import java.io.UnsupportedEncodingException;
+import java.net.URLDecoder;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Set;
+
+import javax.swing.BorderFactory;
+import javax.swing.ButtonGroup;
+import javax.swing.JRadioButton;
+import javax.swing.JScrollPane;
+import javax.swing.JTable;
+import javax.swing.JTextPane;
+import javax.swing.ListSelectionModel;
+import javax.swing.border.EmptyBorder;
+import javax.swing.border.TitledBorder;
+import javax.swing.event.ListSelectionEvent;
+import javax.swing.event.ListSelectionListener;
+import javax.swing.table.DefaultTableModel;
+import javax.swing.table.TableCellRenderer;
+import javax.swing.table.TableColumnModel;
+import javax.swing.table.TableModel;
+
+import net.n3.nanoxml.XMLElement;
+
+import com.izforge.izpack.Pack;
+import com.izforge.izpack.installer.InstallData;
+import com.izforge.izpack.installer.InstallerFrame;
+import com.izforge.izpack.installer.IzPanel;
+import com.izforge.izpack.util.AbstractUIHandler;
+import com.izforge.izpack.util.Debug;
+import com.izforge.izpack.util.OsConstraint;
+
+
+/**
+ * A panel which displays the available installGroups found on the packs to
+ * allow the user to select a subset of the packs based on the pack
+ * installGroups attribute. This panel will be skipped if there are no
+ * pack elements with an installGroups attribute.
+ *
+ * @author Scott.Stark at jboss.org
+ * @version $Revision: 1.1.1.1 $
+ */
+public class InstallationGroupPanel extends IzPanel
+ implements ListSelectionListener
+{
+ private static final long serialVersionUID = 1L;
+
+ /** HashMap<String, Pack> of the InstallData.availablePacks */
+ private HashMap packsByName;
+ private TableModel groupTableModel;
+ private JTextPane descriptionField;
+ private JScrollPane groupScrollPane;
+ private JTable groupsTable;
+ private GroupData[] rows;
+ private int selectedGroup = -1;
+
+ public InstallationGroupPanel(InstallerFrame parent, InstallData idata)
+ {
+ super(parent, idata);
+ buildLayout();
+ }
+
+ /**
+ * If there are no packs with an installGroups attribute, this panel is
+ * skipped. Otherwise, the unique installGroups are displayed in a table.
+ */
+ public void panelActivate()
+ {
+ // Set/restore availablePacks from allPacks; consider OS constraints
+ idata.availablePacks = new ArrayList();
+ for (Iterator i = idata.allPacks.iterator(); i.hasNext(); ) {
+ Pack p = (Pack)i.next();
+ if (OsConstraint.oneMatchesCurrentSystem(p.osConstraints)) idata.availablePacks.add(p);
+ }
+
+ Debug.trace("InstallationGroupPanel.panelActivate, selectedGroup="+selectedGroup);
+ // If there are no groups, skip this panel
+ HashMap installGroups = getInstallGroups(idata);
+ if (installGroups.size() == 0)
+ {
+ super.askQuestion("Skip InstallGroup selection",
+ "Skip InstallGroup selection", AbstractUIHandler.CHOICES_YES_NO);
+ parent.skipPanel();
+ return;
+ }
+
+ // Build the table model from the unique groups
+ groupTableModel = getModel(installGroups);
+ groupsTable.setModel(groupTableModel);
+ TableColumnModel tcm = groupsTable.getColumnModel();
+
+ // renders the radio buttons and adjusts their state
+ TableCellRenderer radioButtonRenderer = new TableCellRenderer() {
+ public Component getTableCellRendererComponent(JTable table, Object value,
+ boolean isSelected, boolean hasFocus,
+ int row, int column) {
+ if (value==null) return null;
+
+ int selectedRow = table.getSelectedRow();
+
+ if (selectedRow != -1) {
+ JRadioButton selectedButton = (JRadioButton)table.getValueAt(selectedRow, 0);
+ if (!selectedButton.isSelected()) {
+ selectedButton.doClick();
+ }
+ }
+
+ JRadioButton button = (JRadioButton) value;
+ button.setForeground(isSelected ?
+ table.getSelectionForeground() : table.getForeground());
+ button.setBackground(isSelected ?
+ table.getSelectionBackground() : table.getBackground());
+
+ // long millis = System.currentTimeMillis() % 100000;
+ // System.out.printf("%1$5d: row: %2$d; isSelected: %3$5b; buttonSelected: %4$5b; selectedRow: %5$d%n", millis, row, isSelected, button.isSelected(), selectedRow);
+
+ return button;
+ }
+ };
+ tcm.getColumn(0).setCellRenderer(radioButtonRenderer);
+
+ //groupsTable.setColumnSelectionAllowed(false);
+ //groupsTable.setRowSelectionAllowed(true);
+ groupsTable.setSelectionMode(ListSelectionModel.SINGLE_SELECTION);
+ groupsTable.getSelectionModel().addListSelectionListener (this);
+ groupsTable.setBorder(BorderFactory.createEmptyBorder(0, 2, 0, 2));
+ groupsTable.setIntercellSpacing(new Dimension(0, 0));
+ groupsTable.setShowGrid(false);
+ if( selectedGroup >= 0 )
+ {
+ groupsTable.getSelectionModel().setSelectionInterval(selectedGroup, selectedGroup);
+ descriptionField.setText(rows[selectedGroup].description);
+ }
+ else
+ {
+ descriptionField.setText(rows[0].description);
+ }
+ }
+
+ /**
+ * Remove all packs from the InstallData availablePacks and selectedPacks
+ * that do not list the selected installation group. Packs without any
+ * installGroups are always included.
+ */
+ public void panelDeactivate()
+ {
+
+ Debug.trace("InstallationGroupPanel.panelDeactivate, selectedGroup="+selectedGroup);
+ if( selectedGroup >= 0 )
+ {
+ removeUnusedPacks();
+ GroupData group = this.rows[selectedGroup];
+ idata.setVariable("INSTALL_GROUP", group.name);
+ Debug.trace("Added variable INSTALL_GROUP="+group.name);
+ }
+ }
+
+ /**
+ * There needs to be a valid selectedGroup to go to the next panel
+ * @return true if selectedGroup >= 0, false otherwise
+ */
+ public boolean isValidated()
+ {
+ Debug.trace("InstallationGroupPanel.isValidated, selectedGroup="+selectedGroup);
+ return selectedGroup >= 0;
+ }
+
+ /**
+ * Update the current selected install group index.
+ * @param e
+ */
+ public void valueChanged(ListSelectionEvent e)
+ {
+ Debug.trace("valueChanged: " + e);
+ if (e.getValueIsAdjusting() == false)
+ {
+ ListSelectionModel lsm = (ListSelectionModel) e.getSource();
+ if( lsm.isSelectionEmpty() )
+ {
+ descriptionField.setText("");
+ }
+ else
+ {
+ selectedGroup = lsm.getMinSelectionIndex();
+ if( selectedGroup >= 0 )
+ {
+ GroupData data = rows[selectedGroup];
+ descriptionField.setText(data.description);
+ ((JRadioButton)groupTableModel.getValueAt(selectedGroup, 0)).setSelected(true);
+ }
+ Debug.trace("selectedGroup set to: "+selectedGroup);
+ }
+ }
+ }
+
+ /* Add the installation group to pack mappings
+ * @see com.izforge.izpack.installer.IzPanel#makeXMLData(net.n3.nanoxml.XMLElement)
+ */
+ public void makeXMLData(XMLElement panelRoot)
+ {
+ InstallationGroupPanelAutomationHelper helper = new InstallationGroupPanelAutomationHelper();
+ idata.setAttribute("GroupData", rows);
+ idata.setAttribute("packsByName", packsByName);
+ helper.makeXMLData(idata, panelRoot);
+ }
+
+ /**
+ * Create the panel ui.
+ */
+ protected void buildLayout()
+ {
+ GridBagConstraints gridBagConstraints;
+
+ descriptionField = new JTextPane();
+ groupScrollPane = new JScrollPane();
+ groupsTable = new JTable();
+
+ setLayout(new GridBagLayout());
+
+ descriptionField.setMargin(new Insets(2, 2, 2, 2));
+ descriptionField.setAlignmentX(LEFT_ALIGNMENT);
+ descriptionField.setCaretPosition(0);
+ descriptionField.setEditable(false);
+ descriptionField.setOpaque(false);
+ descriptionField.setText("<b>Install group description text</b>");
+ descriptionField.setContentType("text/html");
+ descriptionField.setBorder(new TitledBorder(idata.langpack.getString("PacksPanel.description")));
+ gridBagConstraints = new java.awt.GridBagConstraints();
+ gridBagConstraints.gridy = 2;
+ gridBagConstraints.fill = java.awt.GridBagConstraints.BOTH;
+ gridBagConstraints.weightx = 1.0;
+ gridBagConstraints.weighty = 0.3;
+ add(descriptionField, gridBagConstraints);
+
+ groupScrollPane.setBorder(new EmptyBorder(1, 1, 1, 1));
+ groupScrollPane.setViewportView(groupsTable);
+
+ gridBagConstraints = new java.awt.GridBagConstraints();
+ gridBagConstraints.fill = java.awt.GridBagConstraints.BOTH;
+ gridBagConstraints.weightx = 1.0;
+ gridBagConstraints.weighty = 1.0;
+ add(groupScrollPane, gridBagConstraints);
+ }
+
+ protected void removeUnusedPacks()
+ {
+ GroupData data = rows[selectedGroup];
+ Debug.trace("InstallationGroupPanel.removeUnusedPacks, GroupData="+data.name);
+
+ // Now remove the packs not in groupPackNames
+ Iterator iter = idata.availablePacks.iterator();
+ while( iter.hasNext() )
+ {
+ Pack p = (Pack) iter.next();
+
+ //reverse dependencies must be reset in case the user is going
+ //back and forth between the group selection panel and the packs selection panel
+ p.revDependencies = null;
+
+ if( data.packNames.contains(p.name) == false )
+ {
+ iter.remove();
+ Debug.trace("Removed AvailablePack: "+p.name);
+ }
+ }
+
+ idata.selectedPacks.clear();
+ if (!"no".equals(idata.getVariable("InstallationGroupPanel.selectPacks"))) {
+ idata.selectedPacks.addAll(idata.availablePacks);
+ } else {
+ for (Iterator i = idata.availablePacks.iterator(); i.hasNext(); ) {
+ Pack p = (Pack)i.next();
+ if (p.preselected) idata.selectedPacks.add(p);
+ }
+ }
+ }
+ protected void addDependents(Pack p, HashMap packsByName, GroupData data)
+ {
+ data.packNames.add(p.name);
+ data.size += p.nbytes;
+ Debug.trace("addDependents, added pack: "+p.name);
+ if( p.dependencies == null || p.dependencies.size() == 0 )
+ return;
+
+ Iterator iter = p.dependencies.iterator();
+ Debug.trace(p.name+" dependencies: "+p.dependencies);
+ while( iter.hasNext() )
+ {
+ String dependent = (String) iter.next();
+ if( data.packNames.contains(dependent) == false )
+ {
+ Debug.trace("Need dependent: "+dependent);
+ Pack dependentPack = (Pack) packsByName.get(dependent);
+ addDependents(dependentPack, packsByName, data);
+ }
+ }
+ }
+
+ /**
+ * Build the set of unique installGroups data. The GroupData description
+ * is taken from the InstallationGroupPanel.description.[name] property
+ * where [name] is the installGroup name. The GroupData size is built
+ * from the Pack.nbytes sum.
+ *
+ * @param idata - the panel install data
+ * @return HashMap<String, GroupData> of unique install group names
+ */
+ protected HashMap getInstallGroups(InstallData idata)
+ {
+ /* First create a packsByName<String, Pack> of all packs and identify
+ the unique install group names.
+ */
+ packsByName = new HashMap();
+ HashMap installGroups = new HashMap();
+ for (int n = 0; n < idata.availablePacks.size(); n++)
+ {
+ Pack p = (Pack) idata.availablePacks.get(n);
+ packsByName.put(p.name, p);
+ Set groups = p.installGroups;
+ Iterator iter = groups.iterator();
+ Debug.trace("Pack: "+p.name+", installGroups: "+groups);
+ while (iter.hasNext())
+ {
+ String group = (String) iter.next();
+ GroupData data = (GroupData) installGroups.get(group);
+ if (data == null)
+ {
+ String description = getGroupDescription(group);
+ String sortKey = getGroupSortKey(group);
+ data = new GroupData(group, description, sortKey);
+ installGroups.put(group, data);
+ }
+ }
+ }
+ Debug.trace("Found installGroups: " + installGroups.keySet());
+
+ /* Build up a set of the packs to include in the installation by finding
+ all packs in the selected group, and then include their dependencies.
+ */
+ Iterator gditer = installGroups.values().iterator();
+ while( gditer.hasNext() )
+ {
+ GroupData data = (GroupData) gditer.next();
+ Debug.trace("Adding dependents for: "+data.name);
+ Iterator iter = idata.availablePacks.iterator();
+ while( iter.hasNext() )
+ {
+ Pack p = (Pack) iter.next();
+ Set groups = p.installGroups;
+ if( groups.size() == 0 || groups.contains(data.name) == true )
+ {
+ // The pack may have already been added while traversing dependencies
+ if( data.packNames.contains(p.name) == false )
+ addDependents(p, packsByName, data);
+ }
+ }
+ Debug.trace("Completed dependents for: "+data);
+ if( Debug.tracing() )
+ Debug.trace(data);
+ }
+
+ return installGroups;
+ }
+
+ /**
+ * Look for a key = InstallationGroupPanel.description.[group] entry:
+ * first using idata.langpack.getString(key+".html")
+ * next using idata.langpack.getString(key)
+ * next using idata.getVariable(key)
+ * lastly, defaulting to group + " installation"
+ * @param group - the installation group name
+ * @return the group description
+ */
+ protected String getGroupDescription(String group)
+ {
+ String description = null;
+ String key = "InstallationGroupPanel.description." + group;
+ if( idata.langpack != null )
+ {
+ String htmlKey = key+".html";
+ String html = idata.langpack.getString(htmlKey);
+ // This will equal the key if there is no entry
+ if( htmlKey.equalsIgnoreCase(html) )
+ description = idata.langpack.getString(key);
+ else
+ description = html;
+ }
+ if (description == null || key.equalsIgnoreCase(description))
+ description = idata.getVariable(key);
+ if (description == null)
+ description = group + " installation";
+ try
+ {
+ description = URLDecoder.decode(description, "UTF-8");
+ }
+ catch (UnsupportedEncodingException e)
+ {
+ emitWarning("Failed to convert description", e.getMessage());
+ }
+
+ return description;
+ }
+
+ /**
+ * Look for a key = InstallationGroupPanel.sortKey.[group] entry:
+ * by using idata.getVariable(key)
+ * if this variable is not defined, defaults to group
+ * @param group - the installation group name
+ * @return the group sortkey
+ */
+ protected String getGroupSortKey(String group)
+ {
+ String key = "InstallationGroupPanel.sortKey." + group;
+ String sortKey = idata.getVariable(key);
+ if (sortKey == null)
+ sortKey = group;
+ try
+ {
+ sortKey = URLDecoder.decode(sortKey, "UTF-8");
+ }
+ catch (UnsupportedEncodingException e)
+ {
+ emitWarning("Failed to convert sortKey", e.getMessage());
+ }
+
+ return sortKey;
+ }
+
+
+ /**
+ * Look for a key = InstallationGroupPanel.group.[group] entry:
+ * first using idata.langpackgetString(key+".html")
+ * next using idata.langpack.getString(key)
+ * next using idata.getVariable(key)
+ * lastly, defaulting to group
+ * @param group - the installation group name
+ * @return the localized group name
+ */
+ protected String getLocalizedGroupName(String group)
+ {
+ String gname = null;
+ String key = "InstallationGroupPanel.group." + group;
+ if( idata.langpack != null )
+ {
+ String htmlKey = key+".html";
+ String html = idata.langpack.getString(htmlKey);
+ // This will equal the key if there is no entry
+ if( htmlKey.equalsIgnoreCase(html) )
+ gname = idata.langpack.getString(key);
+ else
+ gname = html;
+ }
+ if (gname == null || key.equalsIgnoreCase(gname))
+ gname = idata.getVariable(key);
+ if (gname == null)
+ gname = group;
+ try
+ {
+ gname = URLDecoder.decode(gname, "UTF-8");
+ }
+ catch (UnsupportedEncodingException e)
+ {
+ emitWarning("Failed to convert localized group name", e.getMessage());
+ }
+
+ return gname;
+ }
+
+ protected TableModel getModel(HashMap groupData)
+ {
+ String c1 = parent.langpack.getString("InstallationGroupPanel.colNameSelected");
+ String c2 = parent.langpack.getString("InstallationGroupPanel.colNameInstallType");
+ String c3 = parent.langpack.getString("InstallationGroupPanel.colNameSize");
+ String[] columns = {c1, c2, c3};
+ DefaultTableModel model = new DefaultTableModel (columns, 0)
+ {
+ public boolean isCellEditable (int row, int column)
+ {
+ return false;
+ }
+ };
+ rows = new GroupData[groupData.size()];
+ // The name of the group to select if there is no current selection
+ String defaultGroup = idata.getVariable("InstallationGroupPanel.defaultGroup");
+ Debug.trace("InstallationGroupPanel.defaultGroup="+defaultGroup+", selectedGroup="+selectedGroup);
+ List values = new ArrayList(groupData.values());
+ Collections.sort(values, new Comparator()
+ {
+ public int compare(Object o1, Object o2)
+ {
+ GroupData g1 = (GroupData) o1;
+ GroupData g2 = (GroupData) o2;
+
+ if (g1.sortKey == null || g2.sortKey==null)
+ {
+ return 0;
+ }
+
+ return g1.sortKey.compareTo(g2.sortKey);
+ }
+ });
+
+ Iterator iter = values.iterator();
+ ButtonGroup buttonGroup = new ButtonGroup();
+ boolean madeSelection = false;
+ int count = 0;
+ while (iter.hasNext())
+ {
+ GroupData gd = (GroupData) iter.next();
+ rows[count] = gd;
+ Debug.trace("Creating button#"+count+", group="+gd.name);
+ JRadioButton btn = new JRadioButton(getLocalizedGroupName(gd.name));
+ if( selectedGroup == count )
+ {
+ btn.setSelected(true);
+ Debug.trace("Selected button#"+count);
+ }
+ else if ( selectedGroup < 0 && madeSelection == false )
+ {
+ if( defaultGroup != null )
+ {
+ if( defaultGroup.equals(gd.name) )
+ madeSelection = true;
+ }
+ else if( count == 0 )
+ madeSelection = true;
+ if( madeSelection )
+ {
+ btn.setSelected(true);
+ Debug.trace("Selected button#"+count);
+ selectedGroup = count;
+ }
+ }
+ else
+ {
+ btn.setSelected(false);
+ }
+ buttonGroup.add(btn);
+ String sizeText = gd.getSizeString();
+ Object[] data = { btn, gd.description, sizeText};
+ model.addRow(data);
+ count ++;
+ }
+ return model;
+ }
+
+ protected static class GroupData
+ {
+ static final long ONEK = 1024;
+ static final long ONEM = 1024 * 1024;
+ static final long ONEG = 1024 * 1024 * 1024;
+
+ String name;
+ String description;
+ String sortKey;
+ long size;
+ HashSet packNames = new HashSet();
+
+ GroupData(String name, String description, String sortKey)
+ {
+ this.name = name;
+ this.description = description;
+ this.sortKey = sortKey;
+ }
+
+ String getSizeString()
+ {
+ String s;
+ if (size < ONEK)
+ {
+ s = size + " bytes";
+ }
+ else if (size < ONEM)
+ {
+ s = size / ONEK + " KBytes";
+ }
+ else if (size < ONEG)
+ {
+ s = size / ONEM + " MBytes";
+ }
+ else
+ {
+ s = size / ONEG + " GBytes";
+ }
+ return s;
+ }
+ public String toString()
+ {
+ StringBuffer tmp = new StringBuffer("GroupData(");
+ tmp.append(name);
+ tmp.append("){description=");
+ tmp.append(description);
+ tmp.append(", sortKey=");
+ tmp.append(sortKey);
+ tmp.append(", size=");
+ tmp.append(size);
+ tmp.append(", sizeString=");
+ tmp.append(getSizeString());
+ tmp.append(", packNames=");
+ tmp.append(packNames);
+ tmp.append("}");
+ return tmp.toString();
+ }
+ }
+
+}
Modified: izpack-src/trunk/src/lib/com/izforge/izpack/panels/ShortcutPanel.java
===================================================================
--- izpack-src/trunk/src/lib/com/izforge/izpack/panels/ShortcutPanel.java 2007-11-20 14:32:36 UTC (rev 1910)
+++ izpack-src/trunk/src/lib/com/izforge/izpack/panels/ShortcutPanel.java 2007-11-21 17:00:22 UTC (rev 1911)
@@ -920,15 +920,13 @@
continue;
}
- // TODO: write log info INFO.info( "Checking Condition for " +
- // shortcutSpec.getAttribute( SPEC_ATTRIBUTE_NAME ) );
+ Debug.log( "Checking Condition for " + shortcutSpec.getAttribute( SPEC_ATTRIBUTE_NAME ) );
if (!checkConditions(shortcutSpec))
{
continue;
}
- // TODO write log info INFO.info( "Checked Condition for " +
- // shortcutSpec.getAttribute( SPEC_ATTRIBUTE_NAME ) );
+ Debug.log( "Checked Condition for " + shortcutSpec.getAttribute( SPEC_ATTRIBUTE_NAME ) );
data = new ShortcutData();
data.name = shortcutSpec.getAttribute(SPEC_ATTRIBUTE_NAME);
Modified: izpack-src/trunk/src/lib/com/izforge/izpack/util/FileExecutor.java
===================================================================
--- izpack-src/trunk/src/lib/com/izforge/izpack/util/FileExecutor.java 2007-11-20 14:32:36 UTC (rev 1910)
+++ izpack-src/trunk/src/lib/com/izforge/izpack/util/FileExecutor.java 2007-11-21 17:00:22 UTC (rev 1911)
@@ -252,7 +252,7 @@
ExecutableFile efile = (ExecutableFile) efileIterator.next();
boolean deleteAfterwards = !efile.keepFile;
File file = new File(efile.path);
- Debug.trace("handeling executable file " + efile);
+ Debug.trace("handling executable file " + efile);
// skip file if not for current OS (it might not have been installed
// at all)
Modified: izpack-src/trunk/src/lib/com/izforge/izpack/util/OsVersion.java
===================================================================
--- izpack-src/trunk/src/lib/com/izforge/izpack/util/OsVersion.java 2007-11-20 14:32:36 UTC (rev 1910)
+++ izpack-src/trunk/src/lib/com/izforge/izpack/util/OsVersion.java 2007-11-21 17:00:22 UTC (rev 1911)
@@ -243,7 +243,7 @@
}
catch (IOException e)
{
- // TODO handle or ignore
+ Debug.log("Unable to get release file contents in 'getOsDetails'.");
}
}
}
More information about the izpack-changes
mailing list