Start changeGraphical Toolbox Example

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.

Constructing the panel

When we invoke the GUI Builder, we create a new PDML file called MyGUI.pdml.  We insert a new panel PANEL_1 into this file, which has a title of "Simple Example".  We have already added three elements to this panel using the buttons in the Toolbox window:  a label, a text field, and a pushbutton.

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 files

Now that we have saved the panel definition, let us look at the files produced by the GUI Builder.  First, we show the contents of MyGUI.pdml to give you a flavor of how the Panel Definition Markup Language works.  Because all of your dealings with PDML are through the tools provided by the Graphical Toolbox, it is not necessary to understand the format of this file in detail.

<!-- 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.

Constructing the application

Now that we have saved the panel definition and the generated files, we are ready to construct our application.  All we really need is a new Java source file that will contain our main entry point for the application.  This file will be 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:

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.

Summary

That is it for our initial example.  To give you an overview of the how the Graphical Toolbox works, we have left out a great many features that you can build into a panel.  And we have not even brought up the topic of property sheets or wizards.  We encourage you to experiment, using the GUI Builder's online help as a guide.

For information on how to run this sample as an applet, see Using the Graphical Toolbox in a Browser.
End change