<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en-us" xml:lang="en-us">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="security" content="public" />
<meta name="Robots" content="index,follow" />
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
<meta name="DC.Type" content="reference" />
<meta name="DC.Title" content="Example: Constructing a panel with the GUI Builder" />
<meta name="abstract" content="" />
<meta name="description" content="" />
<meta name="copyright" content="(C) Copyright IBM Corporation 2006" />
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 2006" />
<meta name="DC.Format" content="XHTML" />
<meta name="DC.Identifier" content="pdmlcdex" />
<meta name="DC.Language" content="en-us" />
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
<link rel="stylesheet" type="text/css" href="./ic.css" />
<title>Example: Constructing a panel with the GUI Builder</title>
</head>
<body id="pdmlcdex"><a name="pdmlcdex"><!-- --></a>
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
<h1 class="topictitle1">Example: Constructing a panel with the GUI Builder</h1>
<div><p></p>
<div class="section"><div class="note"><span class="notetitle">Note:</span> Read the <a href="codedisclaimer.htm#codedisclaimer">Code
example disclaimer</a> for important legal information.</div>
<p>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 <strong>Close</strong> button. The application then echos the data
to the Java console.</p>
</div>
<div class="section"><h4 class="sectiontitle">Constructing the panel</h4><p>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.</p>
<p><strong>Figure
1: GUI Builder windows: Beginning to construct a panel</strong></p>
<p> <img src="rzahh101.gif" width="600" alt="GUI Builder windows: Beginning to construct a panel" /> </p>
<p>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".</p>
<p><strong>Figure
2: GUI Builder windows: Changing text in the Properties window</strong></p>
<p><img src="rzahh106.gif" width="600" alt="GUI Builder windows: Changing text in the Properties window" /> </p>
<p><strong>Text field</strong></p>
<p>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 <strong>SampleBean</strong>.
This databean will supply the data for this text field.</p>
<p><strong>Figure 3:
GUI Builder windows: Setting the Data Class property</strong></p>
<p><img src="rzahh107.gif" width="600" alt="GUI Builder windows: Setting the Data Class property" /> </p>
<p>Set the
Attribute property to the name of the bean property that will contain the
data. In this case, the name is <strong> UserData</strong>.</p>
<p><strong>Figure 4: GUI Builder
windows: Setting the Attribute property</strong></p>
<p><img src="rzahh108.gif" width="600" alt="GUI Builder windows: Setting the Attribute property" /> </p>
</div>
<div class="section"><p>Following the above steps binds the <strong>UserData</strong> property to
this text field. At run-time, the Graphical Toolbox obtains the initial value
for this field by calling <strong><span> SampleBean.getUserData</span></strong>. The modified
value is then sent back to the application when the panel closes by calling <strong><span>SampleBean.setUserData</span></strong>.</p>
</div>
<div class="section"><p>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.</p>
</div>
<div class="section"><p><strong>Figure 5: GUI Builder windows: Setting the maximum length of
the text field</strong></p>
<p><img src="rzahh109.gif" width="600" alt="GUI Builder windows: Setting the maximum length of the text field" /> </p>
<p>Indicate
that the context-sensitive help for the text field will be the help topic
associated with the label "Enter some data".</p>
<p><strong>Figure 6: GUI Builder
windows: Setting context-sensitive help for the text field</strong></p>
<p><img src="rzahh110.gif" width="600" alt="GUI Builder windows: Setting context-sensitive help for the text field" /> </p>
<p><strong>Button</strong></p>
<p>Modify
the style property to give the button default emphasis.</p>
<p><strong>Figure 7:
GUI Builder windows: Setting the Style property to give the button default
emphasis</strong></p>
<p><img src="rzahh111.gif" width="600" alt="GUI Builder windows: Setting the Style property to give the button default emphasis" /> </p>
<p>Set the
ACTION property to COMMIT, which causes the <tt> setUserData</tt> method
on the bean to be called when the button is selected.</p>
<p><strong>Figure 8: GUI
Builder windows: Setting the Action property to COMMIT</strong></p>
<p><img src="rzahh112.gif" width="600" alt="GUI Builder windows: Setting the Action property to COMMIT" /> </p>
<p>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 <img src="rzahh544.gif" alt="Save File icon" /> icon in the GUI Builder window. When prompted, specify a file name
of <strong>MyGUI.pdml</strong>.</p>
<p><strong>Figure 9: GUI Builder windows: Setting properties
to generate the online help skeleton and the Java bean</strong></p>
<p><img src="rzahh102.gif" width="600" alt="GUI Builder windows: Setting properties to generate the online help skeleton and the Java bean" /> </p>
</div>
<div class="section"><h4 class="sectiontitle">Generated files</h4><p>After you save the panel definition,
you can look at the files produced by the GUI Builder. <strong>PDML file</strong> Here
is the content of <strong>MyGUI.pdml</strong> 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: </p>
<pre><!-- 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></pre>
<p><strong>Resource bundle</strong></p>
<p>Associated with every
PDML file is a resource bundle. In this example, the translatable resources
were saved in a PROPERTIES file, which is called <strong>MyGUI.properties</strong>.
Notice that the PROPERTIES file also contains customization data for the GUI
Builder.</p>
<pre> ##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</pre>
<p><strong>JavaBean</strong></p>
<p>The example
also generated a Java source code skeleton for the JavaBean object. Here
is the content of <strong>SampleBean.java</strong>:</p>
<pre>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 ="";
}
}</pre>
<p>Note that the skeleton already contains an implementation
of the gettor and settor methods for the <tt>UserData</tt> property. The other
methods are defined by the <tt>DataBean</tt> interface and, therefore, are
required.</p>
<p>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 <tt>load</tt> and <tt>save</tt> 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 <strong><span>DataBean</span></strong> interface in the <a href="javadoc/com/ibm/as400/ui/framework/java/package-summary.html"> javadocs
for the PDML runtime framework</a>.</p>
<p><strong>Help file</strong></p>
<p>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:</p>
<ul><li><a href="helpex.htm#helpex">Creating the Help Document</a></li>
<li><a href="helpinfo.htm#helpinfo">Editing Help Documents generated by
GUI builder</a></li>
</ul>
</div>
<div class="section"><h4 class="sectiontitle">Constructing the application</h4><p>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 <strong>SampleApplication.java</strong>.
It contains the following code:</p>
<pre>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);
}
}</pre>
<p>It is the responsibility of the calling program to initialize
the bean object or objects by calling <strong><span>load</span></strong>. 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.</p>
<p>The
class <strong><span>com.ibm.as400.ui.framework.java.PanelManager</span></strong> 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.</p>
<p>Because a <strong><span>Frame</span></strong> 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.</p>
</div>
<div class="section"><h4 class="sectiontitle">Running the application</h4><p>Here is what the window
looks like when the application is compiled and run:</p>
<p><strong>Figure 10: The
Simple Example application window</strong></p>
<p><img src="rzahh103.gif" alt="The Simple Example application window" /> </p>
<p>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.</p>
<p><strong>Figure
11: The Simple Example online help skeleton</strong></p>
<p><img src="rzahh105.gif" alt="The Simple Example online help skeleton" /> </p>
<p>You can edit the HTML
and add actual help content for the help topics shown.</p>
<p>If the data in
the text field is not valid (for example, if the user clicked on the <strong>Close</strong> 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.</p>
<p><strong>Figure
12: Data Error message</strong></p>
<p><img src="rzahh104.gif" alt="Data Error message" /></p>
<p>For information about how to run this sample
as an applet, see <a href="pdmlbrws.htm#pdmlbrws">Using the Graphical
Toolbox in a Browser</a>.</p>
</div>
</div>
</body>
</html>