Annotated Java Power Tools 2.6.0 Source
Annotated Java Power Tools 2.6.0 Source
The Java file
Stringable.java
(javadocs)
The Stringable interface is one of the most fundamental concepts in
the Java Power Tools library. The required methods are deceptively simple:
public void fromStringData(String data) throws ParseException; public String toStringData();
A Stringable object is an object whose state can be set from a suitable
String via fromStringData and which, conversely, can
supply a String via toStringData that is sufficient to set
its state accurately at a future time.
The fact that fromStringData is permitted in its specification to throw
a ParseException means that a Stringable object is
encouraged to use parsing techniques to read sophisticated data in setting its state
and that it has a built-in mechanism to report errors to its callers.
This permits
Stringable data to be read in a uniform manner from graphical user
interfaces, from console input, and from text files. This also permits error
handling for GUIs and console input to be entirely automated by other classes in the
JPT such as
TextFieldView,
DropdownView,
ColorView,
SliderView, and
ConsoleGateway.
This package contains many examples of Stringable classes. Most of these
classes use parsing in the fromStringData method to permit sophisticated
data input. For instance:
Stringable classes
parse integer arithmetic expressions that may involve integer functions.
Stringable classes
parse floating point arithmetic expressions that may involve integer functions and
floating point functions such as sqrt, exp, log, trigonometic functions, and
hyperbolic functions.
Stringable numeric classes
permit the entry of numeric data via hexadecimal strings. This permits a user to set
numeric data accurately at the bit-level.
Stringable class
parses mixed boolean and arithmetic expressions whose final result is a boolean value.
Stringable class
parses color data as decimal or hexadecimal red, green, blue, and optional alpha data
or as named colors. Support for named colors is provided by the helper class
Colors.
Stringable classes for fundamental Shape objects
parse data in a number of useful specific formats.
Stringable classes for paths
parse path node data with the 5 possible segment types
MOVE, LINE, QUAD,
CUBIC, and CLOSE and parse
path list data with a winding rule and a sequence of
path nodes.
Stringable class for complex numbers
extends the class
XPoint2D,
by adding mathematical operations for complex numbers while using the underlying
x,y data representation of its base class.
Stringable classes for function objects
parse the function data as arrays of coefficients.
Each Stringable class builds in a mechanism for providing
significant and user friendly error messages in case a user does enter
data incorrectly. For the numeric and boolean types, the parser will
attempt to pinpoint the exact location of the error and give a message
that explains the problem. For more complicated data types, the user
may enter the ? character when providing data and the resulting
error message will list all data formats accepted for that data type.
Support for the parsing requirements of Stringable is provided by
many parts of the Java Power Tools infrastructure.
Strings
in this package provides support for decoding a String into a
String[]. These tools go beyond the tools of the Java class
StringTokenizer. The
decode method in this class not only uses its own methods, it
also attempts to decode using the more sophisticated tools of the
edu.neu.ccs.codec package.
Thus, one decode method call combines all decoding strategies.
Finally, the Strings class has several additional useful
utilities.
edu.neu.ccs.parser package contains
the tools for arithmetic and boolean expression parsing as well as the
tools for creating user-defined
SimpleFunction
objects that integrate seamlessly into the parser. For examples of parsing
that combines arithmetic and boolean expressions with user-defined functions,
see the
applets
listed below.
edu.neu.ccs.codec package contains
tools for encoding and decoding string arrays with 100% robustness. Unlike
the simpler tools in the Strings class,
these tools will guarantee that a string array encoded into a string can be
faithfully decoded into its original constituents. The one drawback to the
tools in this package is that the encoded strings are machine-readable but
are not particularly easy to read or enter interactively by humans. Hence,
these tools are more appropriate for
Stringable types by packing and unpacking
the data from internal Stringable member objects.
Stringable data from and to files
Final note: A Stringable object is always mutable. This
is much more convenient for dealing with user interaction and IO than using
immutable data types.
For interesting examples of how the Stringable interface plays out in
graphical user interfaces, see the following 4 applets:
See also
SimpleFunction.
Back to top of edu.neu.ccs or back to top of page
The Java file
XObject.java
(javadocs)
The abstract class XObject is the standard base class for
building many Stringable objects.
The Java file
XNumber.java
(javadocs)
The abstract class XNumber is the standard base class for
building most numeric Stringable objects.
Back to top of edu.neu.ccs or back to top of page
The Java file
XBoolean.java
(javadocs)
The Java file
XChar.java
(javadocs)
Back to top of edu.neu.ccs or back to top of page
The Java file
XByte.java
(javadocs)
The Java file
XShort.java
(javadocs)
The Java file
XInt.java
(javadocs)
The Java file
XLong.java
(javadocs)
The Java file
XFloat.java
(javadocs)
The Java file
XDouble.java
(javadocs)
See also XComplex
Back to top of edu.neu.ccs or back to top of page
The Java file
HexXByte.java
(javadocs)
The Java file
HexXShort.java
(javadocs)
The Java file
HexXInt.java
(javadocs)
The Java file
HexXLong.java
(javadocs)
The Java file
HexXFloat.java
(javadocs)
The Java file
HexXDouble.java
(javadocs)
Back to top of edu.neu.ccs or back to top of page
The Java file
XPoint2D.java
(javadocs)
The Java file
XLine2D.java
(javadocs)
The Java file
XRect.java
(javadocs)
The Java file
XSquare.java
(javadocs)
The Java file
XOval.java
(javadocs)
The Java file
XCircle.java
(javadocs)
The Java file
XRoundRect.java
(javadocs)
The Java file
XRoundSquare.java
(javadocs)
The Java file
XInterval.java
(javadocs)
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
The Java file
XString.java
(javadocs)
The Java file
XBigInteger.java
(javadocs)
The Java file
XBigDecimal.java
(javadocs)
The Java file
XComplex.java
(javadocs)
The XComplex class implements a complex number data type.
The Java file
XColor.java
(javadocs)
The XColor class supports a variety of text formats for the
specification of a color: RGB or RGBA in decimal; assorted hexadecimal
formats that are common on the web; and named colors. The named colors
are based on class Colors.
The Java file
SmallSet.java
(javadocs)
The SmallSet class encapsulates a set of
numbers between 0 and 31. Internally, a set is represented as bits in an
integer. The class provides an efficient utility for enumerating the
subsets of a given set.
Back to top of edu.neu.ccs or back to top of page
The Java file
XPolynomial.java
(javadocs)
The Java file
XFourier.java
(javadocs)
The Java file
XPolynomialComplex.java
(javadocs)
Back to top of edu.neu.ccs or back to top of page
The Java file
Strings.java
(javadocs)
This class contains general purpose string and parsing utilities.
One application of these tools is in the implementation of the
Stringable
interface for several classes.
This class provides support for the exact encoding of a String[]
into a String using a desired delimiter and the corresponding
exact decoding of a String into a String[].
Of course, these tools must assume that the delimiter itself does not
appear in the String data. These decoding
tools go beyond the tools of the Java class StringTokenizer.
This class also supports the notion of a string group. There are
three kinds of string group that may be embedded into a larger
String:
[s0;s1;...](s0,s1,...){s0|s1|...}
The advantage of a string group is that the boundary delimiter pairs
[] () {}
are matched with corresponding internal delimiters
; , |
so that a decoder knows how to decode simply by reading an initial boundary
delimiter and then locating the extent of the string group.
The decode method in this class not only uses its own methods,
it also attempts to decode using the more sophisticated tools of the
edu.neu.ccs.codec package.
Thus, one decode method call combines all decoding strategies.
Finally, this class contains methods to build name-value string pairs of the form name=value and to decompose such pairs. This class also has conversion utilities to go back and forth between strings and numeric types and text-to-html utilities.
The Java file
Colors.java
(javadocs)
The Colors class is a support class that supplies a large list
of named RGB colors. These colors
may be entered directly by the user,
may be used in the
XColor
method fromStringData,
and may be accessed interactively in the dropdown view that is incorporated
as an option into ColorView.
Back to top of edu.neu.ccs or back to top of page
The Java file
Function.java
(javadocs)
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
Parameter.java
(javadocs)
The 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
F.java
(javadocs)
This class consists of higher order functions that will take real functions as arguments and produce a real function as the return value.
The Java file
FunctionComplex.java
(javadocs)
The class FunctionComplex 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
ParameterComplex.java
(javadocs)
The class ParameterComplex 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
FC.java
(javadocs)
This class consists of higher order functions that take complex functions as arguments and produce a complex function as the return value.
See also
SimpleFunction.
Back to top of edu.neu.ccs or back to top of page
The edu.neu.ccs.codec package contains
tools for encoding and decoding string arrays with 100% robustness. Unlike
the simpler tools in the Strings class,
these tools will guarantee that a string array encoded into a string can be
faithfully decoded into its original constituents. The one drawback to the
tools in this package is that the encoded strings are machine-readable but
are not particularly easy to read or enter interactively by humans. Hence,
these tools are more appropriate for
Stringable
types by packing and unpacking
the data from internal
Stringable
member objects.
Stringable
data from and to files
The Java file
Codec.java
(javadocs)
The Codec interface describes the requirements for a tool that can
encapsulate a String[] into a String and then
faithfully unencapsulate the String back into the original
String[].
Back to top of edu.neu.ccs.codec or back to top of page
The Java file
CountPrefixCodec.java
(javadocs)
The Java file
EscapedCodec.java
(javadocs)
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
String[] and a String
The Java file
CodecUtilities.java
(javadocs)
Provides methods to encode either a String[] or a
Stringable[]
into a String using either the default
Codec for this package
or a specified Codec
implementation.
Also provides the inverse method
decode that will faithfully unencapsulate an encoded
String back into a String[].
Encoding and decoding operations should be performed through the methods of
this class rather than by directly calling a particular Codec.
Note: The current default Codec for this package is the
CountPrefixCodec.
Back to top of edu.neu.ccs.codec or back to top of page
The Java file
ConsoleAware.java
(javadocs)
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 Framework (JPF) environment, then these calls will be done automatically.
The console object provides three data streams:
console.in for inputconsole.out for outputconsole.err for error outputIf 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 because
waiting for console input may block the handling of other user
interaction events.
Use one of the classes
SimpleThreadedAction
or
ThreadedAction
to make an action such as user input run in its own thread.
If you use the Java Power Framework (JPF) environment, then separate threads are created automatically for all methods in the JPF GUI so there is no need to deal with separate threading manually.
Back to top of edu.neu.ccs.console or back to top of page
The Java file
ConsoleGateway.java
(javadocs)
The methods provided by ConsoleGateway itself fall into three
categories:
console settingsprompt, pressReturn,
and confirm that handle common input-output activitiesBack to top of edu.neu.ccs.console or back to top of page
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.
setDataType and getDataType
to control the class of the
Stringable
object being inputdemand, demandObject,
request, requestObject, and reading
for input of a
Stringable
object with various optionsdemandBytedemandShortdemandIntdemandLongdemandFloatdemandDoubledemandChardemandBooleandemandStringdemandBigIntegerdemandBigDecimaldemandColorrequestByterequestShortrequestIntrequestLongrequestFloatrequestDoublerequestCharrequestBooleanrequestStringrequestBigIntegerrequestBigDecimalrequestColorBack to top of edu.neu.ccs.console or back to top of page
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 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
(javadocs)
The Java file
ConsoleTextPane.java
(javadocs)
The Java file
ConsoleWindow.java
(javadocs)
Back to top of edu.neu.ccs.console or back to top of page
The Java file
StringableFilter.java
(javadocs)
The Java file
FilterException.java
(javadocs)
The StringableFilter interface describes a filter object that
encapsulates one method:
Stringable filterStringable(Stringable obj) throws FilterException
This filter method is used to determine if the given
Stringable
object is suitable for further processing, that is,
if the object satisfies whatever constraints are represented by the filter.
If the object does satisfy the constraints, the filter method will normally
return the same Stringable object.
However, if state changes must be made,
then the filter method should create and return a new Stringable
object so that the original Stringable object is unchanged.
If the given Stringable object does not satisfy the constraints
of the filter method, then the method should throw a FilterException.
This package contains 2 abstract classes for creating filters and 4 concrete
classes for specific filters. In addition, the class
StringableFilterSequence
provides the mechanism to create a composite filter that invokes a sequence
of filters in turn.
The input operations in the
GeneralView
interface and in the 2 classes that implement this interface,
TextFieldView
and
DropdownView,
permit the caller to supply a StringableFilter to impose
constraints on the user input. If the filter throws a
FilterException then this will be converted to a
ParseException which will then be handled by the
automatic error handlers. Similar options are provided by
the input operations in
ConsoleGateway.
Back to top of edu.neu.ccs.filter or back to top of page
The Java file
NumericFilter.java
(javadocs)
The Java file
BoundFilter.java
(javadocs)
Back to top of edu.neu.ccs.filter or back to top of page
The Java file
CaseActionFilter.java
(javadocs)
The Java file
MinimumBoundFilter.java
(javadocs)
The Java file
MaximumBoundFilter.java
(javadocs)
The Java file
RangeFilter.java
(javadocs)
Back to top of edu.neu.ccs.filter or back to top of page
The Java file
StringableFilterSequence.java
(javadocs)
Back to top of edu.neu.ccs.filter or back to top of page
Back to top of edu.neu.ccs.gui or back to top of page
The three Java interfaces Displayable, TypedView, and
GeneralView are intended to support graphical user interfaces in
which the data for an object may be given by text input. Such GUIs will often
provide additional graphical means for supplying the object data. We arrange
these three interfaces in a hierarchy, that is, Displayable is the
base, TypedView adds behavior to Displayable, and
GeneralView adds behavior to TypedView. The data
model for a TypedView or GeneralView must be a type
that implements Stringable.
The Java interface StringObjectView is intended to support a
direct mapping between strings that appear in the graphical user interface
and specific objects in the internal data structure of the program. Thus,
the selection of a string by the user can map directly to the selection of
an object.
The Java file
Displayable.java
(javadocs)
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.
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.
In a Displayable, incidental aspects of a view such as its
widget geometry and color are normally not part of the view state.
Unlike TypedView and GeneralView,
Displayable does not impose any requirements on the data model.
In Displayable, the two most important methods are:
public void setViewState(String data)
public String getViewState()
The Java file
TypedView.java
(javadocs)
The TypedView interface extends Displayable and
requires methods that deal with the data model. A TypedView
must return the class of its current data model via the method
getDataType. This class must implement
Stringable.
A TypedView should 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 should 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
should normally insist that the user provide valid input while the method
requestObject should normallly offer the user the option of
cancelling the input process if the data is invalid. In the latter situation,
a CancelledException should be
thrown to alert the program of this user decision.
In TypedView, the three most important methods are:
public Class getDataType()
public Stringable demandObject()
public Stringable requestObject() throws CancelledException
In addition to these straightforward methods, a TypedView should
also maintain an internal property list object using the class
InputProperties. In this object,
the view may store additional settings such as error handling parameters.
The Java file
GeneralView.java
(javadocs)
The GeneralView interface extends TypedView and adds
the method setDataType.
public void setDataType(Class dataType)
Thus, a GeneralView is a
TypedView that is able to handle multiple
Stringable data types. This feature
is very powerful.
The GeneralView interface requires additional methods beyond the
method setDataType to allow such views to be used with great
flexibility. These include:
StringableFilter to
restrict the data values permitted in the view.
The helper class
GeneralViewSupport may be
used internally in a GeneralView to assist in implementation
of the various required methods.
The prime examples of GeneralView’s are
TextFieldView
and
DropdownView.
The Java file
StringObjectView.java
(javadocs)
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 StringObjectView’s are
StringObjectRadioPanel
and
StringObjectDropdown.
Note that both GeneralView and StringObjectView require methods
to add or remove action listeners that will be triggered when the view state changes.
Back to top of edu.neu.ccs.gui or back to top of page
The Java file
GeneralViewSupport.java
(javadocs)
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
(javadocs)
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 promptDIALOG_TITLE: the error dialog titleINPUT_MODEL: either JPTConstants.OPTIONAL
or JPTConstants.MANDATORYSUGGESTION: 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
(javadocs)
CancelledException is an exception designating that an input
operation was cancelled by the user.
Back to top of Support classes for the GUI interfaces or back to top of edu.neu.ccs.gui or back to top of page
The Java file
TextFieldView.java (one line text input)
(javadocs)
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
object 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.
Important 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.
These methods parallel similar methods for console IO that are available
through the ConsoleGateway class and
the associated ConsoleAware interface.
Both sets of methods implement automatic arithmetic and boolean expression parsing
using tools in the package edu.neu.ccs.parser.
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 font for the text field view. The default font is
the text field font in the current look and feel but the font may be changed
either in a constructor or after construction.
As a further convenience, TextFieldView provides static methods
to compute the text field width required to hold a particular string or a
particular run of repeated characters using a given font. With these static
methods, the caller can compute the optimal width for a text field based on
the font that will be used in the text field.
TextFieldView inherits from JTextField the ability
to add an ActionListener that will be triggered when the return
key is pressed in the view.
The Java file
TextAreaView.java (multi line text input)
(javadocs)
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 a String object. Using the
methods demandObject and requestObject which
are identical for a TextAreaView, the text in the view is
returned as an XString object. Further processing of the
string data is the responsibility of the caller.
The Java file
StringViewer.java (display of a string in a GUI)
(javadocs)
Class StringViewer provides static tools for viewing a
String in a GUI. The core methods wrap a String in
an Annotation which is in turn wrapped
in a JPTScrollPane whose viewport
size may be set by the caller or may be defaulted to 800 by 600.
The caller can then manually place this scroll pane in a GUI or can
automatically display it in either a frame or an OK dialog box.
The class StringViewer was built specifically to support the
display of a stack trace generated by the class
StackTrace but it has many other
potential applications in which significant amounts of text must be shown
to a user.
The Java file
XObjectView.java
(javadocs)
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 intended to be used as a default view in case no more specific
view is available. This view is in fact rarely used. Note also that this
view may not be used for data input.
Back to top of Views: text fields, text areas, strings or back to top of edu.neu.ccs.gui or back to top of page
The Java file
BooleanView.java (check box selection)
(javadocs)
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.
BooleanView inherits from JCheckBox the ability
to add an ActionListener that will be triggered when the state
of the view (checked or unchecked) changes.
Back to top of Views: check boxes or back to top of edu.neu.ccs.gui or back to top of page
The Java file
RadioPanel.java (radio button selection)
(javadocs)
The RadioPanel class may be used directly to construct a panel
of radio buttons. The class is also the base class for
OptionsView and
StringObjectRadioPanel.
RadioPanel is designed to input a selection using
a set of Java JRadioButton objects.
What makes RadioPanel quite convenient are its constructors
that make it possible to set many choices immediately. Here are some of
the options:
String.RadioPanel is a vertical
list. If some other layout is desired, a
LayoutManager may be supplied.ActionListener that will be
executed when any radio button is selected. Alternately, one
can supply an array of ActionListener objects,
one for each radio button, that targets each button specifically.
To illustrate the interaction of the String array of labels and a
TableLayout layout manager, let us
consider two examples. Both examples will use the same array of 8 labels:
String[] labels =
{ "1", "22", "333", "4444", "55555", "666666", "7777777", "88888888" };
To better illustrate what is happening, we will use a TableLayout
that is set for only 2 rows and 2 columns which is insufficient for 8 labels.
This will permit us to see how the table grows. We will set the cell gaps to
be 10 and will align the radio buttons in each cell to the WEST
which is what is commonly done with radio buttons.
In example 1, we will use an orientation parameter of HORIZONTAL.
Here is the code:
TableLayout layout = new TableLayout(2, 2, 10, 10, WEST, HORIZONTAL);
RadioPanel radio = new RadioPanel(labels, layout);
Here is the screen snapshot for a HORIZONTAL orientation parameter:
In example 2, we will use an orientation parameter of VERTICAL.
Here is the code:
TableLayout layout = new TableLayout(2, 2, 10, 10, WEST, VERTICAL);
RadioPanel radio = new RadioPanel(labels, layout);
Here is the screen snapshot for a VERTICAL orientation parameter:
As you can see, the orientation parameter
(HORIZONTAL or VERTICAL) controls the
direction in which the table grows
if its initial number of rows and columns is insufficient for the data.
A HORIZONTAL TableLayout grows horizontally and
a VERTICAL TableLayout grows vertically. Another way to see
this is:
TableLayout orientation of HORIZONTAL,
each column is filled to its capacity and then objects are placed
in the next column to the right. New columns are added if needed.TableLayout orientation of VERTICAL,
each row is filled to its capacity and then objects are placed
in the next row below. New rows are added if needed.
Although this convention may seem strange, it makes perfect sense if you imagine
starting with a layout with 1 row and 1 column. In that case,
an orientation parameter of HORIZONTAL leads to a horizontal table
and
an orientation parameter of VERTICAL leads to a vertical table.
Final note: When using a RadioPanel, the caller may obtain
the label of the selected radio button,
the index of the selected radio button,
or the selected radio button itself.
The Java file
OptionsView.java (radio button selection)
(javadocs)
An OptionsView is a
RadioPanel that implements
TypedView by setting the data type to
XInt and by using the selected index to set
and get its view state as a TypedView.
The Java file
StringObjectRadioPanel.java (radio button selection)
(javadocs)
A StringObjectRadioPanel is a
RadioPanel that implements
StringObjectView.
Hence the user selection of a radio button implicitly selects its
string which in turn implicitly selects the associated object in
the model.
Back to top of Views: radio buttons or back to top of edu.neu.ccs.gui or back to top of page
The Java file
Dropdown.java (editable dropdown list selection)
(javadocs)
The Dropdown class is a class that provides basic
dropdown list capabilities in its own right and is also the
base class for more sophisticated dropdown objects.
The Java file
DropdownView.java (editable dropdown list selection)
(javadocs)
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)
(javadocs)
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.
Back to top of Views: dropdown lists or back to top of edu.neu.ccs.gui or back to top of page
The Java file
SliderView.java (slider selection)
(javadocs)
Class SliderView permits the construction of
a slider with pixel-level control of the size of the slider
track. The caller can therefore control the relationship
between the minimum and maximum values represented by the
slider and the physical implementation in pixels. This can
permit users to make slider selections with more accuracy.
The SliderView code was completely rewritten
for version 2.6.0. A few older methods that are now obsolete
have been retained for backward compatibility.
This class no longer depends on the Java class JSlider.
In addition to pixel-level control of the size of the slider,
SliderView offers several advantages over the Java
class JSlider.
JSlider, it
is not the default.SliderView provides what we
believe is a better algorithm for automatically computing
the location of tick marks and labels. Moreover, the
underlying methods for showing tick marks and labels are
public so the caller can manually fine tune these objects
to any degree desired.SliderView includes a text
field that shows the current slider value and may be used
to set that value if desired by the user. The text field
may, however, be omitted from the GUI by setting a certain
constructor parameter appropriately.SliderView provides many constructors
which allow the caller to exercise whatever degree of control
is needed in the slider construction.
The SliderView class implements
TypedView
with a type of
XInt
corresponding to the int value returned by a slider.
For examples of a SliderView, see the
Spinning Animation applet
and the
Star Color applet.
In the latter, click on the color box to bring up a
ColorPaneDialog
which uses 4 color sliders each with a gradient paint on its slider track.
Back to top of Views: sliders or back to top of edu.neu.ccs.gui or back to top of page
The Java file
ColorView.java (color selection)
(javadocs)
The ColorView class is a
TypedView
for the user input of a Color.
By default, the view will display a color box using a
PaintSwatch
together with an dropdown list for selection of the color.
If desired, either the color box or the dropdown may be made invisible.
The color box is active. If the color box is clicked, a
ColorPaneDialog
dialog is displayed to permit the user to select the color interactively
using sliders for the red, green, blue, and alpha components of the color.
This dialog permits the user to contrast the selected color with a color
previously entered called the original color.
The dropdown list permits the user to select a color from 142 named colors that are presented in the dropdown as a color swatch together with a color name. These color names follow conventions that have become more or less standard on the web. The dropdown list is also editable so that the user may enter a color using red, green, blue, and optional alpha components using either decimal or hexadecimal formats.
The following sequence of screen snapshots illustrates the features of a
ColorView. First, we show a default ColorView
with color black.
Next, we show the color dropdown list with “DarkOrange” about to be selected.
Next, we show the ColorView with “DarkOrange”.
Next, we show the ColorPaneDialog that is brought up with a
click on the color swatch in the ColorView.
Finally, we show the ColorView after the user has clicked OK
in the ColorPaneDialog.
The Java file
ColorPane.java (color selection)
(javadocs)
A pane in which the user may select a color using sliders for each of the 4 color components: red, green, blue, alpha. For convenience, the pane also contains a color dropdown so the user can start with a named color and then modify that color interactively.
See ColorView
and ColorPaneDialog.
The Java file
ColorPaneDialog.java (color selection)
(javadocs)
An OK-Cancel dialog that contains a ColorPane.
This type of dialog is opened by clicking on the color swatch in a
ColorView.
For a snapshot, click here.
The Java file
MultiColorView.java (multi-color selection)
(javadocs)
Class MultiColorView provides a view for the interactive selection
of multiple colors. In this view, there is a table with labels in column 0
and corresponding ColorView objects in column 1.
The user may set multiples colors by setting each of the individual ColorView
objects. In interfacing with other objects, a MultiColorView can return
either an individual color based on its index or an array of all colors represented in the
view.
One application of MultiColorView is the selection of the function
plot colors in FunctionsPlotter.
Below is a snapshot of the multi-color view as extracted from the larger GUI.
Back to top of Views: color selection or back to top of edu.neu.ccs.gui or back to top of page
The Java file
ComponentFactory.java
(javadocs)
ComponentFactory has 3 static methods:
makeComponent that constructs a Component
from an ObjectmakeIcon that constructs an Icon
from an ObjectmakePaintable that constructs a
Paintable
from an Object
Throughout Java Power Tools, whenever a caller is required to supply a
Component, Icon, or
Paintable, an effort is made
to permit the caller to supply a more general Object and
to have the construction of the desired entity be entirely automated.
For example, if the user wants to install a String into a
GUI in the “standard fashion” then this may be handled
automatically. Of course, the caller retains the ability to build
whatever explicit GUI objects are desired.
If automation is desired by the caller then the 3 static methods
in this class are usually called behind the scenes so that no extra
effort will be required.
In 3 tables below, we will show how the 3 static methods work. Before
that, let us make some general remarks.
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 will call the makePaintable method
to try to convert the Object into a
Paintable.
If that attempt succeeds then the Paintable will be placed
into a PaintableComponent
which is both a Component and an Icon.
On the other hand, if this final attempt fails then null
will be returned.
The table below shows more about how makeComponent works.
| Argument | Return | ||
Component |
The same Component |
||
String |
Annotation |
||
Icon |
Annotation |
||
Action |
JButton |
||
Paint |
PaintSwatch |
||
|
PaintableComponent |
||
| otherwise | null |
The table below shows more about how makeIcon works.
| Argument | Return | ||
Icon |
The same Icon |
||
Paint |
PaintSwatch |
||
|
PaintableComponent |
||
| otherwise | null |
The table below shows more about how makePaintable works.
| Argument | Return |
Paintable |
The same Paintable |
Shape |
ShapePaintable |
PathList |
ShapePaintable |
Image |
ImagePaintable |
ImageIcon |
ImagePaintable |
String |
MultiLineTextPaintable |
Point2D |
PointPaintable |
Object[] |
PaintableSequence |
| otherwise | null |
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 the static method in this class.
Back to top of Factory methods or back to top of edu.neu.ccs.gui or back to top of page
The Java file
TableLayout.java
(javadocs)
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
(javadocs)
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
(javadocs)
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
(javadocs)
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
The Java file
DisplayPanel.java
(javadocs)
Class 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 in its
Displayable components.
DisplayPanel also provides the following special features:
makeComponent that constructs a
Component from an Object by calling the
corresponding static method from
ComponentFactory.
addObject methods that add more general objects to
the panel by using the makeComponent method to automatically
convert these objects into suitable components. This permits a caller to
add more general entities to a GUI without the need to explicitly convert
these entities into components.
frame methods that permit a DisplayPanel
to create a frame (window) with various options and then to insert itself
into that frame. This is known as self-actualization.
generalDialog methods that permit a DisplayPanel
to create a dialog with various options and then to insert itself into that
dialog.
uniformizeSize method that forces all items in the
panel to have the same preferred size if that sizing policy is desired.
The Java file
BasePane.java
(javadocs)
Class BasePane extends
DisplayPanel
and contains common font and size definitions for use in other components.
The common fonts are built using the class
Fonts in
conjunction with any font size adjustment made using the methods in
LookAndFeelTools.
The caller who wishes
to use these common definitions can either extend BasePane
or install components into an instance of BasePane. In
either case, it is the responsibility of the caller to set the fonts for
any components that will use these common definitions. This cannot be
done automatically.
Back to top of Panels: DisplayPanel and BasePane or back to top of edu.neu.ccs.gui or back to top of page
The Java file
TablePanel.java
(javadocs)
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:
HORIZONTALVERTICAL
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:
CENTERNORTHNORTH_EASTEASTSOUTH_EASTSOUTHSOUTH_WESTWESTNORTH_WEST
The Java file
TableGenerator.java
(javadocs)
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
(javadocs)
CellPosition is a simple helper class to encapsulate a row and
column position in a table.
The Java file
HTable.java
(javadocs)
HTable is a derived class of TablePanel
that is constrained to be 1-dimensional and horizontal.
The Java file
VTable.java
(javadocs)
VTable is a derived class of TablePanel
that is constrained to be 1-dimensional and vertical.
Back to top of Panels: TablePanel and associated classes or back to top of edu.neu.ccs.gui or back to top of page
The Java file
BufferedPanel.java
(javadocs)
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.
BufferedImage object holds a bit-map that is used
to paint the background layer of the BufferedPanel.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 Panels: BufferedPanel or back to top of edu.neu.ccs.gui or back to top of page
The Java file
Annotation.java
(javadocs)
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:
Annotation can display multi-line text.Annotation can be in an alert state.Annotation can have a separate icon to denote that it
is in an alert state.Back to top of Panels: Annotation or back to top of edu.neu.ccs.gui or back to top of page
The Java file
Halo.java
(javadocs)
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
(javadocs)
JPTScrollPane extends JScrollPane by adding methods
that help control the preferred size of the JViewport window. Since
the size of the JViewport window is what concerns the caller of a
scroll pane class, this size control is very convenient.
JPTScrollPane does not implement
Displayable
but leaves that to its derived class
ScrollableDisplay.
The Java file
ScrollableDisplay.java
(javadocs)
ScrollableDisplay is a
JPTScrollPane
that also 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.
The Java file
Display.java
(javadocs)
The class 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 may add a label to an object while building the table.
Hence Display is no longer needed to add a label annotation.
Titles may now be created in two ways. The class
DisplayPanel
provides numerous methods to create borders including a titled border
via its titleBorder methods. This provides an alternative to
the use of Display. However, as the screen snapshot below
illustrates, the default conventions for the two approaches are different.
The Display class builds its border using an etch border
for its frame whereas the method titleBorder uses a line border
of thickness 2 as its default. Which is preferable is a matter of aesthetic choice.
The titleBorder family of methods is more general, however, since there
are several variations that permit the caller to choose the base border for the frame.
The titleBorder family of methods also includes options to set the title
font and color and to set the title position in the frame.
To integrate additional components into a GUI that already uses Display,
it is best to continue to use Display for visual continuity. For new
code, the use of titleBorder will provide the most flexibility.
Back to top of Panels: Wrapper panels or back to top of edu.neu.ccs.gui or back to top of page
The Java file
ActionsPanel.java
(javadocs)
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
(javadocs)
DisplayCollection creates a one dimensional table of
Displayable components.
Since the invention of TablePanel, this panel is rarely used.
The Java file
SimpleArrayPanel.java
(javadocs)
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:
TypedView Class object.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:
viewType must not be null.viewType must extend JComponent
so a view may be directly inserted into its panel.viewType must implement
TypedView
so the model data can be extracted from a view by the standard
methods of the
TypedView interface.viewType class must have a default
constructor.
For a snapshot of a SimpleArrayPanel in use, see
PathListView
The Java file
ArrayPanel.java
(javadocs)
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 Panels: Other collection panels or back to top of edu.neu.ccs.gui or back to top of page
The Java file
Zoo.java
(javadocs)
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
(javadocs)
The Java file
ZooContainer.java
(javadocs)
The Java file
Laminate.java
(javadocs)
The three classes above are helper classes for Zoo.
Back to top of Panels: Zoo and associated classes or back to top of edu.neu.ccs.gui or back to top of page
The Java file
JPTFrame.java
(javadocs)
JPTFrame extends the Java JFrame class for
the following purposes.
JFrame that is packed
and opened 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
The Java file
GeneralDialog.java
(javadocs)
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
(javadocs)
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 actionDialogAction.AUTO_CLOSE:
The choice to auto close the dialog after the actionDialogAction.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
(