318 lines
15 KiB
HTML
318 lines
15 KiB
HTML
<?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> |