Java Power Tools Tutorial - Overview of the Toolkit

Introduction

Overview of the Java Power Tools (JPT) design:

The JPT toolkit has been designed to support rapid and robust development of programs that use GUIs to communicate with the user. At the core of JPT is the gui package that contains classes that implement a variety of GUI components and controls the installation of these components in the actual GUI frame. Most of the remaining packages have as their main task the support of the communication between the GUI display and the internal program data model. Because all communication between the GUI display and the program data model is via well formed and encoded strings, these packages provide robust support for the conversion of data values to and from the string format.

Classes that represent information that is expected to receive its values from the current state of the GUI implement the Stringable interface - defining methods for encoding the data model information as a string and extracting the data model information from a well-formed string. The GUI components that allow user input implement the Displayable interface - defining methods for encoding the state of the view as a string and extracting the information needed to refresh the view from a well-formed string. Malformed data input for appropriate GUI components is automatically trapped and referred to the user for remedy action.

At the base of all of JPT is a collection of XObject classes - one for each Java primitive type. These classes provide the foundation for building more complex Stringable objects by creating Stringable mutable object versions of the primitive data types.

Classes in the parser and codec packages are used to encode and decode the data model values from and to strings. In addition, the filters package allows the programmer to specify further constraints on the allowable range of input values.

The JPT also supports a console object that provides three streams - the input, the output, and the error - in a manner similar to the Java native System console. However, the JPT retains full control of the console, supports differential coloring of the three streams, error checked parsing of the typed input, and the option to save the transcript on closing.

The utilities package defines the JPTConstants interface, and provides utilities for arrays, dimensions, sound, files, the MathUtilities class, and a StringableFactory for constructing Stringable objects of a given class.

Overview of the packages in the JPT

edu.neu.ccs:

This package contains the core classes that are the foundation of the entire JPT toolkit. The Stringable interface is implemented by all classes that contain a data model that needs to communicate with the user interface. The X-Objects provide a collection of Stringable mutable objects corresponding to the Java primitve types and a small set of other types.

Stringable interface

An object that implements the Stringable interface must implement two member functions:

void fromStringData(String s) throws ParseException

String toStringData()

that perform the encoding/decoding of the relevant data model values into/from a String.

The functions need not encode all of the member data, but only those relevant data items that will be set from the input supplied by the user. Well formed functions will act as inverses of each other so that

MyObject newObj = new Myobject();

myObject.fromStringData(oldObj.toStringData());

will create newObj that has the same relevant values as the original oldObj.

Conversely, if the object has set its model state calling fromStringData(oldString) and later calls its toStringData method, the resulting newString would represents the same state of this object as was represented by the original oldString. The parsing may cause the two Strings to have a different form, but they will set the relevant model data to the same state.

X-objects

The XObject for a specific primitive type is a Stringable object version of the corresponding primitive type. It mirrors most non-static methods in the corresponding Java convenience class, and adds the toStringData, fromStringData, setValue, and getValue methods, as well as a static convenience method that converts an array of XObjects into a non-mutable array of elements the corresponding primitive type.

When extracting values from the user input, we typically first create the corresponding XObject, then use getValue method to assign the resulting value to a variable of the primitive type.

edu.neu.ccs.codec:

This package contains the interface for classes that implement encoding and decoding of data to and from Strings (codec-s). It also contains two typical codec implementations and a utility class for installing a specific codec.

edu.neu.ccs.console:

This package provides access to the shared JPT console that supports three I/O streams: console.in, console.out, and console.err, with robust input checking and thread control.

ConsoleAware	Interface to be implemented by classes of objects that desire access to the shared text console. This interface simply provides access to the shared ConsoleGateway object console providing text input and output capabilities for threads running in the Java Virtual Machine. Note that it is possible to use System.in, System.out and System.err to directly access the Java Virtual Machine console, but such access may be restricted by a security manager of the Java Virtual Machine, or may not be supported by the Java Virtual Machine on which a thread is running. The shared console object made accessible through this interface has further functionality not provided by the System stream objects.
ConsoleGateway	Provides methods for using a console object to perform text input and output operations. An instance of this class uses the standard system streams, System.in, System.out and System.err by default, but can be "activated". An "activated" console is a separate floating window that displays text output and gathers text input using functionality not provided by the system streams. As some Java Virtual Machines restrict access to the system streams through use of a security manager, an instance of this class may be the only way to provide a text console for an applet or application.
ConsoleGateway.ConsoleInputStream	Inner class of ConsoleGateway that provides input functionality for a console object.
ConsoleGateway.ConsoleOutputStream	Inner class of ConsoleGateway, and derived class of OutputStream that provides output functionality for a console object.

