org.havi.ui
Interface HActionable

All Superinterfaces:
HActionInputPreferred, HNavigable, HNavigationInputPreferred
All Known Subinterfaces:
HSwitchable
All Known Implementing Classes:
HGraphicButton, HTextButton, HToggleButton

public interface HActionable
extends HNavigable, HActionInputPreferred

This interface is implemented by all HAVi UI components that can be actioned by the user.

Event Behaviour

Subclasses of HComponent which implement HActionable must respond to HFocusEvent and 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 HActionEvent class description.

Interaction States

The following interaction states are valid for this HActionable component:

The state machine diagram below shows the valid state transitions for an HActionable component.

Unlike HSwitchable components, the transition back from an actioned state (i.e. one with the 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 ACTIONED_STATE and 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.

See Also:
HNavigable, HActionInputPreferred, HActionEvent, HActionListener

Method Summary
 void addHActionListener(HActionListener l)
          Adds the specified HActionListener to receive HActionEvent events sent from this HActionable.
 HSound getActionSound()
          Return the last action sound set by the setActionSound() method or null if no action sound has been set.
 void removeHActionListener(HActionListener l)
          Removes the specified HActionListener so that it no longer receives HActionEvent events from this HActionable.
 void setActionCommand(java.lang.String command)
          Sets the command name for the HActionEvent event fired by this HActionable.
 void setActionSound(HSound sound)
          Associate a sound to be played when the interaction state of the HActionable makes the following transitions: NORMAL_STATE to ACTIONED_STATE FOCUSED_STATE to ACTIONED_FOCUSED_STATE
 
Methods inherited from interface org.havi.ui.HNavigable
addHFocusListener, getGainFocusSound, getLoseFocusSound, getMove, isSelected, removeHFocusListener, setFocusTraversal, setGainFocusSound, setLoseFocusSound, setMove
 
Methods inherited from interface org.havi.ui.HNavigationInputPreferred
getNavigationKeys, processHFocusEvent
 
Methods inherited from interface org.havi.ui.HActionInputPreferred
getActionCommand, processHActionEvent
 

Method Detail

addHActionListener

public void addHActionListener(HActionListener l)
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.

Parameters:
l - the HActionListener.

removeHActionListener

public void removeHActionListener(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.

Parameters:
l - the HActionListener.

setActionCommand

public void setActionCommand(java.lang.String command)
Sets the command name for the HActionEvent event fired by this HActionable.

Parameters:
command - a String used to set the action command. To remove the command specify a null command parameter.
See Also:
HActionEvent.getActionCommand()

setActionSound

public void setActionSound(HSound sound)
Associate a sound to be played when the interaction state of the HActionable makes the following transitions:

Parameters:
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.

getActionSound

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