JForge ][
A Java Graphical User Interface Builder
Version: 2.56 (Thalia)
and 2.57 (Themis), 11th of January, 1999
Email: jforge@tek-tools.com
WWW: http://www.tek-tools.com/jforge/
Newsgroup: new.tek-tools.com jforge.general, jforge.announce
0. Summary
1. Installation
2. Usage
3. Loading
Your Own Beans
4. The
JForge API and Public Classes
5. FAQ
6. Other
Documentation
JForge is a Graphical User Interface
(GUI) builder for creating user interfaces
in Java using AWT and JFC based beans.
Features:
System requirements:
After the installer has installed JForge on your machine, a setup dialogue box appears. Read the License information and then press the "Next" button.
Type in the directory path of your HOME directory (the current HOME directory is displayed in the text field and you should not need to change it. If you do, you will have to add or update your HOME environment variable to the value you have set in the setup text field). Press the "Next" button.
[ A NOTE ON "HOME": For Unix users, the HOME environment variable is probably self-evident. For users of other single-user operating systems (e.g.: Windows 95/NT), the HOME environment variable is set to the directory of the users' home and provides a link to a standard place where a specific user can place their own files. Java allows access to this environment variable so that applications like JForge can create files and directories in an area that is guaranteed to be accessible. If you do not set your HOME environment variable explicitly under Windows it defaults to the root directory of the disk drive containing the operating system (e.g.: "C:\"). (With Windows NT and JDK 1.2 it defaults to the Profiles area \WINNT\Profiles\). ]
If an error occurs, an error message will appear in the window below the buttons and the screen will remain at the HOME Directory screen. If this happens it will probably be because you do not have access to the specified HOME Directory. Change the directory path and press "Next" again or see your System Administrator.
If successful, Setup tells you. Press the "Next" button again.
Type in your first and last names and then press the "Next" button.
Press the "Finish" button.
If you have registered JForge, type in your registration name/password and press the "Register" button. Make sure you type them exactly as given.
If you have not registered JForge, read the information given on the
dialogue panel and then either press the "I Agree" or "I Disagree" buttons.
"I Disagree" will exit the application.
2. Usage
JForge may be started by following the procedure outlined in Section 1. In addition, JForge may also be started directly from the command line with arguments:
java uk.co.demon.sspl.jforge.Builder [-h] <file.class>
-h shows usage help (the command line options). The optional filename starts JForge and loads the file for editing. This option is useful for IDE's that allow you to call a 3rd party GUI builder.
On startup, JForge displays a main window consisting of three areas; a Bean Tool Bar, a Work Bench and an Information Panel.
The Main Window also contains a standard application menu with the following items:
File ---- New - Creates a new Work Bench. Open - Opens a .class (compiled) Java GUI. Save - Saves the current GUI you are building as a .java file. Save As - Saves the current GUI under a new name as a .java file. Save & Compile - Saves to .java and compiles the code to a .class. Load Serialized - Loads a serialized GUI. Save Serialized - Saves a GUI in serialized form. Exit - Exits JForge.
Edit ---- Cut - Cuts the currently selected component. Copy - Copies the currently selected component. Paste - Pastes a copy of the component that is in the copy buffer. The component is pasted to a different place depending on what is currently selected. If the original component is still selected, the copy is pasted to the same container. If a different component has since been selected, the copy is pasted inside the selected component. Preferences - Edit the JForge builder properties such as colours.
Window ------ Colour Tool - Displays the Colour Tool. Compilation Status - Displays the Compilation Status window. Tree Display - Displays the Tree Hierarchy window.Help
The Work Bench, the large blank area on the right of the Main Window, is the display area for the GUI you are building. What you see on the Work Bench is what will be produced when you save, compile and use the resulting code. The Information panel below the Work Bench displays the X/Y location of the mouse in the Work Bench. It also has three checkboxes to select the Work Bench Mode, Grid visibility and Snap to Grid.
The Work Bench can be placed in two modes; Edit or Test. Edit mode allows you to place components on the Work Bench and manipulate them with the mouse. Test Mode allows you to interact with the components on the display, just like you would be able to do outside JForge.
The Work Bench also allows you to place and size components free-form, or with a snap-to function. Turning on Snap to Grid moves and resizes components that you place on the Work Bench to the nearest grid intersection. To see the grid, switch it on by clicking the Show Grid checkbox.
The Bean Tool Bar allows you to select components to place on the Work Bench. You can either select from the standard pallete of Swing components in the top section, or from a list of loaded beans shown in the "Imported Beans" panel. See the section "Loading Your Own Beans" for information on how to load your own beans into JForge.
To add a component to the Work Bench, select one from the Bean Tool Bar and click the left hand mouse button in the Work Bench. The component will appear with its top right hand corner positioned at the mouse pointer. You can set the initial size when you add a component by clicking and dragging a component out to the desired size on the work bench. You can also change the position and size of any component by dragging the component or the components resize tabs (yellow boxes at the corners and sides of the component outline) respectively.
The current bean changes back to the Selection icon (the pointer) after you place a component on the work bench. To keep the bean selection on the same component selection after placement, click the Lock Component button at the foot of the Beans Tool Bar.
The current component for any operation is outlined in yellow. To select different components, click them with the left hand mouse button.
To select multiple components, click on them with the left-hand mouse button while holding down the SHIFT key. To move a multi-selection, click and drag with the left-hand mouse button while holding the SHIFT key. NOTE: Cut is currently the only JForge operation that works on multiple selections. All other operations work on the first component selected in a group.
To edit the attributes of a selected component, select the component and switch the tabbed pane on the Bean Tool Bar to the Bean Properties tab. While this tab is displayed, any component that you select on the Work Bench will display its attributes in the tab's scrolling list. You can delete the currently selected components by choosing Cut from the Edit menu on the Main Window.
The JForge Preferences editor can be brought up by selecting Preferences from the Edit menu. This dialogue allows you to change various JForge attributes. The Vars Visibility selection specifies the visibility of component identifiers during code generation. Normally you would want these Public, or more likely Protected. The colour selections are fairly straight forward; Base refers to the base colour of the windows, Panel to the colour of panels placed on the windows, Controls to the colour of the controls on the panels, Text to the colour of labels, and Entry Text to the colour of text in entry fields. Note that all of these refer to JForge itself, not the components you place on the Work Bench.
Three text fields allow you to specify the location of a temporary directory (where JForge can place temporary files such as cut/copies), the location of the Setup directory (where the layout and beans files reside), and the command to start the Java compiler.
The Save button saves the properties to a file in the .jforge2 directory in your Home directory (if .jforge2 doesn't exist nothing is written).
The Cancel button closes the editor dialogue without saving.
JForge also contains some tools to help you edit your GUI. You can access them from the Window menu. They are described below.
Colour Tool
The Colour Tool is a passive floating tool; that is, it doesn't change the colour of anything (except if it's a shared colour - see below). JForge provides standard colour controls with two buttons: Change and Edit. Change will use whatever the current colour is on the colour tool, while Edit brings the Colour Tool to the foreground if it is hidden.
The Colour Tool provides two forms of colour: Unique and Shared. Unique colours are just that :- a component that uses a Unique colour will have its own Java Color object. A Shared colour on the other hand may be shared across multiple components. Changing a shared colour in the Colour Tool changes the colour of all the components that use that colour.
Compilation Status
This window provides information on the state of a compilation initiated from the Save & Compile option on the File menu.
Tree Display
The Tree Display shows a graphical representation of the component hierarchy. Initially the nodes in the tree are closed and only the Root Node is visible (the Root Node being the top level component). To open a node, double click the Left Hand mouse button over the node. This will open it up one level. To close it, double click on it again. Closed nodes are shown in green and open nodes in blue.
To open up a whole subsection of the hierarchy, you can press the "Expand Node" button. To close it, press the "Collapse Node" button.
To select a node (and the corresponding component on the Work Bench) click on the node with the Left Hand mouse button. To reposition the node in the tree hierarchy, click and drag with the Left Hand mouse button; the node will turn red and a yellow node outline will follow the mouse pointer. By placing the mouse pointer over another node, the component will be placed into the new position (along with its children).
To add a component to the tree, select
a component from the selection panel or the loaded beans and click on the
node in the tree where you wish to add it.
Saving
To save your work, select the "Save"
or "Save As" items from the File menu. Save will save to the current name
(and will pop up a Save dialogue the first time you save) while "Save As"
will always pop up a Save Dialogue.
JForge allows you to use third party beans and layouts by changing the files in the setup directory. Currently the setup directory contains three files; beans.inf, borders.inf and layouts.inf. These files are read by JForge on startup and give it information about the beans you wish to have loaded. The format of the files is as follows:
<name of the class>:<name of the BeanInfo for the class>
In both cases the name should be the fully qualified (i.e.: with package) name of the classes. If the bean or layout you wish to load doesn't come with a BeanInfo, you can leave the name after the colon blank. JForge will construct the required BeanInfo for the class.
beans.inf is used to specify visual Java bean components; those that can be added to other components from AWT or Swing.
borders.inf is used to specify beans derived from the Swing Border class.
layouts.inf is used to specify
layout beans; beans that provide layout management for components and that
are derived from the AWT LayoutManager class.
IMPORTANT NOTES
Just because a bean or layout has no BeanInfo file, or comes with one, doesn't mean it will work as expected inside JForge. JForge requires additional information about complex beans to make life simple for you when you work with them. Simple beans and layouts usually don't require anything more than what already exists, and complex beans can still be loaded and used without the additional information (but may be impossible to work with).
The additional ("special") information allows JForge to determine how to create a bean, where in the bean it should place other components, how to access the children of the bean, and provides the information that gets written out at source generation that JForge would be unable to determine. It also allows you to deny the user the ability to drop components into a bean. The aim is to allow JForge to load and work with any Bean (so long as the bean can be displayed visually) regardless of how it manages its subcomponents.
Adding the special information is fairly simple and requires nothing more than creating a BeanInfo, a BuilderBeanInfo, or subclassing an existing BeanInfo and implementing the appropriate BuilderBeanInfo. Discussion of creating beans and how to use BeanInfo are outside the scope of this document. You can find out more by reading the interface specifications in the docs directory or by examining the source code provided in the src directory in this archive. Here are some further notes:
-------------------------------------------------------------------
BuilderComponentBeanInfo
and BuilderLayoutBeanInfo can be found in
the package pub.java.gui.builders
(provided in public.jar).
-------------------------------------------------------------------
Layouts - Special layouts with complex
requirements need to implement
BuilderLayoutBeanInfo.
Beans - Special beans
with complex requirements need to implement
BuilderComponentBeanInfo.
Simple Layout - Example: FlowLayoutBeanInfo.java. This layout requires a bean so that the Justification can be displayed as a ComboBox with words rather than numbers. This is an example of providing a plain BeanInfo (the AWT doesn't come with any BeanInfo's for layouts). Note that it doesn't need to live in the java/awt directory; it's there because I haven't moved it out as yet.
Complex Layout - Example: BorderLayoutBeanInfo.java. This layout requires access to protected information in the class and hence needs to live in the java/awt directory. It also requires a customizer. If the layout didn't hide crucial information I wouldn't have had to place the BeanInfo in the java.awt hierarchy.
Simple Bean - Example: JButtonBeanInfo.java (already inside the Swing set).
Complex Bean - Example: BuilderJTabbedPaneBeanInfo.java. This bean needs to provide information to JForge about how to instantiate it, how to add components and how to obtain the child components. It's an example of subclassing the real BeanInfo and adding the information defined in the BuilderComponentBeanInfo interface.
JForge looks for a BeanInfo in the following manner:
a) look in the place specified in
the .inf files
b) look for it in the standard way
(with the introspector) and generate one if necessary.
4. The JForge API and Public Classes
JForge provides access to its internal mechanisms through the class uk.co.demon.sspl.jforge.BuilderAPI. The API allows access to
In addition, JForge allows you to add your own code at startup and shutdown times, as well as through the GUI menu.
External code may be added via the class uk.co.demon.sspl.jforge.PublicStartStopJForge. Two entry points are provided during startup (the first occuring when this class is instantiated before the Main Window and internal variables are initialized, and the second occuring after the Main Window is displayed) and one during shutdown. You can modify the source file for this class and recompile it to add your own code. See the PublicStartStopJForge specification in the docs directory for further information. NOTE: This class is not used by unregistered copies of JForge.
The Menu Handler provides a pluggable menu scheme through the class uk.co.demon.sspl.jforge.PublicMenuHandler. You can modify the source file for this class and recompile it to change the way the menus work or add your own custom menus. See the PublicMenuHandler specification in the docs directory for further information.
For related documentation, please see the Other
Documentation section in this manual.
Q: What kind of GUI's can I read with JForge?
A: Reading GUI classes not
generated by the builder :- You can read any GUI class into JForge provided
that the class has a public constructor that takes no parameters.
Q: I save source and then put comments and handlers into the code. When I load it back in to JForge and save it again, all of my additions disappear! What is going on?
A: If you save source you'll
lose all comments, event handlers and anything else not associated with
the GUI code that may exist in the original source file. To stop this from
happening you should consider splitting your pure-GUI code from event handlers
and initialisation routines. You can do this very easily by just subclassing
the GUI classes produced by JForge and place all your handlers and other
bits of non-GUI code into the subclass.
Q: I save a GUI called myGUI.java, but when I try and load myGUI.java back in it doesn't load. Why?
A: JForge reads .class
files. You must compile myGUI.java first and then open the myGUI.class
file with JForge.
Q: When I place a bean on the work bench, save it, compile it and load it back in to JForge, all of the sub-components (buttons, etc) of the bean can be moved around and changed. Why?
A:When the bean (let's call
it MyBean) is added to the work bench it is an object of class MyBean.
When you save it, you are creating a new class with whatever name you save
it as (say MyNewBean). MyNewBean extends MyBean. As MyBean will have needed
a MyBeanBeanInfo to "stop" you accessing the bean internals in JForge,
MyNewBean will require a MyNewBeanBeanInfo class to do the same for the
new class. MyBeanBeanInfo is not the BeanInfo for MyNewBean, so JForge
will treat the internal components of the bean as separate entities.
Q: I place a JFrame on the Work Bench and add a component to it. The component expands to fill the entire frame and I can't move it or resize it.
A: The standard components
generated by JForge retain all of their default properties when they are
created. This includes any layout managers that come with the component.
In this example, the default layout manager for a JFrame is BorderLayout.
Any component added to the JFrame will be added to the default BorderLayout
position, i.e.: BorderLayout.CENTER, which will make that component expand
to fill the entire content area of the JFrame. To change the layout, edit
the component (in this case, the JFrame) and set its layout manager to
whatever is more appropriate.
Q: I load a GUI created by (hand/another builder) and it doesn't display on the Work Bench, yet it is clearly loaded as it shows up in the Tree Display. What is wrong?
A: If you click on the top level component in the Tree Display
you will probably see a yellow square appear on the Work Bench. The yellow
square is the resize corners of the component. The component has most likely
had no sizes set and when JForge loads it, it displays with whatever the
default sizes are. In this case they are probably close to 0 for both width
and height. another possibility is that the X/Y location is off the Work
Bench. In either case, select the top level component in the tree and examine
the Bean Properties for location and sizing.
Q: Why can't I edit the attributes of some of the borders (e.g.: MatteBorder)?
A: Because of the bad way
in which Javasoft have written most of the Borders as non-beans, the attributes
are not settable. Most of the Border classes can only have their
attributes set in the constructor. JForge already has a hack to get around
the non-zero argument constructor problem with Borders, but to go further
and create a work-around for attributes which have no Set methods would
make JForge less flexible. There is a less-than-optimal solution
(setting the desired attributes at creation time), but this is a low priority.
Note that none of this affects properly written 3rd party borders.
Q:Why is there a long pause when the Bean Properties are first displayed for a component?A: Obtaining the properties for a bean is an expensive operation, time-wise. JForge has a dual-level caching system to speed up the loading of Property sheets that have already been displayed. Subsequent displays of a component's Property sheet are more than five times faster than the initial display.
Q: Why are some of the bean infos that come with JForge in the package uk.co.demon.sspl.beaninfo, some in pub.java.gui.beans, and some in a separately downloadable java.awt?
A: The beans infos in pub.java.gui.beans are public bean
infos that could potentially be used with other GUI Builders. There is
no JForge specific code in them. The bean infos in uk.co.demon.sspl.beaninfo
are JForge specific; the code makes calls to BuilderAPI and therefore
ties them to JForge. The bean infos in java.awt are there because
they need to access protected fields; being part of the same package as
the beans themselves means that they have that level of access.
Q: Is it possible to use AWT components with JForge?
A: Yes. However, it does require that AWT components are given
special BeanInfos. A tutorial on using AWT components with JForge will
be forthcoming.
Q: Is it possible to add external tools to JForge? Is it possible to plug in replacements for the file reading and writing? Is it possible to <insert programming task here>?
A: Yes. JForge comes with an API that provides many entry points
into the application. It also comes with public classes that can be recompiled
to add functionality. For example, if you don't like the way JForge reads
.class files and want it to read Java source, feel free to write
a source code parser and plug it in via the public menu class and the BuilderAPI.
For further details see the links to the documents at the end of this manual.
Q: Why does JForge start up and print a message on the console saying that "com.sun.swing.plaf.<some name>" can't be found?
A: This applies only to using Swing from the separately downloadable
archive (as opposed to the built-in version in JDK 1.2). Your CLASSPATH
is most likely incorrect. The Swing archive comes with several JAR files;
one of these, swingall.jar, contains everything for all platforms
and is the one you should have in your CLASSPATH. If you only want the
bare minimum, you would use swing.jar and a combination of the other
JAR files. Failure to include the correct ones in your CLASSPATH means
that you have an incomplete Swing set up and will result in this JForge
message. That is why it is suggested that you only include swingall.jar.
For further details on which ones to include for your system if you wish
to mix and match JAR files, please see the Swing documentation.
Q: I try to add a JFrame to the Work Bench and nothing happens apart from a dialogue popping up saying I have an incorrect CLASSPATH and exceptions appearing on the console. Why?
A: The answer to the previous question also applies to this one.
Shut down JForge and follow the instructions given above.
Q: Why does the second Tutorial say to add 10 to the Preferred size of the JButton?
A: Unless the Use Native Look and Feel box is deselected
in the JForge Preferences (Edit->Preferences on the Main Menu), JForge
will use the Native Look and Feel (LAF). However, unless Native LAF is
specifically set in a Java program, Cross Platform LAF is used. The Cross
Platform LAF may have a different Font compared to the Native LAF
and hence the PreferredSize setting of the button will be incorrect. As
the Cross Platform LAF has a Font that is different from the standard Microsoft
Font (it's slightly thicker), the button has to be lengthened to take account
of this difference when it is run outside of JForge.
Q: How do I add menus to a Frame? They aren't available on the component palette.
A: Menus are an attribute of JFrames. Pull up the Property Sheet for the JFrame and click on the MenuBar section.
For a step-by-step guide to the basics of creating a form, see the tutorial in the tutorial directory.
For technical information on programming with JForge, the following documentation is relevant:
JForge API and Related Packages
Index of all Fields and Methods