javax.swing
Interface ButtonModel

All Superinterfaces:

ItemSelectable

All Known Implementing Classes:

DefaultButtonModel , JToggleButton.ToggleButtonModel

public interface ButtonModel
extends ItemSelectable

State model for buttons. State Model for buttons. This model is used for check boxes and radio buttons, which are special kinds of buttons, as well as for normal buttons. For check boxes and radio buttons, pressing the mouse selects the button. For normal buttons, pressing the mouse "arms" the button. Releasing the mouse over the button then initiates a button press, firing its action event. Releasing the mouse elsewhere disarms the button.

This model is used for regular buttons, as well as check boxes and radio buttons, which are special kinds of buttons. In practice, a button's UI takes the responsibility of calling methods on its model to manage the state, as detailed below: In use, a UI will invoke setSelected(boolean) when a mouse click occurs over a check box or radio button. It will invoke setArmed(boolean) when the mouse is pressed over a regular button and invoke setPressed(boolean) when the mouse is released. If the mouse travels outside the button in the meantime, setArmed(false) will tell the button not to fire when it sees setPressed. (If the mouse travels back in, the button will be rearmed.)

Note:
A button is triggered when it is both "armed" and "pressed".

In simple terms, pressing and releasing the mouse over a regular button triggers the button and causes and ActionEvent to be fired. The same behavior can be produced via a keyboard key defined by the look and feel of the button (typically the SPACE BAR). Pressing and releasing this key while the button has focus will give the same results. For check boxes and radio buttons, the mouse or keyboard equivalent sequence just described causes the button to become selected.

In details, the state model for buttons works as follows when used with the mouse:
Pressing the mouse on top of a button makes the model both armed and pressed. As long as the mouse remains down, the model remains pressed, even if the mouse moves outside the button. On the contrary, the model is only armed while the mouse remains pressed within the bounds of the button (it can move in or out of the button, but the model is only armed during the portion of time spent within the button). A button is triggered, and an ActionEvent is fired, when the mouse is released while the model is armed - meaning when it is released over top of the button after the mouse has previously been pressed on that button (and not already released). Upon mouse release, the model becomes unarmed and unpressed.

In details, the state model for buttons works as follows when used with the keyboard:
Pressing the look and feel defined keyboard key while the button has focus makes the model both armed and pressed. As long as this key remains down, the model remains in this state. Releasing the key sets the model to unarmed and unpressed, triggers the button, and causes an ActionEvent to be fired.

Method Summary
void	addActionListener ( ActionListener           Adds an ActionListener to the model. button.
void	addChangeListener ( ChangeListener           Adds a ChangeListener to the model. button.
void	addItemListener ( ItemListener           Adds an ItemListener to the model. button.
String	getActionCommand ()           Returns the action command string for the this button.
int	getMnemonic ()           Gets the keyboard mnemonic for the button. this model
boolean	isArmed ()           Indicates partial commitment towards triggering pressing the button.
boolean	isEnabled ()           Indicates if the button can be selected or triggered pressed by an input device, such device (such as a mouse pointer. pointer).
boolean	isPressed ()           Indicates if the button is has been pressed.
boolean	isRollover ()           Indicates that the mouse is over the button.
boolean	isSelected ()           Indicates if the button has been selected.
void	removeActionListener ( ActionListener           Removes an ActionListener from the model. button.
void	removeChangeListener ( ChangeListener           Removes a ChangeListener from the model. button.
void	removeItemListener ( ItemListener           Removes an ItemListener from the model. button.
void	setActionCommand ( String           Sets the action command actionCommand string that gets sent as part of the ActionEvent event when the button is triggered. pressed.
void	setArmed (boolean b)           Marks the button as armed or unarmed. "armed".
void	setEnabled (boolean b)           Enables or disables the button.
void	setGroup ( ButtonGroup           Identifies the group the this button belongs to -- needed for radio buttons, which are mutually exclusive within their group.
void	setMnemonic (int key)           Sets the keyboard mnemonic (shortcut key or accelerator key) for the this button.
void	setPressed (boolean b)           Sets the button to pressed or unpressed.
void	setRollover (boolean b)           Sets or clears the button's rollover state
void	setSelected (boolean b)           Selects or deselects the button.

 

Methods inherited from interface java.awt. ItemSelectable
getSelectedObjects

 

Method Detail

isArmed

boolean isArmed()

Indicates partial commitment towards triggering pressing the button.

Returns:

true if the button is armed, and ready to be triggered pressed

See Also:

setArmed(boolean)

isSelected

boolean isSelected()

Indicates if the button has been selected. Only needed for certain types of buttons - such as radio buttons and check boxes.

Returns:

true if the button is selected

isEnabled

boolean isEnabled()

Indicates if the button can be selected or triggered pressed by an input device, such device (such as a mouse pointer. pointer). (Check boxes are selected, regular buttons are "pressed".)

Returns:

true if the button is enabled enabled, and therefore selectable (or pressable)

isPressed

boolean isPressed()

Indicates if the button is has been pressed.

Returns:

true if the button is has been pressed

isRollover

boolean isRollover()

Indicates that the mouse is over the button.

Returns:

true if the mouse is over the button

setArmed

void setArmed(boolean b)

Marks the button as armed or unarmed. Marks the button as "armed". If the mouse button is released while it is over this item, the button's action event fires. If the mouse button is released elsewhere, the event does not fire and the button is disarmed.

Parameters:

b - whether or not the button should be armed b - true to arm the button so it can be selected

setSelected

void setSelected(boolean b)

Selects or deselects the button.

Parameters:

b - true selects the button, false deselects the button button.

setEnabled

void setEnabled(boolean b)

Enables or disables the button.

Parameters:

b - whether or not the button should be enabled b - true to enable the button

See Also:

isEnabled()

setPressed

void setPressed(boolean b)

Sets the button to pressed or unpressed.

Parameters:

b - whether or not the button should be pressed b - true to set the button to "pressed"

See Also:

isPressed()

setRollover

void setRollover(boolean b)

Sets or clears the button's rollover state

Parameters:

whether - or not the button is in the rollover state b - true to turn on rollover

See Also:

isRollover()

setMnemonic

void setMnemonic(int key)

Sets the keyboard mnemonic (shortcut key or accelerator key) for the this button.

Parameters:

key - an int specifying the accelerator key

getMnemonic

int getMnemonic()

Gets the keyboard mnemonic for the button. this model

Returns:

an int specifying the accelerator key

See Also:

setMnemonic(int)

setActionCommand

void setActionCommand(String s)

Sets the action command actionCommand string that gets sent as part of the ActionEvent event when the button is triggered. pressed.

Parameters:

s - the String that identifies the generated event

See Also:

getActionCommand() , ActionEvent.getActionCommand()

getActionCommand

String getActionCommand()

Returns the action command string for the this button.

Returns:

the String that identifies the generated event

See Also:

setActionCommand(java.lang.String)

setGroup

void setGroup(ButtonGroup group)

Identifies the group the this button belongs to -- needed for radio buttons, which are mutually exclusive within their group.

Parameters:

group - the ButtonGroup the this button belongs to

addActionListener

void addActionListener(ActionListener l)

Adds an ActionListener to the model. button.

Parameters:

l - the listener to add

removeActionListener

void removeActionListener(ActionListener l)

Removes an ActionListener from the model. button.

Parameters:

l - the listener to remove

addItemListener

void addItemListener(ItemListener l)

Adds an ItemListener to the model. button.

Specified by:

addItemListener in interface ItemSelectable

Parameters:

l - the listener to add

See Also:

ItemEvent

removeItemListener

void removeItemListener(ItemListener l)

Removes an ItemListener from the model. button.

Specified by:

removeItemListener in interface ItemSelectable

Parameters:

l - the listener to remove

See Also:

ItemEvent

addChangeListener

void addChangeListener(ChangeListener l)

Adds a ChangeListener to the model. button.

Parameters:

l - the listener to add

removeChangeListener

void removeChangeListener(ChangeListener l)

Removes a ChangeListener from the model. button.

Parameters:

l - the listener to remove