Updated on September 15, 2005 (251 files)

Java Power Tools Packages

Java Source Files in edu.neu.ccs (42 files)

• The Stringable interface
• Abstract Stringable classes
• Stringable encapsulations of the boolean and char types
• Stringable encapsulations of the basic numeric types including complex numbers
• Stringable encapsulations of the basic numeric types using hexadecimal
• Stringable encapsulations of the basic geometric shapes
• Simple tools for handling strings and parsing. These tools are used in implementing Stringable for several classes.
• Stringable encapsulations of some common object types
• Interfaces and tools for dealing with functions and parameters in general and Stringable encapsulations for real and complex polynomials and for Fourier series

The Stringable interface

The Java file Stringable.java

The Stringable interface describes data model objects whose state can both be encapsulated into a String (using toStringData) and be set from a suitable String (using fromStringData).

In particular, a Stringable object is mutable which is often more convenient for dealing with user interaction than immutable types.

Back to top of edu.neu.ccs or back to top of page

Abstract Stringable classes

The Java file XObject.java

The abstract class XObject is the standard base class for building Stringable objects.

The Java file XNumber.java

The abstract class XNumber is the standard base class for building numeric Stringable objects.

Back to top of edu.neu.ccs or back to top of page

Stringable encapsulations of the boolean and char types

The Java file XBoolean.java

The Java file XChar.java

Back to top of edu.neu.ccs or back to top of page

Stringable encapsulations of the basic numeric types including complex numbers

The Java file XByte.java

The Java file XShort.java

The Java file XInt.java

The Java file XLong.java

The Java file XFloat.java

The Java file XDouble.java

The Java file XComplex.java

Back to top of edu.neu.ccs or back to top of page

Stringable encapsulations of the basic numeric types using hexadecimal

The Java file HexXByte.java

The Java file HexXShort.java

The Java file HexXInt.java

The Java file HexXLong.java

The Java file HexXFloat.java

The Java file HexXDouble.java

Back to top of edu.neu.ccs or back to top of page

Stringable encapsulations of the basic geometric shapes

The Java file XPoint2D.java

The Java file XLine2D.java

The Java file XRect.java

The Java file XSquare.java

The Java file XOval.java

The Java file XCircle.java

The Java file XRoundRect.java

The Java file XRoundSquare.java

The Java file XInterval.java

For additional Stringable geometric types, see also PathNode and PathList in the package edu.neu.ccs.gui.

Back to top of edu.neu.ccs or back to top of page

Simple tools for handling strings and parsing. These tools are used in implementing Stringable for several classes.

The Java file Strings.java

Back to top of edu.neu.ccs or back to top of page

Stringable encapsulations of some common object types

The Java file XString.java

The Java file XBigInteger.java

The Java file XBigDecimal.java

The Java file XColor.java

The Java file Colors.java

The Colors class is a support class that supplies a large list of named RGB colors that may be entered directly by the user, may be used in the XColor method fromStringData, and may be accessed interactively in the dropdown view incorporated as an option into ColorView.

Back to top of edu.neu.ccs or back to top of page

Interfaces and tools for dealing with functions and parameters in general and Stringable encapsulations for real and complex polynomials and for Fourier series

The Java file XPolynomial.java

The Java file XPolynomialComplex.java

The Java file XFourier.java

The Java file Function.java

The class Function is a collection of interfaces that classify functions that accept and return values of type double according to the number and kind of direct function arguments. For example, a class that implements the interface Function.OneArg is required to have a method with the following signature.

public double evaluate(double x).

The Java file FunctionComplex.java

The class Function is a collection of interfaces that classify functions that accept and return values of type XComplex according to the number and kind of direct function arguments.

The Java file Parameter.java

Class Parameter is a collection of interfaces that classify functions that accept and return values of type double according to the number and kind of auxiliary function parameters. For example, a class that implements the interface Parameter.ArrayParam is required to have a method with the following signature.

public void setParam(double[] params)

The Java file ParameterComplex.java

Class Parameter is a collection of interfaces that classify functions that accept and return values of type XComplex according to the number and kind of auxiliary function parameters.

The Java file F.java

A class whose contents consists of higher order functions that take real functions as arguments and produce a real function.

The Java file FC.java

A class whose contents consists of higher order functions that take complex functions as arguments and produce a complex function.

Back to top of edu.neu.ccs or back to top of page

Java Source Files in edu.neu.ccs.codec (4 files)

• The Codec interface
• Two Codec implementations
• The Codec utilities

The Codec interface

The Java file Codec.java

The Codec interface describes the requirements for a tool that can encapsulated a String array into a String and then faithfully unencapsulate the String back into the original String array.

A Codec may be used to make a complex Stringable object out of Stringable member data objects.

Encoding and decoding operations should be performed through the methods of the class CodecUtilities rather than by directly calling a particular Codec.

Back to top of edu.neu.ccs.codec or back to top of page

Two Codec implementations

The Java file CountPrefixCodec.java

The Java file EscapedCodec.java

Back to top of edu.neu.ccs.codec or back to top of page

The Codec utilities used to convert between a String array and a String

The Java file CodecUtilities.java

Back to top of edu.neu.ccs.codec or back to top of page

Java Source Files in edu.neu.ccs.console (5 files)

• The ConsoleAware interface
• The ConsoleGateway class
• The ConsoleGateway.ConsoleInputStream inner class
• The ConsoleGateway.ConsoleOutputStream inner class
• The console implementation classes

The ConsoleAware interface

The Java file ConsoleAware.java

The ConsoleAware interface provides access to the console object that is shared by all threads in the program. The console object is an instance of the class ConsoleGateway. Methods that operate on the console object itself include activation of the console so that it uses its own window, selection of the default console settings, and provision of input-output utilities such as prompting that are used by the inner classes.

If you plan to manually initialize the console then the following calls are recommended:

• console.setActivated(true);
• console.selectColorTextScheme();

If you use the Java Power Frame (JPF) environment, then these calls will be done automatically.

The console object provides three data streams:

• console.in for input
• console.out for output
• console.err for error output

If the color text scheme has been enabled, then these streams will use the colors blue, black, and red respectively.

Input-output methods in console and console.in should normally not be called in the event handling thread. Use the class ThreadedAction to make an action (such as user input) run in its own thread. If you use the Java Power Frame (JPF) environment, then separate threads are created automatically for all methods in the JPF GUI so there is no need to deal with the threading issues manually.

Back to top of edu.neu.ccs.console or back to top of page

The ConsoleGateway class

The Java file ConsoleGateway.java

The methods provided by ConsoleGateway itself fall into three categories:

• Methods to control the default console settings
• Methods such as prompt, pressReturn, and confirm that handle common input-output activities
• Technical methods that are rarely called by the end user

Back to top of edu.neu.ccs.console or back to top of page

The ConsoleGateway.ConsoleInputStream inner class

The ConsoleGateway.ConsoleInputStream inner class provides the extended functionality for the input stream console.in. Input of primitive types and simple objects types is fully supported by robust methods that handle input error checking automatically and also parse and evaluate arithmetic and boolean expressions entered by the user. Below is a list of the main method names. Each method usually has several versions to allow the caller to customize the input behavior as desired.

• Methods setDataType and getDataType to control the class of the Stringable object being input
• Methods demandObject, demand, requestObject, request, and reading for input of a Stringable objects with various options
• demandByte
• demandShort
• demandInt
• demandLong
• demandFloat
• demandDouble
• demandChar
• demandBoolean
• demandString
• demandBigInteger
• demandBigDecimal
• demandColor
• requestByte
• requestShort
• requestInt
• requestLong
• requestFloat
• requestDouble
• requestChar
• requestBoolean
• requestString
• requestBigInteger
• requestBigDecimal
• requestColor

Back to top of edu.neu.ccs.console or back to top of page

The ConsoleGateway.ConsoleOutputStream inner class

The ConsoleGateway.ConsoleOutputStream inner class provides the functionality for the output streams console.out and console.err. This class extends the Java class java.io.OutputStream so much of its functionality is inherited from Java. Only a few utility methods are added to this base functionality.