edu.neu.ccs.filter:

This package specifies a StringableFilter interface that consists of a single function

Stringable filterStringable(Stringable obj) throws FilterException

that is implemented by a number of classes in the package (abstract classes and implemented concrete inner classes) or can be implemented by the programmer to fit some desired requirements. The input object passes through the filter and is returned in a possibly modified state. If the input object does not satisfy the filter constraints, FilterExeception is thrown.

Several filters can be combined into a StringableFilterSequence in a pipeline fashion. The StringableFilterSequence itself implements the StringableFilter interface.

StringableFilter	Interface to be implemented by classes of objects that have the capability of filtering Stringable objects that are generated by user input or created internally for computation. This interface defines the specification for filtering Stringable objects, but does not specify what form of filtering procedure will be applied.
BoundFilter	Abstract superclass for filters that represent an inclusive or exclusive bounded range.
CaseActionFilter	Filter used for modification of XString objects, in order to change case, restrict particular character codes, &c.
MaximumBoundFilter	Filter that enforces an inclusive or exclusive numeric upper bound by throwing an exception when the data to be filtered violates the bound.
MinimumBoundFilter	Filter that enforces an inclusive or exclusive numeric lower bound by throwing an exception when the data to be filtered violates the bound.
NumericFilter	Abstract superclass for filters that apply to numeric values.
RangeFilter	Filter that enforces inclusive or exclusive numeric upper and lower bounds by throwing an exception when the data to be filtered violates either bound.
StringableFilterSequence	An ordered collection of filter objects similar to a List that is itself a filter representing the ordered application of the list of filters.
FilterException	Exception to be thrown by a filter when the object to be filtered does not meet the criteria for the filter.

edu.neu.ccs.parser:

The parser package encapsulates the parsing of input Strings to create instances of user's data model objects. The Parser interface contains a single function

Object parse(String data)

The package defines an abstract class AbstractParser for all parsers and instantiates one specific JPTParser class. In addition, the ParserUtilities class can be used to install or get the default parser.

The JPTParser is used to covert input String to a numeric value. It performs full parsing of arithmetic expressions and evaluation of mathematical function from java.lang.Math class.

edu.neu.ccs.pedagogy:

This is a collection of classes useful for specific pedagogical illustrations and experiments. Currently it contains a single class Turtle that behaves in a manner similar to the familiar LOGO™ turtle.

edu.neu.ccs.util:

This package contains several utility classes and a common interface of shared constants. Notice the use of StringableFactory.

JPTConstants interface	Interface that provides common shared constant values for classes in the JPT.
DimensionUtilities	Provides utilities for manipulating Dimension objects.
FileUtilities	Provides utility methods that encapsulate file input and output operations.
JPTUtilities	Provides general utility methods used by various classes in the JPT.
MathUtilities	The class MathUtilities collects several useful static mathematical functions. The class may be viewed as an extension of the tools found in java.lang.Math.
SoundUtilities	Provides static utility methods for playback of sound.
StringableFactory	Class whose instances can construct new instances of Stringable objects of a given class using reflection. Use of this type of factory is the preferred technique for TypedViews and GeneralViews to create and return data models built from user input data.
SystemUtilities	Provides utility methods for gathering information about the system and activating system components.
FileExistsException	Exception thrown to denote the existence of a file that could be inadvertently overwritten if no notification were made of its presence.
JPTError	An error thrown in the JPT that indicates a programming problem rather than a user or system error, which should not need to be caught within an application or applet.

edu.neu.ccs.gui:

The gui package contains several sets of classes that support the creation of powerful GUI components and their installation in the GUI with appropriate layouts and functionality.

The interaction between the data model and the view is supported through the following types of GUI components:

· view interfaces that provide specification for the view - model interaction

· views that allow user input and may display the state of a model

· components (output views) that display the state of a model, or add other information, but do not provide for user input

· graphics support

· actions performed in response to user button selection

· actions performed in response to events

· frames to hold an entire GUI

· temporary dialogs for immediate user interaction

· a console for console interactions - implemented is a separate package

The control over the appearance and functionality of the GUI is provided in an additional collection of classes in the gui package as follows:

