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

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ocap-api Show documentation
There is a newer version: 1.3.1
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 that can be actioned by the user. Event Behaviour
 Subclasses of    {@link org.havi.ui.HComponent    HComponent}    which implement HActionable must respond to   {@link org.havi.ui.event.HFocusEvent    HFocusEvent}    and    {@link org.havi.ui.event.HActionEvent}    events.   Applications should assume that classes which implement HActionable can generate events of the types HFocusEvent and HActionEvent in response to other types of input event. 
 An application may add one or more HActionListener listeners to the component. The actionPerformed method of the HActionListener is invoked whenever the HActionable is actioned. 
  HAVi action events are discussed in detail in the    {@link org.havi.ui.HActionInputPreferred    HActionInputPreferred}   interface description. 
Interaction States
 The following interaction states are valid for this HActionable component: 
     {@link org.havi.ui.HState#NORMAL_STATE    NORMAL_STATE}   
    {@link org.havi.ui.HState#FOCUSED_STATE    FOCUSED_STATE}   
    {@link org.havi.ui.HState#ACTIONED_STATE    ACTIONED_STATE}   	 
    {@link org.havi.ui.HState#ACTIONED_FOCUSED_STATE    ACTIONED_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 HActionable component. 
 
 
 Unlike    {@link org.havi.ui.HSwitchable    HSwitchable}    components, the transition back from an actioned state (i.e. one with the    {@link org.havi.ui.HState#ACTIONED_STATE_BIT}    bit set) is automatically fired once all registered  HActionListener listeners have been called. 
 A direct consequence of this is that HActionable components can only achieve the    {@link org.havi.ui.HState#ACTIONED_STATE    ACTIONED_STATE}    and   {@link org.havi.ui.HState#ACTIONED_FOCUSED_STATE    ACTIONED_FOCUSED_STATE}    states on a temporary basis.  
 HActionable components may not be disabled while actioned.  
Platform Classes
 The following HAVi platform classes implement or inherit the HActionable interface. These classes shall all generate both HFocusEvent and HActionEvent events in addition to any other events specified in the respective class descriptions. 
     {@link org.havi.ui.HGraphicButton}   
    {@link org.havi.ui.HTextButton}   
    {@link org.havi.ui.HToggleButton}    
 * @see org.havi.ui.HNavigable
 * @see org.havi.ui.HActionInputPreferred    
 * @see org.havi.ui.event.HActionEvent
 * @see  org.havi.ui.event.HActionListener
 */

public interface HActionable 
    extends HNavigable, HActionInputPreferred
{
    /**
     * Adds the specified
     * HActionListener to receive HActionEvent
     *  events sent from this HActionable. 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 HActionListener. 
     */
    public void addHActionListener(org.havi.ui.event.HActionListener l);

    /**
     * Removes the specified
     * HActionListener so that it no longer receives
     * HActionEvent events from this
     * HActionable. 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 HActionListener. 
     */
    public void removeHActionListener(org.havi.ui.event.HActionListener l);

    /**
     * Sets the command name for the
     * HActionEvent event fired by this HActionable.
     *
     * @param command a String used to set the action
     * command.
     * @see org.havi.ui.event.HActionEvent#getActionCommand 
     */
    public void setActionCommand(String command);

    /**
	 * Associate a sound to be played when the interaction state of the HActionable makes the following transitions: 
   {@link org.havi.ui.HState#NORMAL_STATE  NORMAL_STATE}  to  {@link org.havi.ui.HState#ACTIONED_STATE  ACTIONED_STATE} 
  {@link org.havi.ui.HState#FOCUSED_STATE  FOCUSED_STATE}  to  {@link org.havi.ui.HState#ACTIONED_FOCUSED_STATE  ACTIONED_FOCUSED_STATE} 
	 * @param sound  the sound to be played, when the component is  actioned. If sound content is already set, the original content  is replaced. To remove the sound specify a null  HSound.
	 * @uml.property  name="actionSound"
	 */
    public void setActionSound(HSound sound);

    /**
     * Return the last action sound set by the
     * setActionSound()  method
     * or null if no action sound has been set.
     */
    public HSound getActionSound();

 
}