SpeedJG - XML based Java Swing GUI Builder

How to use this Java Swing GUI Builder IDE

The SpeedJG HowTos explain, how to quickly come to a result you expect from a fast GUI builder tool. The following tasks will be explicated and it is recommended to follow these trials step by step to get an overall picture of this tool.

How to create a ...

1. GUI Project
2. JFrame
3. JDesktopPane
4. JMenu
5. JPopupMenu
6. JToolBar
7. Java GUI Program
8. XML based GUI Program
9. JSplitPane
10. JScrollPane with a JTree
11. JTabbedPane
12. ButtonGroup
13. Scrollable components-composite

How to create a GUI Project

After you have started SpeedJG the first thing you have to do is to define the project. You can open an existing project or create a new one as explained here. Select New Project either from the the File Menu or from the toolbar.

After that the Project Editor opens where you have to enter the Project Name and the Project Path. When pressing the button near the path text field a File Dialog opens to help you to select the path.

The XML Encoding ComboBox enables you to select the character encoding stored as declaration of this GUI builder document.

If you press Save within this dialog you will see the project-entry within the GUIBuilder tree.

Leave this dialog by pressing Exit. Later on, when leaving the SpeedJG program and saving your project on the hard disk the project will be stored as ProjectPath/ProjectName.gpr (where .gpr means GUI-Project).

Top of page

How to create a JFrame

	Make sure the project where you wish to store the JFrame is selected in the tree.
	Now you can press the New JFrame button on the toolbar.

A new JFrame editor is opened ...

• Activate the Title check box and set this property to Howto Examples.
• Activate the Close Op. check box and set this property to Exit.
• Activate the Bounds check box and press the Check button to see how this frame appears on the screen.
• Change some properties, press Check again, and see what effects your changes have.
• Activate the Frame Icon check box and press the button on the very right of this property. After this a resource editor appears. Within this editor activate the Classpath radio button and select the SpeedJG.jar from the combo box beneath. Navigate to the /images/hew/JGLogo18.gif and leave this dialog with OK.
• Press the Check button within the JFrame editor again and you will see the frame with the selected icon as frame icon.
• Press the Source button to see the source code for this frame.

  Activate the popup menu on the source code panel and select Source Code File to store the Java code. Compile and run the program. As you will see, the result is the same as when pressing the Check button.

• If you are content with your frame press Save to store the JFrame meta data into the tree sructure and Exit this editor.

Top of page

How to create a JDesktopPane

Desktop panes comply with Multiple Document Interfaces in that they allow to open several internal frames within a parent frame. To create such a MDI application first create a new JFrame as we have done before. In the meta-data tree select this frame and press the correspondent toolbar button to create a new JDesktopPane.

Leave the editor as it is, save the properties and select the newly created JDesktopPane in the meta-data tree. Now press the appropriate toolbar button to create a new JInternalFrame. Within this JInternalFrame editor select the Visible check-box and set this property to true. Than select the Bounds check-box and then save the properties of this editor.

Again select the JFrame within the meta-data tree and press the Check button from the toolbar. As you can see you have a functioning MDI.

To customize your windows select the different tabs from the editors, change the properties and check the results.

At this point is to be mentioned that if you check your properties with the editors Check button you'll see the results of the current properties in the editor, whether they are saved or not. But if you select a Component within the meta-data tree and check this Component with the Check button from the toolbar, you only see the results of saved properties. Furthermore, note that if you activate a property you first will see the Swing defaults of this property. If these settings are not sufficient for you, build your own Component repository as a separate GUI project. As several projects can be opened at the same time you can copy your Components into your current project with the Copy and Paste buttons from the toolbar.

Top of page

How to create a JMenu

We use the frame created before to supply it with a new File Menu. First we have to select the frame in the components tree. Now we select new JMenuBar from the toolbar and save the properties as explained before. Then we select this new Component in the tree and select new JMenu from the toolbar.

Check the box Text and set the property to File.

Check the box Mnemonic and set the property to f. Save the newly created JMenu and select it in the tree.

Repeat four times to select new JMenuItem from the toolbar and set the following properties:

Name	Text	Mnemonic	CP ( classpath )	Icon
mnNew	New	n	checked	/toolbarButtonGraphics/general/New16.gif
mnOpen	Open	o	checked	/toolbarButtonGraphics/general/Open16.gif
mnClose	Close	c	checked	/toolbarButtonGraphics/general/Export16.gif
mnExit	Exit	x	unchecked

Save all your properties data, select the frame in the tree and check it with the button from the toolbar. As you can see you have a ready-to-use menu .

