org.havi.ui.HAdjustmentValue Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ocap Show documentation
The newest version!
package org.havi.ui;

/*
 * Copyright 2000-2003 by HAVi, Inc. Java is a trademark of Sun
 * Microsystems, Inc. All rights reserved.  
 */


/**
 * This interface is implemented by all HAVi UI components which have some form of adjustable numerical value (e.g. a range control). Event Behavior
 Subclasses of    {@link org.havi.ui.HComponent}    which implement HAdjustmentValue must respond to   {@link org.havi.ui.event.HFocusEvent}    and    {@link org.havi.ui.event.HAdjustmentEvent}    events.   Applications should assume that classes which implement HAdjustmentValue can generate events of the types HFocusEvent and HAdjustmentEvent in response to other types of input event. 
 An application may add one or more HAdjustmentListener listeners to the component. The    {@link org.havi.ui.event.HAdjustmentListener#valueChanged}   method of the HAdjustmentListener is invoked whenever the value of the HAdjustmentValue is modified. 
  HAVi adjustment events are discussed in detail in the    {@link org.havi.ui.HAdjustmentInputPreferred}    interface description. 
Interaction States
 The following interaction states are valid for this HAdjustmentValue component: 
     {@link org.havi.ui.HState#NORMAL_STATE    NORMAL_STATE}   
    {@link org.havi.ui.HState#FOCUSED_STATE    FOCUSED_STATE}   
    {@link org.havi.ui.HState#DISABLED_STATE    DISABLED_STATE}   
    {@link org.havi.ui.HState#DISABLED_FOCUSED_STATE    DISABLED_FOCUSED_STATE}   
 The state machine diagram below shows the valid state  transitions for an HAdjustmentValue component. 
 
 
 
Platform Classes
 The following HAVi platform classes implement or inherit the HAdjustmentValue interface. These classes shall all generate both HFocusEvent and HAdjustmentEvent events in addition to any other events specified in the respective class descriptions. 
     {@link org.havi.ui.HRangeValue}   
 * @see org.havi.ui.HNavigable
 * @see org.havi.ui.HOrientable
 * @see org.havi.ui.HAdjustmentInputPreferred    
 * @see org.havi.ui.event.HAdjustmentEvent
 * @see  org.havi.ui.event.HAdjustmentListener
 */

public interface HAdjustmentValue
    extends HNavigable, HAdjustmentInputPreferred
{
    /**
	 * Set the unit increment for this HAdjustmentValue.
	 * @param increment  the amount by which the value of the  HAdjustmentValue should change when an  {@link org.havi.ui.event.HAdjustmentEvent#ADJUST_LESS}  or  {@link org.havi.ui.event.HAdjustmentEvent#ADJUST_MORE}  event is  received. Values of increment less than one shall  be treated as a value of one.
	 * @uml.property  name="unitIncrement"
	 */
    public void setUnitIncrement(int increment);

    /**
	 * Get the unit increment for this HAdjustmentValue. 1 shall be returned if this method is called before its corresponding set method.
	 * @return  the increment value for this HAdjustmentValue.
	 * @uml.property  name="unitIncrement"
	 */
    public int getUnitIncrement();
	
    /**
	 * Set the block increment for this HAdjustmentValue.
	 * @param increment  the amount by which the value of the  HAdjustmentValue should change when an  {@link org.havi.ui.event.HAdjustmentEvent#ADJUST_PAGE_LESS}  or  {@link org.havi.ui.event.HAdjustmentEvent#ADJUST_PAGE_MORE}  event is received. Values of  increment less than one shall be treated as a  value of one.
	 * @uml.property  name="blockIncrement"
	 */
    public void setBlockIncrement(int increment);

    /**
	 * Get the block increment for this HAdjustmentValue. 1 shall be returned if this method is called before its corresponding set method.
	 * @return  the block increment value for this HAdjustmentValue.
	 * @uml.property  name="blockIncrement"
	 */
    public int getBlockIncrement();

    /**
     * Adds the specified HAdjustmentListener to
     * receive HAdjustmentEvents
     * sent from this object.  If the listener has
     * already been added further calls will add further references to
     * the listener, which will then receive multiple copies of a
     * single event.
     * 	
     * @param l the HAdjustmentListener to be notified.  
     */
    public void addAdjustmentListener(org.havi.ui.event.HAdjustmentListener l);

    /**
     * Removes the specified HAdjustmentListener so
     * that it no longer receives HAdjustmentEvents from
     * this object. If the specified listener is not registered, the
     * method has no effect. If multiple references to
     * a single listener have been registered it should be noted that
     * this method will only remove one reference per call.
     * 
     * @param l the HAdjustmentListener to be removed from notification.
     */
    public void removeAdjustmentListener(org.havi.ui.event.HAdjustmentListener l);
    
    /**
	 * Associate a sound to be played when the value is modified. The sound is played irrespective of whether an HAdjustmentEvent is sent to one or more listeners.
	 * @param sound  the sound to be played, when the value is  modified. If sound content is already set, the original content  is replaced. To remove the sound specify a null  {@link org.havi.ui.HSound}  .
	 * @uml.property  name="adjustmentSound"
	 */
    public void setAdjustmentSound(HSound sound);
        
    /**
     * Get the sound to be played when the value changes.
     * null shall be returned if this method is called
     * before its corresponding set method.
     * 
     * @return The sound played when the value changes 
     */
    public HSound getAdjustmentSound();

}