Back to top of edu.neu.ccs.console or back to top of page

The console implementation classes

The following classes are used in the implementation of the console functionality and should normally not be called directly by the console user.

The Java file ConsoleInputListener.java

The Java file ConsoleTextPane.java

The Java file ConsoleWindow.java

Back to top of edu.neu.ccs.console or back to top of page

Java Source Files in edu.neu.ccs.filter (9 files)

• The StringableFilter interface and the FilterException class
• Abstract StringableFilter classes
• Concrete StringableFilter classes
• A class to compose StringableFilter objects

The StringableFilter interface and the FilterException class

The Java file StringableFilter.java

The Java file FilterException.java

The StringableFilter interface describes a single filter method that may be used to determine if a given Stringable object is suitable for further processing. If so, this method will return the object if it need not be modified or will return a new object if state changes must be made. If the given Stringable object is not suitable, then the method should throw a FilterException.

Back to top of edu.neu.ccs.filter or back to top of page

Abstract StringableFilter classes

The Java file NumericFilter.java

The Java file BoundFilter.java

Back to top of edu.neu.ccs.filter or back to top of page

Concrete StringableFilter classes

The Java file CaseActionFilter.java

The Java file MinimumBoundFilter.java

The Java file MaximumBoundFilter.java

The Java file RangeFilter.java

Back to top of edu.neu.ccs.filter or back to top of page

A class to compose StringableFilter objects

The Java file StringableFilterSequence.java

Back to top of edu.neu.ccs.filter or back to top of page

Java Source Files in edu.neu.ccs.gui (149 files)

• GUI interfaces for JPT and related support classes
• Basic Views and Widgets
• Layout Managers
• General Panels and related support classes
• Frames
• Actions
• Dialogs
• Error Handling
• Look And Feel
• Graphics Classes
• Shape Creation Classes
• Action Adapters
• Miscellaneous

Back to top of edu.neu.ccs.gui or back to top of page

GUI interfaces for JPT and related classes

The Java file Displayable.java

The Java file TypedView.java

The Java file GeneralView.java

The Java file StringObjectView.java

The three interfaces Displayable, TypedView, and GeneralView specifies a hierarchy of functionality for views intended primarily for mutable data models that are Stringable. The interface StringObjectView specifies the functionality for views that can associate a String represented in the view with an existing Object in the model. This interface may be used for mutable or immutable data models.

The Displayable interface requires methods to deal with the view state of a view, that is, the portion of the state that is in correspondance with a data model. Incidental aspects of a view such as geometry and color are not part of the view state. A Displayable can set or get the current view state as a String, set or get a similar default view state, reset the view to its default state, and handle setEnabled calls by recursive propagation to internal component objects. The Displayable interface does not make any assumptions about the data model.

The TypedView interface extends Displayable and requires methods that deal with the data model. A TypedView can return the class of its data model via the method getDataType. In practice, this class should implement Stringable. A TypedView can also manage the extraction of its view state and the creation of a corresponding data model object via the methods demandObject and requestObject. Both methods totally encapsulate the error checking process so that if the view state is invalid for the desired type of return object then the user will be prompted to make corrections. The method demandObject insists that the user provide valid input while the method requestObject offers the option of cancelling the input process if the data is invalid.

The GeneralView interface extends TypedView and adds the method setDataType. Thus, a GeneralView is a TypedView that is able to handle multiple Stringable data types. The GeneralView interface requires additional methods beyond the method setDataType to allow such views to be used with great flexibility. The prime examples of GeneralViews are TextFieldView and DropdownView.

The StringObjectView interface requires methods that reflect the implicit mapping of strings to objects and objects to strings. The methods getSelectedString and getSelectedObject allow a caller to query the state of the view either by its selected string (which is visible in the view) or by its associated object (which is in the model). In most cases, the user will make selections interactively but it is also possible to set selections directly using the methods setSelectedString and setSelectedObject. The methods getSelectedObject and setSelectedObject permit a caller to work with a StringObjectView entirely in terms of objects in the model which is quite convenient. The prime examples of StringObjectViews are StringObjectRadioPanel and StringObjectDropdown.

Both GeneralView and StringObjectView require methods addActionListener and removeActionListener that will support the automatic execution of actions after an interactive change of the selection in the view by the user.

The Java file GeneralViewSupport.java

The GeneralViewSupport class provides the core functionality of a GeneralView in such a way that actual GeneralView objects can delegate much of their work to this class. Normally, this class is used internally in a GeneralView object.

The Java file InputProperties.java

InputProperties is a class utilized in the specification of the TypedView interface through get and set methods.

An InputProperties object is a property list used to store properties pertaining to input components.

There are four bound properties for an input properties that represent the standard properties for an input component and the parameters it contributes to a standard error strategy:

• INPUT_PROMPT: the error dialog prompt
• DIALOG_TITLE: the error dialog title
• INPUT_MODEL: either JPTConstants.OPTIONAL or JPTConstants.MANDATORY
• SUGGESTION: either null or a String containing a suggestion to the user to help resolve an error

The use of an InputProperties object by a TypedView object permits the TypedView object to control what will happen if an error dialog is needed during input. In particular, if the INPUT_MODEL is OPTIONAL then the error dialog will have a CANCEL button whereas if it is MANDATORY then there will be no CANCEL button and the user will be required to submit valid input.

The InputProperties 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 InputProperties object or the base InputProperties object that contains default property values.

The Java file CancelledException.java

CancelledException is an exception designating that an input operation was cancelled by the user.

Back to top of GUI interfaces or back to top of edu.neu.ccs.gui or back to top of page

Basic Views and Widgets

The Java file TextFieldView.java (one line text input)

The TextFieldView class is a GeneralView designed to input a single line of text using a Java JTextField. A TextFieldView may be used to input any Stringable that may be set using a single line of text that could reasonably be expected to be entered directly by a user. This functionality is provided by the methods demandObject and requestObject specified in the TypedView interface.

Convenience methods are also provided that permit the caller to either demand or request one of the following types: boolean, char, byte, short, int, long, float, double, BigInteger, BigDecimal, and String.

The TextFieldView class provides numerous constructors so that many properties of the view may be set at the time of construction. In particular, the width of the view may be set. The height of the view is determined by the current text field font in the look and feel.

The Java file TextAreaView.java (multi line text input)

The TextAreaView class is a TypedView designed to input multi-line text using a Java JTextArea. Using the method getViewState, the text in the view is returned as an XString object. Further processing of this data is the responsibility of the caller.

The Java file BooleanView.java (check box selection)

The BooleanView class is a TypedView designed to input a boolean value using a Java JCheckBox. If the check box is checked, then the state is true, and if it is unchecked, then the state is false. If the caller wishes to have some Action performed when the user changes the check box state, such an Action may be installed.

The Java file RadioPanel.java (radio button selection)

The RadioPanel class is the base that provides the common functionality for OptionsView and StringObjectRadioPanel. RadioPanel is designed to input a selection using a set of Java JRadioButton objects. The caller may obtain the label of the selected radio button, the index of the selected radio button, or the selected radio button itself. If the caller wishes to have an Action performed when the user changes the selected radio button, then the caller has the option to install an Action that applies to all radio buttons or to install Actions for each individual radio button. If desired, the caller may set a LayoutManager to control the arrangement of the radio buttons.

The Java file OptionsView.java (radio button selection)

The OptionsView class is a TypedView designed to input a selection using a set of Java JRadioButton objects installed in a RadioPanel.

The Java file StringObjectRadioPanel.java (radio button selection)

The StringObjectRadioPanel class is a StringObjectView designed to input a selected object using a corresponding set of Java JRadioButton objects installed in a RadioPanel.

The Java file DropdownView.java (editable dropdown list selection)

The DropdownView class is a GeneralView based on the dropdown list functionality of the Java class JComboBox. DropdownView is designed to input a selection from one of many text strings that are predefined in the program. If the dropdown list is made editable, then the user may also enter string data that will be parsed according the rules of the data type associated with the GeneralView.