· panels that allow for creating aggregates of GUI components

· panels that support direct mouse manipulation of objects

· wrapper containers that enforce the size requirements of the installed GUI components

· layouts that control the placement of the components in the GUI

· error technology - classes that support robust response to user input errors

· specialized technology - classes that support the overall gui package

We provide first a brief overview of the typical steps in creating a GUI. The GUI may be installed in a standalone frame, or may be created as a dialog during the execution of the program. The JPTFrame class is used to create a standalone frame which uses the standalone Java GUI thread to process its interactions.

· The programmer selects the views needed for the user interactions (ColorView, TextFieldViews, BooleanView, etc.) and instantiates them as member data of the GUI application.

· The programmer creates the methods that will perform the desired actions in response to the user's commands (typically one function per action button). For each action, the programmer instantiates a corresponding Action object that creates a button and connects it to the action method.

· Next the programmer decides on the additional user displays - text to be shown in Annotations, titles, etc. and designs the overall appearance of the GUI.

· Finally, the wrappers and containers are used to recursively install the GUI components in the main DisplayPanel and the main DisplayPanel is installed in the JPTFrame.

View Interfaces:

The Displayable view interface allow the implementing class that represents a GUI Component to specify how its view state can be converted to and set from a well-formed String by defining the getViewState() and setViewState() methods. Additional methods provide robustness and flexibility.

The TypedView interface extends Displayable. It provides an interface for views that are designed to display and input data of a specific type. It includes methods that return the type for which the implementing view was designed, methods to get and set InputProperties, and methods to demand or request an Object of the designated type.

The GeneralView further extends the TypedView to allow the user to set the type for the view at construction or at run time.

Displayable -> TypedView -> GeneralView

Displayable	Interface to be implemented by a Component whose input widget values (view state) can be translated to and from a String representation. This interface is the equivalent for view objects to what the Stringable interface represents for model objects. The functionality of the entire GUI package of the JPT assumes that each classes implementing this interface is a derived class of Component, although this requirement cannot be policed by a compiler.
TypedView	Interface to be implemented by a class of interface objects whose data state is appropriate for input of a particular class of model objects. Certain classes that implement this interface should also implement the Fragile interface, but this is not a requirement.
GeneralView	Interface to be implemented by a class of interface objects whose view state may be appropriate for input of various classes of model objects. Most classes that implement this interface should also implement the Fragile interface, but this is not a requirement. A GeneralView is a powerful and general input component that must be capable of instantiating any Stringable class of objects. A class of input component that can only instantiate a single class of Stringable objects should implement the TypedView interface.

Views (user input views):

Views are GUI components that allow the user to input some values. The two views TextFieldView and FileView require a String input that needs to be well formed. These views implement the Fragile interface.

All views implement the Displayable interface that provides for converting the input into a well formed String or setting the view state from a well-formed String via the setViewState() and getViewState() methods. In addition, all these views implement the TypedView interface that includes the demandObject() and requestObject() methods that deliver the user input cast as an object appropriate for the class represented by the view.

Because the TextFieldView plays a critical role in user's input of text and numerical data, we describe it in some detail first. It is the only view where the user's input as a String can be automatically converted to one of the Java primitive types. This view is equipped with a robust error checking strategy.

The TextFieldView class contains convenience methods requestThisType() and demandThisType() for all of the following possible types of input: String, byte, short, int, long, float, double, boolean, char, BigInteger, and BigDecimal. These methods may also take an optional StringableFilter argument that enforces additional constraints on the input.

All these methods invoke parsing of the input String using the appropriate fromString() method of the corresponding XThisType class. If the parsing fails, a ParseException is caught and a modal ErrorDialog is displayed requesting corrective action from the user. For the demand-style input methods the only way to exit this dialog is by providing satisfactory input. The ErrorDialog for the request-style input methods includes a Cancel button. If the user exits through this button or by closing the dialog, a CancelledException is thrown. If the user supplies a Suggestion as the part of InputProperties for this view, a button labeled Suggestion also appears in the ErrorDialog - suggesting to the user a possible valid input String.

For example a programmer may define counterTFV with four String arguments as follows:

TextFieldView counterTFV = new

TextFieldView(defaultString, errorPrompt, errorDialogTitle, suggestion);

then extract the user input as follows:

int counter = counterTFV.demandInt();

and display a new value of the counter by:

