net.sourceforge.jcomponentbreadboard
Class JComponentBreadboard

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.JPanel
                  net.sourceforge.jcomponentbreadboard.JComponentBreadboard

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible

public class JComponentBreadboard
extends javax.swing.JPanel

Represents all aspects of a Java/Swing form--from layout management to how the form is connected to the objects it views and controls. For more information including detailed examples, see the package description and the JComponentBreadboard User's Guide.

Version:

1.0.1 (requires JDK 1.5 or higher)

Author:

John C. Gunther

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JComponent

javax.swing.JComponent.AccessibleJComponent

Field Summary

static net.sourceforge.jcomponentbreadboard.JComponentBreadboard.ColumnarDitto	__ A directive that, when placed into the cell of a breadboard array, instructs JComponentBreadboard to use the object reference immediately to the left of this cell for this cell, too.
static net.sourceforge.jcomponentbreadboard.JComponentBreadboard.ScalingDirective	BISCALE Columns (rows) of the breadboard array whose headers contain this directive both uniformly scale their preferred-size-based widths (heights) up when extra width (height) is available in the parent container, and also uniformly scale down when the parent container is too small.
javax.swing.JButton	CLOSE_BUTTON Whenever they receive the windowClosing event, JDialogs created via createBreadboardDialog are configured to call the doClick method of the CLOSE_BUTTON of the single top-level JComponentBreadboard that they contain.
static java.lang.String	DATA_IS_VALID Special keyword returned by data validation methods to indicate that the data String passed to the method contains valid data.
java.lang.String	DEFAULT_INVALID_DATA_MESSAGE_TITLE The default title of the popup error message dialog if no HTML title tag is included in the string returned from a data validation method function.
static int	DEFAULT_JBRUN_REFRESH_INTERVAL The default interval at which the progress dialog associated with a jbRun launched process is updated, in milliseconds.
static net.sourceforge.jcomponentbreadboard.JComponentBreadboard.ScalingDirective	EXPANDS Columns (rows) of the breadboard array whose headers contain this directive uniformly scale their preferred-size-based widths (heights) up when extra width (height) is available in the parent container, but do not uniformly scale down when the parent container is too small.
static int	MAX_UPSIZE The maximum allowed xUpsize width increase, or yUpsize height increase.
static net.sourceforge.jcomponentbreadboard.JComponentBreadboard.ScalingDirective	NOSCALE Columns (rows) of the breadboard array whose headers contain this directive do not uniformly scale their preferred-size-based widths (heights) up when extra width (height) is available in the parent container, and also do not uniformly scale down when the parent container is too small.
static java.lang.String	REVERT_AND_BEEP Special keyword returned by data validation methods to indicate that the data String passed to the method contains invalid data, and that you want the field to reject this input and, after beeping for feedback, revert the data back to the last validated entry.
static java.lang.String	REVERT_QUIETLY Special keyword returned by data validation methods to indicate that the data String passed to the method contains invalid data, and that you want the field to reject this input and quietly revert back to the last validated entry.
java.lang.String	ROWWISE_DITTO A directive that, when placed into the cell of a breadboard array, instructs JComponentBreadboard to use the object reference immediately above this cell for this cell, too.
static net.sourceforge.jcomponentbreadboard.JComponentBreadboard.ScalingDirective	SHRINKS Columns (rows) of the breadboard array whose headers contain this directive do not scale their preferred-size-based widths (heights) up when extra width (height) is available, but do scale down uniformly when the parent container is too small.

Fields inherited from class javax.swing.JComponent

TOOL_TIP_TEXT_KEY, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

JComponentBreadboard()
Constructs a new JComponentBreadboard.

JComponentBreadboard(java.lang.Object[][] breadboard)
Constructs a new JComponentBreadboard from the specified breadboard array.

Method Summary

void	addNotify() After calling the super class' addNotify method, calls this class' jbRefresh method.
static void	beginProgressMonitoredSection(double startFraction, double endFraction) When called from within a jbRun-created thread, indicates the beginning of a progress monitored section of the jbRun launched process.
static javax.swing.JDialog	createBreadboardDialog(java.awt.Container parent, JComponentBreadboard jcb, java.lang.String title, boolean isModal) Creates a JDialog whose entire content pane contains only the specified single JComponentBreadboard.
static void	endProgressMonitoredSection() When called from within a jbRun-launched thread, ends a progress monitored section begun via beginProgressMonitoredSection.
static boolean	getJbRunCanceled() When called from code executing within a jbRun-launched thread, returns true if the cancel flag has been raised (for example, by the user clicking on the cancel button) since the run started, or false otherwise.
static java.lang.String	getJbRunNoteGlobally() If executed from within the jbRun launched process, returns the text of the note that would be displayed just above the progress bar on jbRun's progress cancel dialog, if that dialog were immediately refreshed.
static double	getJbRunProgressGlobally() Returns the fraction of the (entire) currently executing jbRun-launched process that has been completed so far.
java.lang.Object	getResult() Retrieves the object reference previously set with setResult.
static int	getXUpsize(javax.swing.JComponent jc) Returns the number of pixels that JComponentBreadboard will add to the JComponent's preferred width to form the "adjusted preferred width" used by JComponentBreadboard's layout manager.
static int	getYUpsize(javax.swing.JComponent jc) Returns the number of pixels that JComponentBreadboard will add to the JComponent's preferred height to form the "adjusted preferred height" used by JComponentBreadboard's layout manager.
static boolean	isJbRunRunning() Returns true if a jbRun-launched process is currently executing, false otherwise.
static boolean	isXFilled(javax.swing.JComponent jc) Returns true if the an attribute to expand the JComponent's width to fill out the grid cells that contain it horizontally has been attached to the JComponent, false otherwise.
static boolean	isYFilled(javax.swing.JComponent jc) Returns true if an attribute to expand the JComponent's height to fill out the grid cells that contain it vertically has been attached to the JComponent, false otherwise.
void	jbConnect(javax.swing.JComponent[][] componentArray, java.lang.String rootName) Injects an interface into this JComponentBreadboard-based form that binds the connectable properties of the specified 2-D JComponent array to the form via correspondingly-named, 2-D-array-indexed, getter/setter method defined, properties of the interface.
void	jbConnect(javax.swing.JComponent[] componentArray, java.lang.String rootName) Injects an interface into this JComponentBreadboard-based form that binds the connectable properties of the specified 1-D JComponent array to the form via correspondingly-named, 1-D-array-indexed, getter/setter defined, properties of the interface.
void	jbConnect(javax.swing.JComponent jcomponent, java.lang.String rootName) Injects an interface into this JComponentBreadboard-based form that binds the connectable properties of the specified JComponent to the form via correspondingly-named (getter/setter defined) properties of the interface.
void	jbConnect(javax.swing.KeyStroke[][] keyStrokeArray, java.lang.String rootName) Injects an interface into this JComponentBreadboard-based form that binds the connectable properties of the specified 2-D KeyStroke array to the form via correspondingly-named, row and column indexed, properties of the interface.
void	jbConnect(javax.swing.KeyStroke[] keyStrokeArray, java.lang.String rootName) Injects an interface into this JComponentBreadboard-based form that binds the connectable properties of the specified 1-D KeyStroke array to the form via correspondingly-named, 1-D-array-indexed, properties of the interface.
void	jbConnect(javax.swing.KeyStroke keyStroke, java.lang.String rootName) Injects an interface into this JComponentBreadboard-based form that binds the connectable properties of the specified KeyStroke to the form via correspondingly-named, getter/setter defined, properties of the interface.
void	jbRefresh() Refreshes all the jbConnected JComponents and/or KeyStrokes contained on this JComponentBreadboard.
void	jbReturn() Removes (by calling its dispose method) the parent Frame or Dialog containing the JComponentBreadboard, if such a Frame or Dialog exists, otherwise does nothing.
void	jbReturn(java.lang.Object result) Closes the parent Dialog or Frame of the form via dispose, and sets the result property of this form to the specified Object.
void	jbRun(java.lang.Runnable jbJob) Runs the specified process modally, that is, displaying a modal progress/cancel dialog until the process ends.
static void	jbRunRefresh() If the executing thread that invokes this method was started by jbRun, sets a flag that requests that the parent form from which the jbRun was launched be refreshed the next time jbRun's modal progress/cancel dialog gets refreshed.
void	setBreadboard(java.lang.Object[][] breadboard) Defines this parent container's child components and their layout.
static void	setJbRunCanBeCanceled(boolean canBeCanceled) If executed from within the jbRun launched process, enables or disables the Cancel button on the current progress monitoring dialog.
static void	setJbRunCanceled(boolean progressCanceled) When executed from with a jbRun launched process, sets or unsets that thread's "cancelRequested" flag.
static void	setJbRunNote(java.lang.String note) If executed from within the jbRun launched process, sets the portion of the note (located just above the progress bar) associated with the lowest-level, currently executing, progress monitored section (the "local" note).
static void	setJbRunNoteDelimiter(java.lang.String delimiter) If called within the currently executing progress monitored thread, specifies the delimiter used between the progress notes associated with each progress monitored section when these individual notes are concatenated to produce the note displayed in the progress/cancel dialog of a jbRun-launched thread.
static void	setJbRunProgress(double fraction) When called from within a jbRun launched process, specifies the fraction of the lowest level current progress monitored section of the process that has been completed so far.
static void	setJbRunRefreshInterval(int refreshInterval) If executed from within the jbRun launched process, changes the interval at which the progress/cancel dialog is updated, but only for that process.
static void	setJbRunTitle(java.lang.String title) If executed from within the jbRun launched process, sets the title on the current progress monitoring dialog.
void	setResult(java.lang.Object result) Sets the result object associated with this JComponentBreadboard.
static java.lang.Object	showInputBreadboard(java.awt.Container parent, JComponentBreadboard jcb, java.lang.String title) This method makes it easy to define JOptionPane-like modal dialogs that return a user selectable/configurable object, where the user interface for selecting/configuring the returned object is defined by a single JComponentBreadboard form.
static void	showMessageBreadboard(java.awt.Container parent, JComponentBreadboard jcb, java.lang.String title) Convenience method that is equivalent to showInputBreadboard(parent, jcb, title) except that it discards the returned result.
static javax.swing.JComponent	xAlign(double fraction, javax.swing.JComponent jc) Declares that, in situations in which the JComponent's (possibly xUpsize adjusted) preferred width is smaller than the width of the breadboard grid-cell-block that contains it, the JComponent should be positioned the specified fraction of the way between the extreme flush left and extreme flush right positions.
static javax.swing.JComponent[]	xAlign(double fraction, javax.swing.JComponent[] jca) Convenience method that issues xAlign(fraction, jca[i]) to set the xAlign fraction on every non-null element of a 1-D array of JComponents.
static javax.swing.JComponent[][]	xAlign(double fraction, javax.swing.JComponent[][] jca) Convenience method that issues xAlign(fraction, jca[i][j]) to set the xAlign fraction on every non-null element of a 2-D array of JComponents.
static javax.swing.JComponent	xFill(boolean isXFilled, javax.swing.JComponent jc) Defines whether or not the component should always expand to fill out any extra horizontal space that may be available in the breadboard grid cell(s) that it occupies.
static javax.swing.JComponent[]	xFill(boolean isXFilled, javax.swing.JComponent[] jca) Convenience method equivalent to applying xFill(isXFilled, jca[i]) to every non-null element of the given 1-D array.
static javax.swing.JComponent[][]	xFill(boolean isXFilled, javax.swing.JComponent[][] jca) Convenience method equivalent to applying xFill(isXFilled, jca[i][j]) to every non-null element of the given 2-D array.
static javax.swing.JComponent	xFill(javax.swing.JComponent jc) Convenience method equivalent to xFill(true, jc)
static javax.swing.JComponent[]	xFill(javax.swing.JComponent[] jca) Convenience method equivalent to applying xFill(true, jca[i]) to every non-null element of the given 1-D array.
static javax.swing.JComponent[][]	xFill(javax.swing.JComponent[][] jca) Convenience method equivalent to applying xFill(true, jca[i][j]) to every non-null element of the given 2-D array.
static javax.swing.JSeparator	xSep() Convenience method that returns a new horizontal, flush top, flush left JSeparator
static javax.swing.JPanel	xSpace(int widthInPixels) Convenience method that returns a zero height JPanel whose preferred width is as specified.
static javax.swing.JComponent	xUpsize(int widthIncreaseInPixels, javax.swing.JComponent jc) Declares that, for JComponentBreadboard layout purposes, the specified JComponent should be considered to have a preferred width the specified number of pixels larger than the JComponent's actual preferred width.
static javax.swing.JComponent[]	xUpsize(int widthIncreaseInPixels, javax.swing.JComponent[] jca) Convenience method equivalent to issuing a xUpsize(widthIncreaseInPixels, jc[i])) on every non-null element of a 1-D JComponent array.
static javax.swing.JComponent[][]	xUpsize(int widthIncreaseInPixels, javax.swing.JComponent[][] jca) Convenience method equivalent to issuing a xUpsize(widthIncreaseInPixels, jc[i][j])) on every non-null element of a 2-D JComponent array.
static javax.swing.JComponent	xyAlign(double xFraction, double yFraction, javax.swing.JComponent jc) Convenience method equivalent to xAlign(xFraction, yAlign(yFraction, jc))
static javax.swing.JComponent[]	xyAlign(double xFraction, double yFraction, javax.swing.JComponent[] jca) Convenience method equivalent to applying xyAlign(widthIncreaseInPixels, heightIncreaseInPixels, jca[i])) to every non-null element in the 1-D array.
static javax.swing.JComponent[][]	xyAlign(double xFraction, double yFraction, javax.swing.JComponent[][] jca) Convenience method equivalent to applying xyAlign(widthIncreaseInPixels, heightIncreaseInPixels, jca[i][j])) to every non-null element in the 2-D array.
static javax.swing.JComponent	xyFill(boolean isXFilled, boolean isYFilled, javax.swing.JComponent jc) Convenience method equivalent to xFill(isXFilled,yFill(isYFilled, jc))
static javax.swing.JComponent[]	xyFill(boolean isXFilled, boolean isYFilled, javax.swing.JComponent[] jca) Convenience method equivalent to applying xyFill(isXFilled,isYFilled, jca[i]) to every non-null element of the given 1-D array.
static javax.swing.JComponent[][]	xyFill(boolean isXFilled, boolean isYFilled, javax.swing.JComponent[][] jca) Convenience method equivalent to applying xyFill(isXFilled, isYFilled, jca[i][j]) to every non-null element of the given 2-D array
static javax.swing.JComponent	xyFill(javax.swing.JComponent jc) Convenience method equivalent to xFill(true,yFill(true, jc))
static javax.swing.JComponent[]	xyFill(javax.swing.JComponent[] jca) Convenience method equivalent to xyFill(true, true, jca)
static javax.swing.JComponent[][]	xyFill(javax.swing.JComponent[][] jca) Convenience method equivalent to xyFill(true, true, jca).
static javax.swing.JPanel	xySpace(int widthInPixels, int heightInPixels) Convenience method that returns an empty JPanel whose preferred width and height are as specified.
static javax.swing.JComponent	xyUpsize(int widthIncreaseInPixels, int heightIncreaseInPixels, javax.swing.JComponent jc) Convenience method equivalent to xUpsize(widthIncreaseInPixels, yUpsize(heightIncreaseInPixels, jc)).
static javax.swing.JComponent[]	xyUpsize(int widthIncreaseInPixels, int heightIncreaseInPixels, javax.swing.JComponent[] jca) Convenience method equivalent to applying xyUpsize(widthIncreaseInPixels, heightIncreaseInPixels, jca[i]) to every non-null element in the 1-D array.
static javax.swing.JComponent[][]	xyUpsize(int widthIncreaseInPixels, int heightIncreaseInPixels, javax.swing.JComponent[][] jca) Convenience method equivalent to applying xyUpsize(widthIncreaseInPixels, heightIncreaseInPixels, jca[i][j])) to every non-null element in the 2-D array.
static javax.swing.JComponent	yAlign(double fraction, javax.swing.JComponent jc) Declares that, in situations in which the JComponent's (possibly yUpsize adjusted) preferred height is smaller than the height of the breadboard grid-cell-block that contains it, the JComponent should be positioned the specified fraction of the way between the extreme top and extreme bottom positions.
static javax.swing.JComponent[]	yAlign(double fraction, javax.swing.JComponent[] jca) Convenience method that issues yAlign(fraction, jca[i]) to set the yAlignment of every non-null element of a 1-D array of JComponents.
static javax.swing.JComponent[][]	yAlign(double fraction, javax.swing.JComponent[][] jca) Convenience method that issues yAlign(fraction, jca[i][j]) to set the yAlignment of every non-null element of a 2-D array of JComponents.
static javax.swing.JComponent	yFill(boolean isYFilled, javax.swing.JComponent jc) Defines whether or not the component should always expand to fill out any extra vertical space that may be available in the breadboard grid cell(s) that it occupies.
static javax.swing.JComponent[]	yFill(boolean isYFilled, javax.swing.JComponent[] jca) Convenience method equivalent to applying yFill(isYFilled, jca[i]) to every non-null element of the given 1-D array.
static javax.swing.JComponent[][]	yFill(boolean isYFilled, javax.swing.JComponent[][] jca) Convenience method equivalent to applying yFill(isYFilled, jca[i][j]) to every non-null element of the given 2-D array.
static javax.swing.JComponent	yFill(javax.swing.JComponent jc) Convenience method equivalent to yFill(true, jc)
static javax.swing.JComponent[]	yFill(javax.swing.JComponent[] jca) Convenience method equivalent to applying yFill(true, jca[i]) to every non-null element of the given 1-D array.
static javax.swing.JComponent[][]	yFill(javax.swing.JComponent[][] jca) Convenience method equivalent to applying yFill(true, jca[i][j]) to every non-null element of the given 2-D array.
static javax.swing.JSeparator	ySep() Same as xSep() except returns a new vertically oriented JSeparator, and is used to introduce vertical lines into the breadboard array.
static javax.swing.JPanel	ySpace(int heightInPixels) Convenience method that returns a zero width JPanel whose preferred height is as specified.
static javax.swing.JComponent	yUpsize(int heightIncreaseInPixels, javax.swing.JComponent jc) Declares that, for JComponentBreadboard layout purposes, the specified JComponent should be considered to have a preferred height the specified number of pixels larger than the JComponent's actual preferred height.
static javax.swing.JComponent[]	yUpsize(int heightIncreaseInPixels, javax.swing.JComponent[] jca) Convenience method equivalent to issuing a yUpsize(heightIncreaseInPixels, jc[i])) on every non-null element of a 1-D JComponent array.
static javax.swing.JComponent[][]	yUpsize(int heightIncreaseInPixels, javax.swing.JComponent[][] jca) Convenience method equivalent to issuing a yUpsize(heightIncreaseInPixels, jc[i][j])) on every non-null element of a 2-D JComponent array.