The Java file StringObjectDropdown.java (dropdown list selection)

The StringObjectDropdown class is a StringObjectView based on the dropdown list functionality of the Java class JComboBox. StringObjectDropdown is designed to input a selection from one of many text strings that are predefined in the program. The caller may also obtain the object associated with one of the text strings directly. The dropdown list in this view should not be made editable.

The Java file SliderView.java (slider selection)

The SliderView class is a TypedView designed to input an int value in a bounded range using direct mouse manipulation of a Java JSlider. The caller may add one or more Action objects to be executed either while the slider is sliding or when the slider is released.

The Java file ColorView.java (color selection)

The ColorView class is a TypedView designed to input a Color. The view will show a box displaying the selected color and, optionally, an editable dropdown list for direct input of the color name or of the R, G, B, Alpha values that make up the color (represented in decimal or hexidecimal). If the color box is clicked, a Java JColorChooser dialog is displayed to permit the user to select the color interactively. The dropdown list option is provided since a JColorChooser does not let the user set an Alpha value or choose a color by name.

The Java file FileView.java (file selection by dialog)

The FileView class is 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.

The Java file XObjectView.java

The XObjectView class is a Displayable designed as a view for the output of the String representation of the state of an XObject. This view is not used for user input.

Back to top of Basic Views and Widgets or back to top of edu.neu.ccs.gui or back to top of page

Layout Managers

The Java file TableLayout.java

TableLayout is the most important layout manager in the Java Power Tools. This layout manager will arrange components in a one or two dimensional table as desired. This manager will compute the row heights and column widths from the preferred size of the components and can impose minimum values for these measurements if needed. The gaps between the rows or columns can be set in absolute pixels. If a component is smaller than its cell, then its alignment within the cell can be set to the center or to one of the eight compass directions. Cell alignment can be set for the entire table, for individual rows or columns, or for individual cells. Finally, null components are handled cleanly by leaving cells empty as appropriate.

TableLayout is the technical foundation for the panel TablePanel. TableLayout can also be used for other Java panels to provide fine control of component layout.

Since the invention of TableLayout, we have found in practice that we almost never need to use any other layout manager.

The Java file CenterLayout.java

CenterLayout maintains a single component in the absolute center of the parent container. This manager is a precursor to TableLayout and was inspired by code posted on the internet by an author named "Sapex".

Since the invention of TableLayout, this layout manager is rarely used but it still has a role in JPTFrame since that frame normally has one object in its content pane.

The Java file AlignedLayout.java

AlignedLayout maintains a single component either in the absolute center of the parent container or in one of the eight compass directions. This manager is a precursor to TableLayout.

Since the invention of TableLayout, this layout manager is rarely used.

The Java file AbsoluteLayout.java

AbsoluteLayout is to the extent possible a hands off layout manager. However, in 2.3.5, a serious bug was fixed and this fix required a policy concerning how to compute the size of each of the installed components. Here is the policy.

If a Component is actually a Container then its size is computed by calling getPreferredSize and any existing size set by setSize is ignored. This permits objects that extend Container to effectively change their size by changing the return value of getPreferredSize and this change is not affected by an obsolete value set earlier by setSize.

For a general Component, the size is set to be the maximum of getSize and getMinimumSize. This approach was a design choice based on the fact that for many older Java Component objects people often directly set the size and do not bother with the minimum size. This means that the resulting size set in this layout manager is at least a big as both the actual size set earlier and the minimum size.

The size policy is consistent with the effort in JPT to use getPreferredSize (which is algorithmic) rather than rely on size settings that may become obsolete for dynamically changing components.

The use of this layout manager is not recommended unless the application is fully capable of handling the layout responsibities for a panel.

AbsoluteLayout is used for the Zoo panel.

Back to top of Layout Managers or back to top of edu.neu.ccs.gui or back to top of page

General Panels and related support classes

• DisplayPanel and the helper class ComponentFactory
• BufferedPanel
• TablePanel and associated classes
• Zoo and associated classes
• Other collection panels
• Annotation
• Wrapper panels

Back to top of General Panels or back to top of edu.neu.ccs.gui or back to top of page

The base panel: DisplayPanel

The Java file DisplayPanel.java

DisplayPanel is the base panel for all other JPT panels. DisplayPanel implements the Displayable interface and is designed to recursively propagate Displayable method calls to contained components that are also Displayable. In particular, the method setEnabled is propagated to all of its immediate components (which oddly is not the Java default) and will therefore recursively propagate to its Displayable components.

DisplayPanel also provides the default implementation of the following special methods:

• The makeComponent method that constructs a Component from an Object by calling the corresponding static method from ComponentFactory
• The addObject methods that add more general objects to the panel by using the makeComponent method to convert these objects into suitable components
• The uniformizeSize method that forces all items in the panel to have the same preferred size if that sizing policy is desired
• The methods needed to implement error handling

The Java file ComponentFactory.java

ComponentFactory has 3 static methods:

• makeComponent that constructs a Component from an Object
• makeIcon that constructs an Icon from an Object
• makePaintable that constructs a Paintable from an Object

The first two methods both make certain specific attempts to convert a general Object into the desired type. If these attempts fail then the methods use the makePaintable method to try to convert the Object into a Paintable. If that attempt succeeds then the Paintable is placed into a PaintableComponent. On the other hand, if this final attempt fails then null is returned.

The table below shows more about how makeComponent works.

The table below shows more about how makeIcon works.

The table below shows more about how makePaintable works.

Notice that if the argument to makePaintable is an array of Object then the method is called recursively on the items in the array to make a PaintableSequence.

To permit overriding, the method makeComponent in DisplayPanel is a member method that calls this static method.

Back to top of General Panels or back to top of edu.neu.ccs.gui or back to top of page

BufferedPanel

The Java file BufferedPanel.java

BufferedPanel is a panel that automates the refresh process by repainting itself from a persistent graphics state that is stored in 2 data structures for the background layer and sprite layer.

• A BufferedImage object holds a bit-map that is used to paint the background layer of the BufferedPanel.
• A PaintableSequence object holds a collection of Paintable objects that are painted above the background layer in the sprite layer. Since these objects are Paintable, they have all of the properties of Paintable including the ability to be mutated by arbitrary affine transforms.

To use the BufferedPanel background layer properly, the caller should paint to the stored buffer whose graphics context is available through the method call getBufferGraphics. All calls in Java 2D graphics are available for this purpose. For more sophisticated manipulation of the background layer, the caller may access the buffer itself through the method call getBuffer.

To use the sprite layer of a BufferedPanel, there are various methods to add, append, or remove one or more objects to or from the layer. These objects are passed through the makePaintable method of ComponentFactory to create a Paintable if needed.

When the caller is ready to display the changes made to the 2 panel data structures, the repaint method on the panel should be invoked.

A BufferedPanel may be made responsive to the mouse by installing appropriate mouse actions using the built-in mouse action adapter object. Such actions may be defined by the caller. There is also a default set of mouse actions that may be used to drag the paintables in the sprite layer. To obtain these actions, use the method installSimpleMouseActions.

Back to top of General Panels or back to top of edu.neu.ccs.gui or back to top of page

TablePanel and associated classes

The Java file TablePanel.java

TablePanel is the most important panel in the Java Power Tools. This panel is based on TableLayout. TablePanel is designed to quickly build one or two dimensional tables of components constructed from objects using the makeComponent method. Due to the TableLayout algorithms, TablePanel is able to handle the alignment of objects within cells and the gaps between cells. Furthermore, since TablePanel's nest within TablePanel's, layouts of arbitrary complexity may be easily achieved.

The TablePanel constructors are designed to allow a table to be built in a ready to use state by permitting the caller to provide all objects to be installed and all other relevant parameters. The objects may be supplied as an array of Object that is either one or two dimensional. These objects will be converted to components using the method makeComponent.

It is also possible to build a table algorithmically by supplying the dimensions of the table together with a strategy for building objects that is encapsulated in a TableGenerator object.

