Brought to you by EarthWeb
ITKnowledge Logo Login Graphic Click Here!
Click Here!
ITKnowledge
Search this book:
 
Search the site:
 
EXPERT SEARCH ----- nav

EarthWeb Direct

EarthWeb Direct

EarthWeb sites: other sites

Previous Table of Contents Next


KeySelection Managers

The JComboBox class defines an inner interface that manages selection in the combo box with keystrokes. The KeySelectionManager interface shown in Listing 10.15 defines a single method, selectionForKey. This method returns the index of the element selected by the given character in the given ComboBoxModel. It returns –1 if the character does not select an element.

The JComboBox class contains the selectWithKeyChar method that calls the key selection manager with the given character and selects the element at the index returned from the key selection manager. The selectWithKeyChar method returns true if an element was selected, false otherwise. A ComboBoxEditor could use this capability to streamline editing in a combo box by allowing the user to select an element in the model by typing its first character. The KeySelectionManager for a combo box can be set with the setKeySelectionManager method and queried with the getKeySelectionManager method. The keySelectionManager is not a bound property.

Listing 10.15 The KeySelectionManager Interface

public interface KeySelectionManager {
    /** Given <code>aKey</code> and the model, returns the row
     *  that should become selected. Return -1 if no match was
     *  found.
     *
     * @param  aKey  a char value, usually indicating a keyboard key that
     *               was pressed
     * @param aModel a ComboBoxModel — the component’s data model,
     *               containing the list of selectable items
     * @return an int equal to the selected row, where 0 is the
     *         first item and -1 is none.
     */
    int selectionForKey(char aKey,ComboBoxModel aModel);
}

Bounded Components

The JFC contains a few components that display information that falls within a numerical range. These components use the BoundedRangeModel to manage the range and the current value. Examples of range components in the JFC are scrollbars, sliders, and progress bars. These components and the BoundedRangeModel are discussed in this section.

The BoundedRangeModel Interface

The BoundedRangeModel interface specifies the methods required for the JFC bounded range model. This type of model specifies a constrained integer range with a minimum, maximum, and current value. A listener to the model is defined as a ChangeListener. The ChangeListener is notified when any of the properties of the model change. The BoundedRangeModel contains the valueIsAdjusting flag, which allows listeners of the model to optimize their behavior. This flag is set to true when many changes are going to occur quickly in the model, and set to false when the changes are complete. A typical example of this behavior is when the user drags a scrollbar.

The BoundedRangeModel defines the extent property. For a view such as a scrollbar, the extent represents the portion of the model that is currently viewed. The extent must be non-negative and the current value in the model, and it cannot be greater that the model’s maximum value.

The setRangeProperties method is defined to allow all the properties defined by the BoundedRangeModel to be set with a single method call.

Classes that implement the BoundedRangeModel interface should guarantee the following relationship between the model properties:

minimum <= value <= value + extent <= maximum

Listing 10.16 The BoundedRangeModel Interface

public interface BoundedRangeModel
{
    /**
     * Returns the minimum acceptable value.
     *
     * @return the value of the minimum property
     * @see #setMinimum
     */
    int getMinimum();

  /**
     * Sets the model’s minimum to <I>newMinimum</I>.   The
     * other three properties may be changed as well, to ensure
     * that:
     * <pre>
     * minimum <= value <= value+extent <= maximum
     * </pre>
     * <p>
     * Notifies any listeners if the model changes.
     *
     * @param newMinimum the model’s new minimum
     * @see #getMinimum
     * @see #addChangeListener
     */
    void setMinimum(int newMinimum);

    /**
     * Returns the model’s maximum.  Note that the upper
     * limit on the model’s value is (maximum - extent).
     *
     * @return the value of the maximum property.
     * @see #setMaximum
     * @see #setExtent
     */
    int getMaximum();

    /**
     * Sets the model’s maximum to <I>newMaximum</I>. The other
     * three properties may be changed as well, to ensure that
     * <pre>
     * minimum <= value <= value+extent <= maximum
     * </pre>
     * <p>
     * Notifies any listeners if the model changes.
     *
     * @param newMaximum the model’s new maximum
     * @see #getMaximum
     * @see #addChangeListener
     */
    void setMaximum(int newMaximum);