Methods inherited from class javax.swing.JPanel

getAccessibleContext, getUI, getUIClassID, setUI, updateUI

Methods inherited from class javax.swing.JComponent

addAncestorListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintImmediately, paintImmediately, print, printAll, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, contains, createImage, createImage, createVolatileImage, createVolatileImage, dispatchEvent, enable, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

__

public static final net.sourceforge.jcomponentbreadboard.JComponentBreadboard.ColumnarDitto __

A directive that, when placed into the cell of a breadboard array, instructs JComponentBreadboard to use the object reference immediately to the left of this cell for this cell, too. In other words, a kind of across columns ditto mark.

The odd name for this keyword ("__") is meant to suggest an ellipsis or "fill in the blank", to save space, and to make the breadboard array easier to read.

See Also:

setBreadboard, ROWWISE_DITTO

BISCALE

public static final net.sourceforge.jcomponentbreadboard.JComponentBreadboard.ScalingDirective BISCALE

Columns (rows) of the breadboard array whose headers contain this directive both uniformly scale their preferred-size-based widths (heights) up when extra width (height) is available in the parent container, and also uniformly scale down when the parent container is too small.

See Also:

setBreadboard, NOSCALE, SHRINKS, EXPANDS

CLOSE_BUTTON

public final javax.swing.JButton CLOSE_BUTTON

Whenever they receive the windowClosing event, JDialogs created via createBreadboardDialog are configured to call the doClick method of the CLOSE_BUTTON of the single top-level JComponentBreadboard that they contain. To handle windowClosing in such a JDialog, simply jbConnect the top level JComponentBreadboard's CLOSE_BUTTON and then implement the injected setter method of the JButton interface to handle this "close button click" just as you would for any other JButton.

For example, the NumericInputDialog example in the User's Guide employs a single code line (jbConnect(CLOSE_BUTTON, "ok");) to ensure that closing the dialog is equivalent to clicking the "OK" button.

If you do not connect the top-level JComponentBreadboard's CLOSE_BUTTON in this manner, that CLOSE_BUTTON will be automatically connected to a default event handler (containing the single line "jbReturn();") the first time a windowClosing event is seen by the createBreadboardDialog-created JDialog .

DATA_IS_VALID

public static final java.lang.String DATA_IS_VALID

Special keyword returned by data validation methods to indicate that the data String passed to the method contains valid data. See the section titled Data Validation Method Signatures within the jbConnect method's javadocs for more information. For an example that uses DATA_IS_VALID within a data validation method that validates a numeric entry field, see the NumericInputDialog application of the JComponentBreadboard User's Guide.

See Also:

REVERT_QUIETLY, REVERT_AND_BEEP, DEFAULT_INVALID_DATA_MESSAGE_TITLE, jbConnect

DEFAULT_INVALID_DATA_MESSAGE_TITLE

public final java.lang.String DEFAULT_INVALID_DATA_MESSAGE_TITLE

The default title of the popup error message dialog if no HTML title tag is included in the string returned from a data validation method function.

See the Data Validation Method Signatures section of the jbConnect method for more information.

See Also:

DATA_IS_VALID, REVERT_AND_BEEP, REVERT_QUIETLY, jbConnect, Constant Field Values

DEFAULT_JBRUN_REFRESH_INTERVAL

public static final int DEFAULT_JBRUN_REFRESH_INTERVAL

The default interval at which the progress dialog associated with a jbRun launched process is updated, in milliseconds. This constant equals 1000 milliseconds (which equals 1 second).

See Also:

setJbRunRefreshInterval, Constant Field Values

EXPANDS

public static final net.sourceforge.jcomponentbreadboard.JComponentBreadboard.ScalingDirective EXPANDS

Columns (rows) of the breadboard array whose headers contain this directive uniformly scale their preferred-size-based widths (heights) up when extra width (height) is available in the parent container, but do not uniformly scale down when the parent container is too small.

See Also:

setBreadboard, NOSCALE, SHRINKS, BISCALE

MAX_UPSIZE

public static final int MAX_UPSIZE

The maximum allowed xUpsize width increase, or yUpsize height increase.

With screen coordinates of around 10 times larger than this, Swing starts producing a variety of strange error messages. Moreover, it is unlikely increases larger than this -- far more than a whole screen of pixels on today's monitors--will be needed for the fine-tuning adjustments of xUpsize and yUpsize.

An IllegalArgumentException is thrown if the first arg of xUpsize or yUpsize exceeds this limit.

See Also:

xUpsize, yUpsize, Constant Field Values

NOSCALE

public static final net.sourceforge.jcomponentbreadboard.JComponentBreadboard.ScalingDirective NOSCALE

Columns (rows) of the breadboard array whose headers contain this directive do not uniformly scale their preferred-size-based widths (heights) up when extra width (height) is available in the parent container, and also do not uniformly scale down when the parent container is too small.

See Also:

setBreadboard, SHRINKS, EXPANDS, BISCALE

REVERT_AND_BEEP

public static final java.lang.String REVERT_AND_BEEP

Special keyword returned by data validation methods to indicate that the data String passed to the method contains invalid data, and that you want the field to reject this input and, after beeping for feedback, revert the data back to the last validated entry.

See Also:

DATA_IS_VALID, REVERT_QUIETLY, DEFAULT_INVALID_DATA_MESSAGE_TITLE, jbConnect

REVERT_QUIETLY

public static final java.lang.String REVERT_QUIETLY

Special keyword returned by data validation methods to indicate that the data String passed to the method contains invalid data, and that you want the field to reject this input and quietly revert back to the last validated entry.

See Also:

DATA_IS_VALID, REVERT_AND_BEEP, DEFAULT_INVALID_DATA_MESSAGE_TITLE, jbConnect

ROWWISE_DITTO

public final java.lang.String ROWWISE_DITTO

A directive that, when placed into the cell of a breadboard array, instructs JComponentBreadboard to use the object reference immediately above this cell for this cell, too. In other words, a conventional ditto mark. This constant is equal to the String literal "", and the intention is that the "" String literal, rather than this constant, will be placed onto actual breadboard arrays both to save space and also for its mnemonic significance (when interpreted as a ditto mark).

See Also:

setBreadboard, "columnar ditto", Constant Field Values

SHRINKS

public static final net.sourceforge.jcomponentbreadboard.JComponentBreadboard.ScalingDirective SHRINKS

Columns (rows) of the breadboard array whose headers contain this directive do not scale their preferred-size-based widths (heights) up when extra width (height) is available, but do scale down uniformly when the parent container is too small.

See Also:

setBreadboard, NOSCALE, EXPANDS, BISCALE

Constructor Detail

JComponentBreadboard

public JComponentBreadboard()

Constructs a new JComponentBreadboard.

The breadboard array must be set later via the setBreadboard method.

See Also:

setBreadboard

JComponentBreadboard

public JComponentBreadboard(java.lang.Object[][] breadboard)

Constructs a new JComponentBreadboard from the specified breadboard array.

Equivalent to constructing via the no-arg constructor and then immediately calling setBreadboard(breadboard).

See Also:

setBreadboard

Method Detail

addNotify

public void addNotify()

After calling the super class' addNotify method, calls this class' jbRefresh method.

Because Swing calls this addNotify method when the component is first added to a Dialog, Frame, etc., this initial refresh assures that all connected components contained in this form properly reflect the data they are bound to (via jbConnect) when they first become visible/accessible to the user.

Note: Because the isDefaultButton property of the parent Dialog or Frame can be indirectly defined by the getXxxisDefaultButton auxiliary property of the injected interface of a JButton, we need to assure that the initial refresh is done only AFTER the form is added to the Dialog or Frame. Placing it into the addNotify method assures this.

Overrides:

addNotify in class javax.swing.JComponent

beginProgressMonitoredSection

public static void beginProgressMonitoredSection(double startFraction,
                                                 double endFraction)

When called from within a jbRun-created thread, indicates the beginning of a progress monitored section of the jbRun launched process. An associated endProgressMonitoredSection line indicates the end of the progress monitored section.

These two methods delimit sections of the jbRun launched process roughly the same way that curly brackets do in normal program text. For example, nesting is allowed, and any "begins" unmatched by "ends" that remain after the jbRun launched thread finishes will result in an IllegalStateException being thrown.

This method does nothing if called from a non-jbRun-created thread.

The startFraction, endFraction parameters of this, and of any enclosing (higher level) progress monitored sections, recursively determine the range within the progress bar into which settings made with setJbRunProgress(fraction) are mapped.

Progress monitored sections make it easier for jbRun launched processes to provide percent-done type feedback via setJbRunProgress when the processes involve multiple, complex, nested, subsections. For a simple example of such a process, see the RandomWalks example application in the JComponentBreadboard User's Guide.

Typically, when a process is divided into several sequential sections, the startFraction, endFraction pairs will be adjacent, disjoint ranges that cover the interval from 0 to 1 (for a two section process you might have (0,0.5) for the first section and (0.5, 1.0) for the second). However, such intervals are not required and, for special situations (for example, when the fraction complete is revised downward to reflect new information) may not always be appropriate.

Parameters:

startFraction - an estimate of the fraction (on a elapsed time basis) of the enclosing (parent) progress monitored section that has been completed when this progress monitored section begins. A number in the range 0 to 1 (and that is less than or equal to endFraction) is required.

