To demonstrate how to use the Graphical Toolbox to build your user interface, this example constructs a simple panel that illustrates the basic features and operation of the Graphical Toolbox environment. Then the example shows to build a small Java application that displays the panel. When the user enters data in the text field and clicks on the Close button, the application will echo the data to the Java console.
We entered the text for the label in the correct field in the Properties window, which displays when the label is selected.
Next we consider the text field. Because the text field will contain data, we can set several properties that will allow the GUI Builder to perform some additional work on our behalf. We set the Data Class property to the name of a bean class named SampleBean that will supply the data for this text field.
We set the Attribute property to the name of the bean property, UserData, that will contain the data.
In effect, we are binding the UserData property to this text field. At run-time, the Graphical Toolbox obtains the initial value for this field by calling SampleBean.getUserData, and the modified value is sent back to the application when the panel closes by calling SampleBean.setUserData.
Now we want to set some data validation on the text field. We specified that the user is required to supply some data, and that it must be a string with a maximum length of 15 characters.
Finally, we indicated that the context-sensitive help for the text field should be the help topic associated with the label "Enter some data".
For the pushbutton, we modified the style property to give it default emphasis.
We have also set the Action property to COMMIT. This causes the setUserData method on the bean to be called when the button is pressed.
Before saving the panel, we set properties at the level of the PDML file
to generate both the online help skeleton and the JavaBean. Then
we saved the file by clicking on the
icon in the main GUI Builder window.
<!-- Generated by GUIBUILDER -->
<PDML version="1.0" source="JAVA" basescreensize="1280x1024">
<PANEL name="PANEL_1">
<TITLE>PANEL_1</TITLE>
<SIZE>351,162</SIZE>
<LABEL name="LABEL_1" disabled="no">
<TITLE>LABEL_1</TITLE>
<LOCATION>18,36</LOCATION>
<SIZE>94,18</SIZE>
</LABEL>
<TEXTFIELD name="TEXT_1" masked="no" editable="yes" disabled="no">
<TITLE>TEXT_1</TITLE>
<LOCATION>125,31</LOCATION>
<SIZE>191,26</SIZE>
<DATACLASS>SampleBean</DATACLASS>
<ATTRIBUTE>UserData</ATTRIBUTE>
<STRING minlength="0" maxlength="15" required="yes"/>
<HELPALIAS>LABEL_1</HELPALIAS>
</TEXTFIELD>
<BUTTON name="BUTTON_1" disabled="no">
<TITLE>BUTTON_1</TITLE>
<LOCATION>125,100</LOCATION>
<SIZE>100,26</SIZE>
<STYLE>DEFAULT</STYLE>
<ACTION>COMMIT</ACTION>
</BUTTON>
</PANEL>
</PDML>
Associated with every PDML file is a resource bundle. In this case we chose to save the translatable resources in a PROPERTIES file, which is called MyGUI.properties. You will notice that the PROPERTIES file also contains customization data for the GUI Builder.
##Generated by GUIBUILDER
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
Recall that we generated a Java source code skeleton for the JavaBean object. Here are the contents 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 are, therefore, required.
The GUI Builder has already invoked the Java compiler for the skeleton and produced the corresponding class file. For the purposes of our simple example, we 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 package com.ibm.as400.ui.framework.java.
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.
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.
We could edit the HTML if we chose, 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.
For information on how to run this sample as an applet, see Using
the Graphical Toolbox in a Browser.