Now I want to show you how to use the Move Up Component and Move Down Component button. As we want to separate the Exit menu item from the rest of the File menu items we select the JMenu in the tree and create a new JSeparator. When you save this Component it is added to the tree, but it is the last one in the menu. This is not what we want, so we select the newly created separator in the tree and press the Move Up Component button. To see the result, select the frame again and check it.

Top of page

How to create a JPopupMenu

To demonstrate a popup menu we select the JInternalFrame we have created within our JDesktopPane from the tree. Now we activate the toolbar button new JPopupMenu and save the newly created Component. After that we select one of the menu items of the already created JMenu from the tree press Copy Component in the toolbar, then select our JPopupMenu in the tree and press Paste Component in the toolbar. Thereafter check the frame, activate the internal frame, press the mouse-popup button and you will see the result.

While doing this you will get some warnings on the Warning Panel. This is because we copied the Components without changing their names. As these names become the variable names when creating the source code, we are warned here. So if you later on wish to address these Components within your Java code, change their Name property by opening them in the editor via the Edit ... button from the toolbar. This will be necessary for the menu items, but not for the separator, because it will scarcely be manipulated by the program.

Top of page

How to create a JToolbar

We use the frame created before to provide it with a new toolbar. First we have to select the frame in the components tree. Before adding the toolbar we have to set the Layout property of the frame to BorderLayout. This is because the toolbar needs to place itself on the North, West, South or East of a panel. When changing the layout of the frame to BorderLayout we also have to change the Constraint property of the JDesktopPane in our example to Center because the GUI builder has to know where to place the JDesktopPane within the frame.

After making sure we have again selected the frame in our tree, we press new JToolBar from the toolbar, set the Constraint property here to North and save the Component as known. Then we select this Component in the tree and repeat three times to select new JButton from the toolbar and set the following properties:

Name	CP ( classpath )	Icon	Tooltip
btnNew	checked	/toolbarButtonGraphics/general/New24.gif	New File
btnOpen	checked	/toolbarButtonGraphics/general/Open24.gif	Open File
btnClose	checked	/toolbarButtonGraphics/general/Export24.gif	Close File

Save all your properties data, select the frame in the tree and check it. As you can see you have a ready-to-use toolbar.

Top of page

How to create a Java GUI program

To get to the source code of the frame we have created so far select the frame in the tree and press the Generate View Java Code button from the toolbar. I assume the Name property of the frame is still set to myJFrame. So activate the popup menu on the source code panel and save the code as MyJFrame.java .

Be sure the SpeedJG.jar is visible on your CLASSPATH, compile the file, execute it, and you will have the same result as seen before by checking the frame.

When exporting the generated source code yet another time into the same file a dialog pops up and asks you to overwrite it. By default SpeedJG only overwrites the previously generated code lines of the GUI class (or the Controller class when generating the controller code). Thus if you modify the layout of your GUI with SpeedJG and re-generate the code, your individually added code lines in your main class handling the GUI access (or controller events) remain untouched and valid.

Now there are some words to be said about the necessity of the code line
import speed.jg.*;
residing in the generated code:

1. As you can see the code also contains a class named MyJFrameGUI, and this class extends another class named GUIObject. The latter is located in the SpeedJG.jar in a package named speed.jg. This is because it is used both by the GUI builder and the code it generates.
   So in case of sharing your programs generated with this tool, do you need to share the SpeedJG.jar too? Not at all! As a licensed user, you are allowed to share the GUIObject.java file with your code if you observe the relevant copyright notes.
   If you use the XML features (dynamical loading of GUI objects) of this tool - I'll show you later how this works - you must also share the SpeedJG.jar file and the user of your programs has to be a licensed SpeedJG user too.
2. The main task of the GUIObject class is to store the different Components in a Hashtable and serve them later on. Further tasks are to load images and other resources from the CLASSPATH, serve popup menu controllers and calculate the size of Components with respect to their containers.

Are we able now to comment out the line
import speed.jg.*;
and use the locally stored GUIObject.java? Yes and no!

Yes, because we used some images out of the SpeedJG.jar. Therefore it is necessary in this example to have this .jar file on our CLASSPATH.

No, because SpeedJG borrowed these images from the Sun Java look and feel Graphics Repository - jlfgr-1_0.jar - If you have this .jar file at your fingertips you can comment out the import speed.jg.*; line and put the GUIObject.java and the jlfgr-1_0.jar on your CLASSPATH.

The next task on our source code discourse will be how to generate the controller code with the event listeners. So go back into the GUI builder tool, select the frame in the tree and press the toolbar button Generate Controller Java Code.