endFraction - an estimate of the fraction (on an elapsed time basis) of the enclosing (parent) progress monitored section that will be completed when this progress monitored section ends. A number in the range 0 to 1 (and that is greater than or equal to startFraction) is required.

See Also:

endProgressMonitoredSection, jbRun

createBreadboardDialog

public static javax.swing.JDialog createBreadboardDialog(java.awt.Container parent,
                                                         JComponentBreadboard jcb,
                                                         java.lang.String title,
                                                         boolean isModal)

Creates a JDialog whose entire content pane contains only the specified single JComponentBreadboard. The JDialog also provides a convenient JComponentBreadboard-specific windowClosing event handling mechanism, using the click event handler of the JComponentBreadboard's pre-defined CLOSE_BUTTON field.

Both the showMessageBreadboard and showInputBreadboard methods create their JDialogs using this method.

The conventions honored by these special JDialogs are listed below:

1. The dialog has a single child component--the JComponentBreadboard passed in as an argument to this method. Essentially these are "JComponentBreadboard-based" JDialogs.

2. Whenever jbConnect has been invoked to connect the special built-in CLOSE_BUTTON object of this single child JComponentBreadboard (for example, via a line such as jbConnect(CLOSE_BUTTON, "close") within the JComponentBreadboard's constructor) the windowClosing event handler will call CLOSE_BUTTON.doClick (and do nothing else). The system will automatically create such a connection that simply closes (disposes of) the window, if you have not connected your own. Note that, except for simple dialogs, simply closing the dialog will rarely be an appropriate closing action.

3. An initial pack is performed on the JDialog before it is returned, which assures its content pane will have an initial size equal to the preferred size of the top-level JComponentBreadboard it contains.

Parameters:

parent - the parent Dialog or Frame of the created dialog. Using null will use a default, system-wide parent.

jcb - the JComponentBreadboard (a JPanel) that will be the sole top-level JComponent contained by the created JDialog. All the components and behaviours of the form are contained within this top-level JComponentBreadboard

title - the title of the created JDialog

isModal - specify true to create a modal dialog, false for a modeless dialog

See Also:

showMessageBreadboard, showInputBreadboard, CLOSE_BUTTON

endProgressMonitoredSection

public static void endProgressMonitoredSection()

When called from within a jbRun-launched thread, ends a progress monitored section begun via beginProgressMonitoredSection.

When called from some other kind of thread, does nothing.

See Also:

beginProgressMonitoredSection

getJbRunCanceled

public static boolean getJbRunCanceled()

When called from code executing within a jbRun-launched thread, returns true if the cancel flag has been raised (for example, by the user clicking on the cancel button) since the run started, or false otherwise.

When called from a non-jbRun-launched thread, always returns false.

getJbRunNoteGlobally

public static java.lang.String getJbRunNoteGlobally()

If executed from within the jbRun launched process, returns the text of the note that would be displayed just above the progress bar on jbRun's progress cancel dialog, if that dialog were immediately refreshed.

The nested sequence of progress monitored sections forms a heirarchy, similar to a heirarchy of folders in a directory tree. Each monitored section can potentially have a distinct note. This method starts from the top-most or "root" enclosing progress monitored section and works its way down this heirarchy to the lowest level, currently executing, progress monitored section. Non-null messages from each section (specified via setJbRunNote) are concatenated together in this order, interspersed with the current setJbRunNoteDelimiter defined delimiter (a space by default). The resulting note is then prefixed with any non-null note specified (via setJbRunNote) before the jbRun process was launched, to form the note returned by this method.

If executed outside of a jbRun launched process, returns the last note specified outside of any jbRun launched process via setJbRunNote, or null if no such specification has been made.

See Also:

setJbRunNoteDelimiter, setJbRunNote, jbRun

getJbRunProgressGlobally

public static double getJbRunProgressGlobally()

Returns the fraction of the (entire) currently executing jbRun-launched process that has been completed so far. This fraction corresponds to the fraction of the progress/cancel dialog's progress bar that is filled in.

Note that the fraction returned by this method will not in general equal the fraction last specified via setJbRunProgress since that fraction indicates only the "local fraction", that is, the fraction of the immediately enclosing progress monitored section that has been completed.

The fraction returned by this method depends both on the last specified "local fraction", and (recursively) on the startFraction, endFraction parameters passed to all of the beginProgressMonitoredSection methods, that with their associated endProgressMonitoredSection methods, bracket the currently executing code line.

See Also:

setJbRunProgress, jbRun, beginProgressMonitoredSection

getResult

public java.lang.Object getResult()

Retrieves the object reference previously set with setResult.

If no call to setResult has been made, the default returned object reference is null.

See Also:

setResult

getXUpsize

public static int getXUpsize(javax.swing.JComponent jc)

Returns the number of pixels that JComponentBreadboard will add to the JComponent's preferred width to form the "adjusted preferred width" used by JComponentBreadboard's layout manager.

Parameters:

jc - the component whose xUpsize setting is to be returned

Returns:

the number of pixels the given component's width has been increased above the preferred width via the xUpsize method. If xUpsize has not been applied to the component, returns 0.

See Also:

xUpsize(int, JComponent)

getYUpsize

public static int getYUpsize(javax.swing.JComponent jc)

Returns the number of pixels that JComponentBreadboard will add to the JComponent's preferred height to form the "adjusted preferred height" used by JComponentBreadboard's layout manager.

Parameters:

jc - the component whose yUpsize setting is to be returned

Returns:

the number of pixels the given component's height has been increased above its preferred height via the yUpsize method. If yUpsize has not been applied to the component, returns 0.

See Also:

yUpsize(int, JComponent)

isJbRunRunning

public static boolean isJbRunRunning()

Returns true if a jbRun-launched process is currently executing, false otherwise.

Starting a second jbRun-launched process while one is already running will raise an IllegalStateException, so this method can be used to check for such a problem and issue an appropriate message to the user instead.

Note that jbRun always creates and displays a modal (blocking) progress/cancel dialog during the run. In most GUIs, this will itself be sufficient to prevent the launching of a second jbRun process. Thus, explicit checks via this method will usually not be needed.

isXFilled

public static boolean isXFilled(javax.swing.JComponent jc)

Returns true if the an attribute to expand the JComponent's width to fill out the grid cells that contain it horizontally has been attached to the JComponent, false otherwise.

Such attributes are attached via the xFill method.

Parameters:

jc - the JComponent whose xFill attribute is to be returned

Returns:

true if horizontal filling is enabled for the component, else false.

See Also:

xFill(boolean, JComponent)

isYFilled

public static boolean isYFilled(javax.swing.JComponent jc)

Returns true if an attribute to expand the JComponent's height to fill out the grid cells that contain it vertically has been attached to the JComponent, false otherwise.

Such attributes are attached via the yFill method.

Parameters:

jc - the JComponent whose yFill attribute is to be returned

Returns:

true if vertical filling is enabled for the component, else false.

See Also:

yFill(boolean, JComponent)

jbConnect

public void jbConnect(javax.swing.JComponent[][] componentArray,
                      java.lang.String rootName)

Injects an interface into this JComponentBreadboard-based form that binds the connectable properties of the specified 2-D JComponent array to the form via correspondingly-named, 2-D-array-indexed, getter/setter method defined, properties of the interface.

Except for two extra, initial, integer arguments indicating the 0-based row and column positions of each component within the array, the injected interface for each JComponent of the array is the same as it would have been had each individual JComponent been connected via code such as:

   jbConnect(componentArray[i][j], rootName);

Note: null array elements are allowed--they are quietly skipped.

For example, if the array contained JCheckBoxes, and were connected via the line:

  jbConnect(myCheckBoxArray, "myCheckboxes");

Then the following code would be one possible implementation of the required part of the associated interface injected into the JComponentBreadboard whose jbConnect method was invoked:

private boolean[] myBooleans = new boolean[myCheckBoxArray.length][myCheckBoxArray[0].length];
public boolean getMyCheckboxes(int iRow, int iCol) {
  return myBooleans[iRow][iCol];
}
public void setMyCheckboxes(int iRow, int iCol, boolean isChecked) {
  myBooleans[iRow][iCol] = isChecked;
}

See the DateChooser sample application for an example that connects a 2-D array of JToggleButtons to facilitate the implementation of a traditional monthly-calendar-style date selection pop-up modal dialog.

The types of the JComponents in the array need not be the same, but if they have different injected interfaces you will have to implement the required methods of every applicable interface. For example, if your array contained both JCheckBox and JTextField elements, you would be required to implement both a getter of the form public boolean getXxx(int iRow, int iCol) and another of the form public String getXxx(int iRow, int iCol) (plus the two corresponding setter methods).

Parameters:

componentArray - the 2-D array of JComponents to be connected to the form via an injected, array element offset indexed, interface. Any null elements will be quietly skipped.

rootName - the root name to be included immediately after the get or set (except with the first letter capitalized) in the method names of the injected interface.

See Also:

jbConnect(JComponent, String), jbConnect(JComponent[], String)

jbConnect

public void jbConnect(javax.swing.JComponent[] componentArray,
                      java.lang.String rootName)

Injects an interface into this JComponentBreadboard-based form that binds the connectable properties of the specified 1-D JComponent array to the form via correspondingly-named, 1-D-array-indexed, getter/setter defined, properties of the interface.

Except for an extra, initial, integer argument indicating the 0-based position of each component within the array, the injected interface for each JComponent of the array is the same as it would have been had each individual JComponent been connected via code such as:

     jbConnect(componentArray[i], rootName);

Note: null elements are allowed--they are quietly skipped.

For example, if the array contained JCheckBoxes, and were connected via the line:

  jbConnect(myCheckBoxArray, "myCheckboxes");

Then the following code would be one possible implementation of the required part of the associated interface injected into the JComponentBreadboard whose jbConnect method was invoked:

private boolean[] myBooleans = new boolean[myCheckBoxArray.length];
public boolean getMyCheckboxes(int iRow) {
  return myBooleans[iRow];
}
public void setMyCheckboxes(int iRow, boolean isChecked) {
  myBooleans[iRow] = isChecked;
}

See the RandomWalks application in the User's Guide for an example that, by jbConnecting to an array of JSpinners, allows the user to specify an array of integer walk lengths via the spinners.

The types of the JComponents in the array need not be the same, but if they have different injected interfaces you will have to implement the required methods of every applicable interface. For example, if your array contained both JCheckBox and JTextField elements, you would be required to implement both a getter of the form public boolean getXxx(int iRow) and another of the form public String getXxx(int iRow) (plus the two corresponding setter methods).

Parameters:

componentArray - the array of JComponents to be connected to this form via an injected, array element offset indexed, interface

rootName - the root name to be included immediately after the get or set (except with the first letter capitalized) in the method names of the injected interface

See Also:

jbConnect(JComponent, String)

jbConnect

public void jbConnect(javax.swing.JComponent jcomponent,
                      java.lang.String rootName)

Injects an interface into this JComponentBreadboard-based form that binds the connectable properties of the specified JComponent to the form via correspondingly-named (getter/setter defined) properties of the interface.

The injected interface of a connectable JComponent of a specific sub-type (JCheckBox, JLabel, etc.) contains methods associated with up to 1 main (viewable and controllable) property, and 1 or more auxiliary (viewable only) properties. For example, a JTextField contains 1 main property corresponding to its user editable String whereas a JLabel does not have a main property, since it is not possible for the user to directly change a JLabel's state by interacting with it. However, both components support auxiliary properties corresponding their enabled and visible properties.

When present, the part of the injected interface corresponding to the main property must be implemented in the JComponentBreadboard whose jbConnect method is invoked (an IllegalStateException will be raised otherwise). This required part of the interface has the follow general format:

public MainPropertyType getRootName()
public void setRootName(MainPropertyType value)

In the above:

1. RootName is simply the rootName String passed in as the second parameter of jbConnect, except that, in accord with Java naming conventions, the first character is capitalized.

2. MainPropertyType is the type of the main property associated with the connected JComponent. For example, this would be a String for a JTextField, a boolean for a JCheckBox and a double for a JSpinner configured so as to allow the entry of floating point values.

   JButton and JMenuItem have a MainPropertyType of void and are a special case. For connections involving such components, the setter method has no arguments (it is called for it's side-effects--for example, it performs some calculation when the user clicks the button) and the getter method (why would you need to get nothing?) is eliminated.

For example, if a JComponentBreadboard's constructor contained the line:

jbConnect(myJTextField, "userName");

Then, that JComponentBreadboard's class would be required to implement two methods such as those shown below:

private String theUserName = "";
public String getUserName() {
  return theUserName;
}
public void setUserName(String userEnteredUserName) {
  theUserName = userEnteredUserName;
}

Because the jbConnect was executed, JComponentBreadboard assures that whenever the user finalizes their edits of myJTextField's String (for example, by tabbing to the next field), the setUserName method is invoked with the user-modified String as its argument. Also, it assures that whenever the theUserName field is changed as a side-effect of the user interacting with some other connected component on the form, (e.g. by clicking a "login as JohnSmith" checkbox whose bound setter method contains the line theUserName = "JohnSmith";) the getUserName method is invoked and the value it returns is stuffed back into the String displayed by myJTextField.

For a complete example that uses jbConnect to synchronize the checked/unchecked state of a JCheckBox (its main property) with a boolean setter/getter defined property of a JComponentBreadboard-based form, see the HelloWorldPlus application in the JComponentBreadboard User's Guide.

For an example of using jbConnect to keep more than one component in synch whenever the user changes any one of them, see the CelsiusFahrenheitConverter example application in the JComponentBreadboard User's Guide. In this application, two JSliders and two JSpinners are all connected to the form so that they all view and control a single underlying double that represents the temperature in degrees Celsius. Whenever the user changes the temperature via any one of these connected JComponents, the newly selected temperature is automatically properly displayed by all four connected JComponents.

The auxiliary (view-only) part of the injected interface has the following general format:

public TypeOfAuxiliaryProp1 getRootNameNameOfAuxiliaryProp1()
public TypeOfAuxiliaryProp2 getRootNameNameOfAuxiliaryProp2()
 ...
public TypeOfAuxiliaryPropN getRootNameNameOfAuxiliaryPropN()

In the above:

1. RootName, as before, is the first-letter-capitalized string passed in as jbConnect's second parameter.

2. TypeOfAuxiliaryProp1 is the type of the first auxiliary property. For example, for the enabled property this would be boolean.

3. NameOfAuxiliaryProp1 is the first-letter-capitalized name of the first auxiliary property. This generally corresponds to the part of the name of a corresponding setter method of the JComponent that comes after "set". For example, the name corresponding to setVisible would be "Visible", the name corresponding to setEnabled, "Enabled", etc.

   In a small number of cases, the name does not correspond to any setter method in the connected JComponent, but rather represents a "grafted on" JComponentBreadboard convenience extension of the class. For example, a connected JComboBox supports a String[] "items" property (which lets you dynamically change list items by implementing, say, public String[] getMyComboBoxItems()). However, JComboBox does not actually contain a setItems(String[] listItems) method. Behind the scenes, JComponentBreadboard emulates such a setter using the JComboBox's setModel method.

For a simple auxiliary property example, see the HelloWorldPlus application in the User's Guide, which implements an auxiliary property getter with the signature public String getUseExpectedPhraseToolTipText() to dynamically change the toolTipText property of a connected JCheckBox.

Data Validation Method Signatures

In additional to the above methods, JComponents that have a main, user manipulated, property of of type String can optionally validate user entered Strings by implementing a data validation method with the following signature:

public String getRootNameInvalidDataMessage(String testInput)

This method must be defined so as to return either:

1. DATA_IS_VALID if the testInput passed to it is valid.

2. REVERT_QUIETLY if the testInput passed to it is not valid, and you want to quietly reject the user's entry by reverting to the last validated entry.

3. REVERT_AND_BEEP if the testInput passed to it is not valid, and you want to beep and then to reject the user's entry by reverting to the last validated entry.

4. An arbitrary String message (which can include the Swing subset of HTML) that is suitable for display in a pop-up dialog describing the error if the testInput is not valid. This popup allows the user either to correct the entry or to revert to the last validated value.

   Use the HTML <title> tag within this string to define the title of the pop-up error dialog (for example, <title>Invalid Numeric Entry</title>). If the title tag isn't included in the returned string, the default title of the popup dialog is "Invalid Input".

This method, if defined, will be automatically invoked immediately after the user finishes entering a new String into the associated JComponent (the entry is finalized when the JComponent loses the focus). Note that, though such interactive user edits are always validated, progammatically made changes to the bound-properties associated with the JComponent are not.

Connecting one JComponentBreadboard to another

JComponentBreadboard extends JPanel, and the injected interface of a connected JComponentBreadboard is the same as for a JPanel. However, there is one important functional difference.

Whenever the user interacts with one of the JComponents connected to the connected-from JComponentBreadboard in a manner than changes its state, any JComponents connected to the connected-to JComponentBreadboard will be automatically updated to reflect any changes to the underlying objects they are bound to.

Uni-directional, bi-directional and circular connections, to any depth, are supported. For example if two JComponentBreadboards are connected to each other, user initiated changes to components connected to either of them will automatically be reflected in both.

Detailed Injected Interface Specifications

The exact signatures of the various injected methods discussed above depend upon the exact subclass of the JComponent being connected, and in some cases also on how that object has been configured. For example, floating point JSpinners and integer JSpinners, though of exactly the same class, have different injected interfaces that reflect the fact that, due to their different configurations, their main properties have different types (double vs int).

To help you determine the exact injected interface for a given connection, JComponentBreadboard provides a feature called exceptional code generation that displays the complete set of method signatures (the so-called injected interface for the connection) as part of any exception raised by this method. When implemented, these methods must be public methods of the JComponentBreadboard sub-class that issued the jbConnect that injected the interface.

A handy trick is to issue the exact same jbConnect call twice. Since each JComponent can only be connected once, this produces an exception that includes the full interface specs for the connected JComponent in question.

The non-array forms of every possible exceptional code generated interface are tabulated below for your convenience (for the 1-D or 2-D array forms of these interfaces, simply prepend one or two integer arguments to each method's argument list). Follow the "injected interface" link on each row of the table to see the interface associated with JComponents of that type (or their sub-classes). The generated code shown for each interface was obtained by passing in an object of that table row's class as the first, and a dummy rootName argument of "xxx" as the second, parameter of jbConnect.

Internally, JComponentBreadboard stores a table each row of which defines the injected interfaces associated with each connectable class, and always chooses the interface associated with the most closely matching class as the interface for the specific JComponent type you are connecting. For example, connections to instances of JPasswordField (an descendent of JTextComponent) in effect inheirit JTextComponent's injected interface, because there is no explicitly defined JPasswordField row on the table. The table includes a JComponent row, so technically all JComponents are connectable. However, the injected interface associated with this least-common-denominator JComponent row (which is used by the JSeparator class, for example) does not have a main property, and supports only limited, generic, auxiliary properties (enabled, visible, etc.)

Major connectable JComponent types, and their injected interfaces

JComponent	Type of main property	Injected interface
JButton	void	injected interface
JCBKeyStroke	void	injected interface
JMenuItem	void	injected interface
JToggleButton	boolean	injected interface
JRadioButton	boolean	injected interface
JCheckBox	boolean	injected interface
JComboBox	String	injected interface
JLabel	--none--	injected interface
JProgressBar	--none--	injected interface
JScrollBar	int	injected interface
JSlider	int	injected interface
JSpinner	int	injected interface
JSpinner	double	injected interface
JSpinner	Date	injected interface
JSpinner	String	injected interface
JTextField	String	injected interface
JTextArea	String	injected interface
JEditorPane	String	injected interface
JPanel	--none--	injected interface
JSeparator	--none--	injected interface

//
// REQUIRED 'jbConnect(JButton,"xxx")' injected method that is
// invoked by this JButton's event handler:
//   public void setXxx() {}
//
// OPTIONAL 'jbConnect(JButton,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JButton:
//   public String getXxxText() {}
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}
//   public boolean getXxxContentAreaFilled() {}
//   public boolean getXxxIsDefaultButton() {}

//
// REQUIRED 'jbConnect(KeyStroke,"xxx")' injected method that is
// invoked by this JCBKeyStroke's event handler:
//   public void setXxx() {}
//
// OPTIONAL 'jbConnect(KeyStroke,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JCBKeyStroke:
//   public boolean getXxxEnabled() {}

//
// REQUIRED 'jbConnect(JMenuItem,"xxx")' injected method that is
// invoked by this JMenuItem's event handler:
//   public void setXxx() {}
//
// OPTIONAL 'jbConnect(JMenuItem,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JMenuItem:
//   public String getXxxText() {}
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}
//   public boolean getXxxContentAreaFilled() {}

//
// REQUIRED 'jbConnect(JToggleButton,"xxx")' injected methods
// that define the boolean viewed and controlled by this JToggleButton:
//   public boolean getXxx() {}
//   public void setXxx(boolean value) {}
//
// OPTIONAL 'jbConnect(JToggleButton,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JToggleButton:
//   public String getXxxText() {}
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}
//   public boolean getXxxContentAreaFilled() {}

