A base class for buttons. More...
Inherits Component, SettableTooltipClient, ApplicationCommandManagerListener, Value::Listener, and KeyListener.
Inherited by ArrowButton, DrawableButton, HyperlinkButton, ImageButton, ShapeButton, TabBarButton, TextButton, ToggleButton, and ToolbarItemComponent.
Public Types | |
| enum | ConnectedEdgeFlags { ConnectedOnLeft = 1, ConnectedOnRight = 2, ConnectedOnTop = 4, ConnectedOnBottom = 8 } |
A combination of these flags are used by setConnectedEdges(). More... | |
| enum | ButtonState { buttonNormal, buttonOver, buttonDown } |
Used by setState(). More... | |
Public Member Functions | |
| virtual | ~Button () |
| Destructor. | |
| void | setButtonText (const String &newText) |
| Changes the button's text. | |
| const String | getButtonText () const |
| Returns the text displayed in the button. | |
| bool | isDown () const throw () |
| Returns true if the button is currently being held down by the mouse. | |
| bool | isOver () const throw () |
| Returns true if the mouse is currently over the button. | |
| void | setToggleState (bool shouldBeOn, bool sendChangeNotification) |
| A button has an on/off state associated with it, and this changes that. | |
| bool | getToggleState () const throw () |
| Returns true if the button in 'on'. | |
| Value & | getToggleStateValue () |
| Returns the Value object that represents the botton's toggle state. | |
| void | setClickingTogglesState (bool shouldToggle) throw () |
| This tells the button to automatically flip the toggle state when the button is clicked. | |
| bool | getClickingTogglesState () const throw () |
| Returns true if this button is set to be an automatic toggle-button. | |
| void | setRadioGroupId (int newGroupId) |
| Enables the button to act as a member of a mutually-exclusive group of 'radio buttons'. | |
| int | getRadioGroupId () const throw () |
| Returns the ID of the group to which this button belongs. | |
| void | addButtonListener (ButtonListener *newListener) |
| Registers a listener to receive events when this button's state changes. | |
| void | removeButtonListener (ButtonListener *listener) |
| Removes a previously-registered button listener. | |
| virtual void | triggerClick () |
| Causes the button to act as if it's been clicked. | |
| void | setCommandToTrigger (ApplicationCommandManager *commandManagerToUse, int commandID, bool generateTooltip) |
| Sets a command ID for this button to automatically invoke when it's clicked. | |
| int | getCommandID () const throw () |
| Returns the command ID that was set by setCommandToTrigger(). | |
| void | addShortcut (const KeyPress &key) |
| Assigns a shortcut key to trigger the button. | |
| void | clearShortcuts () |
| Removes all key shortcuts that had been set for this button. | |
| bool | isRegisteredForShortcut (const KeyPress &key) const |
| Returns true if the given keypress is a shortcut for this button. | |
| void | setRepeatSpeed (int initialDelayInMillisecs, int repeatDelayInMillisecs, int minimumDelayInMillisecs=-1) throw () |
| Sets an auto-repeat speed for the button when it is held down. | |
| void | setTriggeredOnMouseDown (bool isTriggeredOnMouseDown) throw () |
| Sets whether the button click should happen when the mouse is pressed or released. | |
| uint32 | getMillisecondsSinceButtonDown () const throw () |
| Returns the number of milliseconds since the last time the button went into the 'down' state. | |
| void | setVisible (bool shouldBeVisible) |
| (overridden from Component to do special stuff). | |
| void | setTooltip (const String &newTooltip) |
| Sets the tooltip for this button. | |
| const String | getTooltip () |
| Returns the string that this object wants to show as its tooltip. | |
| void | setConnectedEdges (int connectedEdgeFlags) |
| Hints about which edges of the button might be connected to adjoining buttons. | |
| int | getConnectedEdgeFlags () const throw () |
| Returns the set of flags passed into setConnectedEdges(). | |
| bool | isConnectedOnLeft () const throw () |
| Indicates whether the button adjoins another one on its left edge. | |
| bool | isConnectedOnRight () const throw () |
| Indicates whether the button adjoins another one on its right edge. | |
| bool | isConnectedOnTop () const throw () |
| Indicates whether the button adjoins another one on its top edge. | |
| bool | isConnectedOnBottom () const throw () |
| Indicates whether the button adjoins another one on its bottom edge. | |
| void | setState (const ButtonState newState) |
| Can be used to force the button into a particular state. | |
Protected Member Functions | |
| Button (const String &buttonName) | |
| Creates a button. | |
| virtual void | clicked () |
| This method is called when the button has been clicked. | |
| virtual void | clicked (const ModifierKeys &modifiers) |
| This method is called when the button has been clicked. | |
| virtual void | paintButton (Graphics &g, bool isMouseOverButton, bool isButtonDown)=0 |
| Subclasses should override this to actually paint the button's contents. | |
| virtual void | buttonStateChanged () |
| Called when the button's up/down/over state changes. | |
| virtual void | internalClickCallback (const ModifierKeys &modifiers) |
| void | handleCommandMessage (int commandId) |
| void | mouseEnter (const MouseEvent &e) |
| void | mouseExit (const MouseEvent &e) |
| void | mouseDown (const MouseEvent &e) |
| void | mouseDrag (const MouseEvent &e) |
| void | mouseUp (const MouseEvent &e) |
| bool | keyPressed (const KeyPress &key) |
| bool | keyPressed (const KeyPress &key, Component *originatingComponent) |
| bool | keyStateChanged (bool isKeyDown, Component *originatingComponent) |
| void | paint (Graphics &g) |
| void | parentHierarchyChanged () |
| void | focusGained (FocusChangeType cause) |
| void | focusLost (FocusChangeType cause) |
| void | enablementChanged () |
| void | applicationCommandInvoked (const ApplicationCommandTarget::InvocationInfo &) |
| void | applicationCommandListChanged () |
| void | valueChanged (Value &value) |
A base class for buttons.
This contains all the logic for button behaviours such as enabling/disabling, responding to shortcut keystrokes, auto-repeating when held down, toggle-buttons and radio groups, etc.
A combination of these flags are used by setConnectedEdges().
| enum Button::ButtonState |
Used by setState().
| Button::Button | ( | const String & | buttonName | ) | [explicit, protected] |
Creates a button.
| buttonName | the text to put in the button (the component's name is also initially set to this string, but these can be changed later using the setName() and setButtonText() methods) |
| virtual Button::~Button | ( | ) | [virtual] |
Destructor.
| void Button::setButtonText | ( | const String & | newText | ) |
Changes the button's text.
| const String Button::getButtonText | ( | ) | const |
Returns the text displayed in the button.
| bool Button::isDown | ( | ) | const throw () |
Returns true if the button is currently being held down by the mouse.
| bool Button::isOver | ( | ) | const throw () |
Returns true if the mouse is currently over the button.
This will be also be true if the mouse is being held down.
| void Button::setToggleState | ( | bool | shouldBeOn, | |
| bool | sendChangeNotification | |||
| ) |
A button has an on/off state associated with it, and this changes that.
By default buttons are 'off' and for simple buttons that you click to perform an action you won't change this. Toggle buttons, however will want to change their state when turned on or off.
| shouldBeOn | whether to set the button's toggle state to be on or off. If it's a member of a button group, this will always try to turn it on, and to turn off any other buttons in the group | |
| sendChangeNotification | if true, a callback will be made to clicked(); if false the button will be repainted but no notification will be sent |
| bool Button::getToggleState | ( | ) | const throw () |
Returns true if the button in 'on'.
By default buttons are 'off' and for simple buttons that you click to perform an action you won't change this. Toggle buttons, however will want to change their state when turned on or off.
| Value& Button::getToggleStateValue | ( | ) |
Returns the Value object that represents the botton's toggle state.
You can use this Value object to connect the button's state to external values or setters, either by taking a copy of the Value, or by using Value::referTo() to make it point to your own Value object.
| void Button::setClickingTogglesState | ( | bool | shouldToggle | ) | throw () |
This tells the button to automatically flip the toggle state when the button is clicked.
If set to true, then before the clicked() callback occurs, the toggle-state of the button is flipped.
| bool Button::getClickingTogglesState | ( | ) | const throw () |
Returns true if this button is set to be an automatic toggle-button.
This returns the last value that was passed to setClickingTogglesState().
| void Button::setRadioGroupId | ( | int | newGroupId | ) |
Enables the button to act as a member of a mutually-exclusive group of 'radio buttons'.
If the group ID is set to a non-zero number, then this button will act as part of a group of buttons with the same ID, only one of which can be 'on' at the same time. Note that when it's part of a group, clicking a toggle-button that's 'on' won't turn it off.
To find other buttons with the same ID, this button will search through its sibling components for ToggleButtons, so all the buttons for a particular group must be placed inside the same parent component.
Set the group ID back to zero if you want it to act as a normal toggle button again.
| int Button::getRadioGroupId | ( | ) | const throw () |
Returns the ID of the group to which this button belongs.
(See setRadioGroupId() for an explanation of this).
| void Button::addButtonListener | ( | ButtonListener * | newListener | ) |
Registers a listener to receive events when this button's state changes.
If the listener is already registered, this will not register it again.
| void Button::removeButtonListener | ( | ButtonListener * | listener | ) |
Removes a previously-registered button listener.
| virtual void Button::triggerClick | ( | ) | [virtual] |
| void Button::setCommandToTrigger | ( | ApplicationCommandManager * | commandManagerToUse, | |
| int | commandID, | |||
| bool | generateTooltip | |||
| ) |
Sets a command ID for this button to automatically invoke when it's clicked.
When the button is pressed, it will use the given manager to trigger the command ID.
Obviously be careful that the ApplicationCommandManager doesn't get deleted before this button is. To disable the command triggering, call this method and pass 0 for the parameters.
If generateTooltip is true, then the button's tooltip will be automatically generated based on the name of this command and its current shortcut key.
| int Button::getCommandID | ( | ) | const throw () |
Returns the command ID that was set by setCommandToTrigger().
| void Button::addShortcut | ( | const KeyPress & | key | ) |
Assigns a shortcut key to trigger the button.
The button registers itself with its top-level parent component for keypresses.
Note that a different way of linking buttons to keypresses is by using the setCommandToTrigger() method to invoke a command.
| void Button::clearShortcuts | ( | ) |
Removes all key shortcuts that had been set for this button.
| bool Button::isRegisteredForShortcut | ( | const KeyPress & | key | ) | const |
Returns true if the given keypress is a shortcut for this button.
| void Button::setRepeatSpeed | ( | int | initialDelayInMillisecs, | |
| int | repeatDelayInMillisecs, | |||
| int | minimumDelayInMillisecs = -1 | |||
| ) | throw () |
Sets an auto-repeat speed for the button when it is held down.
(Auto-repeat is disabled by default).
| initialDelayInMillisecs | how long to wait after the mouse is pressed before triggering the next click. If this is zero, auto-repeat is disabled | |
| repeatDelayInMillisecs | the frequently subsequent repeated clicks should be triggered | |
| minimumDelayInMillisecs | if this is greater than 0, the auto-repeat speed will get faster, the longer the button is held down, up to the minimum interval specified here |
| void Button::setTriggeredOnMouseDown | ( | bool | isTriggeredOnMouseDown | ) | throw () |
Sets whether the button click should happen when the mouse is pressed or released.
By default the button is only considered to have been clicked when the mouse is released, but setting this to true will make it call the clicked() method as soon as the button is pressed.
This is useful if the button is being used to show a pop-up menu, as it allows the click to be used as a drag onto the menu.
| uint32 Button::getMillisecondsSinceButtonDown | ( | ) | const throw () |
Returns the number of milliseconds since the last time the button went into the 'down' state.
| void Button::setVisible | ( | bool | shouldBeVisible | ) | [virtual] |
| void Button::setTooltip | ( | const String & | newTooltip | ) | [virtual] |
Sets the tooltip for this button.
Reimplemented from SettableTooltipClient.
| const String Button::getTooltip | ( | ) | [virtual] |
Returns the string that this object wants to show as its tooltip.
Reimplemented from SettableTooltipClient.
| void Button::setConnectedEdges | ( | int | connectedEdgeFlags | ) |
Hints about which edges of the button might be connected to adjoining buttons.
The value passed in is a bitwise combination of any of the values in the ConnectedEdgeFlags enum.
E.g. if you are placing two buttons adjacent to each other, you could use this to indicate which edges are touching, and the LookAndFeel might choose to drawn them without rounded corners on the edges that connect. It's only a hint, so the LookAndFeel can choose to ignore it if it's not relevent for this type of button.
| int Button::getConnectedEdgeFlags | ( | ) | const throw () |
Returns the set of flags passed into setConnectedEdges().
| bool Button::isConnectedOnLeft | ( | ) | const throw () |
Indicates whether the button adjoins another one on its left edge.
| bool Button::isConnectedOnRight | ( | ) | const throw () |
Indicates whether the button adjoins another one on its right edge.
| bool Button::isConnectedOnTop | ( | ) | const throw () |
Indicates whether the button adjoins another one on its top edge.
| bool Button::isConnectedOnBottom | ( | ) | const throw () |
Indicates whether the button adjoins another one on its bottom edge.
| void Button::setState | ( | const ButtonState | newState | ) |
Can be used to force the button into a particular state.
This only changes the button's appearance, it won't trigger a click, or stop any mouse-clicks from happening.
The state that you set here will only last until it is automatically changed when the mouse enters or exits the button, or the mouse-button is pressed or released.
| virtual void Button::clicked | ( | ) | [protected, virtual] |
This method is called when the button has been clicked.
Subclasses can override this to perform whatever they actions they need to do.
Alternatively, a ButtonListener can be added to the button, and these listeners will be called when the click occurs.
Reimplemented in HyperlinkButton.
| virtual void Button::clicked | ( | const ModifierKeys & | modifiers | ) | [protected, virtual] |
This method is called when the button has been clicked.
By default it just calls clicked(), but you might want to override it to handle things like clicking when a modifier key is pressed, etc.
Reimplemented in TabBarButton.
| virtual void Button::paintButton | ( | Graphics & | g, | |
| bool | isMouseOverButton, | |||
| bool | isButtonDown | |||
| ) | [protected, pure virtual] |
Subclasses should override this to actually paint the button's contents.
It's better to use this than the paint method, because it gives you information about the over/down state of the button.
| g | the graphics context to use | |
| isMouseOverButton | true if the button is either in the 'over' or 'down' state | |
| isButtonDown | true if the button should be drawn in the 'down' position |
Implemented in ArrowButton, DrawableButton, HyperlinkButton, ImageButton, ShapeButton, TextButton, ToggleButton, ToolbarItemComponent, and TabBarButton.
| virtual void Button::buttonStateChanged | ( | ) | [protected, virtual] |
Called when the button's up/down/over state changes.
Subclasses can override this if they need to do something special when the button goes up or down.
Reimplemented in ArrowButton.
| virtual void Button::internalClickCallback | ( | const ModifierKeys & | modifiers | ) | [protected, virtual] |
For internal use only.
| void Button::handleCommandMessage | ( | int | commandId | ) | [protected, virtual] |
For internal use only.
Reimplemented from Component.
| void Button::mouseEnter | ( | const MouseEvent & | e | ) | [protected, virtual] |
For internal use only.
Reimplemented from Component.
| void Button::mouseExit | ( | const MouseEvent & | e | ) | [protected, virtual] |
For internal use only.
Reimplemented from Component.
| void Button::mouseDown | ( | const MouseEvent & | e | ) | [protected, virtual] |
For internal use only.
Reimplemented from Component.
| void Button::mouseDrag | ( | const MouseEvent & | e | ) | [protected, virtual] |
For internal use only.
Reimplemented from Component.
| void Button::mouseUp | ( | const MouseEvent & | e | ) | [protected, virtual] |
For internal use only.
Reimplemented from Component.
| bool Button::keyPressed | ( | const KeyPress & | key | ) | [protected, virtual] |
For internal use only.
Reimplemented from Component.
| bool Button::keyPressed | ( | const KeyPress & | key, | |
| Component * | originatingComponent | |||
| ) | [protected, virtual] |
For internal use only.
Implements KeyListener.
| bool Button::keyStateChanged | ( | bool | isKeyDown, | |
| Component * | originatingComponent | |||
| ) | [protected, virtual] |
For internal use only.
Reimplemented from KeyListener.
| void Button::paint | ( | Graphics & | g | ) | [protected, virtual] |
For internal use only.
Reimplemented from Component.
| void Button::parentHierarchyChanged | ( | ) | [protected, virtual] |
For internal use only.
Reimplemented from Component.
| void Button::focusGained | ( | FocusChangeType | cause | ) | [protected, virtual] |
For internal use only.
Reimplemented from Component.
| void Button::focusLost | ( | FocusChangeType | cause | ) | [protected, virtual] |
For internal use only.
Reimplemented from Component.
| void Button::enablementChanged | ( | ) | [protected, virtual] |
For internal use only.
Reimplemented from Component.
| void Button::applicationCommandInvoked | ( | const ApplicationCommandTarget::InvocationInfo & | ) | [protected, virtual] |
For internal use only.
Implements ApplicationCommandManagerListener.
| void Button::applicationCommandListChanged | ( | ) | [protected, virtual] |
For internal use only.
Implements ApplicationCommandManagerListener.
| void Button::valueChanged | ( | Value & | value | ) | [protected, virtual] |
For internal use only.
Implements Value::Listener.
1.6.3
