Creating your user interface

You can create your user interface using the GUI Builder tool.

To start the GUI Builder, use the following command:

     java com.ibm.as400.ui.tools.GUIBuilder [-plaf look and feel]

If you did not set your CLASSPATH environment variable to contain the Graphical Toolbox JAR files, then you will need to specify them on the command line using the classpath option. See Setting Up the Graphical Toolbox.

Options -plaf look and feel

The platform look and feel that you want. This option lets you override the default look and feel that is set based on the platform you are developing on, so you can preview your panels to see how they will look on different operating system platforms. The following look and feel values are accepted:

Windows^®
Metal
Motif

Currently, additional look and feel attributes that Swing 1.1 may support are not supported by the GUI Builder

Types of user interface resources

When you start the GUI Builder for the first time, you need to create a new PDML file. From the menu bar on the GUI Builder widow, select File --> New File. After you create your new PDML file, you can define any of the following types of UI resources that you want it to contain.

Panel: The fundamental resource type. It describes a rectangular area within which UI elements are arranged. The UI elements may consist of simple controls, such as radio buttons or text fields, images, animations, custom controls, or more sophisticated subpanels (see the following definitions for Split Pane, Deck Pane and Tabbed Pane). A panel may define the layout for a stand-alone window or dialog, or it may define one of the subpanels that is contained in another UI resource.
Menu: A popup window containing one or more selectable actions, each represented by a text string ("Cut", "Copy" and "Paste" are examples). You can define mnemonics and accelerator keys for each action, insert separators and cascading submenus, or define special checked or radio button menu items. A menu resource may be used as a stand-alone context menu, as a drop-down menu in a menu bar, or it may itself define the menu bar associated with a panel resource.
Toolbar: A window consisting of a series of push buttons, each representing a possible user action. Each button may contain text, an icon or both. You can define the toolbar as floatable, which lets the user drag the toolbar out of a panel and into a stand-alone window.
Property Sheet: A stand-alone window or dialog consisting of a tabbed panels and OK, Cancel, and Help buttons. Panel resources define the layout of each tabbed window.
Wizard: A stand-alone window or dialog consisting of a series of panels that are displayed to the user in a predefined sequence, with Back, Next, Cancel, Finish, and Help buttons. The wizard window may also display a list of tasks to the left of the panels which track the user's progress through the wizard.
Split Pane: A subpane consisting of two panels separated by a splitter bar. The panels may be arranged horizontally or vertically.
Tabbed Pane: A subpane that forms a tabbed control. This tabbed control can be placed inside of another panel, split pane, or deck pane.
Deck Pane: A subpane consisting of a collection of panels. Of these, only one panel can be displayed at a time. For example, at runtime the deck pane might change the panel which is displayed depending on a given user action.
String Table: A collection of string resources and their associated resource identifiers.

Generated files

The translatable strings for a panel are not stored in the PDML file itself, but in a separate Java™ resource bundle. The tools let you specify how the resource bundle is defined, either as a Java PROPERTIES file or as a ListResourceBundle subclass. A ListResourceBundle subclass is a compiled version of the translatable resources, which enhances the performance of your Java application. However, it will slow down the GUI Builder's saving process, because the ListResourceBundle will be compiled in each save operation. Therefore it's best to start with a PROPERTIES file (the default setting) until you're satisfied with the design of your user interface.

You can use the tools to generate HTML skeletons for each panel in the PDML file. At runtime, the correct help topic is displayed when the user clicks on the panel's Help button or presses F1 while the focus is on one of the panel's controls. You must insert your help content at the appropriate points in the HTML, within the scope of the  and  tags. For more specific help information see Editing Help Documents generated by GUI builder.

You can generate source code skeletons for the JavaBeans™ that will supply the data for a panel. Use the Properties window of the GUI Builder to fill in the DATACLASS and ATTRIBUTE properties for the controls which will contain data. The DATACLASS property identifies the class name of the bean, and the ATTRIBUTE property specifies the name of the gettor/settor methods that the bean class implements. Once you've added this information to the PDML file, you can use the GUI Builder to generate Java source code skeletons and compile them. At runtime, the appropriate gettor/settor methods will be called to fill in the data for the panel.

Note: The number and type of gettor/settor methods is dependent on the type of UI control with which the methods are associated. The method protocols for each control are documented in the class description for the DataBean class.

Finally, you can serialize the contents of your PDML file. Serialization produces a compact binary representation of all of the UI resources in the file. This greatly improves the performance of your user interface, because the PDML file must not be interpreted in order to display your panels.

To summarize: If you have created a PDML file named MyPanels.pdml, the following files will also be produced based on the options you have selected on the tools:

MyPanels.properties if you have defined the resource bundle as a PROPERTIES file
MyPanels.java and MyPanels.class if you have defined the resource bundle as a ListResourceBundle subclass
<panel name>.html for each panel in the PDML file, if you have elected to generate online help skeletons
<dataclass name>.java and <dataclass name>.class for each unique bean class that you have specified on your DATACLASS properties, if you have elected to generate source code skeletons for your JavaBeans
<resource name>.pdml.ser for each UI resource defined in the PDML file, if you've elected to serialize its contents.

Note: The conditional behavior functions (SELECTED/DESELECTED) will not work if the panel name is the same as the one in which the conditional behavior function is being attached. For instance, if PANEL1 in FILE1 has a conditional behavior reference attached to a field that references a field in PANEL1 in FILE2, the conditional behavior event will not work. To fix this, rename PANEL1 in FILE2 and then update the conditional behavior event in FILE1 to reflect this change.

Running the Resource Script Converter

To start the Resource Script Converter, invoke the Java interpreter as follows:

     java com.ibm.as400.ui.tools.PDMLViewer

You can also run the Resource Script Converter in batch mode using the following command:

     java com.ibm.as400.ui.tools.RC2XML file [options]

Where file is the name of the resource script (RC file) to be processed. Options

-x name: The name of the generated PDML file. Defaults to the name of the RC file to be processed.
-p name: The name of the generated PROPERTIES file. Defaults to the name of the PDML file.
-r name: The name of the generated ListResourceBundle subclass. Defaults to the name of the PDML file.
-package name: The name of the package to which the generated resources will be assigned. If not specified, no package statements will be generated.
-l locale: The locale in which to produce the generated resources. If a locale is specified, the appropriate 2-character ISO language and country or region codes are suffixed to the name of the generated resource bundle.
-h: Generate HTML skeletons for online help.
-d: Generate source code skeletons for JavaBeans.
-s: Serialize all resources.

Mapping Windows Resources to PDML

All dialogs, menus, and string tables found in the RC file will be converted to the corresponding Graphical Toolbox resources in the generated PDML file. You can also define DATACLASS and ATTRIBUTE properties for Windows controls that will be propagated to the new PDML file by following a simple naming convention when you create the identifiers for your Windows resources. These properties will be used to generate source code skeletons for your JavaBeans when you run the conversion.

The naming convention for Windows resource identifiers is:

     IDCB_<class name>_<attribute>

where <class name> is the fully-qualified name of the bean class that you want to designate as the DATACLASS property of the control, and <attribute> is the name of the bean property that you want to designate as the ATTRIBUTE property of the control.

For example, a Windows text field with the resource ID IDCB_com_MyCompany_MyPackage_MyBean_SampleAttribute produces a DATACLASS property of com.MyCompany.MyPackage.MyBean and an ATTRIBUTE property of SampleAttribute. If you elect to generate JavaBeans when you run the conversion, the Java source file MyBean.java is produced, containing the package statement package com.MyCompany.MyPackage, and gettor and settor methods for the SampleAttribute property.