//
// REQUIRED 'jbConnect(JRadioButton,"xxx")' injected methods
// that define the boolean viewed and controlled by this JRadioButton:
//   public boolean getXxx() {}
//   public void setXxx(boolean value) {}
//
// OPTIONAL 'jbConnect(JRadioButton,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JRadioButton:
//   public String getXxxText() {}
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}
//   public boolean getXxxContentAreaFilled() {}

//
// REQUIRED 'jbConnect(JCheckBox,"xxx")' injected methods
// that define the boolean viewed and controlled by this JCheckBox:
//   public boolean getXxx() {}
//   public void setXxx(boolean value) {}
//
// OPTIONAL 'jbConnect(JCheckBox,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JCheckBox:
//   public String getXxxText() {}
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}
//   public boolean getXxxContentAreaFilled() {}

//
// REQUIRED 'jbConnect(JComboBox,"xxx")' injected methods
// that define the String viewed and controlled by this JComboBox:
//   public String getXxx() {}
//   public void setXxx(String value) {}
//
// OPTIONAL 'jbConnect(JComboBox,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JComboBox:
//   public String getXxxInvalidDataMessage(String value) {}
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}
//   public String[] getXxxItems() {}
//   public boolean getXxxEditable() {}

//
// REQUIRED 'jbConnect(JLabel,"xxx")' injected methods (none)
//
// OPTIONAL 'jbConnect(JLabel,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JLabel:
//   public String getXxxText() {}
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}
//   public Border getXxxBorder() {}
//   public Icon getXxxIcon() {}
//   public Icon getXxxDisabledIcon() {}
//   public int getXxxHorizontalTextPosition() {}
//   public int getXxxVerticalTextPosition() {}
//   public int getXxxIconTextGap() {}

//
// REQUIRED 'jbConnect(JProgressBar,"xxx")' injected methods (none)
//
// OPTIONAL 'jbConnect(JProgressBar,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JProgressBar:
//   public int getXxxValue() {}
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}
//   public int getXxxMinimum() {}
//   public int getXxxMaximum() {}
//   public boolean getXxxStringPainted() {}
//   public boolean getXxxIndeterminate() {}

//
// REQUIRED 'jbConnect(JScrollBar,"xxx")' injected methods
// that define the int viewed and controlled by this JScrollBar:
//   public int getXxx() {}
//   public void setXxx(int value) {}
//
// OPTIONAL 'jbConnect(JScrollBar,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JScrollBar:
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}
//   public int getXxxMinimum() {}
//   public int getXxxMaximum() {}
//   public int getXxxUnitIncrement() {}
//   public int getXxxBlockIncrement() {}
//   public int getXxxVisibleAmount() {}

//
// REQUIRED 'jbConnect(JSlider,"xxx")' injected methods
// that define the int viewed and controlled by this JSlider:
//   public int getXxx() {}
//   public void setXxx(int value) {}
//
// OPTIONAL 'jbConnect(JSlider,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JSlider:
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}
//   public int getXxxExtent() {}
//   public boolean getXxxInverted() {}
//   public Dictionary getXxxLabelTable() {}
//   public int getXxxMajorTickSpacing() {}
//   public int getXxxMaximum() {}
//   public int getXxxMinimum() {}
//   public int getXxxMinorTickSpacing() {}
//   public boolean getXxxPaintLabels() {}
//   public boolean getXxxPaintTicks() {}
//   public boolean getXxxPaintTrack() {}
//   public boolean getXxxSnapToTicks() {}

//
// REQUIRED 'jbConnect(JSpinner(SpinnerNumberModel),"xxx")' injected methods
// that define the int viewed and controlled by this JSpinner:
//   public int getXxx() {}
//   public void setXxx(int value) {}
//
// OPTIONAL 'jbConnect(JSpinner(SpinnerNumberModel),"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JSpinner:
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Dimension getXxxPreferredSize() {}
//   public int getXxxMinimum() {}
//   public int getXxxMaximum() {}
//   public int getXxxStepSize() {}

//
// REQUIRED 'jbConnect(JSpinner(SpinnerNumberModel),"xxx")' injected methods
// that define the double viewed and controlled by this JSpinner:
//   public double getXxx() {}
//   public void setXxx(double value) {}
//
// OPTIONAL 'jbConnect(JSpinner(SpinnerNumberModel),"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JSpinner:
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Dimension getXxxPreferredSize() {}
//   public double getXxxMinimum() {}
//   public double getXxxMaximum() {}
//   public double getXxxStepSize() {}

//
// REQUIRED 'jbConnect(JSpinner(SpinnerDateModel),"xxx")' injected methods
// that define the Date viewed and controlled by this JSpinner:
//   public Date getXxx() {}
//   public void setXxx(Date value) {}
//
// OPTIONAL 'jbConnect(JSpinner(SpinnerDateModel),"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JSpinner:
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Dimension getXxxPreferredSize() {}
//   public Date getXxxStart() {}
//   public Date getXxxEnd() {}

//
// REQUIRED 'jbConnect(JSpinner(SpinnerListModel),"xxx")' injected methods
// that define the String viewed and controlled by this JSpinner:
//   public String getXxx() {}
//   public void setXxx(String value) {}
//
// OPTIONAL 'jbConnect(JSpinner(SpinnerListModel),"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JSpinner:
//   public String getXxxInvalidDataMessage(String value) {}
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Dimension getXxxPreferredSize() {}
//   public String[] getXxxItems() {}

//
// REQUIRED 'jbConnect(JTextField,"xxx")' injected methods
// that define the String viewed and controlled by this JTextField:
//   public String getXxx() {}
//   public void setXxx(String value) {}
//
// OPTIONAL 'jbConnect(JTextField,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JTextField:
//   public String getXxxInvalidDataMessage(String value) {}
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}
//   public Color getXxxDisabledTextColor() {}
//   public Color getXxxSelectedTextColor() {}
//   public Color getXxxSelectionColor() {}
//   public boolean getXxxEditable() {}
//   public Insets getXxxMargin() {}

//
// REQUIRED 'jbConnect(JTextArea,"xxx")' injected methods
// that define the String viewed and controlled by this JTextArea:
//   public String getXxx() {}
//   public void setXxx(String value) {}
//
// OPTIONAL 'jbConnect(JTextArea,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JTextArea:
//   public String getXxxInvalidDataMessage(String value) {}
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}
//   public Color getXxxDisabledTextColor() {}
//   public Color getXxxSelectedTextColor() {}
//   public Color getXxxSelectionColor() {}
//   public boolean getXxxEditable() {}
//   public Insets getXxxMargin() {}

//
// REQUIRED 'jbConnect(JEditorPane,"xxx")' injected methods
// that define the String viewed and controlled by this JEditorPane:
//   public String getXxx() {}
//   public void setXxx(String value) {}
//
// OPTIONAL 'jbConnect(JEditorPane,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JEditorPane:
//   public String getXxxInvalidDataMessage(String value) {}
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}
//   public Color getXxxDisabledTextColor() {}
//   public Color getXxxSelectedTextColor() {}
//   public Color getXxxSelectionColor() {}
//   public boolean getXxxEditable() {}
//   public Insets getXxxMargin() {}