counterTFV.setViewState("" + counter);

TextFieldView

A GeneralView for input of Stringable objects or elements of the data state of a Stringable object.

Other user input views:

These views correspond to similar Java views, but implement the Displayable and TypedView interfaces. In addition, the ColorView provides functionality beyond the basic Java JColorChooser.

BooleanView	A TypedView for the input of a boolean value via a checkbox.
ColorView	A TypedView for the input of a Color containing both a box displaying the selected color and an optional text field for direct input of the component values that make up the selected color. The currently selected color value can be changed through a JColorChooser dialog that appears when the view is clicked a given number of times. The currently selected color value can be changed by entering the component values for the desired color into the text field in the following formats: red, green, blue red, green, blue, alpha Changes to the input in the text field take effect when the user presses the Return key. Each of the component values must be an integer value in the range [0, 255].
DropdownView	A TypedView for selection of one of various String choices.
OptionsView	A TypedView for selection of one out of various indexed and labeled choices represented by JRadioButtons.
SliderView	A TypedView for input of int values in a bounded range using direct manipulation.
TextAreaView	A TypedView for input of Strings that may represent multiple lines of text.
FileView	A TypedView for input of a filename that either represents a path to an existing file or a path to which a file could be written. Provides a button that brings up a JFileChooser for easy choice of an existing file.
FileView.ExtensionFileFilter	Inner Class: A file filter that accepts all files with a specific extension.

Components (output views):

This collection of classes is used to display a view of some object, but not receive keyboard input from the user.

The ImageCapsule and the ShapeCapsule can be directly manipulated by the mouse (change size and location) when installed in the Zoo. These objects can also be installed in other panels as normal components.

Annotation	A Displayable component representing an annotation in a GUI, such as the prompt for an input object or the caption for an image. The functionality of this class is based on the functionality of the JLabel class provided in the javax.swing package, with the following additional functionality: · An annotation can display multi-line text. · An annotation can be in an alert state. · An annotation can have a separate icon to denote that it is in an alert state.
XObjectView	View for output of the String representation of the state of an XObject. Implements Displayable, PropertyChangeListener, ConsoleAware
ImageCapsule	A JComponent encapsulating an image, and acting as its view.
ShapeCapsule	A JComponent encapsulating a shape, and acting as its view.

Graphics:

The BufferedPanel class allows the programmer to display any kind of graphics in an automatically double-buffered pane that automatically refreshes itself when necessary. The BufferedPanel comes with an installed MouseActionAdapter and the programmer only needs to install the appropriate MouseActions that correspond to the desired mouse events. The PlotTool and PlotMark classes encapsulate the drawing of scaled graphs, charts, and images.

BufferedPanel	A panel that maintains a persistent graphics state by repainting itself from a stored BufferedImage object. This behavior differs from the double-buffering provided in JComponent in that its intention is not necessarily to provide flicker-free repaints and will retain the effects of method calls on its graphics context regardless of whether or not those calls are in a paint method. To ensure proper performance, the user should paint to the buffer graphics context, which is available through the getBufferGraphics method, rather than a component graphics context provided as an argument to the paint method or returned by the getGraphics method.
PlotTool	Encapsulates the transform between world and image coordinates for use in plotting data graphs. Provides functions to plot or mark an array of Point2D data or an array of such Point2D arrays. Automatically handles the painting of axes, grid lines, and tick marks on the axes. The "world" coordinate space refers to the coordinate space inhabited by the data arrays or functions that are to be plotted. The "image" coordinate space refers to the coordinate space of the graphics context on which the plots are painted.
PlotMark	Helper class for drawing geometric shapes or marks at a specified point in a graphics context.
BufferedPanel.Painter	Panel that paints the internal BufferedImage that maintains the persistent graphics state of a BufferedPanel.

Example of use of BufferedPanel:

// square window for painting

private BufferedPanel window =

new BufferedPanel(BUFFER_WIDTH, BUFFER_HEIGHT);

// get the mouse action adapter from the graphics window panel

MouseActionAdapter adapter = window.getMouseActionAdapter();

// get the graphics context to draw line, rectangle, oval, image...

Graphics2D G = window.getBufferGraphics();

Actions and related classes

The ActionsPanel class is a GUI component that contains a button for each action installed in it. This can be specified by adding one Action at a time, or supplying an array of Action objects to the constructor.

