org.havi.ui

Class HToggleGroup

java.lang.Object

org.havi.ui.HToggleGroup

public class HToggleGroup
extends Object

HToggleButtons within the same HToggleGroup will behave so that a maximum of one HToggleButton has switchable state true, as returned by getSwitchableState, so as to achieve a "radio button" effect. When an HToggleButton is acted upon to change its switchable state to true, then if any other HToggleButton within the HToggleGroup currently has switchable state true, it will have its switchable state set to false. Similarly, if an HToggleButton is added which has switchable state true, then any current HToggleButton within the HToggleGroup with switchable state true, shall have its switchable state modified to false.

If the forced selection mode for the HToggleGroup is set via a call to setForcedSelection(true) then there will always be one HToggleButton selected (i.e. with switchable state true), and if necessary the HToggleGroup will automatically force a selection to ensure this. If forced selection mode is not set it is valid for there to be no selection, i.e. all HToggleButtons may have switchable state false. By default forced selection mode is not set.

Note that when an HToggleButton has switchable state true this implies that the interaction state as returned by getInteractionState will be either the ACTIONED_STATE or ACTIONED_FOCUSED_STATE state.

Similarly, a switchable state of false implies that the interaction state is any other state for which the ACTIONED_STATE_BIT is not set. See the HSwitchable class description for more information about the valid interaction states.

The parameters to the constructors are as follows, in cases where parameters are not used, then the constructor should use the default values.

Default parameter values exposed in the constructors

Parameter	Description	Default value	Set method	Get method
None.

Default parameter values not exposed in the constructors

Description	Default value	Set method	Get method
Enable or disable buttons in group	enable	setEnabled	isEnabled
Forced selection mode.	false	setForcedSelection	getForcedSelection

Constructor Summary

Constructors

Constructor and Description
HToggleGroup() Creates a new version instance of an HToggleGroup

Method Summary

Methods

Modifier and Type	Method and Description
protected void	add(HToggleButton button) Add the specified HToggleButton to this HToggleGroup.
HToggleButton	getCurrent() Returns the HToggleButton from this HToggleGroup which has state true, or null otherwise, for example, if there are no HToggleButtons associated with this HToggleGroup, or if all HToggleButtons within this HToggleGroup have state false.
boolean	getForcedSelection() Return the current forced selection mode of the group.
boolean	isEnabled() Determines whether the HToggleGroup is enabled.
protected void	remove(HToggleButton button) Remove the specified HToggleButton to this HToggleGroup.
void	setCurrent(HToggleButton selection) If the specified HToggleButton is a member of this HToggleGroup, then it is selected, its state is set to true and consequently any other HToggleButtons within the HToggleGroup will have their states set to false.
void	setEnabled(boolean enable) Enables or disables the group, depending on the value of the parameter enable.
void	setForcedSelection(boolean forceSelection) Set the forced selection mode of the group.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HToggleGroup

public HToggleGroup()

Creates a new version instance of an HToggleGroup

Method Detail

getCurrent

public HToggleButton getCurrent()

Returns the HToggleButton from this HToggleGroup which has state true, or null otherwise, for example, if there are no HToggleButtons associated with this HToggleGroup, or if all HToggleButtons within this HToggleGroup have state false.

Returns:

the currently selected HToggleButton or null if no such HToggleButton exists.

setCurrent

public void setCurrent(HToggleButton selection)

If the specified HToggleButton is a member of this HToggleGroup, then it is selected, its state is set to true and consequently any other HToggleButtons within the HToggleGroup will have their states set to false.

If the specified HToggleButton is not a member of this HToggleGroup, then no actions are performed.

Parameters:

selection - the HToggleButton to be set as the currently selected item within the HToggleGroup.

setForcedSelection

public void setForcedSelection(boolean forceSelection)

Set the forced selection mode of the group. If forceSelection is true and no HToggleButton is currently selected in the group the first HToggleButton automatically has its switchable state set to true. If no HToggleButton components have been added to this group there will be no visual indication of the mode change.

Parameters:

forceSelection - if this parameter is true the group is forced to always have one HToggleButton selected (i.e. with switchable state true). Otherwise, the group may have either one or zero HToggleButton(s) selected.

getForcedSelection

public boolean getForcedSelection()

Return the current forced selection mode of the group.

Returns:

the current forced selection mode. If this value is true the group is forced to always have one HToggleButton selected (i.e. with switchable state true). Otherwise, the group may have either one or zero HToggleButton(s) selected.

setEnabled

public void setEnabled(boolean enable)

Enables or disables the group, depending on the value of the parameter enable. An enabled group's HToggleButtons can respond to user input and generate events. An HToggleGroup is initially enabled by default.

Enabling or disabling an HToggleGroup enables or disables all the HToggleButton components in the group by calling their setEnabled methods.

Whether or not a group is enabled does not affect the adding or removing of HToggleButtons from that group.

Parameters:

enable - true to enable all the HToggleButton components in the group, false to disable them.

See Also:

isEnabled()

isEnabled

public boolean isEnabled()

Determines whether the HToggleGroup is enabled. HToggleGroups are enabled initially by default. A group may be enabled or disabled by calling its setEnabled method.

Returns:

true if the component is enabled; false otherwise.

See Also:

setEnabled(boolean)

add

protected void add(HToggleButton button)

Add the specified HToggleButton to this HToggleGroup. The HToggleButton will be enabled or disabled as necessary to match the current state of the HToggleGroup as determined by the isEnabled method.

If the HToggleGroup is empty and forced selection mode is active then the HToggleButton will automatically have its switchable state set to true. Note that any ActionListeners registered with the HToggleButton are not called as a result of this operation.

This method is protected to allow the platform to override it in subclasses of HToggleGroup. It is not intended for use by the application and conformant applications shall not use this method.

Parameters:

button - the HToggleButton to add to the HToggleGroup.

remove

protected void remove(HToggleButton button)

Remove the specified HToggleButton to this HToggleGroup. If button is not part of this HToggleGroup this method throws a java.lang.IllegalArgumentException.

If the HToggleButton is the currently selected button in this group and forced selection mode is set the first remaining HToggleButton will automatically have its switchable state set to true. Note that any ActionListeners registered with the HToggleButton are not called as a result of this operation.

This method is protected to allow the platform to override it in subclasses of HToggleGroup. It is not intended for use by the application and conformant applications shall not use this method.

Parameters:

button - the HToggleButton to remove from the HToggleGroup.

Throws:

IllegalArgumentException - if button is not a member of this HToggleGroup.