//
// REQUIRED 'jbConnect(JPanel,"xxx")' injected methods (none)
//
// OPTIONAL 'jbConnect(JPanel,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JPanel:
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}
//   public Border getXxxBorder() {}

//
// REQUIRED 'jbConnect(JSeparator,"xxx")' injected methods (none)
//
// OPTIONAL 'jbConnect(JSeparator,"xxx")' injected methods that can
// be implemented to define auxiliary properties of this JSeparator:
//   public boolean getXxxEnabled() {}
//   public boolean getXxxVisible() {}
//   public String getXxxToolTipText() {}
//   public Color getXxxForeground() {}
//   public Color getXxxBackground() {}
//   public Dimension getXxxPreferredSize() {}

Adding or Expanding a Type-Specific Injected Interface

In cases in which the connectable properties of the JComponent have simple setter/getter based interfaces it is quite easy to add support for a new JComponent sub-class. However, this can only be done by changing the source code. You simply add a new row to the jbComponents table (defined statically in the JComponentBreadboard.java file) and then fill in the various slots defining the component's injected interface (these slots include places for the names/types of the main property and auxiliary properties) in that table row (each such row contains an instance of the class JBComponentInfo). See existing table rows in the source code (indeed, you can often copy such an existing row and use it as a starting point) for examples. It's even easier to extend the interface of an already supported JComponent class by adding additional auxiliary methods.

Parameters:

jcomponent - the JComponent whose interface is to be injected into this JComponentBreadboard.

rootName - all the method names in the injected interface begin with either "get" or "set" and are all followed by the specified rootName (except that it's first letter will be capitalized).

See Also:

DATA_IS_VALID, REVERT_AND_BEEP, REVERT_QUIETLY, DEFAULT_INVALID_DATA_MESSAGE_TITLE

jbConnect

public void jbConnect(javax.swing.KeyStroke[][] keyStrokeArray,
                      java.lang.String rootName)

Injects an interface into this JComponentBreadboard-based form that binds the connectable properties of the specified 2-D KeyStroke array to the form via correspondingly-named, row and column indexed, properties of the interface.

Works in a manner exactly analogous to jbConnect(JComponent[][],String) except that the elements of the array are KeyStrokes, rather than JComponents. See that method for further details.

Parameters:

keyStrokeArray - the array of KeyStrokes to be connected to the form via an injected, row and column offset indexed, interface

rootName - the root name to be included immediately after the get or set (except with the first letter capitalized) in the method names of the injected interface.

See Also:

jbConnect(JComponent[][],String), jbConnect(KeyStroke, String)

jbConnect

public void jbConnect(javax.swing.KeyStroke[] keyStrokeArray,
                      java.lang.String rootName)

Injects an interface into this JComponentBreadboard-based form that binds the connectable properties of the specified 1-D KeyStroke array to the form via correspondingly-named, 1-D-array-indexed, properties of the interface.

Works in a manner exactly analogous to jbConnect(JComponent[],String) except that the elements of the array are KeyStrokes, rather than JComponents. See that method for further details.

Parameters:

keyStrokeArray - the array of KeyStrokes to be connected to the form via an injected, array element offset indexed, interface

rootName - the root name to be included immediately after the get or set (except with the first letter capitalized) in the method names of the injected interface.

See Also:

jbConnect(JComponent[],String), jbConnect(KeyStroke, String)

jbConnect

public void jbConnect(javax.swing.KeyStroke keyStroke,
                      java.lang.String rootName)

Injects an interface into this JComponentBreadboard-based form that binds the connectable properties of the specified KeyStroke to the form via correspondingly-named, getter/setter defined, properties of the interface.

The KeyStroke interface works similarly to that of a JButton or JMenuItem, except that pressing the keystroke, rather than clicking the button or selecting the menu item, fires the event handling code.

The KeyStroke handler is only active when this JComponentBreadboard, or one of the JComponents it contains, has the focus. Thus, different regions of the form, each associated with a different JComponentBreadboard sub-form, could each have, for example, different arrow-key handlers.

However, for most applications KeyStroke handling is uniform across the entire form, so you will want to connect KeyStrokes to a single, top-level, JComponentBreadboard that is the only top-level JComponent within the parent Dialog or Frame.

In the special case where every focusable JComponent on a top-level JComponentBreadboard is disabled, Swing's default focus handling will result in a situation in which the top-level JComponentBreadboard does not have the focus, and thus the KeyStroke handlers for the top-level JComponentBreadboard will not work. If this is not what you want in this (very unusual) situation, you will need to invoke the requestFocusInWindow method of the top-level JComponentBreadboard.

Connected KeyStrokes work exactly as if a hidden JMenuItem with the specified KeyStroke as it's accelerator, were added and connected to the JComponentBreadbreadboard in lieu of the KeyStroke. Though you usually won't have to know this to use it, in fact, KeyStroke support is currently implemented by adding and connecting to such a hidden JMenuItem.

Because connecting to a KeyStroke works exactly like connecting to a hidden JMenuItem (of the special tagging subclass of JMenuItem called JCBKeyStroke), all of the discussion under the jbConnect(JComponent, String) method applies equally to the KeyStroke connections created by this method. In particular, see the JCBKeyStroke row of the injected interfaces table in that method's javadocs for the interface supported by a connected KeyStroke.

See the NumericInputDialog application of the JComponentBreadboard User's Guide for an example that jbConnects to a KeyStroke in order to support canceling the dialog by pressing the ESCAPE key.

Parameters:

keyStroke - the KeyStroke for which an interface is to be injected into this JComponentBreadboard form

rootName - the root name that always follows immediately after the get or set (except that the first letter will be capitalized) in the method names of the injected interface.

See Also:

jbConnect(JComponent, String)

jbRefresh

public void jbRefresh()

Refreshes all the jbConnected JComponents and/or KeyStrokes contained on this JComponentBreadboard.

For each connected JComponent or KeyStroke on this form, jbRefresh will call the getter methods associated with that component or key stroke's injected interface, and then use the results so obtained to set the associated properties of the connected JComponent or KeyStroke.

JComponentBreadboards that have been connected to another JComponentBreadboard will automatically invoke jbRefresh on the connected-to JComponentBreadboard whenever they are refreshed. Circular connections are allowed, each so-connected JComponentBreadboard is guaranteed not to be refreshed more than once per top-level jbRefresh invocation.

To avoid all possibility of thread-related errors, it is safest to call this method only from the Swing thread (for example, via invokeLater, or within a jbConnect-bound setter method, which JComponentBreadboard always invokes from within the Swing thread). In particular, if you need to request a refresh of the parent form from within a jbRun launched process (these processes do not run in the Swing thread) use jbRunRefresh, not this method.

Note: JComponentBreadboard automatically invokes jbRefresh when the component is first added to a top level Frame or Dialog (via the addNotify method) and after each time that the user changes the state of any connected component. Thus, explicit calls to this method are expected to be very rare.

See Also:

jbRunRefresh, addNotify

jbReturn

public void jbReturn()

Removes (by calling its dispose method) the parent Frame or Dialog containing the JComponentBreadboard, if such a Frame or Dialog exists, otherwise does nothing.

This is mainly intended for use by JComponentBreadboards that are created via createBreadboardDialog, though other user created dialogs may find it provides a useful way to close down the dialog containing the breadboard, too.

See Also:

jbReturn(Object)

jbReturn

public void jbReturn(java.lang.Object result)

Closes the parent Dialog or Frame of the form via dispose, and sets the result property of this form to the specified Object.

In many contexts, this method will play a role analogous to the Java language's return statement.

This method is equivalent to: setResult(result); jbReturn();

Parameters:

result - the object to be returned when the modal JDialog or JFrame that contains this JComponentBreadboard-based form closes (via a call to dispose). Though this is the main use of the returned result, strictly speaking, this param is just an object that various clients (such as the modal dialog created via showInputBreadboard) of a form can retrieve via getResult in any context in which the concept of a returned value from your form may be useful.

See Also:

jbReturn, setResult, showInputBreadboard

jbRun

public void jbRun(java.lang.Runnable jbJob)

Runs the specified process modally, that is, displaying a modal progress/cancel dialog until the process ends. The progress dialog has the same basic layout as that of the JDK's ProgressMonitor class: a progress bar above which is a text message (describing the progress of the process), and beneath which is a Cancel button (that can be used to cancel the process).

By default, the progress dialog is configured as follows:

1. The progress dialog's title contains the string "Progress..."
2. The note above the progress dialog's progress bar is left blank.
3. The progress bar is in indeterminate mode (that is, it displays an animation indicative of ongoing work, but not a numerical percentage completed).
4. The Cancel button is disabled, and the close box cannot be used to dismiss the dialog.

These defaults have the distinct advantage of not requiring any changes to the source code of the executing process. For relatively quick running processes, the default configuration is hard to improve upon, given it's convenience. To change the title or introduce a fixed note above the progress bar (which can still be done without making any changes to the executing process' code) invoke setJbRunNote or setJbRunTitle just before invoking jbRun.

However, for longer running processes you often need to give the user the chance to cancel the process, as well as a numerical indication of the percentage completed so far, detailed messages, etc. Such detailed progress feedback will require that the progress-monitored code be "progress/cancel feedback instrumented" by including appropriate invocations of the following JComponentBreadboard static methods:

Method	What it does
setJbRunTitle	Changes the title of the progress/cancel dialog
setJbRunNote	Changes the part of the note above the progress/cancel dialog's progress bar that is associated with the lowest level progress monitored section that the currently executing code line is a part of.
setJbRunNoteDelimiter	Changes the delimiter interspersed between the individual notes from each progress monitored section when those notes get concatenated to form the note displayed above the progress bar.
setJbRunCanBeCanceled	Enables/disabled the cancel button on the progress/cancel dialog.
getJbRunCanceled	Returns true if the cancel flag has been raised (for example, by the user clicking on the cancel button) since the jbRun began, false otherwise. Note that unless the process polls using this method periodically, user clicks on the cancel button will be ignored.
setJbRunRefreshInterval	Defines the interval, in milliseconds, between refreshes of the progress/cancel dialog (default is 1000 milliseconds, which equals 1 second)
setJbRunProgress	Defines the fraction (via an argument between 0 and 1) of the current "process monitored section" that is completed so far.
beginProgressMonitoredSection	Delimits (along with its companion method below) progress monitored sections of the process. See discussion below.
endProgressMonitoredSection	Delimits (along with its companion method above) progress monitored sections of the process. See discussion below.

Specifying Progress Feedback For Complex, Nested, Processes

Except in tutorials, it is very unusual to have a process that consist of a single loop or similarly straightforward, easily instrumented computation. Instead, a method X might represent 10% of the total work in some top-level method A that calls X. But that same X could represent 50% of the total work when called by some other top-level method B. Worse, some future development might incorporate both A and B into some even higher level method W, and so on, ad-infinituum.

Processes launched by jbRun can easily provide progress/cancel feedback for such complex, nested, processes, by bracketing each part between invocations of beginProgressMonitoredSection(startFraction, endFraction) and endProgressMonitoredSection, as illustrated in the code below:

beginProgressMonitoredSection(0.0, 0.5); // first half
firstHalfOfComputation();
endProgressMonitoredSection();
beginProgressMonitoredSection(0.5, 1.0); // second half
beginProgressMonitoredSection(0.0, 0.5);
firstHalfOfSecondHalfOfComputation();
endProgressMonitoredSection();
beginProgressMonitoredSection(0.5, 1.0);
secondHalfOfSecondHalfOfComputation();
endProgressMonitoredSection();
endProgressMonitoredSection();

beginProgressMonitoredSection's first argument (startFraction) represents your best estimate of the fraction of the enclosing (parent) progress monitored section that has been completed when the new progress monitored section begins. The second argument (endFraction) is your best estimate of the fraction of the enclosing parent progress monitored section that will have been completed when this sub-section ends (in other words, when the matching endProgressMonitoredSection method is reached).

Note that there will always be a system created, top-level, progress monitored section that includes the entire process and whose associated startFraction is always 0.0 and whose associated endFraction is always 1.0 (corresponding to 0 to 100% on the progress/cancel dialog's progress bar).

The setJbRunProgress method is aware of the depth and structure of the progress monitored sections that enclose its invocation, and its settings are decoded into progress bar positions accordingly. For example, a setJbRunProgress(0.5) that occurred within firstHalfOfComputation in the above code would set the progress bar at the 25% complete mark, but if that same call occured within the secondHalfOfSecondHalfOfComputation method, it would set the progress bar at the 87.5% mark (= (75 + 100)/2, that is, halfway through the fourth quarter). The nesting of such sections can go to virtually any depth (a limit of 100 is enforced to help catch improper usage). Each additional level maps the progress fraction settings in that sub-section into increasingly smaller subdivision of the overall progress bar.

Just as the meaning of the setJbRunProgress method's argument depends on the progress sections that contain it, the setJbRunNote method's note is similarly dependent. Specifically, each setJbRunNote call defines the note only for the lowest level progress monitored section that the code line that invokes the method is currently a part of. The displayed message above the progress bar, however, concatenates the non-null messages from all progress monitored sections, from the highest to the lowest level, that contain the currently executing line of code. A delimiter (by default a space, but specifiable via setJbRunNoteDelimiter) is interspersed between the individual messages from each section. Finally, if setJbRunNote was invoked outside of any jbRun invoked process, it defines a "global prefix" that gets prepended just before the note is displayed.

For example, if just before invoking jbRun we had issued a setJbRunNote("Running"), and then, within the jbRun's top level progress monitored section we had issued a setJbRunNote("Top-Level-Code") and then within a beginProgressMonitoredSection...endProgressMonitoredSection bracketed sub-section we had issued a setJbRunNote("Subsection-1") the displayed note above the progress bar when executing within subsection 1 (assuming no further sub-sections were introduced and the default single space delimiter) would be "Running Top-Level-Code Subsection-1".

For an example that uses jbRun to launch a process that employs most of the static methods mentioned above to "progress/cancel instrument" the process, see the RandomWalks example application.

Parameters:

jbJob - the process whose code will be executed modally with progress/cancel feedback. A blocking (modal) progress/cancel dialog is displayed until the process ends.

jbRunRefresh

public static void jbRunRefresh()

If the executing thread that invokes this method was started by jbRun, sets a flag that requests that the parent form from which the jbRun was launched be refreshed the next time jbRun's modal progress/cancel dialog gets refreshed. Otherwise, does nothing.

See Also:

jbRun, jbRefresh

setBreadboard

public void setBreadboard(java.lang.Object[][] breadboard)

Defines this parent container's child components and their layout. The breadboard array argument defines the rectangular block of cells occupied by each child component within a flexible rectilinear grid, as well as the conditions under which each row and column of this grid scales up and/or scales down in response to the availability of space in the parent container. This available space is determined, ultimately, by the size of the top level Dialog or Frame container, which can typically be altered via the sizing border by the end user.

The breadboard array must be rectangular (all rows must have the same number of elements) and must have the following general format:

null	scalingDirective	scalingDirective	scalingDirective	...
scalingDirective	jComponentRef	jComponentRef	jComponentRef	...
scalingDirective	jComponentRef	jComponentRef	jComponentRef	...
scalingDirective	jComponentRef	jComponentRef	jComponentRef	...
...	...	...	...	...

In the above:

• scalingDirective must be either NOSCALE, SHRINKS, EXPANDS, or BISCALE. These row and column headers define how extra/deficit space in the parent is distributed across each row and column. They do not correspond to any physical space on the form itself.

• jComponentRef must be either null, a reference to a JComponent, a reference to a 1-D array of JComponents (a JComponent[]) or a reference to a rectangular 2-D array of JComponents (a JComponent[][] all of whose rows have the same number of elements), or a row or column ditto keyword ("" or __) that resolves to such a reference. The area of the breadboard that contains these jComponentRefs defines the grid positions occupied by each JComponent on the form, which in turn defines the relative placement of these JComponents on the form.

• The upper left corner cell, though usually left null, may optionally contain a scalingDirective that can be referenced via row or column dittos in the row and column headers.

A special no-header format is also supported, in which the row and column headers are completely eliminated. In this case each row and column is given, by default, the NOSCALE scaling directive.

Rules governing the placement of jComponentRefs in the breadboard array:

1. The breadboard array must have at least one non-header cell (to represent an empty breadboard, you can place null into this single cell).
2. The special keyword "" (conventional ditto) is allowed in any row except the first. When present, for every such cell, the nearest non-"" reference above the cell but in the same column is copied into the cell, and the rules below are then applied to the so-transformed breadboard array.
3. The special keyword __ (columnar ditto) is allowed in any column except the first. When present, for every such cell, the nearest non-__ reference to the left of the cell in the same row is copied into the cell, and the rules below are then applied to the so-transformed breadboard array.
4. Individual JComponent references must be placed into a single rectangular sub-block within the breadboard array. The single component occupies the corresponding position within the breadboard grid, which determines the relative placement of this component on the form.
5. All 2-D array references must refer to rectangular arrays (arrays all of whose rows have the same number of elements).
6. All 2-D array references that reference arrays with more than one row and more than one column must be placed into a single rectangular sub-block of the breadboard array that has exactly the same number of rows and columns as the 2-D array (the JComponents in the 2-D array will be placed into the corresponding cells in the breadboard array).
7. All 2-D arrays references that reference an array with only one row and more than one column must be placed into a rectangular sub-block of the breadboard with the same number of columns and one or more rows. The single JComponent in each column of the 2-D array is placed into the entire corresponding column of the breadboard sub-block.
8. All 2-D arrays references that reference an array with only one column and more than one row must be placed into a rectangular sub-block of the breadboard with the same number of rows and one or more columns. The single JComponent in each row of the 2-D array is placed into the entire corresponding row of the breadboard sub-block.
9. All 1-D array references that reference arrays with more than one element must be placed into either a single row, or a single column, that has exactly the same number of elements as the 1-D array. The JComponents in the array will be placed into the corresponding cells in the breadboard array.
10. All 2-D and 1-D array references that contain a single JComponent element, are replaced with a reference to that single element, and then follow the same rules as for individual JComponent references.
11. No JComponent, regardless of if it is placed on the breadboard grid directly, or indirectly via an array reference, can be mapped into more than one rectangular sub-block of the breadboard array.
12. Array elements may also be null, which indicates unoccupied space in the grid.
13. Any references (for example, a reference to a 2-D array with three zero-element rows) not explicitly mentioned above are illegal.

Failure to comply with the above rules will cause this method to throw an IllegalArgumentException that is informative enough so that you don't need to refer back to this list.

How component placement and sizing are determined (the layout algorithm)

Note: The code that implements the layout manager is so simple that you might prefer to consult it directly (c.f. the layoutContainer method in JComponentBreadboard.java) rather than relying on the more intuitive description below.

There are three basic steps in the determination of component placement and sizing:

1. The preferred size determined height of each row, and the preferred size determined width of each column of the breadboard grid are calculated.
2. If the parent container's actual size is different than the sum of these preferred size determined heights and widths, certain rows and columns (as indicated by the row and column scalingDirectives) are either uniformly scaled up or uniformly scaled down such that (if possible) the so-rescaled grid exactly fits within the parent container.
3. Components are positioned and sized within the rectangular block of grid cells that they occupy.

As a simple example of this process, consider a grid in which each grid cell is occupied by just a single JComponent (no multi-cell sub-blocks), and where every row and column has the BISCALE scaling directive:

1. The preferred size determined height of each row is the maximum preferred height of all the JComponents within that row. Similarly, the preferred size determined width of each column is the maximum preferred width of all JComponents within that column.
2. Because each row and column contains the BISCALE directive, each preferred size determined row height is scaled up or down uniformly such that the sum of all so-rescaled row heights exactly equals the parent's height. Similarly, each preferred size determined column width is scaled up or down uniformly such that the sum of all so-adjusted column widths equals the parent container's actual width.
3. With these adjusted grid-sizes in hand, the exact location of the grid cell that contains each JComponent is determined. Although the JComponent will always be placed within that cell, the exact location and sizing within that grid-cell will be determined by consulting additional layout attributes (such as those governing alignment) described below.

The key role of preferredSize. The built-in preferred size estimates provided by Swing are central to how JComponentBreadboard places your components on the form. The key reason preferred sizes work so well to define basic grid-sizes is that Swing, by default, computes its preferred size estimates as the smallest size each JComponent requires to display itself well. For example, with the default font size, a JButton with the label "OK" will have a smaller preferred width than one with the label "Cancel", because part of the preferred width computation takes into account the amount of space required to display the button's label without truncating it.

Determining the preferred size determined row and column heights

For each JComponent on the breadboard array we manufacture a rigid steel bar whose length is equal to the (possibly yUpsize-adjusted) preferred height of that JComponent.

We construct a series of parallel rigid steel rectangular shelves (each of negligible thickness), and hang them from the ceiling via a special system of pulleys that allows them to move up and down while remaining parallel to the ceiling. These dividers correspond to the bottom edges of each of the rows in the breadboard array (with the ceiling representing the top edge of the first row) so there will be N such dividers, where N is the number of rows in the breadboard array.

We take each rigid bar and weld it to the bottom edge of the steel divider (or ceiling) that represents the top edge of the grid-cell-block that contains the corresponding JComponent, so that the bar is perpendicular to the row dividers, pointing down. We then drill holes immediately under the spot where the bar was welded in every row divider that is inside that component's grid-cell-block, but not in the row divider that represents the bottom edge of this JComponent's grid-cell block. (note that this implies that JComponents that occupy only a single row in the grid don't require any drilling). The bar is threaded through these holes, so that the inner row dividers can move freely around the bar.

We repeat this process for each JComponent on the grid, adding appropriately sized bars and drilling holes for intermediary row dividers where needed, until there is one bar in place for each JComponent on the breadboard grid.

The pulleys are pulled as tight as possible, until every row-divider-shelf, while still parallel to the ceiling, is as close to the ceiling as possible. Namely, each divider is either flush against the bottom tip of one or more of the steel bars, or else flush against the row divider immediately above it (or against the ceiling for the first row divider). The final vertical distances between each metal divider equals the preferred sized determined height of each row. Note that if we give each breadboard grid row these heights, the rigid bars assure us that it will always be possible to fit each JComponent into it's corresponding grid-cell-block at it's preferred height. Simultaneously, the tight pulleys assure us that the sum of all these heights is as small as it can possibly be.

This entire process is repeated, in an exactly analogous manner, to determine the preferred size determined column widths. Specifically, we use the same apparatus, except that the number of dividers is equal to the number of columns in the breadboard array, and the bar lengths are equal to the widths of each component, and the welded-to dividers are those corresponding to the left-edge of the grid-cell block containing the component, and holes are drilled in the shelves corresponding to the inner column dividers of the each component's grid-cell-block. (Or, if you prefer, just imagine rotating the breadboard array clockwise through a right angle, so that all the column dividers become row dividers).

The preferred height and width of the JComponentBreadboard as a whole (which in turn impacts its own placement within its own parent container) equals the sum of all of their preferred-height-determined row heights and the sum of all of their preferred-width-determined column widths.

Note that in the above algorithm, the row heights and column widths are determined independently. For example, changes to the preferred height of a component can never have any impact on the preferred size determined column widths. This generates more easily predicted layout decisions than layout algorithms (such as that used by GridBagLayout) that lack such independence.

Scaling up and down to fit within the actual size of the parent container

The sum of all the "preferred row heights" as determined by the above algorithm may either be:

1. Equal to the actual height of the parent container
2. Less than the actual height of the parent container (space surplus in parent)
3. Greater than the actual height of the parent container (space deficit in parent)

For a top-level JComponentBreadboard occupying the entire content pane, the size of its parent container changes whenever the user resizes the Dialog or Frame via it's sizing border.

In the first case, no further rescaling of the row heights is required, and they simply remain at their preferred-size-determined values.

In the second case, every row with a non-zero preferred height whose row header contains either the EXPANDS or BISCALE scaling directive is uniformly scaled up so as to use up the extra space in the parent (if there are no such "up-scaleable" rows, no changes are made to the row heights from their preferred size determined values).

In the third case, every row whose row header contains either the SHRINKS or BISCALE scalingDirective is scaled down uniformly until the so-rescaled grid has a height that exactly equals the height of the parent container, or until all "down-scalable" rows have zero height, whichever comes first.

Note that the above rules imply that in some cases it will not be possible for the grid to be scaled up or down to exactly equal the height of the parent container. In such cases, the grid will be positioned as determined by the layout manager of its own parent container.

Exactly analogous rules are applied to distribute any horizontal surplus or deficit space in the parent container across the columns of the grid.

Placement of each JComponent within it's grid-cell block

The final (possibly rescaled) row heights and column widths determine exactly the position (within this container's x-y coordinate system) of the grid-cell-block that contains each JComponent. Although the algorithm assures that the initial preferred-size-determined grid produces grid-cell-blocks that are large enough to contain every JComponent at their preferred sizes, due to the presence of larger components in nearby cells, as well as the impact of any "scaling up" that may have been done, the final grid-cell-block could be larger than the JComponent it contains. Furthermore, due to the impact of any "scaling down" that may have been done, the final grid-cell-block could also be too small to contain the JComponent at it's preferred size.

In light of the above, JComponentBreadboard uses the following rules to determine the exact size and placement of each component within it's grid-cell block:

1. If the grid-cell-block and the JComponent are exactly the same height, (an exact fit) no adjustment is required and the JComponent is simply placed into the grid-cell block at it's preferred height.
2. If the block is shorter than the preferred height of the JComponent it contains, the JComponent's height is simply set equal to the smaller, grid-cell-block's height.
3. If the block is taller than the JComponent it contains, and if the JComponent's yFill attribute is true, then the JComponent's height is also set equal to the height of the grid-cell-block that contains it.
4. If the block is taller and the yFill attribute is false, then the JComponent remains at it's preferred height, and will be flush against the top edge of its grid-cell-block if it's alignmentY property equals 0, flush against the bottom edge if it's alignmentY property equals 1, and a fraction "f" of the way between these two extremes if the alignmentY property equals a number "f" between 0 and 1.

Exactly analogous rules (using xFill instead of yFill, alignmentX instead of alignmentY, etc.) apply independently to the horizontal placement and sizing of the JComponent relative to the width of it's containing grid-cell-block.

For an example of how these rules work themselves out in defining the placement of components within a specific form, including examples of each of the four allowed scaling directives, see the CelsiusFahrenheitConverter application in the JComponentBreadboard User's Guide.

Parameters:

breadboard - an array that defines the relative positions of all components on this form within a flexible, rectilinear grid.

See Also:

xFill, yFill, xAlign, yAlign, xUpsize, yUpsize, NOSCALE, SHRINKS, EXPANDS, BISCALE

setJbRunCanBeCanceled

public static void setJbRunCanBeCanceled(boolean canBeCanceled)

If executed from within the jbRun launched process, enables or disables the Cancel button on the current progress monitoring dialog.

If executed outside of a jbRun launched process, changes the initial, default, enabled/disabled state of the progress monitoring dialog's Cancel button for any future jbRun launched processes.

If this method is never invoked, the Cancel button is disabled by default.

Parameters:

canBeCanceled - true to enable the Cancel button on the progress/cancel dialog, false to disable it.

See Also:

jbRun

setJbRunCanceled

public static void setJbRunCanceled(boolean progressCanceled)

When executed from with a jbRun launched process, sets or unsets that thread's "cancelRequested" flag. Otherwise, does nothing.

Typically, this flag will be set as a consequence of the user clicking on the Cancel button of the progress/cancel feedback dialog displayed by the jbRun method. Hence this method is only needed in those rare cases where you need to request such a cancel operation programmatically, or when you need to "un-cancel" a previous cancel request.

Parameters:

progressCanceled - true to set the progress cancel flag, false to reset this flag (to "un-cancel")

See Also:

getJbRunCanceled, jbRun

setJbRunNote

public static void setJbRunNote(java.lang.String note)

If executed from within the jbRun launched process, sets the portion of the note (located just above the progress bar) associated with the lowest-level, currently executing, progress monitored section (the "local" note).

If executed outside of a jbRun launched process sets the initial note that gets prepended to whatever other notes are set within any future jbRun launched processes (if there are no setJbRunNote calls within the launched process, this prefix becomes the fixed note for the entire run)

Parameters:

note - the text of the note, in plain text or in the Swing subset of HTML.

See Also:

getJbRunNoteGlobally, jbRun

setJbRunNoteDelimiter

public static void setJbRunNoteDelimiter(java.lang.String delimiter)

If called within the currently executing progress monitored thread, specifies the delimiter used between the progress notes associated with each progress monitored section when these individual notes are concatenated to produce the note displayed in the progress/cancel dialog of a jbRun-launched thread.

When invoked from some other thread, sets the default delimiter to be used the next time jbRun launches such a thread.

Swing-subset HTML may be used (for example, <br>). A single space delimiter is used by default.

For complex processes, the nested progress monitored sections containing the currently executing code line form a hierarchy, with the overall process at the top and the lowest level currently executing progress monitored section at the bottom. The formation of the displayed notes from the notes of each progress monitored section is analogous to how the names of sub-folders get concatenated (interspersed with appropriatedly leaning slashes) to define the absolute path of a specific, lowest-level, folder.

Parameters:

delimiter - the String to place between the notes of each progress monitored section when these notes get concatenated together to form the displayed note. Swing-subset HTML may be used.

See Also:

jbRun

setJbRunProgress

public static void setJbRunProgress(double fraction)

When called from within a jbRun launched process, specifies the fraction of the lowest level current progress monitored section of the process that has been completed so far.

When called outside of a jbRun launched process, defines the initial default fraction complete for newly launched jbRun processes (by default, this is Double.NaN, which places the progress bar in indeterminate mode).

Parameters:

fraction - the fraction completed so far (on a computing time basis) of the lowest level currently executing progress monitored section. The only allowed value outside of the range 0 to 1 is Double.NaN, which means "fraction complete is unknown", and places the progress bar in indeterminate mode.

See Also:

jbRun

setJbRunRefreshInterval

public static void setJbRunRefreshInterval(int refreshInterval)

If executed from within the jbRun launched process, changes the interval at which the progress/cancel dialog is updated, but only for that process.

If executed outside of a jbRun launched process, changes the initial, default, refresh interval for the progress monitoring dialog of any future jbRun launched processes.

Warning: Very long refresh intervals can cause user feedback problems, very short refresh intervals can cause performance problems. The default of 1000 milliseconds (= 1 second) is expected to be a good choice for most applications.

Parameters:

refreshInterval - the time interval, in milliseconds, between successive refreshes of the progress monitoring dialog.

See Also:

DEFAULT_JBRUN_REFRESH_INTERVAL, jbRun

setJbRunTitle

public static void setJbRunTitle(java.lang.String title)

If executed from within the jbRun launched process, sets the title on the current progress monitoring dialog.

If executed outside of a jbRun launched process, changes the initial, default, title of the progress monitoring dialog for any future jbRun launched processes.

Parameters:

title - the title of the progress/cancel dialog

See Also:

jbRun

setResult

public void setResult(java.lang.Object result)

Sets the result object associated with this JComponentBreadboard.

Methods such as showInputBreadboard, that define the content pane of a modal dialog using a single JComponentBreadboard-defined form, use setResult and getResult to specify and retrieve the result to be returned by that modal dialog.

Typically, setResult is not called directly, but rather as a side effect of a call such as jbReturn(returnValue). Such a call will invoke setResult(returnValue) and then call dispose on the Dialog or Frame that contains the JComponentBreadboard. (The dispose call closes the modal dialog).

The program that invoked the modal JDialog that displayed the JComponentBreadboard-based form would then call getResult to retrieve the value to be returned to the caller who invoked the modal dialog.

For an example application that uses showInputDialog, and jbReturn in this coordinated manner, see NumericInputDialog in the User's Guide.

Parameters:

result - the object that will be retrieved by getResult, and that plays the role of the returned value from the form in various contexts.

See Also:

getResult, jbReturn, showInputBreadboard

showInputBreadboard

public static java.lang.Object showInputBreadboard(java.awt.Container parent,
                                                   JComponentBreadboard jcb,
                                                   java.lang.String title)

This method makes it easy to define JOptionPane-like modal dialogs that return a user selectable/configurable object, where the user interface for selecting/configuring the returned object is defined by a single JComponentBreadboard form.

Analogous to JOptionPane.showInputDialog, except that it is not limited to just accepting String inputs.

The jbReturn method (whose argument is the returned object) will usually be invoked in, say, a JButtton event handler, to close the modal dialog and return a result. The pre-defined CLOSE_BUTTON JButton will typically be connected to handle the windowClosing event.

The JComponentBreadboard User's Guide contains examples that use showInputBreadboard along with these techniques to modally prompt the user for a validated numeric entry (the NumericInputDialog application) and a calendar-selected Date entry (the DateChooser application).

Parameters:

parent - parent Frame, Dialog, or null to use Swing's system-wide default parent. Container objects not Frames or Dialogs will raise an IllegalArgumentException.

jcb - the JComponentBreadboard the user will interact with, that defines the content pane of the dialog, and that lets the user specify/modify the value the dialog will return.

title - the title of the dialog

Returns:

the Object returned by jcb.getResult(). This is the object defined by the last jcb.setResult call (note that jbReturn(returnValue), automatically calls setResult(returnValue) before closing the dialog).

See Also:

jbReturn, setResult, createBreadboardDialog

showMessageBreadboard

public static void showMessageBreadboard(java.awt.Container parent,
                                         JComponentBreadboard jcb,
                                         java.lang.String title)

Convenience method that is equivalent to showInputBreadboard(parent, jcb, title) except that it discards the returned result.

Analogous to JOptionPane.showMessageDialog

Parameters:

parent - parent Frame, Dialog, or null to use Swing's system-wide default parent. Container objects not Frames or Dialogs will raise an IllegalArgumentException.

jcb - the JComponentBreadboard the user will interact and that defines the content pane of the dialog.

title - the title of the dialog

See Also:

showInputBreadboard

xAlign

public static javax.swing.JComponent xAlign(double fraction,
                                            javax.swing.JComponent jc)

Declares that, in situations in which the JComponent's (possibly xUpsize adjusted) preferred width is smaller than the width of the breadboard grid-cell-block that contains it, the JComponent should be positioned the specified fraction of the way between the extreme flush left and extreme flush right positions.

For example, a fraction of 0 means flush left, a fraction of 1 flush right, and a fraction of 0.5 means horizontally centered.

Note: this method changes the JComponent's xAlignment property via a call to jc.setXAlignment(fraction).

Parameters:

fraction - the fraction of the way between the extreme left and extreme right positions within the breadboard grid-cell-block that contains the component at which to position the component horizontally.

jc - the JComponent to receive this horizontal alignment attribute

Returns:

the JComponent passed in as the last argument (jc), whose x alignment has been modified.

See Also:

setBreadboard, xUpsize, yAlign

xAlign

public static javax.swing.JComponent[] xAlign(double fraction,
                                              javax.swing.JComponent[] jca)

Convenience method that issues xAlign(fraction, jca[i]) to set the xAlign fraction on every non-null element of a 1-D array of JComponents.

Parameters:

fraction - the fraction of the way between the extreme left and extreme right positions within the breadboard grid-cell-blocks that contain the components at which to position the components horizontally.

jca - contains the JComponents to receive this horizontal alignment attribute

Returns:

the array reference passed in as its second argument

See Also:

xAlign(double, JComponent)

xAlign

public static javax.swing.JComponent[][] xAlign(double fraction,
                                                javax.swing.JComponent[][] jca)

Convenience method that issues xAlign(fraction, jca[i][j]) to set the xAlign fraction on every non-null element of a 2-D array of JComponents.

Parameters:

fraction - the fraction of the way between the extreme left and extreme right positions within the breadboard grid-cell-blocks that contain the components at which to position the components horizontally.

jca - contains the JComponents to receive this horizontal alignment attribute

Returns:

the array reference passed in as its second argument.

See Also:

xAlign(double, JComponent)

xFill

public static javax.swing.JComponent xFill(boolean isXFilled,
                                           javax.swing.JComponent jc)

Defines whether or not the component should always expand to fill out any extra horizontal space that may be available in the breadboard grid cell(s) that it occupies.

For most JComponents, the default if not specified is not to fill. The exception is for horizontally oriented JComponents (horizontally oriented JScrollbars, JSliders, etc.--any JComponent with a getOrientation method that returns SwingConstants.HORIZONTAL) which fill by default.

Parameters:

isXFilled - true if horizontal filling is to be enabled, false if not.

jc - the JComponent whose horizontal fill attribute is to be specified.

Returns:

the JComponent whose fill attribute was specified (jc).

See Also:

yFill(boolean, JComponent), setBreadboard

xFill

public static javax.swing.JComponent[] xFill(boolean isXFilled,
                                             javax.swing.JComponent[] jca)

Convenience method equivalent to applying xFill(isXFilled, jca[i]) to every non-null element of the given 1-D array.

Parameters:

isXFilled - true if horizontal filling is to be enabled, false if not.

jca - the JComponent array containing the elements operated upon.

Returns:

the array reference passed in as its second argument

See Also:

xFill(boolean, JComponent)

xFill

public static javax.swing.JComponent[][] xFill(boolean isXFilled,
                                               javax.swing.JComponent[][] jca)

Convenience method equivalent to applying xFill(isXFilled, jca[i][j]) to every non-null element of the given 2-D array.

Parameters:

isXFilled - true if horizontal filling is to be enabled, false if not.

jca - the JComponent array containing the elements operated upon.

Returns:

the array reference passed in as its second argument.

See Also:

xFill(boolean, JComponent)

xFill

public static javax.swing.JComponent xFill(javax.swing.JComponent jc)

Convenience method equivalent to xFill(true, jc)

Parameters:

jc - the JComponent whose horizontal fill attribute is set to true.

Returns:

the JComponent reference passed in as its argument.

See Also:

xFill(boolean, JComponent)

xFill

public static javax.swing.JComponent[] xFill(javax.swing.JComponent[] jca)

Convenience method equivalent to applying xFill(true, jca[i]) to every non-null element of the given 1-D array.

Parameters:

jca - the JComponent array containing the elements operated upon.

Returns:

the array reference passed in as its argument

See Also:

xFill(boolean, JComponent)

xFill

public static javax.swing.JComponent[][] xFill(javax.swing.JComponent[][] jca)

Convenience method equivalent to applying xFill(true, jca[i][j]) to every non-null element of the given 2-D array.

Parameters:

jca - the JComponent array containing the elements operated upon.

Returns:

the array reference passed in as its argument

See Also:

xFill(boolean, JComponent)

xSep

public static javax.swing.JSeparator xSep()

Convenience method that returns a new horizontal, flush top, flush left JSeparator

This method can be used to more easily introduce horizontal separator lines into a JComponentBreadboard's breadboard array.

Returns:

the new JSeparator

See Also:

ySep, setBreadboard

xSpace

public static javax.swing.JPanel xSpace(int widthInPixels)

Convenience method that returns a zero height JPanel whose preferred width is as specified.

This method can be used to introduce small amounts of horizontal space between JComponents within the breadboard array.

Parameters:

widthInPixels - width of zero height JPanel to be returned, in pixels

Returns:

a zero height JPanel of the specified width

See Also:

ySpace, xySpace, setBreadboard

xUpsize

public static javax.swing.JComponent xUpsize(int widthIncreaseInPixels,
                                             javax.swing.JComponent jc)

Declares that, for JComponentBreadboard layout purposes, the specified JComponent should be considered to have a preferred width the specified number of pixels larger than the JComponent's actual preferred width.

Use this method to increase or decrease the width of a JComponent from what it would normally be (e.g. if you want a slightly wider JButton than Swing would normally provide).

Parameters:

widthIncreaseInPixels - the number of pixels wider that you want the width to be. Value must not exceed MAX_UPSIZE. Negative values can be used to decrease the width. However, if the sum of the width adjustment and original preferred width is ever less than 0, the adjusted preferred width will be exactly 0, not negative.

jc - the JComponent whose preferred width is to be adjusted

Returns:

the JComponent whose preferred width was adjusted (jc).

xUpsize

public static javax.swing.JComponent[] xUpsize(int widthIncreaseInPixels,
                                               javax.swing.JComponent[] jca)

Convenience method equivalent to issuing a xUpsize(widthIncreaseInPixels, jc[i])) on every non-null element of a 1-D JComponent array.

Parameters:

widthIncreaseInPixels - the width increase attribute to be set on each JComponent in the array

jca - the 1-D array of JComponents operated upon.

Returns:

the 1-D array reference, jca, passed into it.

See Also:

xUpsize(int, JComponent)

xUpsize

public static javax.swing.JComponent[][] xUpsize(int widthIncreaseInPixels,
                                                 javax.swing.JComponent[][] jca)

Convenience method equivalent to issuing a xUpsize(widthIncreaseInPixels, jc[i][j])) on every non-null element of a 2-D JComponent array.

Parameters:

widthIncreaseInPixels - the width increase attribute to be set on each JComponent in the array

jca - the 2-D array of JComponents operated upon.

Returns:

the 2-D array reference, jca, passed into it.

See Also:

xUpsize(int, JComponent)

xyAlign

public static javax.swing.JComponent xyAlign(double xFraction,
                                             double yFraction,
                                             javax.swing.JComponent jc)

Convenience method equivalent to xAlign(xFraction, yAlign(yFraction, jc))

Parameters:

xFraction - the fraction of the way between the extreme left and extreme right positions (within the breadboard grid-cell-block that contains the component) at which to position the component horizontally.

yFraction - the fraction of the way between the extreme top and extreme bottom positions (within the breadboard grid-cell-block that contains the component) at which to position the components vertically.

jc - the JComponent to receive these alignment attributes

Returns:

the JComponent reference passed in as its third argument

See Also:

xAlign(double, JComponent), yAlign(double, JComponent)

xyAlign

public static javax.swing.JComponent[] xyAlign(double xFraction,
                                               double yFraction,
                                               javax.swing.JComponent[] jca)

Convenience method equivalent to applying xyAlign(widthIncreaseInPixels, heightIncreaseInPixels, jca[i])) to every non-null element in the 1-D array.

