We need you!

Icon

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

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The section Built-in Panel Types introduces the various panels available in IzPack. The usage of each is described, and the panels are listed by their class name (this is the name that must be used with the classname attribute). 

Attributes

AttributeDescriptionRequired
classnameThe class name of the panel. The attribute value class name is case-sensitive, meaning that if the case in the installation file differs from the case in the class file, the . The compiler will throw an IllegalArgumentException if the class can not be found.. Yes
idA unique identifier for a panel which can be used to reference this panel in userinput panel definitions.No
conditionThe id of a condition that has to evaluate to true in order for this panel to appear. If this attribute is not specified. the panel is always shown.No
jarThe jar file where the classes for this panel can be found. If this attribute is empty or unspecified, the classes for this panel must be merged using the <jar> tag.No
topBuffer

Represents the percentage of leftover vertical space to place on top of the components. Setting "topBuffer=0 is useful if you don't want your panel to be " prevents the panel from being moved up or down during dynamic validation (showing and hiding components within the same panel)layout creation.

If the rigid attribute is set to true, the topBuffer value represents the number of pixels to place on top of the components rather than the percentage of left over space.

Default: 25 

No
rigid

When set to "true", the topBuffer will represent a number of pixels rather than a percentage.

Default: false

No
allowClose

Determines whether confirmation is required when quitting the installer from this panel and panels defined before this panel. 

Set to "true" to allow the installer to be closed using the "Quit" or "Done" button without confirmation on this panel, but require confirmation on previous panels without this attribute. 

Set to "false" to prompt for confirmation when Quit or Done is pressed on this and previous panels without this attribute. 

If there is no "allowClose" attribute IzPack will exhibit its classic behavior, which is to prompt for confirmation until the files are copied unless the Previous and Next buttons are both disabled.

For example, to force confirmation when quitting from all but the last panel, specify allowClose="true" on the last and only the last panel, as seen in the following example.

Code Block
titleExample
languagexml
<panels>
  <panel classname="HTMLHelloPanel"/>
  <panel classname="HTMLInfoPanel"/>
  <panel classname="HTMLLicencePanel"/>
  <panel classname="TargetPanel"/>
  <panel classname="PacksPanel"/>
  <panel classname="InstallPanel"/>
  <panel classname="ShortcutPanel"/>
  <panel classname="SimpleFinishPanel" allowClose="true"/>
</panels>

Default: unspecified

Since: IzPack 5.0 RC5

No

Nested Elements 

Configuration

...

Specifies an optional help file for a panel. The contents of the help file is shown in a small window on the panel, when the user clicks on the Help button.

The help file text can contain text that is formated using HTML elements(<p>,<h1>,<ul>,<li>, etc.) to specify the format.

The button is only shown when a help for the language exists.

AttributeDescriptionRequired
iso3The ISO3 representation of the language in which the help is written.Yes
srcThe path where to the compiler will find the help file to displaybe displayed.Yes

Validator

Specifies an optional panel data validator. See the section Panel Data Validators.

Actions

Specifies one or more optional panel life-cycle actions.  See the section Panel Actions.

...

Code Block
titleA panel with help files in German and English.
languagehtml/xml
<panel classname="HelloPanel" id="hello"  condition="verbosemode">
  <help iso3="deu" src="HelloPanelHelp_deu.html" />
  <help iso3="eng" src="HelloPanelHelp_eng.html" />
</panel>

 

A basic typical selection of panels, including a conditional panel with a condition and a panel invoking custom panel code contained in a jar file, with a custom configuration providing parameters to the "finishPanel" class

Code Block
titleBasic selection of panels
languagehtml/xml
<panels>
    <panel classname="HelloPanel">
      <help iso3="deu" src="HelloPanelHelp_deu.html" />
      <help iso3="eng" src="HelloPanelHelp_eng.html" />        
    </panel>
    <panel classname="LicencePanel"/>
    <panel classname="TargetPanel"/>
    <panel classname="InstallPanel"/>
    <panel classname="UserInputPanel" id="myuserinput" condition="pack2selected" />
    <panel classname="FinishPanel" jar="MyFinishPanel.jar">
      <configuration>
        <param name="MyParam1" value="some value"/>
        <param name="MyParam2" value="some other value"/>
      </configuration>
    </panel>
</panels>

 

A installation file showing the <panels> section in context.

Code Block
titlePanel in the context of an installation specification
languagehtml/xml
<installation version="5.0"
              xmlns:izpack="http://izpack.org/schema/installation"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://izpack.org/schema/installation http://izpack.org/schema/5.0/izpack-installation-5.0.xsd">

  <info>
    <appname>Test</appname>
    <appversion>0.0</appversion>
    <appsubpath>myapp</appsubpath>
    <javaver   sion>1.6</javaversion>
  </info>
  <resources>
    <res id="InfoPanel.info" src="doc/readme.txt" parse="yes"/>
    <res id="LicencePanel.licence" src="legal/License.txt"/>
  </resources> 

  <guiprefs width="800" height="600" resizable="no">
    <splash>images/peas_load.gif</splash>
    <laf name="substance">
      <os family="windows" />
      <os family="unix" />
      <param name="variant" value="mist-silver" />
    </laf>
    <laf name="substance">
      <os family="mac" />
      <param name="variant" value="mist-aqua" />
    </laf>
   <modifier key="useHeadingPanel" value="yes" />
 </guiprefs>

 <panels>
   <panel classname="HelloPanel">
      <help iso3="deu" src="HelloPanelHelp_deu.html" />
      <help iso3="eng" src="HelloPanelHelp_eng.html" />        
   </panel>
   <panel classname="LicencePanel"/>
   <panel classname="TargetPanel"/>
   <panel classname="InstallPanel"/>
   <panel classname="UserInputPanel" id="myuserinput" condition="pack2selected" />
   <panel classname="FinishPanel" jar="MyFinishPanel.jar">
     <configuration>
        <param name="MyParam1" value="some value"/>
        <param name="MyParam2" value="some other value"/>
      </configuration>
   </panel>
  </panels>
  ...

</installation>

Internationalization

The following key suffixes can be translated:

  • headline
  • headinfo<number>

The built-in translation of these labels can be overridden in the following way:

  • Add custom translations to a IzPack resource CustomLangPack.xml_<ISO3>
  • The following translation keys and lookup order can be used:
    1. If a panel ID is defined:
      <panelId>.<subKey>
    2. If no panel ID is defined:
      <Fully_qualified_panel_classname>.<subkey>
Warning
titleChanges that might break existing IzPack 4 installers

The  order attribute of <panel> is no longer read (ignored) and can't therefore used as part of the translation key any longer.

For variant 2., the fully qualified classname must be used now, not just the simple one.

Example 1:

Code Block
titleinstall.xml
languagehtml/xml
<resources>
  <res id="CustomLangPack.xml_eng" src="i18n/CustomLangPack.xml_eng"/>
</resources>
 
<panels>
  <panel classname="TargetPanel"/>
</panels>
Code Block
titleCustomLangPack.xml_eng
languagehtml/xml
<langpack>
  <str id="com.izforge.izpack.panels.target.TargetPanel.headline" txt="Please select the installation directory"/>
</langpack>

Example 2:

Code Block
titleinstall.xml
languagehtml/xml
<resources>
  <res id="CustomLangPack.xml_eng" src="i18n/CustomLangPack.xml_eng"/>
</resources>
 
<panels>
  <panel classname="TargetPanel" id="target.panel"/>
</panels>
Code Block
titleCustomLangPack.xml_eng
languagehtml/xml
<langpack>
  <str id="target.panel.headline" txt="Please select the installation directory"/>
</langpack>