    /**
     * Returns the model’s current value.  Note that the upper
     * limit on the model’s value is <code>maximum - extent</code>
     * and the lower limit is <code>minimum</code>.
     *
     * @return  the model’s value
     * @see     #setValue
     */
    int getValue();

    /**
     * Sets the model’s current value to <code>newValue</code>
     * if <code>newValue</code> satisfies the model’s contraints.
     * Those constraints are:
     * <pre>
     * minimum <= value <= value+extent <= maximum
     * </pre>
     * Otherwise, if <code>newValue</code> is less than
     * <code>minimum</code> it’s set to <code>minimum</code>,
     * if it’s greater than <code>maximum</code>
     * then it’s set to <code>maximum</code>, and
     * if it’s greater than <code>value+extent</code> then it’s set to
     * <code>value+extent</code>.
     * <p>
     * When a BoundedRange model is used with a scrollbar the value
     * specifies the origin of the scrollbar knob (aka the “thumb” or
     * “elevator”).  The value usually represents the origin of the
     * visible part of the object being scrolled.
     * <p>
     * Notifies any listeners if the model changes.
     *
     * @param newValue the model’s new value
     * @see #getValue
     */
    void setValue(int newValue);

    /**
     * This attribute indicates that any upcoming changes to the value
     * of the model should be considered a single event. This attribute
     * will be set to true at the start of a series of changes to the
     * value, and will be set to false when the value has finished
     * changing.  Normally this allows a listener to only take action
     * when the final value change is committed, instead of having to do
     * updates for all intermediate values.
     * <p>
     * Sliders and scrollbars use this property when a drag is under way.
     *
     * @param b true if the upcoming changes to the value property are
     *          part of a series
     * @see #getValueIsAdjusting
     */
    void setValueIsAdjusting(boolean b);

    /**
     * Returns true if the current changes to the value property are part
     * of a series.
     *
     * @return the valueIsAdjustingProperty.
     * @see #setValueIsAdjusting
     */
    boolean getValueIsAdjusting();

    /**
     * Returns the model’s extent, the length of the inner range that
     * begins at the model’s value.
     *
     * @return  the value of the model’s extent property
     * @see     #setExtent
     * @see     #setValue
     */
    int getExtent();

    /**
     * Sets the model’s extent.  The <I>newExtent</I> is forced to
     * be greater than or equal to zero and less than or equal to
     * maximum - value.
     * <p>
     * When a BoundedRange model is used with a scrollbar the extent
     * defines the length of the scrollbar knob (aka the “thumb” or
     * “elevator”).  The extent usually represents how much of the
     * object being scrolled is visible.
     * <p>
     * Notifies any listeners if the model changes.
     *
     * @param  newExtent the model’s new extent
     * @see #getExtent
     * @see #setValue
     */
    void setExtent(int newExtent);

    /**
     * This method sets all of the model’s data with a single method
     * call. The method results in a single change event being generated.
     * This is convenient when you need to adjust all the model data
     * simultaneously and do not want individual change events to occur.
     *
     * @see #setValue
     * @see #setExtent
     * @see #setMinimum
     * @see #setMaximum
     * @see #setValueIsAdjusting
     */
    void setRangeProperties( int value, int extent, int min,
                             int max, boolean adjusting );
    /**
     * Adds a ChangeListener to the model’s listener list.
     *
     * @param x the ChangeListener to add
     * @see #removeChangeListener
     */
    void addChangeListener(ChangeListener x);
    /**
     * Removes a ChangeListener from the model’s listener list.
     *
     * @param x the ChangeListener to remove
     * @see #addChangeListener
     */
    void removeChangeListener(ChangeListener x);
}


Previous Table of Contents Next
HomeAbout UsSearchSubscribeAdvertising InfoContact UsFAQs
Use of this site is subject to certain Terms & Conditions.
Copyright (c) 1996-1999 EarthWeb Inc. All rights reserved. Reproduction in whole or in part in any form or medium without express written permission of EarthWeb is prohibited. Read EarthWeb's privacy statement.