The TablePanel class has numerous constructors but the three most important constructors are:

        TablePanel(Object[][] contents, int hgap, int vgap, int align)

        TablePanel(Object[] contents, int orientation, int hgap, int vgap, int align)

        TablePanel(TableGenerator tg, int rows, int cols, int hgap, int vgap, int align)

In the first two constructors, the contents array parameter supplies the objects that will be converted into components via the makeComponent method and then inserted into the table. In the third constructor, the TableGenerator tg supplies the objects for the table algorithmically and the size of the table is determined by the given rows and cols. In the second constructor, the caller must supply the display orientation which is one of the following constants from SwingConstants or JPTConstants:

• HORIZONTAL
• VERTICAL

The parameters hgap and vgap represent the standard horizontal and vertical gap between table cells. Finally, the align parameter determines the alignment of components within table cells when the components are smaller than the cells. The align parameter is one of the following constants from SwingConstants or JPTConstants:

• CENTER
• NORTH
• NORTH_EAST
• EAST
• SOUTH_EAST
• SOUTH
• SOUTH_WEST
• WEST
• NORTH_WEST

The Java file TableGenerator.java

The TableGenerator interface specifies an algorithm for building the contents of a table via the method makeContents that returns an Object for each row and column of the table.

The Java file CellPosition.java

CellPosition is a simple helper class to encapsulate a row and column position in a table.

Back to top of General Panels or back to top of edu.neu.ccs.gui or back to top of page

Zoo and associated classes

The Java file Zoo.java

A Zoo is a ZooContainer that allows selection and direct mouse manipulation of its components.

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

An individual component, or a collection of components, may be selected through direct mouse manipulation or through method calls. A selected component is painted with a box surrounding its bounds. The components that are currently selected may be retrieved using various methods. 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 may be grouped into a ZooGroup which is treated as a single entity in the Zoo.

To permit a child item to be treated alternately as an object for mouse manipulation or as Java component with its own functionality, each child item is encapsulated in a transparent Laminate object that will either handle the mouse when the child item is being manipulated or, if the Zoo is not in edit mode, will pass this mouse information through to the component that is encapsulated.

The Java file ZooGroup.java

The Java file ZooContainer.java

The Java file Laminate.java

The three classes above are helper classes for Zoo.

Back to top of General Panels or back to top of edu.neu.ccs.gui or back to top of page

Other collection panels

The Java file ActionsPanel.java

ActionsPanel is a precursor to TablePanel. Its use of an array of Action objects to define a panel of JButton objects was one of the inspirations for TablePanel. Despite the fact that one can now install a button into a TablePanel using an Action object, there are still reasons to use ActionsPanel. Since an ActionsPanel consists solely of buttons, one can define the default button that is executed by a press of the return key. In addition, ActionsPanel makes it easy to provide each button with a tool tip. To make all buttons in an ActionsPanel have the same size, use the inherited method uniformizeSize.

The Java file DisplayCollection.java

DisplayCollection creates a one dimensional table of Displayable components.

Since the invention of TablePanel, this panel is rarely used.

The Java file SimpleArrayPanel.java

SimpleArrayPanel (which was introduced in 2.4.0) is a much simpler way to create user controlled array views than the older class ArrayPanel. It is recommended that this class be used for future development.

The javadoc introduction for SimpleArrayPanel contains detailed instructions for the use of this panel. We excerpt the opening remarks from these instructions.

Class SimpleArrayPanel provides a panel that can hold one or more views of a given type with the number of such views under interactive user control.

The views are arranged in a 4-column vertical list with the following structure in each row:

• Column 0 contains an automatically generated row label.
• Column 1 contains a view whose type is supplied in the constructor as a TypedView Class object.
• Column 2 contains a button that will in effect insert a new row at that position.
• Column 3 contains a button that will in effect delete that particular row.

This 4-column vertical list is placed in a scroll pane. The designer can determine how many rows will be visible at once.

The interactive controls that permit the user to change the total number of views are placed in a panel underneath the scroll pane.

To construct a SimpleArrayPanel, the user must supply its viewType which is an object of type Class that defines the view that will be repeated in the panel.

The following restrictions on the viewType must hold:

• The viewType must not be null.
• The viewType must extend JComponent so a view may be directly inserted into its panel.
• The viewType must implement TypedView so the model data can be extracted from a view by the standard methods of the TypedView interface.
• Normally, the viewType class must have a default constructor.

For a snapshot of a SimpleArrayPanel in use, see PathListView

The Java file ArrayPanel.java

ArrayPanel is an abstract class implementing the interface TypedView whose purpose is to provide for the input of a possibly dynamic array of Stringable objects.

An ArrayPanel is an integrated component containing a collection of TypedView's for input of Stringable objects of a specific type, with the option of controls for the dynamic modification of the length of the array by the user.

To implement ArrayPanel, it is necessary to build a derived class that implements the abstract methods. It is also recommended that the designer consider overriding the protected method createViewFor. It is this method that constructs the views for the items in the array. By default, this method returns a vanilla TextFieldView. It is likely that the designer will either want to return a customized TextFieldView or a more sophisticated TypedView.

Since an ArrayPanel may have few components when it is initialized, it is important to allow for dynamic growth by the user. It is recommend that the ArrayPanel be inserted into a wrapper of type JPTScrollPane or of type ScrollableDisplay. Then, using the sizing methods of the wrapper, one can provide enough space for the ArrayPanel.

Back to top of General Panels or back to top of edu.neu.ccs.gui or back to top of page

Annotation

The Java file Annotation.java

Annotation extends DisplayPanel to provide 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.

Back to top of General Panels or back to top of edu.neu.ccs.gui or back to top of page

Wrapper panels

The Java file Display.java

Display is a wrapper class designed to add either annotation text as a label or title text as a titled border or both to its wrapped component.

Since the invention of TablePanel, one can add a label to an object while building the table. Hence Display is no longer used for this purpose to the same degree as it was in the past. On the other hand, Display is still frequently used to create titled borders around an object.

The Java file Halo.java

Halo is a wrapper class for one Object viewed as a Component. This class uses a CenterLayout and provides positive minimal insets.

The purpose of Halo is to provide a panel that just barely surrounds its wrapped component. This is useful because, when the JPT detects an input error, it highlights the panel surrounding the component in which the error occured. By wrapping a component in which an error may occur, the error highlighting is focused precisely on that component.

In particular, it is recommended that if a TextFieldView, say, view, is to be inserted into a TablePanel and if there is a possibility of an input error within view, then the following idiom should be used for the inserted object:

• new Halo(view)

The Java file JPTScrollPane.java

JPTScrollPane extends JScrollPane by adding methods that help control the preferred size of the JViewport window.

JPTScrollPane does not implement Displayable.

The Java file ScrollableDisplay.java

ScrollableDisplay is a JPTScrollPane that implements Displayable. A ScrollableDisplay contains a single Displayable object as its viewport view and delegates its Displayable method calls to this view.

The functionality of this class assumes that the viewport view for this scroll pane is a Displayable object that is set through the setDisplay method, and effects are undefined if the viewport view is set through other means.

Back to top of General Panels or back to top of edu.neu.ccs.gui or back to top of page

Frames

The Java file JPTFrame.java

JPTFrame extends the Java JFrame class for the following purposes.

• To provide static factory methods named frame that accept a general object and attempt to wrap that object in a suitable fashion so the object may be placed in a JFrame that is packed and opened automatically.
• To permit the frame to be positioned on the screen in the center or at one of the eight compass directions with allowances made for any screen insets needed to keep the frame away from taskbars or menus placed by the operating system at the screen edges.
• To make it is easy to maximize or iconify a frame or return a frame to its normal size.
• To provide more flexible window closing operations that control the exit from the Java virtual machine automatically.

The same static frame factory methods have also been introduced into the class JPF as convenience methods for testing and experimentation.

The class DisplayPanel has a parallel set of member frame methods that permit a DisplayPanel to frame itself. We call this ability self actualization.

Back to top of Frames or back to top of edu.neu.ccs.gui or back to top of page

Actions

The Java file SimpleAction.java

