This example demonstrates how to use the Graphical Toolbox by constructing a simple panel. It is an overview that illustrates the basic features and operation of the Graphical Toolbox environment. After showing you how to construct a panel, the example goes on to show you how to build a small Java™ application that displays the panel. In this example, the user enters data in a text field and clicks on the Close button. The application then echos the data to the Java console.
Constructing the panel
When you start the GUI Builder, the Properties and GUI Builder windows appear. Create a new file named "MyGUI.pdml". For this example, insert a new panel. Click the "Insert Panel" icon in File Builder window. Its name is "PANEL1". Change the title by modifying information in the Properties window; type "Simple Example" in the "Title" field. Remove the three default buttons by selecting them with your mouse and pressing "Delete". Using the buttons in the Panel Builder window, add the three elements shown in Figure 1: a label, a text field, and a pushbutton.
Figure 1: GUI Builder windows: Beginning to construct a panel
By selecting the label, you can change its text in the Properties window. In this example, the same has been done for the pushbutton, changing its text to "Close".
Figure 2: GUI Builder windows: Changing text in the Properties window
Text field
The text field will contain data and, therefore, you can set several properties that will allow the GUI Builder to perform some additional work. For this example, you set the Data Class property to the name of a bean class named SampleBean. This databean will supply the data for this text field.
Figure 3: GUI Builder windows: Setting the Data Class property
Set the Attribute property to the name of the bean property that will contain the data. In this case, the name is UserData.
Figure 4: GUI Builder windows: Setting the Attribute property
Following the above steps binds the UserData property to this text field. At run-time, the Graphical Toolbox obtains the initial value for this field by calling SampleBean.getUserData. The modified value is then sent back to the application when the panel closes by calling SampleBean.setUserData.
Specify that the user is required to supply some data, and that the data must be a string with a maximum length of 15 characters.
Figure 5: GUI Builder windows: Setting the maximum length of the text field
Indicate that the context-sensitive help for the text field will be the help topic associated with the label "Enter some data".
Figure 6: GUI Builder windows: Setting context-sensitive help for the text field
Button
Modify the style property to give the button default emphasis.
Figure 7: GUI Builder windows: Setting the Style property to give the button default emphasis
Set the ACTION property to COMMIT, which causes the setUserData method on the bean to be called when the button is selected.
Figure 8: GUI Builder windows: Setting the Action property to COMMIT
Before
you save the panel, set properties at the level of the PDML file to generate
both the online help skeleton and the Java bean. Then you save the file by clicking
on the 
icon in the GUI Builder window. When prompted, specify a file name
of MyGUI.pdml.
Figure 9: GUI Builder windows: Setting properties to generate the online help skeleton and the Java bean
Generated files
After you save the panel definition, you can look at the files produced by the GUI Builder. PDML file Here is the content of MyGUI.pdml to give you an idea of how the Panel Definition Markup Language works. Because you use PDML only through the tools provided by the Graphical Toolbox, it is not necessary to understand the format of this file in detail:
<!-- Generated by GUI Builder --> <PDML version="2.0" source="JAVA" basescreensize="1280x1024"> <PANEL name="PANEL1"> <TITLE>PANEL1<TITLE> <SIZE>351,162<</SIZE> <LABEL name="LABEL1""> <TITLE>PANEL1.LABEL1</TITLE> <LOCATION>18,36</LOCATION> <SIZE>94,18</SIZE> <HELPLINK>PANEL1.LABEL1</HELPLINK> </LABEL> <TEXTFIELD name="TEXTFIELD1"> <TITLE>PANEL1.TEXTFIELD1</TITLE> <LOCATION>125,31</LOCATION> <SIZE>191,26</SIZE> <DATACLASS>SampleBean</DATACLASS> <ATTRIBUTE>UserData</ATTRIBUTE> <STRING minlength="0" maxlength="15"/> <HELPALIAS>LABEL1</HELPALIAS> </TEXTFIELD> <BUTTON name="BUTTON1"> <TITLE>PANEL1.BUTTON1</TITLE> <LOCATION>125,100</LOCATION> <SIZE>100,26</SIZE> <STYLE>DEFAULT<</STYLE> <ACTION>COMMIT</ACTION> <HELPLINK>PANEL1.BUTTON1</HELPLINK> </BUTTON> </PANEL> </PDML>
Resource bundle
Associated with every PDML file is a resource bundle. In this example, the translatable resources were saved in a PROPERTIES file, which is called MyGUI.properties. Notice that the PROPERTIES file also contains customization data for the GUI Builder.
##Generated by GUI Builder
BUTTON_1=Close
TEXT_1=
@GenerateHelp=1
@Serialize=0
@GenerateBeans=1
LABEL_1=Enter some data:
PANEL_1.Margins=18,18,18,18,18,18
PANEL_1=Simple Example
JavaBean
The example also generated a Java source code skeleton for the JavaBean object. Here is the content of SampleBean.java:
import com.ibm.as400.ui.framework.java.*;
public class SampleBean extends Object
implements DataBean
{
private String m_sUserData;
public String getUserData()
{
return m_sUserData;
}
public void setUserData(String s)
{
m_sUserData = s;
}
public Capabilities getCapabilities()
{
return null;
}
public void verifyChanges()
{
}
public void save()
{
}
public void load()
{
m_sUserData ="";
}
}
Note that the skeleton already contains an implementation of the gettor and settor methods for the UserData property. The other methods are defined by the DataBean interface and, therefore, are required.
The GUI Builder has already invoked the Java compiler for the skeleton and produced the corresponding class file. For the purposes of this simple example, you do not need to modify the bean implementation. In a real Java application you would typically modify the load and save methods to transfer data from an external data source. The default implementation of the other two methods is often sufficient. For more information, see the documentation on the DataBean interface in the javadocs for the PDML runtime framework.
Help file
The GUI Builder also creates an HTML framework called a Help Document. Help writers can easily manage help information by editing this file. For more information, see the following topics:
Constructing the application
Once the panel definition and the generated files have been saved, you are ready to construct the application. All you need is a new Java source file that will contain the main entry point for the application. For this example, the file is called SampleApplication.java. It contains the following code:
import com.ibm.as400.ui.framework.java.*;
import java.awt.Frame;
public class SampleApplication
{
public static void main(String[] args)
{
// Instantiate the bean object that supplies data to the panel
SampleBean bean = new SampleBean();
// Initialize the object
bean.load();
// Set up to pass the bean to the panel manager
DataBean[] beans = { bean };
// Create the panel manager. Parameters:
// 1. PDML file as a resource name
// 2. Name of panel to display
// 3. List of data objects that supply panel data
// 4. An AWT Frame to make the panel modal
PanelManager pm = null;
try { pm = new PanelManager("MyGUI", "PANEL_1", beans, new Frame()); }
catch (DisplayManagerException e)
{
// Something didn't work, so display a message and exit
e.displayUserMessage(null);
System.exit(1);
}
// Display the panel - we give up control here
pm.setVisible(true);
// Echo the saved user data
System.out.println("SAVED USER DATA: '" + bean.getUserData() + "'");
// Exit the application
System.exit(0);
}
}
It is the responsibility of the calling program to initialize the bean object or objects by calling load. If the data for a panel is supplied by multiple bean objects, then each of the objects must be initialized before passing them to the Graphical Toolbox environment.
The class com.ibm.as400.ui.framework.java.PanelManager supplies the API for displaying standalone windows and dialogs. The name of the PDML file as supplied on the constructor is treated as a resource name by the Graphical Toolbox - the directory, ZIP file, or JAR file containing the PDML must be identified in the classpath.
Because a Frame object is supplied on the constructor, the window will behave as a modal dialog. In a real Java application, this object might be obtained from a suitable parent window for the dialog. Because the window is modal, control does not return to the application until the user closes the window. At that point, the application simply echoes the modified user data and exits.
Running the application
Here is what the window looks like when the application is compiled and run:
Figure 10: The Simple Example application window
If the user presses F1 while focus is on the text field, the Graphical Toolbox will display a help browser containing the online help skeleton that the GUI Builder generated.
Figure 11: The Simple Example online help skeleton
You can edit the HTML and add actual help content for the help topics shown.
If the data in the text field is not valid (for example, if the user clicked on the Close button without supplying a value), the Graphical Toolbox will display an error message and return focus to the field so that data can be entered.
Figure 12: Data Error message
For information about how to run this sample as an applet, see Using the Graphical Toolbox in a Browser.