ptolemy.actor.gui

Class PtolemyQuery

java.lang.Object

java.awt.Component

java.awt.Container

javax.swing.JComponent

javax.swing.JPanel

ptolemy.gui.Query

ptolemy.actor.gui.PtolemyQuery

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, java.util.EventListener, javax.accessibility.Accessible, CloseListener, QueryListener, ChangeListener, ValueListener

public class PtolemyQuery
extends Query
implements QueryListener, ValueListener, ChangeListener, CloseListener

This class is a query dialog box with various entries for setting the values of Ptolemy II attributes that implement the Settable interface and have visibility FULL. One or more entries are associated with an attribute so that if the entry is changed, the attribute value is updated, and if the attribute value changes, the entry is updated. To change an attribute, this class queues a change request with a particular object called the change handler. The change handler is specified as a constructor argument.

It is important to note that it may take some time before the value of a attribute is actually changed, since it is up to the change handler to decide when change requests are processed. The change handler will typically delegate change requests to the Manager, although this is not necessarily the case.

To use this class, add an entry to the query using addStyledEntry().

Since:

Ptolemy II 0.4

Version:

$Id$

Author:

Brian K. Vogel and Edward A. Lee, Contributor: Christoph Daniel Schulze

See Also:

Serialized Form

Pt.AcceptedRating:

Yellow (neuendor)

Pt.ProposedRating:

Yellow (eal)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PtolemyQuery.ActionableEntry Panel containing an entry box and button that performs the action specified by an Actionable.
class	PtolemyQuery.HierarchicalConfigurer Panel containing an entry box and button that opens another query to edit the parameters of a specified parameter.

Nested classes/interfaces inherited from class ptolemy.gui.Query

Query.QueryActionListener, Query.QueryColorChooser, Query.QueryFileChooser, Query.QueryFocusListener, Query.QueryItemListener, Query.SliderListener

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

javax.swing.JPanel.AccessibleJPanel

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

javax.swing.JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

java.awt.Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Map	_attributes Maps an entry name to the attribute that is attached to it.

Fields inherited from class ptolemy.gui.Query

_background, _constraints, _entries, _grid, _listeners, DEFAULT_ENTRY_HEIGHT, DEFAULT_ENTRY_WIDTH

Fields inherited from class javax.swing.JComponent

listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

accessibleContext, 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

Constructors

Constructor and Description
PtolemyQuery(NamedObj handler) Construct a panel with no queries in it and with the specified change handler.

Method Summary

Modifier and Type	Method and Description
protected void	_addPair(java.lang.String name, javax.swing.JLabel label, java.awt.Component widget, java.lang.Object entry) Override the base class to put a button on the right if the Settable object for which we are adding an entry itself contains Settable parameters.
PtolemyQuery.ActionableEntry	addActionable(java.lang.String name, java.lang.String label, java.lang.String defaultValue, Actionable actionable) Create an entry box with a button for the specified action.
void	addStyledEntry(Settable attribute) Add a new entry to this query that represents the given attribute.
boolean	adjustEditable(Settable settable, java.awt.Component component) Adjust the editability of the component depending on whether the attribute has Settable.NOT_EDITABLE visibility and if the _exportMode attribute is set in the container.
void	attachParameter(Settable attribute, java.lang.String entryName) Attach an attribute to an entry with name entryName, of a Query.
void	changed(java.lang.String name) Queue a change request to alter the value of the attribute attached to the specified entry, if there is one.
void	changeExecuted(ChangeRequest change) Notify this class that a change has been successfully executed by the change handler.
void	changeFailed(ChangeRequest change, java.lang.Exception exception) Notify the listener that a change attempted by the change handler has resulted in an exception.
static java.awt.Color	preferredBackgroundColor(java.lang.Object object) Return the preferred background color for editing the specified object.
static java.awt.Color	preferredForegroundColor(java.lang.Object object) Return the preferred foreground color for editing the specified object.
void	valueChanged(Settable attribute) Notify this query that the value of the specified attribute has changed.
void	windowClosed(java.awt.Window window, java.lang.String button) Unsubscribe as a listener to all objects that we have subscribed to.

Methods inherited from class ptolemy.gui.Query

_constructLabel, _recalculatePreferredSize, _textAreaSetRowsAndRepackParent, addCheckBox, addChoice, addChoice, addChoice, addColorChooser, addDisplay, addDisplay, addFileChooser, addFileChooser, addFileChooser, addFileChooser, addFileChooser, addFileChooser, addFileChooser, addLine, addLine, addPassword, addPassword, addQueryListener, addRadioButtons, addSelectButtons, addSeparator, addSlider, addSlider, addText, addTextArea, addTextArea, addTextArea, booleanValue, doubleValue, getBooleanValue, getCharArrayValue, getDoubleValue, getIntValue, getMaximumSize, getObjectValue, getStringValue, getTextHeight, getTextWidth, hasEntry, intValue, notifyListeners, removeQueryListener, set, setAndNotify, setBackground, setBoolean, setColumns, setDisplay, setEnabled, setInsets, setLine, setMessage, setSlider, setTextHeight, setTextWidth, setToolTip, stringToColor, stringValue