Be sure you have activated the by default suggested listeners in the upcoming dialog. After confirming by pressing OK you will see the code in the source code tab. The name of the class this code belongs to is the name taken over from the Component we generated it for, plus either the extension Controller if we have more than one listener or Listener if we have only one. So save this code as MyJFrameController.java. In this context it has to be mentioned that the selections you made will be stored within the XML structure of the respective component. Thus if you generate the controller code the next time you will get exactly the same selections you made before. If you generate the controller code for the first time, you will get the default Listeners presented; and if you want to come back to the default listeners at a later date, Deselect all listeners, continue with OK and invoke this dialog again.

As from now there are two different possibilities to activate the controller code.

The first alternative is to simply uncomment the generated code line within our main class MyJFrame as shown below and modify the event-stubs within the MyJFrameController class. But when generating the controller code the next time, the changes you made within the controller class will be overwritten anyway, because the stubs residing there belong to the generated code class!

public class MyJFrame
{
  public MyJFrame()
  { GUIObject gui = new MyJFrameGUI();
    MyJFrameController controller = new MyJFrameController(gui);
    JFrame frame = (JFrame) gui.getComponent("myJFrame");
    frame.show();
  }
...

The second and anyway better solution is to regard our MyJFrameController class as a Swing Adapter class that is tailored to our application, and let the MyJFrame class extend the controller.

public class MyJFrame extends MyJFrameController
{
  public MyJFrame()
  { super(new MyJFrameGUI());
    myJFrame.show();
  }
...

Thus we get a first class Model-View-Controller separation whereas

• all components are accessible from within our main class, and
• the altered code lines within this (MyJFrame) class remain unchanged when generating new view or controller code.

Top of page

How to create an XML based GUI program

The meta data of all Components we have created so far are stored as XML. The GUI builder is able to create Java Components with this information, and so are you. Within our SpeedJG.jar file resides a SpeedJG.class, capable to generate a GUIObject with the GUI information stored as XML.

To extract the XML information from our tool, we again select the frame in the meta-data tree and press the Generate XML Meta Data button in the toolbar. Now we have the content as text information and we store this information in a file named MyJFrame.xml.

Afterwards we save our MyJFrame.java as MyJFrame2.java and keep only the following code lines:

import speed.util.*;

public class MyJFrame2 extends MyJFrameController
{ public MyJFrame2() throws Exception
  { super(SpeedJG.CreateGUI(XMLDocument.fromFile("MyJFrame.xml").getContent()));
    myJFrame.show();
  }
  public static void main(String[] args) throws Exception
  { MyJFrame2 myJFrame = new MyJFrame2();
  }
}

Now compile this newly created program and you will see that it works like the old one. The trick is that SpeedJG dynamiclly generates the GUIObject that is passed to the controller from XML; and this works perfectly because we have a state-of-the-art MVC separation!

Top of page

How to create a JSplitPane

As the following examples are based on a new frame, we leave the one above and create a new one giving it the Name myJFrame3. Meanwhile you should be familar with the tool and also with how to create the source code so that we now will concentrate on how to build the rest of the Components not explained yet.

Coming back to our myJFrame3 we select this frame in the tree and create a new JSplitPane by pressing the new JSplitPane button on the right toolbar. Try Check from the Editors Panel and from the toolbar. You will have a functioning JSplitPane.

Note: This JSplitPane can only contain two other Components. If you add more than these two they will be ignored.

Top of page

How to create a JScrollPane with a JTree

The first thing we want to add to our JSplitPane is a JTree to be found on the left side of the split pane. But a JTree alone doesn't make much sense because it has no viewport of its own that scrolls when the tree expands. Therefore follow these steps:

• In the Tree Panel of the GUI builder select the JSplitPane you have created and add a JScrollPane by pressing the new JScrollPane button on the right toolbar.
• In the Tree Panel of the GUI builder select the JScrollPane you have just created and add a JTree by pressing the new JTree button on the right toolbar.
• Activate the Items check box within the JTree editor.

Select your frame and check it out and you will see the tree you've created from the string resources

Root:leaf_1|leaf_2|leaf_3.

If you want to have an XML structure as a model, change to the editor of the tree Component, select XMLFile from the Items combo box, press the resource dialog button (furthest right) and search for the MyJFrame.xml file we have created in our examples above.

Top of page

How to create a JTabbedPane

The next Component we add to our JSplitPane will be a JTabbedPane as the second element. So you have to select the JSplitPane in the builder tree and do the following steps:

• Press the new JTabbedPane button on the right toolbar. Save this Component within the Editors Panel and select this Component in the builder tree.
• Press the new JPanel button on the right toolbar.
  Set the following properties of this panel: Name to panel1 and Tab Title to Tab 1.
  Save this Component.
• Again press the new JPanel button on the right toolbar and set the properties:
  Name to panel2 and Tab Title to Tab 2.
  Save this Component.

Check out your frame.

Top of page

How to create a ButtonGroup

To create a button group is also a simple task. What we have to do is to create a number of buttons and assign the same ButtonGroup name to all these buttons. To demonstrate this, follow these steps:

• Select the panel1 Tab we created in the GUI builder tree in the previous example.
• Press the new JRadioButton on the right toolbar at first only once.
• Set the Group property of this JRadioButton to radioGroup and pess Save.
• Twice press new JRadioButton now. As you can see the system knows that there is already a Button-Group.
• Set the Name property of these buttons to radioButton1, radioButton2, radioButton3.
• Set the Text properties to RadioButton1, RadioButton2, RadioButton3.
• Set the Group property of all these buttons to radioGroup.
• Set the Selected property of the first button to true so that this button is the one initially selected.

Save your buttons and check out your frame.

Now let's come to the Size Ratio property in this context. If you want all three buttons to have the same width of one third of the panel they are laid out set their SizeRatio (X-Multiply-Divide-Ratio) property to 3 as seen in this picture.

Check your frame and see the result. You can also get to this if you change the layout of your panel to a GridLayout with 3 columns. But, for example, if you want to arrange a JLabel to two fifths width and a JTextField nearby to three fifths, this might be an easier way than to work with GridBagLayout.

Top of page

How to create a scrollable components-composite

The SizeRatio property we used in the previous example does not only help us when sizing a single component but also when dynamically sizing a group of components that should be laid out on a panel residing in JScrollPane. Look at the image on the left side (displaying the guiTranslationExample-JFrame from the Examples.gpr GUI Project-file) that shows three panels with dialog components arranged within a JScrollPane one below the other. If the (combined) height of these panels exceeds a maximum visible height, a scrollbar appears and the user is able to scroll to the component of his interest. So what we want to achieve is to have a screen form of variable size with an arrangement of components adjusting themselves. But the height of these components should be fixed and only their width should change in dependency of the frame width. Moreover if the height of all the contained components together exceeds the height of visibility they should be scrollable to visibility on demand (there is of course as well the possibility to scroll them as fixed witdths horizontally, but that's not within the focus of this chapter).

In order to demonstrate our intention the guiTranslationExample-JFrame contained in the Examples.gpr GUI Project-file (to be found in the SpeedJG home directory) is used. The picture below shows all the components in their parent-child dependency that are involved in this scenario, together with their properties that are of particular importance in this regard.

1. The top level component of course is a JScrollPane (named spFieldEdit in our example).
2. Within this JScrollPane a JPanel (pnFieldEdit) is enclosed with Box_Axis_Y Layout. Thus every component added to it will be laid out below the one before; and thus we are able to add more than one component group to be considered when measuring the height. Additionally this JPanel will dynamically adjust its width if the width of the JScrollPane changes; and the width of the JScrollPane changes if its scrollbar becomes visible or if its parent component changes its width. If at runtime the preferred height of all component groups laid out within this pnFieldEdit exceeds the visible height of the JScrollPane, the latter enables its scroll feature.
3. Next in the hierarchy we find some JPanels each arranging a group of dialog components. One of these, the pnCustomerData JPanel, will be regarded now as follows.
   • The preferred- minimum- and maximum-height is set as fixed height of 84. Thus if this would be the only JPanel laid out in its parent container, the JScrollPane would begin to scroll if it's visible height falls below 84.
   • The height is set to 84 because this JPanel shall contain four lines of components, each with a height of 20. The remainder of 4 is because this JPanel has a border of size 2 (2 at the top and 2 at the bottom).
   • The Layout is set to Flow-Layout without any gaps. Thus you can add components one by one, and if there is lack of space within the current row the next component added will be laid out in the next row. Because this JPanel has a height of 80 (without the border) we can place four rows of components in it if they are not higher than 20 (or a fourth of 80 resp.).
4. At last we insert the single form components one by one, each with a SizeRatio height of one fourth (80 / 4 = 20) of the parent pnCustomerData JPanel. The first is the lbName JLabel with a SizeRatio width of one sixth and the second the tfName JTextField with a SizeRatio width of five sixth of their parent container. Thus these two exactly fit into and fill in the first row of the pnCustomerData JPanel, and the rest of the components are added analogously.

When working with this GUI builder tool you see that the component editors of SpeedJG make extensive use of the feature described in this chapter.

Top of page