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:

• NORMAL_STATE
• FOCUSED_STATE
• ACTIONED_STATE
• ACTIONED_FOCUSED_STATE
• DISABLED_STATE
• DISABLED_FOCUSED_STATE

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.

• HGraphicButton
• HTextButton
• HToggleButton

See Also:

HNavigable, HActionInputPreferred, HActionEvent, HActionListener

Method Summary

Methods

Modifier and Type	Method and Description
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(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:

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

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

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

void setActionCommand(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

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

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

HSound getActionSound()

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