Simple Window Example

The complete example's file is available as simplewindow.xml.

Please note that the application never quits. The Swing thread starts up, but never shuts down. After your window is opened, you will need to forcibly close down your JVM by using Ctrl+C from the command-line (or some other way).

Task Presentation

You have been tasked to create a login screen. You have been told that this screen must include an Ok and Cancel button, an icon, and two labels/fields to enter the user name and password. Everything is normal, up to now.

You have also been told to use the Java Gui Builder (JGB) to build this screen. So, you run over to the software's Web Site to download the appropriate JARs.

After installing and perusing the documentation, you are ready to start...

Programmer's luck...

While perusing the documentation, you happened to take a look at the DTD. You noticed that the first element that must go in your XML file is the window tag. So, you open up a new file in your favorite editor, and you type the following:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE window PUBLIC "-//SOURCEFORGE/Java Gui Builder DTD version 1.0//EN"
    "http://jgb.sourceforge.net/dtd/jgb.dtd">
<window>
</window>

You save this file as mywindow.xml

You decide to try that file with the provided runexample.bat batch file. You type the following at a command-line (or shell) prompt:

C:\jgb>bin\runexample.bat

You receive the following error message:

Error:  Missing argument - <xml file>
Usage:
  java jgb.examples.BuildWindowFromXmlFile [--verbose|-v] [--show] <xml file>
where
    --show is asking for the packing and setting
        the visiblity of the built window
    --verbose or -v is asking for the Builder to be verbose
    and <xml file> is the path to an XML file which should be processed

What the BuildWindowFromXmlFile class is telling you here is that you need to provide it with the name of the source XML file it should be processing. You try that again, but now receive a complaint about a missing attribute. So, cursing your foolishness, you read the docs again for the window element.

Warrior's luck...

The DTD tells you that window elements must have an id and type attribute. So, following the documentation, you faithfully add the required attributes:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE window PUBLIC "-//SOURCEFORGE/Java Gui Builder DTD version 1.0//EN"
    "http://jgb.sourceforge.net/dtd/jgb.dtd">
<window id="loginDialog" type="jdialog">
</window>

Well, that looks good ! You save the file, and you try to use runexample.bat again:

C:\jgb>bin\runexample.bat --show mywindow.xml

Hehe ! This time, it works ! You have a window that pops up on your screen. It is of minimal size, and it contains nothing, but you have the window up there ! So, the rest is adding layout regions and controls as they are needed. You decide to add the ok and cancel buttons first (it will start going faster here):

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE window PUBLIC "-//SOURCEFORGE/Java Gui Builder DTD version 1.0//EN"
    "http://jgb.sourceforge.net/dtd/jgb.dtd">
<window id="loginDialog" type="jdialog">
    <controls>
        <constraints>
            <constant name="java.awt.BorderLayout.SOUTH" />
        </constraints>

        <panel>
            <button id="okButton" />
            <button id="cancelButton" />
        </panel>
    </controls>
</window>

Better and better ! The buttons are there, but they have no text or icons. So, we update this section:

<button id="okButton" text="Ok" mnemonic="o" />
<button id="cancelButton" text="Cancel" mnemonic="c" />

When you run the program again, you get exactly what you expected:

Coder's luck...

Well, you can now proceed with the top part of the dialog box. First of all, we'll split the top portion in two, vertically. The left side will be reserved for the picture, and the right side will contain the two labels and text fields. So, firing up your editor again, you write the following:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE window SYSTEM "http://jgb.sourceforge.net/dtd/jgb.dtd">
<window id="loginDialog" type="jdialog">
 <controls>
  <constraints>
   <constant name="java.awt.BorderLayout.CENTER" />
  </constraints>

  <panel layout="GridLayout" columns="2" />

  <constraints>
   <constant name="java.awt.BorderLayout.SOUTH" />
  </constraints>
  <panel>
   <button id="okButton" ... />
   ...
  </panel>
 </controls>
</window>

Running that does not have any appreciable changes. Both cells of the grid layout are empty. We have to fill them in with something:

<panel layout="GridLayout" columns="2">
    <label id="loginImage" text="Graphics Placeholder" />

    <panel layout="GridLayout" rows="4">
        <label text="User Name:" mnemonic="u" />
        <textfield id="userNameField" columns="8" />

        <label text="Password:" mnemonic="p" />
        <textfield id="passwordField" columns="8" />
    </panel>
</panel>

Running this XML code results in the following screen:

Hacker's luck...

Well, that looks quite a bit interesting... Finally, you decide to add the image that was required in the beginning. You check the JavaDocs for JLabel, and find that it can only accept an Icon. You further check up and see that the ImageIcon accepts a URL as parameter. So, you fire up your editor again, and you code away:

<window id="loginDialog" type="jdialog">
    <object id="junitIconURL" class="java.net.URL">
        <constructor>
            <parameter name="url">
                <value type="string" data="http://www.junit.org/images/frogMov.gif" />
            </parameter>
        </constructor>
    </object>

    <object id="loginImageIcon" class="javax.swing.ImageIcon">
        <constructor>
            <parameter name="url"><ref refid="junitIconURL" /></parameter>
        </constructor>
    </object>

    <controls>
    ...
    </controls>
</window>

What you've done here is declare two different objects: a java.net.URL and a javax.swing.ImageIcon. The URL does not have a no-arg constructor, so you had to call the one with a java.lang.String. ImageIcon too does not have a no-arg constructor. It can be called with a java.net.URL though. Which is what you did with the above code.

The next step is to use these items on the left-side of the main panel. So, here goes:

...
<controls>
    <constraints>
        <constant name="java.awt.BorderLayout.CENTER" />
    </constraints>

    <panel layout="GridLayout" rows="1" columns="2" hgap="6" >
        <label id="loginImage">
            <property name="icon">
                <ref refid="loginImageIcon" />
            </property>
        </label>
        ...
    </panel>
    ...
</controls>

<panel layout="GridLayout">
    ...

Beginner's luck...

Firing up the BuildWindowFromXmlFile, you realize that you are done ! This screen is complete. The only thing missing is the event-handling code for the Ok and Cancel buttons. This feature is left as an exercise to the reader, after reading about event handling in JGB. Here is the final login dialog:

That almost concludes our example. You've made the screen, and it looks good. You now need to include this screen in your final application. With the following lines, this screen will be instantiated and ready for use in your mainstream application:

public class MainApplication {
    private jgb.builder.Builder guiBuilder = new jgb.builder.Builder();

    public void show(java.io.FileInputStream in) throws java.io.IOException {
        guiBuilder.parse(in);
        JDialog loginDialog = (JDialog)guiBuilder.get("loginDialog");
        loginDialog.setTitle("Main Application Login");
        loginDialog.setModal(true);
        loginDialog.pack();
        loginDialog.setVisible(true);
    }

    public static void main(String[] args) throws java.lang.Exception {
        new MainApplication().show(new FileInputStream(...));
    }
}

After you've written this code, you realize that you will update the XML source file since you are setting properties on the dialog. But, let us leave that for another time...

Hosted on SourceForge.net

Valid XHTML 1.0 !

Valid CSS !

Code Coverage provided by Clover