SimpleAction is an abstract class that is a simple extension of the Java AbstractAction class. It is used to simplify the programming interface for an object representing a GUI action. For convenience, SimpleAction also implements ChangeListener and PropertyChangeListener.

To implement a SimpleAction, one must extend the abstract class and define the following method:

        public void perform()

Since an Action is a data member and a data member may have the same name as a method, there is a convenient convention in which the perform method is implemented by calling a class method whose name is identical to that of the Action. Here is the template:

        private SimpleAction name_of_action =
            new SimpleAction("name as text string") {
                public void perform() {
                    name_of_action();
                }
            };

Notice that name_of_action in line 1 is the member data being defined and name_of_action in line 4 is the method call. The method must of course be defined elsewhere in the class. Notice also that this definition template uses an anonymous inner class to, in effect, convert a method into an object.

The Java file ActionSequence.java

ActionSequence implements the composite pattern for Action objects by maintaining a list of such objects and then executing them in sequence when its own actionPerformed method is called.

The Java file ActionWrapper.java

ActionWrapper is the base class for encapsulating an Action object and producing a new Action object that adds extra functionality on top of the original functionality.

The Java file ThreadedAction.java

ThreadedAction is an ActionWrapper that performs its encapsulated Action in a newly created separate thread.

Using ThreadedAction makes it extremely easy to ensure that actions launched from a GUI run in separate threads from the GUI thread. This technique is used, in particular, for all buttons in the Java Power Frame user interface.

See also Action Adapters

Back to top of Actions or back to top of edu.neu.ccs.gui or back to top of page

Dialogs

The Java file GeneralDialog.java

GeneralDialog creates a dialog box with an arbitrary Component in the upper half of its window and a suitable ActionsPanel in the lower half of its window that contains actions to respond to the data in the Component and to dismiss the dialog. For convenience, the user may supply a general object to be placed in the upper half of the dialog window and this object will be converted to a component using the makeComponent method.

GeneralDialog provides controls to set what happens when the dialog box opens and closes and to choose the default button that will be executed if the user presses the return key. When the dialog is closed, the caller may query if the dialog was cancelled.

GeneralDialog provides static make methods to return simple objects of its own type. This makes it easier to specify common dialogs. GeneralDialog also provides static show methods to both create and show a dialog in one step. If a dialog created via a show method is cancelled, then a CancelledException will be thrown to signal the caller.

The most commonly used constructor for GeneralDialog is:

        GeneralDialog(Object displayObject, String title, Object[][] actionData, boolean modal)

The displayObject is converted into a component using the makeComponent method and placed into the upper half of the dialog window. The 2-dimensional array actionData is used to create the dialog buttons in the lower half of the dialog window. Each sub-array of actionData consists of an Action together with one of the constants from DialogAction that determine what will happen to the dialog after that action is performed.

The Java file DialogAction.java

DialogAction is an ActionWrapper that encapsulates an Action together with information about what should happen to the dialog box when the Action is completed. The options for the completion are:

• DialogAction.KEEP_OPEN: The choice to keep the dialog open after the action
• DialogAction.AUTO_CLOSE: The choice to auto close the dialog after the action
• DialogAction.SET_CANCEL: The choice to both close the dialog and mark the dialog as cancelled

GeneralDialog uses DialogAction internally. The constructors for GeneralDialog provide an elegant way to specify pairs consisting of an action and a completion operation that will be used to construct the ActionsPanel of the dialog.

The Java file SimpleDialog.java

SimpleDialog consists of static methods to either demand or request via a dialog box an item whose type is one of the following: boolean, char, byte, short, int, long, float, double, or String. There are also static methods to either demand or request via a dialog box any Stringable object that may be returned by the demand or request methods of a TypedView object. The static methods in this class all utilize InputDialog.

The Java file JPTDialog.java

JPTDialog is the base class for dialogs constructed from a TypedView and a set of Action's that are formed into an ActionsPanel.

JPTDialog is a precursor to GeneralDialog. The main difference is that GeneralDialog uses an arbitrary Component while JPTDialog requires a TypedView.

The Java file InputDialog.java

InputDialog extends JPTDialog and provides a modal dialog box for input of a Stringable object using the supplied TypedView object.

The InputProperties for the TypedView 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 the suggestion property is not-null, then a Suggest button is also provided. The advantage that InputDialog has over GeneralDialog is in the automatic creation of these buttons based on the InputProperties for the TypedView.

InputDialog also provides static convenience methods for input using a supplied TypedView.

The Java file ErrorDialog.java

ErrorDialog extends InputDialog and provides a modal dialog box for input of Stringable objects that is used by the standard error handling strategy for Fragile components in the JPT.

Back to top of Dialogs or back to top of edu.neu.ccs.gui or back to top of page

Error Handling

The Java file Fragile.java

Fragile is an 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.

The Java file AlertEvent.java

AlertEvent is a class of AWTEvent's that designates that a graphical input object should enter or exit alert status.

The Java file AlertListener.java

AlertListener is an interface to be implemented by a graphical interface component capable of altering its visualization to signal a user alert state.

The Java file MalformedDataEvent.java

MalformedDataEvent extends AlertEvent and defines a class of events that designates 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.

The Java file MalformedDataListener.java

MalformedDataListener is an interface extending AlertListener that should be implemented by graphical interface components that desire to be notified when Fragile interface components encounter malformed data.

Back to top of Error Handling or back to top of edu.neu.ccs.gui or back to top of page

Look And Feel

The Java file LookAndFeelTools.java

LookAndFeelTools contains several static methods that assist in using the Java look-and-feel facilities.

The most important static method is showSelectLookAndFeelDialog that permits the user to select from among the installed look-and-feel options and that also permits the user to change the default font sizes in a systematic manner by a small increment or decrement. This functionality is particularly useful in teaching situations in which instructors and students wish to see what happens to a GUI using different look-and-feel choices.

Another important static method is adjustAllDefaultFontSizes that will increment all of the many default font sizes by the same amount. This functionality is particularly useful in teaching situations in which the default font sizes may be too small to be seen by students when using computer projection. An instructor may call this method once prior to opening any windows and all fonts will become suitably larger.

In general, the methods in this class must be called prior to the opening of any window frame or other dialog box to avoid having different look and feel settings in different windows.

Back to top of edu.neu.ccs.gui or back to top of page

Graphics Classes

• Paintable
• AbstractPaintable
• Support Classes
• Paintables for Shapes, Images, and Text
• Paintable Wrappers
• PaintableSequence
• Paintable Tools
• Paint Tools
• Color Tools
• Image Tools
• Graphics Capsules
• Data and Function Plots

Back to top of Graphics or back to top of edu.neu.ccs.gui or back to top of page

Paintable

The Java file Paintable.java

Paintable is an interface that describes an object that can paint onto a graphics context. In addition, a Paintable can return its bounds and center, can set its visibility on or off, can set its opacity to a value between 0 and 1, and can determine if a point is included in the region painted so that mouse manipulation is supported. Furthermore, a Paintable may be mutated using an arbitrary invertible AffineTransform.

The Java file Mutator.java

Class Mutator encapsulates:

• A static abstract class Strategy that defines a mutator strategy that may be applied to a Paintable object
• Several static methods that construct Mutator.Strategy objects
• Two constants that control the usage of Mutator.Strategy objects in a PaintableSequence

The two Mutator.StrategyUsage constants for a PaintableSequence are:

• Mutator.StrategyUsage.MUTATE_AS_GROUP
• Mutator.StrategyUsage.MUTATE_AS_ITEMS

Back to top of Graphics or back to top of edu.neu.ccs.gui or back to top of page

AbstractPaintable

The Java file AbstractPaintable.java

The abstract class AbstractPaintable defines objects that implement Paintable.

Back to top of Graphics or back to top of edu.neu.ccs.gui or back to top of page

Support Classes

The Java file SupportsPropertyChange.java

SupportsPropertyChange is an interface for objects that can add PropertyChangeListener objects, can fire PropertyChangeEvent events directly to those listeners, and can forward internal PropertyChangeEvent events to those listeners as well.

