Package ptolemy.actor.gui

Class 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 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 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 Description
      protected java.util.Map _attributes
      Maps an entry name to the attribute that is attached to it.

      • 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 Description
      PtolemyQuery​(NamedObj handler)
      Construct a panel with no queries in it and with the specified change handler.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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 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, 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, requestFocus, requestFocus, requestFocusInWindow, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMixingCutoutShape, 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.