Parameters:

xFraction - the fraction of the way between the extreme left and extreme right positions (within the breadboard grid-cell-blocks that contain the components) at which to position the components horizontally.

yFraction - the fraction of the way between the extreme top and extreme bottom positions (within the breadboard grid-cell-blocks that contain the components) at which to position the components vertically.

jca - contains the JComponents to receive these alignment attributes

Returns:

the array passed in as the third parameter

See Also:

xyAlign(double, double, JComponent)

xyAlign

public static javax.swing.JComponent[][] xyAlign(double xFraction,
                                                 double yFraction,
                                                 javax.swing.JComponent[][] jca)

Convenience method equivalent to applying xyAlign(widthIncreaseInPixels, heightIncreaseInPixels, jca[i][j])) to every non-null element in the 2-D array.

Parameters:

xFraction - the fraction of the way between the extreme left and extreme right positions (within the breadboard grid-cell-blocks that contain the components) at which to position the components horizontally.

yFraction - the fraction of the way between the extreme top and extreme bottom positions (within the breadboard grid-cell-blocks that contain the components) at which to position the components vertically.

jca - contains the JComponents to receive these alignment attributes

Returns:

the array passed in as the third parameter

See Also:

xyAlign(double, double, JComponent)

xyFill

public static javax.swing.JComponent xyFill(boolean isXFilled,
                                            boolean isYFilled,
                                            javax.swing.JComponent jc)

Convenience method equivalent to xFill(isXFilled,yFill(isYFilled, jc))

Parameters:

isXFilled - true if horizontal filling is to be enabled, false if not.

isYFilled - true if vertical filling is to be enabled, false if not.

jc - the JComponent operated upon

Returns:

the JComponent operated upon

See Also:

xFill(boolean, JComponent), yFill(boolean, JComponent)

xyFill

public static javax.swing.JComponent[] xyFill(boolean isXFilled,
                                              boolean isYFilled,
                                              javax.swing.JComponent[] jca)

Convenience method equivalent to applying xyFill(isXFilled,isYFilled, jca[i]) to every non-null element of the given 1-D array.

Parameters:

isXFilled - true if horizontal filling is to be enabled, false if not.

isYFilled - true if vertical filling is to be enabled, false if not.

jca - the JComponent array whose elements are operated upon

Returns:

the JComponent array whose elements were operated upon

See Also:

xyFill(boolean, boolean, JComponent)

xyFill

public static javax.swing.JComponent[][] xyFill(boolean isXFilled,
                                                boolean isYFilled,
                                                javax.swing.JComponent[][] jca)

Convenience method equivalent to applying xyFill(isXFilled, isYFilled, jca[i][j]) to every non-null element of the given 2-D array

Parameters:

isXFilled - true if horizontal filling is to be enabled, false if not.

isYFilled - true if vertical filling is to be enabled, false if not.

jca - the JComponent array whose elements are operated upon

Returns:

the JComponent array whose elements were operated upon

See Also:

xyFill(boolean, boolean, JComponent)

xyFill

public static javax.swing.JComponent xyFill(javax.swing.JComponent jc)

Convenience method equivalent to xFill(true,yFill(true, jc))

Parameters:

jc - the JComponent operated upon

Returns:

the JComponent operated upon

See Also:

xFill(boolean, JComponent), yFill(boolean, JComponent)

xyFill

public static javax.swing.JComponent[] xyFill(javax.swing.JComponent[] jca)

Convenience method equivalent to xyFill(true, true, jca)

Parameters:

jca - the JComponent array whose elements are operated upon

Returns:

the JComponent array whose elements were operated upon

See Also:

xyFill(boolean, boolean, JComponent[])

xyFill

public static javax.swing.JComponent[][] xyFill(javax.swing.JComponent[][] jca)

Convenience method equivalent to xyFill(true, true, jca).

Parameters:

jca - the JComponent array whose elements are operated upon

Returns:

the JComponent array whose elements were operated upon

See Also:

xyFill(boolean, boolean, JComponent[][])

xySpace

public static javax.swing.JPanel xySpace(int widthInPixels,
                                         int heightInPixels)

Convenience method that returns an empty JPanel whose preferred width and height are as specified.

This method can be used to introduce small amounts of vertical and horizontal space within the breadboard array.

Parameters:

widthInPixels - width JPanel to be returned, in pixels

heightInPixels - height of JPanel to be returned, in pixels

Returns:

an empty JPanel of the specified dimensions

See Also:

xSpace, ySpace, setBreadboard

xyUpsize

public static javax.swing.JComponent xyUpsize(int widthIncreaseInPixels,
                                              int heightIncreaseInPixels,
                                              javax.swing.JComponent jc)

Convenience method equivalent to xUpsize(widthIncreaseInPixels, yUpsize(heightIncreaseInPixels, jc)).

Parameters:

widthIncreaseInPixels - the number of pixels wider that you want the width to be. Value must not exceed MAX_UPSIZE. Negative values can be used to decrease the width. However, if the sum of the width adjustment and original preferred width is ever less than 0, the adjusted preferred width will be exactly 0, not negative.

heightIncreaseInPixels - the number of pixels taller that you want the height to be. Value must not exceed MAX_UPSIZE. Negative values can be used to decrease the height. However, if the sum of this height adjustment and the original preferred height is ever less than 0, the adjusted preferred height will be exactly 0, not negative.

jc - the JComponent whose preferred height is to be adjusted

Returns:

the JComponent whose preferred height was adjusted (jc).

See Also:

xUpsize(int, JComponent), yUpsize(int, JComponent)

xyUpsize

public static javax.swing.JComponent[] xyUpsize(int widthIncreaseInPixels,
                                                int heightIncreaseInPixels,
                                                javax.swing.JComponent[] jca)

Convenience method equivalent to applying xyUpsize(widthIncreaseInPixels, heightIncreaseInPixels, jca[i]) to every non-null element in the 1-D array.

Parameters:

widthIncreaseInPixels - the width increase attribute to be set on each JComponent in the array

heightIncreaseInPixels - the height increase attribute to be set on each JComponent in the array

jca - the 1-D array of JComponents operated upon.

Returns:

the 1-D array reference, jca, passed into it.

See Also:

xyUpsize(int, int, JComponent)

xyUpsize

public static javax.swing.JComponent[][] xyUpsize(int widthIncreaseInPixels,
                                                  int heightIncreaseInPixels,
                                                  javax.swing.JComponent[][] jca)

Convenience method equivalent to applying xyUpsize(widthIncreaseInPixels, heightIncreaseInPixels, jca[i][j])) to every non-null element in the 2-D array.

Parameters:

widthIncreaseInPixels - the width increase attribute to be set on each JComponent in the array

heightIncreaseInPixels - the height increase attribute to be set on each JComponent in the array

jca - the 2-D array of JComponents operated upon.

Returns:

the 2-D array reference, jca, passed into it.

See Also:

xyUpsize(int, int, JComponent)

yAlign

public static javax.swing.JComponent yAlign(double fraction,
                                            javax.swing.JComponent jc)

Declares that, in situations in which the JComponent's (possibly yUpsize adjusted) preferred height is smaller than the height of the breadboard grid-cell-block that contains it, the JComponent should be positioned the specified fraction of the way between the extreme top and extreme bottom positions.

For example, a fraction of 0 means flush against the top edge, a fraction of 1 flush against the bottom edge, and a fraction of 0.5 means vertically centered.

Note: this method changes the JComponent's yAlignment property via a call to jc.setYAlignment(fraction).

Parameters:

fraction - of the way between the extreme top and extreme bottom positions (within the breadboard grid-cell-block that contains the component) at which to position the component vertically.

jc - the JComponent to receive this vertical alignment attribute

Returns:

the JComponent passed in as the last argument, whose y alignment has been modified.

See Also:

setBreadboard, yUpsize, xAlign

yAlign

public static javax.swing.JComponent[] yAlign(double fraction,
                                              javax.swing.JComponent[] jca)

Convenience method that issues yAlign(fraction, jca[i]) to set the yAlignment of every non-null element of a 1-D array of JComponents.

Parameters:

fraction - of the way between the extreme top and extreme bottom positions (within the breadboard grid-cell-blocks that contain the components) at which to position the components vertically.

jca - contains the JComponents to receive this vertical alignment attribute

Returns:

the array reference passed in as its second argument

See Also:

yAlign(double, JComponent)

yAlign

public static javax.swing.JComponent[][] yAlign(double fraction,
                                                javax.swing.JComponent[][] jca)

Convenience method that issues yAlign(fraction, jca[i][j]) to set the yAlignment of every non-null element of a 2-D array of JComponents.

Parameters:

fraction - of the way between the extreme top and extreme bottom positions (within the breadboard grid-cell-blocks that contain the components) at which to position the components vertically.

jca - contains the JComponents to receive this vertical alignment attribute

Returns:

the array reference passed in as its second argument

See Also:

yAlign(double, JComponent)

yFill

public static javax.swing.JComponent yFill(boolean isYFilled,
                                           javax.swing.JComponent jc)

Defines whether or not the component should always expand to fill out any extra vertical space that may be available in the breadboard grid cell(s) that it occupies.

For most JComponents, the default if not specified is not to fill. The exception is for vertically oriented JComponents (vertically oriented JScrollbars, JSliders, etc.--any JComponent with a getOrientation method that returns SwingConstants.VERTICAL) which fill by default.

Parameters:

isYFilled - true if vertical filling is to be enabled, false if not.

jc - the JComponent whose vertical fill attribute is to be specified.

Returns:

the JComponent whose fill attribute was specified (jc).

See Also:

xFill(boolean, JComponent), setBreadboard

yFill

public static javax.swing.JComponent[] yFill(boolean isYFilled,
                                             javax.swing.JComponent[] jca)

Convenience method equivalent to applying yFill(isYFilled, jca[i]) to every non-null element of the given 1-D array.

Parameters:

isYFilled - true if vertical filling is to be enabled, false if not.

jca - the JComponent array whose elements are operated upon

Returns:

the JComponent array whose elements were operated upon

See Also:

yFill(boolean, JComponent)

yFill

public static javax.swing.JComponent[][] yFill(boolean isYFilled,
                                               javax.swing.JComponent[][] jca)

Convenience method equivalent to applying yFill(isYFilled, jca[i][j]) to every non-null element of the given 2-D array.

Parameters:

isYFilled - true if vertical filling is to be enabled, false if not.

jca - the JComponent array whose elements are operated upon

Returns:

the JComponent array whose elements were operated upon

See Also:

yFill(boolean, JComponent)

yFill

public static javax.swing.JComponent yFill(javax.swing.JComponent jc)

Convenience method equivalent to yFill(true, jc)

Parameters:

jc - the JComponent whose vertical fill attribute is to be specified.

Returns:

the JComponent whose fill attribute was specified (jc).

See Also:

yFill(boolean, JComponent)

yFill

public static javax.swing.JComponent[] yFill(javax.swing.JComponent[] jca)

Convenience method equivalent to applying yFill(true, jca[i]) to every non-null element of the given 1-D array.

Parameters:

jca - the JComponent array whose elements are operated upon

Returns:

the JComponent array whose elements were operated upon

See Also:

yFill(boolean, JComponent)

yFill

public static javax.swing.JComponent[][] yFill(javax.swing.JComponent[][] jca)

Convenience method equivalent to applying yFill(true, jca[i][j]) to every non-null element of the given 2-D array.

Parameters:

jca - the JComponent array whose elements are operated upon

Returns:

the JComponent array whose elements were operated upon

See Also:

yFill(boolean, JComponent)

ySep

public static javax.swing.JSeparator ySep()

Same as xSep() except returns a new vertically oriented JSeparator, and is used to introduce vertical lines into the breadboard array.

See Also:

xSep

ySpace

public static javax.swing.JPanel ySpace(int heightInPixels)

Convenience method that returns a zero width JPanel whose preferred height is as specified.

This method can be used to introduce small amounts of vertical space between JComponents within the breadboard array.

Parameters:

heightInPixels - height of zero width JPanel to be returned, in pixels

Returns:

a zero width JPanel of the specified height

See Also:

xSpace, xySpace, setBreadboard

yUpsize

public static javax.swing.JComponent yUpsize(int heightIncreaseInPixels,
                                             javax.swing.JComponent jc)

Declares that, for JComponentBreadboard layout purposes, the specified JComponent should be considered to have a preferred height the specified number of pixels larger than the JComponent's actual preferred height.

Use this method to increase or decrease the height of a JComponent from what it would normally be (e.g. if you want a slightly taller JButton than Swing would normally provide)

Parameters:

heightIncreaseInPixels - the number of pixels taller that you want the height to be. Value must not exceed MAX_UPSIZE. Negative values can be used to decrease the height. However, if the sum of this height adjustment and the original preferred height is ever less than 0, the adjusted preferred height will be exactly 0, not negative.

jc - the JComponent whose preferred height is to be adjusted

Returns:

the JComponent whose preferred height was adjusted (jc).

yUpsize

public static javax.swing.JComponent[] yUpsize(int heightIncreaseInPixels,
                                               javax.swing.JComponent[] jca)

Convenience method equivalent to issuing a yUpsize(heightIncreaseInPixels, jc[i])) on every non-null element of a 1-D JComponent array.

Parameters:

heightIncreaseInPixels - the height increase to be set on each JComponent in the array

jca - the 1-D array of JComponents operated upon.

Returns:

the 1-D array reference, jca, passed into it.

See Also:

yUpsize(int, JComponent)

yUpsize

public static javax.swing.JComponent[][] yUpsize(int heightIncreaseInPixels,
                                                 javax.swing.JComponent[][] jca)

Convenience method equivalent to issuing a yUpsize(heightIncreaseInPixels, jc[i][j])) on every non-null element of a 2-D JComponent array.

Parameters:

heightIncreaseInPixels - the height increase attribute to be set on each JComponent in the array

jca - the 2-D array of JComponents operated upon.

Returns:

the 2-D array reference, jca, passed into it.

See Also:

xUpsize(int, JComponent)