The SimpleAction class simplifies the definition of individual actions. This class extends Java AbstractAction class by providing an abstract method perform() with no parameters. The programmer defines the action and its perform() behavior by instantiating an object in a class built via the on-the-fly extension technique. The constructor for SimpleAction takes a String and possibly an Icon to be used as a label for the corresponding button.

So, for example, the following code defines a SimpleAction object doThisAction. The constructor argument specifies that the button label will be "Do This Button". The perform() method is defined on-the-fly with its only task being a call to the doThis() method. The doThis() method then specifies how the program responds to the activation of this button. It is a member function in the class that defined the SimpleAction object doThisAction.

/** Action to execute doThis method. */

protected SimpleAction doThisAction = // define action object instance

new SimpleAction("Do This Button") { // button label as argument

// for the constructor

public void perform() { doThis(); } // method called by perform

// inside the on-the-fly class

};

The ActionSequence class allows the programmer to specify a sequence of methods to be grouped into a single Action. The ThreadedAction and DialogAction classes perform specialized tasks. Also, see Event Action Adapters.

ActionsPanel	A panel containing Action objects represented by buttons that initiate their respective actions.
SimpleAction	A trivial extension of the Java AbstractAction class used to simplify the programming interface for a class representing a GUI action.
ActionSequence	An ordered collection of Action objects similar to a List that is itself an Action object representing the ordered execution of the list of actions.
ActionWrapper	Base class for encapsulating Action objects to provide extra functionality in ThreadedAction and DialogAction
ThreadedAction	An ActionWrapper that performs its encapsulated action in a newly created separate thread.
DialogAction	Encapsulates an Action that will be performed for a GeneralDialog.

Event Action Adapters:

This is a collection of sets of three classes, each designed to simplify the handling of a specific set of events - one for each of the following event categories: Change, Focus, Key, Mouse, PropertyChange, Window.

We explain the functionality using the mouse events as an example.

The MouseAction class acts in a manner similar to SimpleAction. The programmer specifies the methods that should be executed when a specific MouseEvent is signaled. The MouseActionEvent class represents the class of events that can be triggered by some mouse behavior (drag, click, move, etc.). The MouseActionAdapter class implements the MouseListener interface and allows the programmer to install MouseActions that specify the method to be performed in response to specific MouseEvents.

The GUI component that is expected to listen to the mouse events installs a MouseActionAdapter object as follows:

MouseActionAdapter adapter = new MouseActionAdapter(this);

It can then install the actions to be performed in response to specific mouse events as follows:

// track the mouse drag

adapter.addMouseDraggedAction(new MouseAction() {

public void mouseActionPerformed(MouseEvent mevt) {

track(mevt);

}

});

and leverage the information received from the mouse events as follows:

public void track(MouseEvent mevt) {

// record the mouse position in its text field views as it is dragged

xMouseTFV.setViewState((int)mevt.getX() + "");

yMouseTFV.setViewState((int)mevt.getY() + "");

}

ChangeAction	Encapsulates an action that is performed as a result of a ChangeEvent.
ChangeActionAdapter	An adapter class for receiving change events, and performing actions in response to those events.

ChangeActionEvent	Class of events representing an action triggered by a change event.
FocusAction	Encapsulates an action that is performed as a result of a FocusEvent.
FocusActionAdapter	An adapter class for receiving focus events, and performing actions in response to those events.
FocusActionEvent	Class of events representing an action triggered by a focus event.
KeyAction	Encapsulates an action that is performed as a result of a KeyEvent.
KeyActionAdapter	An adapter class for receiving key events, and performing actions in response to those events.
KeyActionEvent	Class of events representing an action triggered by a key event.
MouseAction	Encapsulates an action that is performed as a result of a MouseEvent.
MouseActionAdapter	An adapter class for receiving mouse input events and performing actions in response to those events.
MouseActionEvent	Class of events representing an action triggered by a mouse event.
PropertyChangeAction	Encapsulates an action that is performed as a result of a PropertyChangeEvent.
PropertyChangeActionAdapter	An adapter class for receiving property change events, and performing actions in response to those events.
PropertyChangeActionEvent	Class of events representing an action triggered by a property change event.
WindowAction	Encapsulates an action that is performed as a result of a WindowEvent.
WindowActionAdapter	An adapter class for receiving window events and performing actions in response to those events.
WindowActionEvent	Class of events representing an action triggered by a window event.

Windows:

The JPTFrame class is used to instantiate a GUI window that controls the overall user interactions in the standard Java GUI thread. Typically the class (e.g. myClass) that creates the GUI extends the DisplayPanel. This panel is then installed using the class main method by calling a static convenience method createQuickJPTFrame to create a new JPTFrame. This function takes two arguments. The first argument is a String that will be the title for the window. The second argument is generated by the call to the constructor for myClass to instantiate the actual panel.

// create a window titled "My Program"

// whose contents are defined by the MyClass constructor

public static void main(String[] args) {

JPTFrame.createQuickJPTFrame("My Program", new MyClass());

}

JPTFrame

An extended JFrame class that allows more flexible window closing operations and automatically resizes to ensure that the contents of the frame are the desired size regardless of frame insets.

Dialog:

The base class JPTDialog extends the Java JDialog. It allows the user to install a TypedView and contains an ActionsPanel where a programmer can install arbitrary actions. Programmer may also select whether this should be a modal dialog.

InputDialog encapsulates the typical tasks needed to extract user input as a Stringable object from a modal dialog. ErrorDialog is a further extension, used to control the handling of user input errors.

GeneralDialog allows the programmer to create arbitrary dialogs with general components and actions.

JPTDialog -> InputDialog -> ErrorDialog -> GeneralDialog

JPTDialog	Dialog box containing a TypedView and an ActionsPanel that contains actions that interact with the view.
InputDialog	A modal dialog box for input of a Stringable object that also provides static convenience methods for input using a provided input component. The input properties for the input object determine the input model for the dialog box. In the mandatory model, OK and Reset buttons are provided. In the optional model, a Cancel button is provided in addition to the buttons provided for the mandatory model If a suggested view state is present in the input properties for the given input component, a Suggest button is also provided.
ErrorDialog	A modal dialog box for input of Stringable objects that is used by the standard error handling strategy for Fragile components in the JPT.
GeneralDialog	A dialog box containing a Component and an ActionsPanel that contains actions to respond to and dismiss the dialog.
SimpleDialog	Provides only static convenience methods for simple modal dialog box input for one data item.

Panels:

The basic container for the GUIs is the DisplayPanel. It is extended by six different specialized panels as follows:

DisplayPanel -> Display

-> DisplayCollection

-> ArrayPanel

-> TablePanel

-> ActionsPanel

-> Zoo

ActionsPanel and Zoo are described elsewhere due to their special functionality.

The ScrollableDisplay is a wrapper that extends Java JScrollPane and can contain any Displayable object. Other wrappers will be described later.

DisplayPanel	A Displayable JPanel that recursively propagates Displayable method calls only to contained components that are also Displayable.
Display	A panel containing a Displayable object, with the option of a title and an Annotation.
DisplayCollection	A dynamic linear collection of Displayable objects, displayed using either a horizontal or vertical layout.
ArrayPanel	An abstract TypedView designed for input of an array of a single type of Stringable objects.
TablePanel	A DisplayPanel designed to use a TableLayout as its layout manager.
ScrollableDisplay	A JScrollPane that contains a single Displayable object, and delegates Displayable method calls to its viewport view.
Display.Settings	Data structure encapsulating the content and layout properties for a Display.

Panels that support direct manipulation:

The class ZooContainer and its derived classes Zoo and ZooGroup control components that can be moved and manipulated by a mouse control during the program execution. Also see ImageCapsule and ShapeCapsule. These classes are designed for direct manipulation in ZooContainers.

DisplayPanel -> ZooContainer -> Zoo

-> ZooGroup

A Zoo is a container used to contain components that can be moved and resized through direct manipulation. In this way, a Zoo is like a desktop for components.

An individual component, or a collection of components, can be selected through direct manipulation or through method calls. A selected component is painted with a box surrounding its bounds. Selected components can be retrieved using methods defined in the ZooContainer class. A component is selected if it is clicked with the mouse. To select multiple components, hold the Shift key when selecting the components.

Components in a Zoo are called child items. All child items are contained at the top level of the Zoo. Components can be grouped into a ZooGroup, which is treated as a single entity in the Zoo. Components in a Zoo that are contained within a group are called items. Since a group can be recursively contained within a group, there can be any number of levels to the containment hierarchy for items in a Zoo. Only the top level items are considered to be child items. A Zoo could have only one child item, but many items, if the single child item is a group of components.

If a Zoo is restricting the bounds of its components, it will not allow a component to be moved or resized so that the component is not completely contained within the bounds of the Zoo. If a Zoo is not restricting the bounds of its components, a component can be moved or resized to any extent. A Zoo restricts bounds by default.

If a Zoo is in design mode, a child item can be moved and resized by clicking and dragging a side or corner of the component as noted by a rectangular anchor. An anchor is not shown if the component can not be resized. A component can not be resized to a width or height out of the limits of its minimum and maximum sizes. If a Zoo is not in design mode, all of its items behave normally. A Zoo is in design mode by default.

A 3rd dimension -- z-order -- is applied to the child items in a Zoo. This z-order determines the order in which components are painted and will cause one of two overlapping components to appear to be on top of the other. Several methods described below can modify the z-order of child items contained in a zoo. Items in a group reside at the z-order of the group itself. The z-order within a group determines the order in which the components of the group are painted.

Technical details:

This panel assumes an AbsoluteLayout. Behavior is undefined if this panel is set to have a layout other than an AbsoluteLayout.

A grouped component resized through direct manipulation will appear to scale in size as the group is resized, whether or not the component will actually scale in size when the resize is completed. If the parent container for the grouped component does not scale its contents, the grouped component will snap back to its original size when the resize is completed.

ZooContainer

Abstract superclass for containers used in a Zoo. Top-level components in a ZooContainer are subject to a z-ordering that affects the display of the components. Z-order is implemented in the same manner as it is for standard Java containers: in a set of n contained components, a z-order position of 0 represents the top component and a z-order position of n - 1 represents the bottom component. The z-order position of a given component is equal to the number of components relatively higher than the given component. Within a ZooContainer, the top-level components are considered "child items" of the container. Components which reside in a ZooContainer at any level of nesting, including the top-level, are considered "items" of the container. A ZooContainer has the capability of associating collections of top-level components into groups. A group may contain any number of nested groups. A group at top level has a single z-order position and is represented by a ZooGroup. When a group at top level is disassociated, its grouped components are returned to the top level where they assume the relative z-order of the group, and actual z-order positions defined by their z-order within the disassociated group. Note that this panel assumes an AbsoluteLayout. Behavior is undefined if this panel is set to have a layout other than an AbsoluteLayout.

continued ...

Zoo	ZooContainer allowing selection and direct manipulation of components.
ZooGroup	Associative collection of components contained within a Zoo. Groups may be nested to an arbitrary depth. By default, a group has a transparent background and its bounds are determined by the union of the bounds for the components it groups. When a group is resized, its contained components are scaled accordingly so that they maintain the same relative size and location within the group. The minimum and maximum sizes for a group are determined by minimum and maximum scaling factors that can be applied to the contained components without violating the minimum and maximum sizes for any of the contained components. This panel assumes an AbsoluteLayout. Behavior is undefined if this panel is set to have a layout other than an AbsoluteLayout. A grouped component resized through direct manipulation will appear to scale in size as the group is resized, whether or not the component will actually scale in size when the resize is completed. If the parent container for the grouped component does not scale its contents, the grouped component will snap back to its original size when the resize is completed.
Laminate	Extends JComponent, is used to "laminate" an existing component by mimicking its size and location and always maintaining a higher z-order, in order to impart mouse handling without intervention by the laminated component.

Wrapper Containers:

The wrapper containers and panel classes control the organization and appearance of the GUI components. They can recursively contain other containers or components. There are four wrapper classes that control the size and orientation of the GUI components. The class hierarchy of wrappers is the following:

ComponentWrapper -> DisplayWrapper -> TypedViewWrapper -> GeneralViewWrapper

ComponentWrapper	Wrapper for a single component that uses a AlignedLayout and faithfully respects minimum, maximum, and preferred sizes.
DisplayWrapper	Wrapper for a single Displayable object that uses a AlignedLayout and faithfully respects minimum, maximum, and preferred sizes.
TypedViewWrapper	Wrapper for a TypedView that uses a AlignedLayout and faithfully respects minimum, maximum, and preferred sizes.
GeneralViewWrapper	Wrapper for a GeneralView that uses a AlignedLayout and faithfully respects minimum, maximum, and preferred sizes.

Layouts:

These classes are convenience layout managers used in the installation of GUI components.

AbsoluteLayout	Layout manager allowing child components of a container to control their own locations and sizes.
AlignedLayout	Layout that maintains a single component in a justified position within the parent container.
CenterLayout	Layout that maintains a single component in the absolute center of the parent container.
TableLayout	Layout manager effecting a table with an arbitrary number of rows and columns, each with their own width and height.

Error Technology:

Any GUI component can signal that it is in an Alert state by implementing the AlertListener interface that allows the programmer to specify what action to take at the start and at the end of an AlertEvent. AlertListener extends the Java Listener interface that in turn allows this class to be included in the list of registered listeners and receive notification of various events. The class AlertEvent extends the Java AWTEvent and can signal whether the alert is on or off.

AlertEvent	Class of AWTEvents encapsulating the designation that a graphical input object should enter or exit alert status.
AlertListener	Interface to be implemented by a graphical interface component capable of altering its visualization to signal a user alert state.

The classes that implement the Fragile interface need to define two methods that allow the programmer to register and de-register a specific MalformedDataListener via the addMalformedDataListener and removeMalformedDataListener methods.

The MalformedDataListener interface in turn requires that the implementing class defines the method dataMalformed() that will take the necessary action in response to the passed MalformedDataEvent. This interface extends the AlertListener.

The MalformedDataEvent class records as its member data the ParseException that triggered the event and the String that was parsed when the exception occurred, or the String that was provided to remedy the original error.

The classes that implement TypedView interface use these classes to implement a robust error strategy that signals the error in parsing the input by setting the misbehaving view into the alert state and displaying a modal error dialog requesting corrections from the user. Upon correction (or, when allowed, dismissal) of the error, the modal dialog disappears and the alert state is turned off. The programmer leverages most of this work from two functions: demandObject() and requestObject(). The demandObject() function cannot terminate until a satisfactory input is provided. The requestObject() function allows the user to cancel without correcting the error by throwing CancelledException.

MalformedDataEvent	Class of AWTEvents encapsulating the designation that a graphical input object has just been verified to have a malformed view state, or has just had its previously malformed view state restored to a well-formed state.
MalformedDataListener	Interface to be implemented by a class of graphical interface components that desire to be notified when Fragile interface components encounter malformed data.
Fragile	Interface to be implemented by classes of graphical interface components whose view state may be malformed. This is most appropriate for user editable fields, but also may be appropriate for other interface controls that may not be malformed but could have a view state outside of a valid range. This interface only specifies that the component must be able to register and deregister objects from receiving notification when the component is found to have a malformed view state and when the view state of the component is returned to a well-formed value.
CancelledException	Exception designating that an input operation was cancelled by the user.
InputProperties	A property list used to store properties pertaining to input components. There are four bound properties for an input properties object that represent the standard properties for an input component and the parameters it contributes to a standard error strategy: INPUT_PROMPT - prompt explaining the error DIALOG_TITLE - title for the error dialog INPUT_MODEL - mandatory or optional(can cancel) SUGGESTION - suggested input to fix error This class implements a data structure that can be used to store any number of input properties of any type, keyed using String property names. An input properties object can be created so that it shadows the properties stored in a preexisting input properties object or the base input properties object that contains default property values. Properties with the same name that are stored in the top level input properties object are returned in favor of lower level properties stored in the shadowed input properties object(s). Properties stored in the lower level input properties object(s) are returned by the top level input properties object if those properties are not shadowed by higher level properties with the same names.

Specialized Technology:

These three classes simplify some of the calculations for plotting and positioning of table items.

CellPosition	Encapsulates a row-column pair referencing an index in a 2-dimensional array.
Interval	Encapsulates an interval of double precision numbers. The endpoints of the interval may be supplied in any order and will be ordered automatically.
Transform1D	A 1-dimensional transform class for simple affine scaling and for working with the components of a rectilinear 2-dimensional affine transform. The transform has the form z --> factor * z + offset.

Organizers:

These classes and interfaces help in organizing the tasks of building some of the components.

TableGenerator

Interface for a class that can be used to make the contents of a table by implementing method: public Object makeContents(int row, int col) Creates the object that will become the contents in the given row and given column of the table.

ComponentFactory

Provides one static method that constructs an appropriate Component for suitable objects: public static Component makeComponent(Object o) Returns a Component suitable for the given object. · If the parameter is a Component then that Component will be returned. · If the parameter is a String, Icon, Image, Shape, or Action then the parameter will be suitably wrapped to form a Component and that Component will be returned. · Otherwise, null will be returned.