Many of the methods in this interface are identical to methods found in one or more of the following Java classes:

• Component
• JComponent
• PropertyChangeSupport
• SwingPropertyChangeSupport

The Java file PropertyChangeForwardingListener.java

PropertyChangeForwardingListener is a PropertyChangeListener that forwards a PropertyChangeEvent event that it receives to an object that implements the interface SupportsPropertyChange by causing that object to fire the same event to its own listeners.

PropertyChangeForwardingListener is intended to permit PropertyChangeEvent events that are fired within a composite object to be handled by the listeners for the entire object.

More generally, PropertyChangeForwardingListener may be used to forward events to any appropriate object that implements the interface SupportsPropertyChange.

The Java file TransformFactory.java

TransformFactory provides a collection of static methods that construct AffineTransform objects for common 2-dimensional transforms. Such transforms need not be centered at the origin. The methods support the computation of both specific transforms and random transforms. In addition, methods are provided to find the composite of a pair of transforms or an array of transforms.

In this class, angle measurement is in degrees not radians. A positive angle is in the direction from the positive x-axis towards the positive y-axis.

Back to top of Graphics or back to top of edu.neu.ccs.gui or back to top of page

Paintables for Shapes, Images, and Text

The Java file ShapePaintable.java

ShapePaintable creates an AbstractPaintable using a Shape object and other related data, specifically, a PaintMode strategy, 2 Paint objects for filling the Shape and for drawing its boundary, and a Stroke object for determining how the boundary will be drawn.

The Java file PaintMode.java

The abstract class PaintMode defines the requirements for an object that can control the painting of a ShapePaintable. In fact, a ShapePaintable implements the abstract methods in its base class AbstractPaintable by using the algorithmics of its PaintMode member data object. These algorithmics include the paint operation itself and the computation of the original bounding box (before mutation) and the test for whether a point is among the pixels painted (again before mutation).

PaintMode provides some examples of its own objects as static member data:

• PaintMode.FILL: Fill the shape
• PaintMode.DRAW: Draw the shape boundary
• PaintMode.FILL_DRAW: Fill the shape then draw the shape boundary

PaintMode also provides some static convenience methods to directly fill, draw, or fill_draw a Shape onto a graphics context. These methods create a temporary ShapePaintable to do the work of painting so the effects are identical to those that the user would achieve by explicitly constructing the associated ShapePaintable.

The Java file ImagePaintable.java

ImagePaintable creates an AbstractPaintable using one of the following:

• an image specified by an Image object
• an image specified by an ImageIcon object
• an image specified by a filename
• an image specified by a URL

The Java file ImagePaintableLite.java

ImagePaintableLite creates an AbstractPaintable using one of the following:

• an image specified by a filename
• an image specified by a URL

To save memory, an ImagePaintableLite does not cache its image but rather retrieves its image as needed for paint operations. Thus the class trades time for space. This design enables a program to access a much larger collection of images at one time than would be possible by directly using the Java classes Image or ImageIcon or the JPT class ImagePaintable. These other classes all retain the bit data for an image and thus entail a high memory cost.

In practice, Java appears to use some form of caching for images obtained using ImagePaintableLite. Thus, although the impact on main memory is much reduced for an ImagePaintableLite, the speed of refresh for such an image is excellent.

The Java file TextPaintable.java

TextPaintable creates an AbstractPaintable using a String to paint, a Font, a Paint object to determine how the String will be painted, a TextBounds strategy to determine whether the bounds will be tight or loose, a TextAnchor strategy to determine what position in the String will be considered the anchor, and finally the (x,y) coordinates of the anchor.

The Java file TextBounds.java

The TextBounds class defines an interface that specifies how to compute accurate bounds for a TextPaintable.

The TextBounds class also defines static objects that implement the interface it defines:

• TextBounds.TIGHT to obtain a tight bounding box
• TextBounds.LOOSE to obtain Java's default bounding box

The Java file TextAnchor.java

The TextAnchor class defines interfaces that specify how to compute the location and bounds of a String that will be displayed using a given Font in conjunction with a given anchor position.

The TextAnchor class also defines static objects that implement the interfaces it defines. The static objects used directly by the class TextPaintable are the following:

• TextAnchor.LEFT_BASELINE
• TextAnchor.CENTER_BASELINE
• TextAnchor.RIGHT_BASELINE
• TextAnchor.LEFT_ASCENTLINE
• TextAnchor.CENTER_ASCENTLINE
• TextAnchor.RIGHT_ASCENTLINE
• TextAnchor.LEFT_DESCENTLINE
• TextAnchor.CENTER_DESCENTLINE
• TextAnchor.RIGHT_DESCENTLINE
• TextAnchor.LEFT_LEADINGLINE
• TextAnchor.CENTER_LEADINGLINE
• TextAnchor.RIGHT_LEADINGLINE

The Java file PointPaintable.java

A PointPaintable creates a Paintable using a point, a PlotMark, and a Paint. When a mutation is applied to a point paintable, it is applied to the position at which the point paintable does its painting but does not affect the shape rendered.

Back to top of Graphics or back to top of edu.neu.ccs.gui or back to top of page

Paintable Wrappers

The Java file Tile.java

Tile will wrap a Paintable in order to allow mutation to occur without changing the internal paintable. This is useful, for example, for games that may use the same paintable to define multiple pieces that must be movable independently.

The Java file TileBox.java

A TileBox is a Tile with a border that may be selected more easily since any point in the box is viewed as within the paintable.

The Java file ClippingWrapper.java

ClippingWrapper will wrap a Paintable and a clipping Shape to obtain a Paintable that clips the original Paintable to the Shape.

Back to top of Graphics or back to top of edu.neu.ccs.gui or back to top of page

PaintableSequence

The Java file PaintableSequence.java

PaintableSequence encapsulates a sequence of Paintable objects. As of 2.4.0, one can supply general Object's rather than Paintable's and the makePaintable method will be invoked to convert the Object's into Paintable's. In particular, if a parameter is of type Object[], then this parameter will be recursively converted into a PaintableSequence that is installed as a single item into this sequence.

Whenever there is a change in the overall mutator for the sequence, this change is immediately applied to the individual items in the sequence. As a consequence, the individual sequence items maintain their own knowledge of the net mutation that must be applied in paint operations. In particular, as far as geometry is concerned, an individual sequence item may be viewed either as part of the sequence or as a stand-alone Paintable. This design decision enables interactive manipulation of sequence items to be handled in a natural fashion.

A PaintableSequence object has a Mutator.StrategyUsage state object that determines whether a Mutator.Strategy should apply to the sequence as a whole or to individual items.

Back to top of Graphics or back to top of edu.neu.ccs.gui or back to top of page

Paintable Tools

The Java file PaintableTools.java

PaintableTools collects static methods that construct objects of other types from Paintable objects. The types of objects that may be constructed are as follows:

• Icon
• BufferedImage
• TexturePaint
• JButton
• JPTComponent

This functionality means that Paintable objects can integrate smoothly into standard Java graphics classes and components.

The Java file JPTComponent.java

The abstract class JPTComponent extends JComponent in order to:

• Implement those methods in SupportsPropertyChange that are not already (publically) implemented in JComponent
• Add a KeyActionAdapter for this component
• Add a MouseActionAdapter for this component

The Java file PaintableComponent.java

The class PaintableComponent both extends JPTComponent and implements the Java interface Icon. This class uses a Paintable to provide the paint method for the object viewed as a component or as an icon.

The Java file PaintableButton.java

The class PaintableButton extends JButton and uses a Paintable to provide its Icon.

The Java file PaintableSequenceComposite.java

The class PaintableSequenceComposite is a base class for the construction of Paintable classes. Although the class is not abstract, nothing useful can be done with it directly.

A derived class can control exactly what is inserted into the internal PaintableSequence via the protected access method getPaintableSequence() but this sequence is not visible to a public caller. Thus, all features of a PaintableSequence are available to a derived class without public exposure of this implementation.

The class PaintBar is an example of a derived class of PaintableSequenceComposite.

The Java file Refresh.java

