HActionable

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `HActionInputPreferred` interface 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
`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.
  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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD