ptolemy.actor.gui
Class PtolemyQuery

java.lang.Object
  extended byjava.awt.Component
      extended byjava.awt.Container
          extended byjavax.swing.JComponent
              extended byjavax.swing.JPanel
                  extended byptolemy.gui.Query
                      extended byptolemy.actor.gui.PtolemyQuery
All Implemented Interfaces:
javax.accessibility.Accessible, ChangeListener, CloseListener, java.util.EventListener, java.awt.image.ImageObserver, java.awt.MenuContainer, QueryListener, java.io.Serializable, 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: PtolemyQuery.java,v 1.101.2.1 2004/06/18 00:48:52 cxh Exp $
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 inherited from class javax.swing.JPanel
javax.swing.JPanel.AccessibleJPanel
 
Nested classes inherited from class javax.swing.JComponent
javax.swing.JComponent.AccessibleJComponent
 
Nested classes inherited from class java.awt.Container
java.awt.Container.AccessibleAWTContainer
 
Nested classes inherited from class java.awt.Component
java.awt.Component.AccessibleAWTComponent, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy
 
Field Summary
 
Fields inherited from class ptolemy.gui.Query
_background, _constraints, _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
 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, addCheckBox, addChoice, addChoice, addChoice, addColorChooser, addDisplay, addFileChooser, addFileChooser, addLine, addLine, addPassword, addPassword, addQueryListener, addRadioButtons, addSelectButtons, addSlider, addTextArea, addTextArea, addTextArea, booleanValue, doubleValue, getBooleanValue, getCharArrayValue, getDoubleValue, getIntValue, getMaximumSize, getStringValue, getTextHeight, getTextWidth, intValue, notifyListeners, removeQueryListener, set, setAndNotify, setBackground, setBoolean, setColumns, setDisplay, setEnabled, setLine, setMessage, setSlider, setTextHeight, setTextWidth, setToolTip, stringValue
 
Methods inherited from class javax.swing.JPanel
getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getGraphics, getHeight, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMinimumSize, getNextFocusableComponent, getPreferredSize, getPropertyChangeListeners, getPropertyChangeListeners, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBorder, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFont, setForeground, 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, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, 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, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, 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, processMouseEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, 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
 

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.

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.

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.