Refresh encapsulates a method for graphics refresh. This method is used to refresh the components created by the methods in PaintableTools and may also be used in other contexts.

Back to top of Graphics or back to top of edu.neu.ccs.gui or back to top of page

Paint Tools

The Java file PaintAlgorithm.java

The interface PaintAlgorithm describes the essentials that a class must provide in order to create a Java BufferedImage and a Java TexturePaint.

The Java file PaintTools.java

The class PaintTools contains static methods that create a Java BufferedImage or a Java TexturePaint from a PaintAlgorithm as well as numerous static methods to manipulate such algorithms or use such algorithms to create new algorithms. Examples include methods to create hatch patterns.

The Java file PaintBar.java

The class PaintBar implements a Paintable that paints a one or two dimensional array of painted disks. The constructor supplies an array of Paint objects, one for each disk. The user can choose the diameter of the disks and the gap between the disks.

As an application, an object of this class may be embedded in a PaintableComponent and used to implement a custom paint selector control.

Back to top of Graphics or back to top of edu.neu.ccs.gui or back to top of page

Color Tools

The Java file PaintSwatch.java

The class PaintSwatch is a light weight component to draw a rectangular paint swatch with a given Paint, size, and optional Border. This class also implements the Icon interface.

The Java file SwatchNamePair.java

The class SwatchNamePair provides a component with a PaintSwatch and its name. The swatch has the default size and border.

The Java file SwatchNameRenderer.java

The class SwatchNameRenderer is designed to implement ListCellRenderer by providing pairs using a PaintSwatch and its name. The class constructor provides a renderer for the swatch-name pairs generated from the color names obtained via Colors.getColorNamesAsArray.

The Java file VisualColorList.java

The class VisualColorList displays the named colors as defined in class Colors using a square color swatch and a label. The programmer has some control of the swatch size and pane height. This class is intended to provide color information not as a GUI control. Use class ColorView with the dropdown view enabled to obtain a control with color swatches and names.

Back to top of Graphics or back to top of edu.neu.ccs.gui or back to top of page

Image Tools

For convenience, we first list here three classes related to images that are also listed elsewhere.

The Java file ImagePaintable.java

ImagePaintable creates an AbstractPaintable using one of the following:

• an image specified by an Image object
• an image specified by an ImageIcon object
• an image specified by a filename
• an image specified by a URL

The Java file ImagePaintableLite.java

ImagePaintableLite creates an AbstractPaintable using one of the following:

• an image specified by a filename
• an image specified by a URL

To save memory, an ImagePaintableLite does not cache its image but rather retrieves its image as needed for paint operations. Thus the class trades time for space. This design enables a program to access a much larger collection of images at one time than would be possible by directly using the Java classes Image or ImageIcon or the JPT class ImagePaintable. These other classes all retain the bit data for an image and thus entail a high memory cost.

In practice, Java appears to use some form of caching for images obtained using ImagePaintableLite. Thus, although the impact on main memory is much reduced for an ImagePaintableLite, the speed of refresh for such an image is excellent.

The Java file ImageCapsule.java

ImageCapsule is a JComponent encapsulating an Image.

The construction of a component using ImageCapsule may be achieved via:

        new ImageCapsule(image);

A similar effect may now be achieved via:

        PaintableTools.makeComponent(new ImagePaintable(image));

The advantage of ImageCapsule is that the component can be constructed without the nested calls. The disadvantage is that the full range of choices built into ImagePaintable are not available.

We now list the additional classes that support images.

The Java file ImageTools.java

The class ImageTools contains tools to read image files from a local directory on disk and return these files as arrays of any of the following types:

• Image
• ImagePaintable
• ImagePaintableLite

The tools can read all images in a given directory; read the images listed in a text file that contains a list of image file names; or read a list of images whose file names are contained in a String array.

The Java file WebImageTools.java

The class WebImageTools contains tools to read image files from the web and return these files as arrays of any of the following types:

• Image
• ImagePaintable
• ImagePaintableLite

The tools can read read the images listed in a text file that contains a list of image file names or read a list of images whose file names are contained in a String array. If the image list is obtained from a file, that file may reside in the same web location as the images or may be located at a different URL if that is more convenient.

The Java file ImageViewer.java

The class ImageViewer creates an image viewer for a list of local image files. The images will be displayed in a vertical list and each image will be annotated with its file name, its image dimensions, and the index of the file in the file list. The caller may select whether to show images at full size or to autoscale so that each image fits within the available scrollpane viewport.

In tests, this class was able to display more than 100 large images at once. This is due to the use of the class ImagePaintableLite which requires only a small memory footprint. Using standard Java tools, the attempt to display the same images led to memory overflow.

The Java file WebImageViewer.java

The class WebImageViewer creates an image viewer for a list of web image files. The images will be displayed in a vertical list and each image will be annotated with its file name, its image dimensions, and the index of the file in the file list. The caller may select whether to show images at full size or to autoscale so that each image fits within the available scrollpane viewport.

In tests, this class was able to display more than 100 large images at once. This is due to the use of the class ImagePaintableLite which requires only a small memory footprint. Using standard Java tools, the attempt to display the same images led to memory overflow.

The Java file ImageViewerBase.java

The class ImageViewerBase is the base class that contains the common GUI code for ImageViewer and WebImageViewer. Its constructor is protected so it may not be directly instantiated.

The Java file RequestImageViewer.java

The class RequestImageViewer creates a simple GUI so that the end user may provide the directory and image file list name to construct an ImageViewer for images on the local file system.

The image file list text file is optional. If omitted, all images in the directory will be displayed in lexicographic order.

The Java file RequestWebImageViewer.java

The class RequestWebImageViewer creates a simple GUI so that the end user may provide the web URLs and image file list name to construct a WebImageViewer for images on the web.

The image file list text file is mandatory since there is no way to obtain the list of all images in a web directory by direct means.

Back to top of Graphics or back to top of edu.neu.ccs.gui or back to top of page

Capsule Classes

The Java file ShapeCapsule.java

ShapeCapsule is JComponent encapsulating a Shape and a fill Paint and acting as a view for this filled shape.

The construction of a component using ShapeCapsule may be achieved via:

        new ShapeCapsule(shape, paint);

A similar effect may now be achieved via:

        PaintableTools.makeComponent(new ShapePaintable(shape, null, paint));

The advantage of ShapeCapsule is that the component can be constructed without the nested calls. The disadvantage is that the full range of choices built into ShapePaintable are not available.

The Java file ImageCapsule.java

ImageCapsule is a JComponent encapsulating an Image.

The construction of a component using ImageCapsule may be achieved via:

        new ImageCapsule(image);

A similar effect may now be achieved via:

        PaintableTools.makeComponent(new ImagePaintable(image));

The advantage of ImageCapsule is that the component can be constructed without the nested calls. The disadvantage is that the full range of choices built into ImagePaintable are not available.

Back to top of Graphics or back to top of edu.neu.ccs.gui or back to top of page

Data and Function Plots

The Java file PlotTool.java

PlotTool encapsulates the transform between world and image coordinates for use in plotting data graphs. PlotTool provides functions to plot or mark an array of Point2D data or an array of such Point2D arrays. PlotTool automatically handles the painting of grid lines, axes, 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.

The Java file PlotMark.java

PlotMark is a helper class for drawing geometric shapes or marks at a specified point in a graphics context.

The Java file PlotMarkAlgorithm.java

PlotMarkAlgorithm defines the requirements for an algorithm that will produce a scalable shape defined in the neighborhood of a given point.

The Java file Transform1D.java

Transform1D encapsulates a 1-dimensional transform 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.

The Java file DataTables2D.java

Class DataTables2D provides static methods to create data tables from functions of type Function.OneArg.

The data tables may be used for plotting with the plot tools, for numerical processing, or for associating values with weights in probability.

Back to top of Graphics or back to top of edu.neu.ccs.gui or back to top of page

Shape Creation Classes

• General definitions
• Classes based on a vertex-tangent concept
• Classes based on a path list with lines, quads, and cubics

General definitions

The Java file ClosureMode.java

