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

Direct Known Subclasses:

Configure.Query

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: PtolemyQuery.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Brian K. Vogel and Edward A. Lee

See Also:

Serialized Form

Accepted Rating:

Yellow (neuendor)

Proposed Rating:

Yellow (eal)

Nested Class Summary

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.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

protected java.util.Map	_attributes Maps an entry name to the attribute that is attached to it.
private ComponentDialog	_dialog
private NamedObj	_handler
private boolean	_ignoreChangeNotifications
private boolean	_isOpenErrorWindow
private PtolemyQuery	_query
private java.util.Map<java.lang.String,java.lang.String>	_revertValue
private ErrorHandler	_savedErrorHandler
private static java.awt.Color	_STRING_MODE_BACKGROUND_COLOR
private java.util.Map<Settable,java.util.List<java.lang.String>>	_varToListOfEntries

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

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

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

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

Method Summary

private java.lang.String	_getTranslatedExpression(Settable attribute) Return the expression for the specified Settable, unless it is an instance of DoubleRangeParameter, in which case, return the expression mapped into a integer suitable for use by JSlider.
void	addStyledEntry(Settable attribute) Add a new entry to this query that represents the given attribute.
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

_addPair, _recalculatePreferredSize, addCheckBox, addChoice, addChoice, addChoice, addColorChooser, addDisplay, addFileChooser, addFileChooser, addFileChooser, addFileChooser, addFileChooser, addFileChooser, addLine, addLine, addPassword, addPassword, addQueryListener, addRadioButtons, addSelectButtons, addSeparator, 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, 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, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, 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, transferFocusBackward, 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, 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, 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, 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.

_dialog

private ComponentDialog _dialog

_handler

private NamedObj _handler

_ignoreChangeNotifications

private boolean _ignoreChangeNotifications

_isOpenErrorWindow

private boolean _isOpenErrorWindow

_query

private PtolemyQuery _query

_revertValue

private java.util.Map<java.lang.String,java.lang.String> _revertValue

_savedErrorHandler

private ErrorHandler _savedErrorHandler

_STRING_MODE_BACKGROUND_COLOR

private static java.awt.Color _STRING_MODE_BACKGROUND_COLOR

_varToListOfEntries

private java.util.Map<Settable,java.util.List<java.lang.String>> _varToListOfEntries

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

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.

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.

_getTranslatedExpression

private java.lang.String _getTranslatedExpression(Settable attribute)

Return the expression for the specified Settable, unless it is an instance of DoubleRangeParameter, in which case, return the expression mapped into a integer suitable for use by JSlider.

Parameters:

attribute - The Settable whose expression we want.

Returns:

The expression.