Methods inherited from class javax.swing.JPanel

getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI

Methods inherited from class javax.swing.JComponent

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

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, 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, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, 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, 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, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, 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, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

_attributes

protected java.util.Map _attributes

Maps an entry name to the attribute that is attached to it.

Constructor Detail

PtolemyQuery

public PtolemyQuery(NamedObj handler)

Construct a panel with no queries in it and with the specified change handler. When an entry changes, a change request is queued with the given change handler. The change handler should normally be a composite actor that deeply contains all attributes that are attached to query entries. Otherwise, the change requests might get queued with a handler that has nothing to do with the attributes. The handler is also used to report errors.

Parameters:

handler - The change handler.

Method Detail

addActionable

public PtolemyQuery.ActionableEntry addActionable(java.lang.String name,
                                                  java.lang.String label,
                                                  java.lang.String defaultValue,
                                                  Actionable actionable)

Create an entry box with a button for the specified action.

Parameters:

name - The name used to identify the entry (when calling get).

label - The label to attach to the entry.

defaultValue - The default entry value.

actionable - The specification for the action name and action.

Returns:

The component.

addStyledEntry

public void addStyledEntry(Settable attribute)

Add a new entry to this query that represents the given attribute. The name of the entry will be set to the name of the attribute, and the attribute will be attached to the entry, so that if the attribute is updated, then the entry is updated. If the attribute contains an instance of ParameterEditorStyle, then defer to the style to create the entry, otherwise just create a default entry. The style used in a default entry depends on the class of the attribute and on its declared type, but defaults to a one-line entry if there is no obviously better style. Only the first style that is found is used to create an entry.

Parameters:

attribute - The attribute to create an entry for.

adjustEditable

public boolean adjustEditable(Settable settable,
                              java.awt.Component component)

Adjust the editability of the component depending on whether the attribute has Settable.NOT_EDITABLE visibility and if the _exportMode attribute is set in the container.

Parameters:

settable - The attribute to be tested

component - The component to disabled if the attribute has Settable.NOT_VISIBILITY and _expertMode is not present in the container of the attribute.

Returns:

true if the component should be editable, false otherwise.

attachParameter

public void attachParameter(Settable attribute,
                            java.lang.String entryName)

Attach an attribute to an entry with name entryName, of a Query. This will cause the attribute to be updated whenever the specified entry changes. In addition, a listener is registered so that the entry will change whenever the attribute changes. If the entry has previously been attached to a attribute, then it is detached first from that attribute. If the attribute argument is null, this has the effect of detaching the entry from any attribute.

Parameters:

attribute - The attribute to attach to an entry.

entryName - The entry to attach the attribute to.

changeExecuted

public void changeExecuted(ChangeRequest change)

Notify this class that a change has been successfully executed by the change handler.

Specified by:

changeExecuted in interface ChangeListener

Parameters:

change - The change that has been executed.

changeFailed

public void changeFailed(ChangeRequest change,
                         java.lang.Exception exception)

Notify the listener that a change attempted by the change handler has resulted in an exception. This method brings up a new dialog to prompt the user for a corrected entry. If the user hits the cancel button, then the attribute is reverted to its original value.

Specified by:

changeFailed in interface ChangeListener

Parameters:

change - The change that was attempted.

exception - The exception that resulted.

changed

public void changed(java.lang.String name)

Queue a change request to alter the value of the attribute attached to the specified entry, if there is one. This method is called whenever an entry has been changed. If no attribute is attached to the specified entry, then do nothing.

Specified by:

changed in interface QueryListener

Parameters:

name - The name of the entry that has changed.

preferredBackgroundColor

public static java.awt.Color preferredBackgroundColor(java.lang.Object object)

Return the preferred background color for editing the specified object. The default is Color.white, but if the object is an instance of Parameter and it is in string mode, then a light blue is returned.

Parameters:

object - The object to be edited.

Returns:

the preferred background color.

preferredForegroundColor

public static java.awt.Color preferredForegroundColor(java.lang.Object object)

Return the preferred foreground color for editing the specified object. This returns Color.black, but in the future this might be changed to use color for some informative purpose.

Parameters:

object - The object to be edited.

Returns:

the preferred foreground color.

valueChanged

public void valueChanged(Settable attribute)

Notify this query that the value of the specified attribute has changed. This is called by an attached attribute when its value changes. This method updates the displayed value of all entries that are attached to the attribute.

Specified by:

valueChanged in interface ValueListener

Parameters:

attribute - The attribute whose value has changed.

windowClosed

public void windowClosed(java.awt.Window window,
                         java.lang.String button)

Unsubscribe as a listener to all objects that we have subscribed to.

Specified by:

windowClosed in interface CloseListener

Parameters:

window - The window that closed.

button - The name of the button that was used to close the window.

_addPair

protected void _addPair(java.lang.String name,
                        javax.swing.JLabel label,
                        java.awt.Component widget,
                        java.lang.Object entry)

Override the base class to put a button on the right if the Settable object for which we are adding an entry itself contains Settable parameters.

Overrides:

_addPair in class Query

Parameters:

name - The name of the entry.

label - The label.

widget - The interactive entry to the right of the label.

entry - The object that contains user data.