ClosureMode encapsulates as objects the choices for the closure mode of a polygon or bezier cubic curve. The closure modes are:

• ClosureMode.CLOSED
• ClosureMode.OPEN

The Java file WindingRule.java

WindingRule encapsulates as objects the two constants from GeneralPath: WIND_NON_ZERO and WIND_EVEN_ODD. The winding rules are:

• WindingRule.WIND_NON_ZERO
• WindingRule.WIND_EVEN_ODD

Back to top of Shape Creation or back to top of edu.neu.ccs.gui or back to top of page

Classes based on a vertex-tangent concept

The Java file BaseShape.java

BaseShape encapsulates a Shape defined using vertex and tangent data.

Specifically, BaseShape encapsulates:

• A 2-dimensional array of vertices for a polygon or a Bézier curve
• A 2-dimensional array of tangents to define the Bézier segments in the case of a Bézier curve.

A BaseShape is parametrized by three additional settings:

• A Path.Strategy setting
• A ClosureMode setting
• A WindingRule setting

BaseShape contains the common code and data for several derived classes.

Although not abstract, BaseShape may not be instantiated directly since it does not have a public constructor.

The Java file BaseVertexShape.java

BaseVertexShape extends BaseShape to provide the common functionality for those classes that either do not use the tangent data of BaseShape or compute the tangent data automatically using the vertex data and other internal settings.

Although not abstract, BaseVertexShape may not be instantiated directly since it does not have a public constructor.

The Java file PolygonShape.java

PolygonShape extends BaseVertexShape and fixes its Path.Strategy to be Path.POLYGON. This class does not use the tangent array inherited from BaseShape.

The Java file PolygonDotsShape.java

PolygonDotsShape extends BaseVertexShape and fixes its Path.Strategy to be Path.POLYGON_DOTS. This class does not use the tangent array inherited from BaseShape.

The Java file AutomaticShape.java

AutomaticShape implements a BaseShape in which the tangent array is always computed from the vertex array automatically using a Tangent.Strategy object.

The default tangent strategy produces Bézier curves in which the first and second derivatives of the curve are continuous at each vertex. This strategy is described in the article:

Richard Rasala, Explicit Cubic Spline Interpolation Formulas, in Andrew S. Glassner, Graphics Gems, Academic Press, 1990, 579-584.

To define a shape in which the tangent array varies independently of the vertex array, use the class TweakableShape.

The Java file AutomaticCurve.java

AutomaticCurve extends AutomaticShape and fixes its Path.Strategy to be Path.BEZIER_CUBIC.

The Java file TweakableShape.java

TweakableShape implements a BaseShape in which the vertex array and the tangent array may be changed independently of one another.

To define a shape in which the tangent array is computed from the vertex array automatically, use the class AutomaticShape.

The Java file TweakableCurve.java

TweakableCurve extends TweakableShape and fixes its Path.Strategy to be Path.BEZIER_CUBIC.

The Java file Tangent.java

Tangent encapsulates an interface Strategy that defines the requirement for a strategy that can automatically use the vertex array and boundary information to generate the tangent array for Bézier curves.

Tangent provides some examples of Strategy objects via factory methods and also makes their methods directly available as public static methods in the class to permit others to create Strategy objects.

The factory method bezierStrategy encapsulates the strategy discussed in the article:

Richard Rasala, Explicit Cubic Spline Interpolation Formulas, in Andrew S. Glassner, Graphics Gems, Academic Press, 1990, 579-584.

The factory method chordStrategy encapsulates a strategy in which the tangent at a given vertex is some fixed fraction of the chord joining the two adjacent vertices.

The Java file Path.java

Path encapsulates an interface Strategy that defines the requirement for a strategy that can automatically build a GeneralPath given:

• a vertex array
• a tangent array
• a choice of ClosureMode
• a choice of WindingRule

Path also provides some examples of Strategy objects and some useful static methods. The Strategy objects are:

• Path.POLYGON: make a polygon path joining the vertex points and ignore the tangent array
• Path.POLYGON_DOTS: make a path consisting of the polygon dots at the vertex points and ignore the tangent array
• Path.BEZIER_CUBIC: use the vertex and tangent arrays to construct a Bézier cubic curve
• Path.BEZIER_FRAME: use the vertex and tangent arrays to construct the polygonal frame that is used in the Bézier cubic algorithm
• Path.BEZIER_TANGENT_SEGMENTS: use the vertex and tangent arrays to construct a sequence of disjoint tangent segments at each of the vertex points

The most useful static methods in Path are:

• append that will append an array of Shape objects to a Java GeneralPath object using specified connectivity constraints
• showShapeStructure that will display the structure of a Shape including its dots, control dots, and Bézier frame

Back to top of Shape Creation or back to top of edu.neu.ccs.gui or back to top of page

Classes based on a path list with lines, quads, and cubics

The Java file PathNode.java

PathNode defines a data structure for one segment of a path. It uses simplified path constants MOVE, LINE, QUAD, CUBIC, and CLOSE that are equal to the corresponding complicated constants in GeneralPath. The class methods allow one to set individual segment coordinates or x,y coordinate pairs in a easy manner.

The Java file PathList.java

PathList defines a data structure for a general path that consist of a WindingRule and a list data structure of PathNode objects that may be flexibly created, edited, and searched. Although this class ultimately uses the Java class GeneralPath to construct Shape objects, this class provides far more flexibility than GeneralPath. It is therefore possible to easily use this class for interactive graphics.

The Java file PathListIterator.java

PathListIterator provides a Java PathIterator based on a PathList This class is not really essential since Shape creation may be very efficiently done directly in class PathList.

Furthermore, Java has serious performance problems when it attempts to append to an existing path using a PathIterator. Therefore we recommend working directly with PathList whenever possible.

The Java file PathNodeView.java

PathNodeView provides a view for setting PathNode data through a GUI.

The Java file PathListView.java

PathListView provides a view for setting PathList data through a GUI. This view uses a SimpleArrayPanel to allow the user to control the number and contents of the PathNode objects in the list.

Below is a screen snapshot of the Shape Editor Demo that uses a PathList to specify the MOVE, LINE, QUAD, CUBIC, and CLOSE path segments that constitute the path for the shape. The path segment data on the left hand side is reflected in the shape structure painted on the right hand side. This demo application uses a PathListView in top half of the left hand column.

The PathListView occupies the top half of the left column and includes the sub-panels titled with "Winding Rule" and "Path Node List". The "Winding Rule" sub-panel simply has 2 radio buttons to select the winding rule.

The "Path Node List" uses a SimpleArrayPanel to collect the PathNode items for the PathList.

The buttons signal insert path node view and the buttons signal delete path node view.

The buttons to the right of a particular path node view insert or delete that view while the buttons below insert or delete at the end of the list. You may also set the total number of path node views at once and then fill in the views one-by-one.

The five path segment types that may be entered interactively in a path node view are as follows.

• MOVE[x1;y1]
• LINE[x1;y1]
• QUAD[x1;y1;x2;y2]
• CUBIC[x1;y1;x2;y2;x3;y3]
• CLOSE[]

        public void mouseActionPerformed(MouseEvent mevt)

        public class Methods extends JPF {

            public static void main(String[] args) { new Methods(); }

            // enter here any member or static data declarations as desired

            // enter here the public methods to be made into GUI buttons

            // enter here any non-public helper methods as desired
        }

        public void LaunchFoo() { Foo.main(null); }

        return declaresConstructors(Foo.class,
            new String[] {
                "public Foo()",
                "public Foo(int x)",
                "public Foo(int x, int y)" } );

        return declaresMethods(Foo.class,
            new String[] {
                "public void setX(int x)",
                "public int xValue()",
                "public void setY(int y)",
                "public int yValue()" } );

        return declaresConstructorsAndMethods(Foo.class,
            new String[] {
                "public Foo()",
                "public Foo(int x)",
                "public Foo(int x, int y)" },
            new String[] {
                "public void setX(int x)",
                "public int xValue()",
                "public void setY(int y)",
                "public int yValue()" } );