- All Superinterfaces:
ItemSelectable
- All Known Implementing Classes:
DefaultButtonModel
,JToggleButton.ToggleButtonModel
public interface ButtonModel extends ItemSelectable
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 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.
- Since:
- 1.2
-
Method Summary
Modifier and Type Method Description void
addActionListener(ActionListener l)
Adds anActionListener
to the model.void
addChangeListener(ChangeListener l)
Adds aChangeListener
to the model.void
addItemListener(ItemListener l)
Adds anItemListener
to the model.String
getActionCommand()
Returns the action command string for the button.default ButtonGroup
getGroup()
Returns the group that the button belongs to.int
getMnemonic()
Gets the keyboard mnemonic for the button.boolean
isArmed()
Indicates partial commitment towards triggering the button.boolean
isEnabled()
Indicates if the button can be selected or triggered by an input device, such as a mouse pointer.boolean
isPressed()
Indicates if the button is pressed.boolean
isRollover()
Indicates that the mouse is over the button.boolean
isSelected()
Indicates if the button has been selected.void
removeActionListener(ActionListener l)
Removes anActionListener
from the model.void
removeChangeListener(ChangeListener l)
Removes aChangeListener
from the model.void
removeItemListener(ItemListener l)
Removes anItemListener
from the model.void
setActionCommand(String s)
Sets the action command string that gets sent as part of theActionEvent
when the button is triggered.void
setArmed(boolean b)
Marks the button as armed or unarmed.void
setEnabled(boolean b)
Enables or disables the button.void
setGroup(ButtonGroup group)
Identifies the group the 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 button.void
setPressed(boolean b)
Sets the button to pressed or unpressed.void
setRollover(boolean b)
Sets or clears the button's rollover statevoid
setSelected(boolean b)
Selects or deselects the button.Methods declared in interface java.awt.ItemSelectable
getSelectedObjects
-
Method Details
-
isArmed
boolean isArmed()Indicates partial commitment towards triggering the button.- Returns:
true
if the button is armed, and ready to be triggered- 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 by an input device, such as a mouse pointer.- Returns:
true
if the button is enabled
-
isPressed
boolean isPressed()Indicates if the button is pressed.- Returns:
true
if the button is 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.- Parameters:
b
- whether or not the button should be armed
-
setSelected
void setSelected(boolean b)Selects or deselects the button.- Parameters:
b
-true
selects the button,false
deselects the button
-
setEnabled
void setEnabled(boolean b)Enables or disables the button.- Parameters:
b
- whether or not the button should be enabled- 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- See Also:
isPressed()
-
setRollover
void setRollover(boolean b)Sets or clears the button's rollover state- Parameters:
b
- whether or not the button is in the rollover state- See Also:
isRollover()
-
setMnemonic
void setMnemonic(int key)Sets the keyboard mnemonic (shortcut key or accelerator key) for the button.- Parameters:
key
- an int specifying the accelerator key
-
getMnemonic
int getMnemonic()Gets the keyboard mnemonic for the button.- Returns:
- an int specifying the accelerator key
- See Also:
setMnemonic(int)
-
setActionCommand
Sets the action command string that gets sent as part of theActionEvent
when the button is triggered.- Parameters:
s
- theString
that identifies the generated event- See Also:
getActionCommand()
,ActionEvent.getActionCommand()
-
getActionCommand
String getActionCommand()Returns the action command string for the button.- Returns:
- the
String
that identifies the generated event - See Also:
setActionCommand(java.lang.String)
-
setGroup
Identifies the group the button belongs to -- needed for radio buttons, which are mutually exclusive within their group.- Parameters:
group
- theButtonGroup
the button belongs to
-
getGroup
Returns the group that the button belongs to. Normally used with radio buttons, which are mutually exclusive within their group.- Implementation Requirements:
- The default implementation of this method returns
null
. Subclasses should return the group set by setGroup(). - Returns:
- the
ButtonGroup
that the button belongs to - Since:
- 10
-
addActionListener
Adds anActionListener
to the model.- Parameters:
l
- the listener to add
-
removeActionListener
Removes anActionListener
from the model.- Parameters:
l
- the listener to remove
-
addItemListener
Adds anItemListener
to the model.- Specified by:
addItemListener
in interfaceItemSelectable
- Parameters:
l
- the listener to add- See Also:
ItemEvent
-
removeItemListener
Removes anItemListener
from the model.- Specified by:
removeItemListener
in interfaceItemSelectable
- Parameters:
l
- the listener to remove- See Also:
ItemEvent
-
addChangeListener
Adds aChangeListener
to the model.- Parameters:
l
- the listener to add
-
removeChangeListener
Removes aChangeListener
from the model.- Parameters:
l
- the listener to remove
-