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.
Classes | |
| class | Listener |
| Used to receive callbacks when a button is clicked. More... | |
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 noexcept |
| Returns true if the button is currently being held down by the mouse. | |
| bool | isOver () const noexcept |
| 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 noexcept |
| Returns true if the button in 'on'. | |
| Value & | getToggleStateValue () |
| Returns the Value object that represents the botton's toggle state. | |
| void | setClickingTogglesState (bool shouldToggle) noexcept |
| This tells the button to automatically flip the toggle state when the button is clicked. | |
| bool | getClickingTogglesState () const noexcept |
| 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 noexcept |
| Returns the ID of the group to which this button belongs. | |
| void | addListener (Listener *newListener) |
| Registers a listener to receive events when this button's state changes. | |
| void | removeListener (Listener *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 noexcept |
| 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) noexcept |
| Sets an auto-repeat speed for the button when it is held down. | |
| void | setTriggeredOnMouseDown (bool isTriggeredOnMouseDown) noexcept |
| Sets whether the button click should happen when the mouse is pressed or released. | |
| uint32 | getMillisecondsSinceButtonDown () const noexcept |
| Returns the number of milliseconds since the last time the button went into the 'down' state. | |
| void | setTooltip (const String &newTooltip) |
| Sets the tooltip for this button. | |
| const String | getTooltip () |
| Returns the tooltip assigned to this object. | |
| void | setConnectedEdges (int connectedEdgeFlags) |
| Hints about which edges of the button might be connected to adjoining buttons. | |
| int | getConnectedEdgeFlags () const noexcept |
| Returns the set of flags passed into setConnectedEdges(). | |
| bool | isConnectedOnLeft () const noexcept |
| Indicates whether the button adjoins another one on its left edge. | |
| bool | isConnectedOnRight () const noexcept |
| Indicates whether the button adjoins another one on its right edge. | |
| bool | isConnectedOnTop () const noexcept |
| Indicates whether the button adjoins another one on its top edge. | |
| bool | isConnectedOnBottom () const noexcept |
| 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. | |
| JUCE_DEPRECATED (void addButtonListener(Listener *)) | |
| JUCE_DEPRECATED (void removeButtonListener(Listener *)) | |
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) |
| Called to handle a command that was sent by postCommandMessage(). | |
| void | mouseEnter (const MouseEvent &e) |
| Called when the mouse first enters this component. | |
| void | mouseExit (const MouseEvent &e) |
| Called when the mouse moves out of this component. | |
| void | mouseDown (const MouseEvent &e) |
| Called when a mouse button is pressed while it's over this component. | |
| void | mouseDrag (const MouseEvent &e) |
| Called when the mouse is moved while a button is held down. | |
| void | mouseUp (const MouseEvent &e) |
| Called when a mouse button is released. | |
| bool | keyPressed (const KeyPress &key) |
| Called when a key is pressed. | |
| bool | keyPressed (const KeyPress &key, Component *originatingComponent) |
| Called to indicate that a key has been pressed. | |
| bool | keyStateChanged (bool isKeyDown, Component *originatingComponent) |
| Called when any key is pressed or released. | |
| void | paint (Graphics &g) |
| Components can override this method to draw their content. | |
| void | parentHierarchyChanged () |
| Called to indicate that the component's parents have changed. | |
| void | visibilityChanged () |
| Called when this component's visiblility changes. | |
| void | focusGained (FocusChangeType cause) |
| Called to indicate that this component has just acquired the keyboard focus. | |
| void | focusLost (FocusChangeType cause) |
| Called to indicate that this component has just lost the keyboard focus. | |
| void | enablementChanged () |
| Callback to indicate that this component has been enabled or disabled. | |
| void | applicationCommandInvoked (const ApplicationCommandTarget::InvocationInfo &) |
| Called when an app command is about to be invoked. | |
| void | applicationCommandListChanged () |
| Called when commands are registered or deregistered from the command manager, or when commands are made active or inactive. | |
| void | valueChanged (Value &value) |
| Called when a Value object is changed. | |
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 |
Returns true if the button is currently being held down by the mouse.
| bool Button::isOver | ( | ) | const |
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 |
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 ) |
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 |
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 |
Returns the ID of the group to which this button belongs.
(See setRadioGroupId() for an explanation of this).
| void Button::addListener | ( | Listener * | 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::removeListener | ( | Listener * | 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 |
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 |
||
| ) |
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 ) |
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 |
Returns the number of milliseconds since the last time the button went into the 'down' state.
| void Button::setTooltip | ( | const String & | newTooltip ) | [virtual] |
Sets the tooltip for this button.
Reimplemented from SettableTooltipClient.
| const String Button::getTooltip | ( | ) | [virtual] |
Returns the tooltip assigned to this object.
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 |
Returns the set of flags passed into setConnectedEdges().
| bool Button::isConnectedOnLeft | ( | ) | const |
Indicates whether the button adjoins another one on its left edge.
| bool Button::isConnectedOnRight | ( | ) | const |
Indicates whether the button adjoins another one on its right edge.
| bool Button::isConnectedOnTop | ( | ) | const |
Indicates whether the button adjoins another one on its top edge.
| bool Button::isConnectedOnBottom | ( | ) | const |
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.
| Button::JUCE_DEPRECATED | ( | void | addButtonListenerListener * ) |
| Button::JUCE_DEPRECATED | ( | void | removeButtonListenerListener * ) |
| 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, DrawableButton, and ToolbarButton.
| virtual void Button::internalClickCallback | ( | const ModifierKeys & | modifiers ) | [protected, virtual] |
| void Button::handleCommandMessage | ( | int | commandId ) | [protected, virtual] |
Called to handle a command that was sent by postCommandMessage().
This is called by the message thread when a command message arrives, and the component can override this method to process it in any way it needs to.
Reimplemented from Component.
| void Button::mouseEnter | ( | const MouseEvent & | e ) | [protected, virtual] |
Called when the mouse first enters this component.
If the mouse button isn't pressed and the mouse moves into a component, this will be called to let the component react to this.
When the mouse button is pressed and held down while being moved in or out of a component, no mouseEnter or mouseExit callbacks are made - only mouseDrag messages are sent to the component that the mouse was originally clicked on, until the button is released.
If you're writing a component that needs to repaint itself when the mouse enters and exits, it might be quicker to use the setRepaintsOnMouseActivity() method.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| void Button::mouseExit | ( | const MouseEvent & | e ) | [protected, virtual] |
Called when the mouse moves out of this component.
This will be called when the mouse moves off the edge of this component.
If the mouse button was pressed, and it was then dragged off the edge of the component and released, then this callback will happen when the button is released, after the mouseUp callback.
If you're writing a component that needs to repaint itself when the mouse enters and exits, it might be quicker to use the setRepaintsOnMouseActivity() method.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| void Button::mouseDown | ( | const MouseEvent & | e ) | [protected, virtual] |
Called when a mouse button is pressed while it's over this component.
The MouseEvent object passed in contains lots of methods for finding out which button was pressed, as well as which modifier keys (e.g. shift, ctrl) were held down at the time.
Once a button is held down, the mouseDrag method will be called when the mouse moves, until the button is released.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| void Button::mouseDrag | ( | const MouseEvent & | e ) | [protected, virtual] |
Called when the mouse is moved while a button is held down.
When a mouse button is pressed inside a component, that component receives mouseDrag callbacks each time the mouse moves, even if the mouse strays outside the component's bounds.
If you want to be able to drag things off the edge of a component and have the component scroll when you get to the edges, the beginDragAutoRepeat() method might be useful.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| void Button::mouseUp | ( | const MouseEvent & | e ) | [protected, virtual] |
Called when a mouse button is released.
A mouseUp callback is sent to the component in which a button was pressed even if the mouse is actually over a different component when the button is released.
The MouseEvent object passed in contains lots of methods for finding out which buttons were down just before they were released.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| bool Button::keyPressed | ( | const KeyPress & | key ) | [protected, virtual] |
Called when a key is pressed.
When a key is pressed, the component that has the keyboard focus will have this method called. Remember that a component will only be given the focus if its setWantsKeyboardFocus() method has been used to enable this.
If your implementation returns true, the event will be consumed and not passed on to any other listeners. If it returns false, the key will be passed to any KeyListeners that have been registered with this component. As soon as one of these returns true, the process will stop, but if they all return false, the event will be passed upwards to this component's parent, and so on.
The default implementation of this method does nothing and returns false.
Reimplemented from Component.
| bool Button::keyPressed | ( | const KeyPress & | key, |
| Component * | originatingComponent | ||
| ) | [protected, virtual] |
Called to indicate that a key has been pressed.
If your implementation returns true, then the key event is considered to have been consumed, and will not be passed on to any other components. If it returns false, then the key will be passed to other components that might want to use it.
| key | the keystroke, including modifier keys |
| originatingComponent | the component that received the key event |
Implements KeyListener.
| bool Button::keyStateChanged | ( | bool | isKeyDown, |
| Component * | originatingComponent | ||
| ) | [protected, virtual] |
Called when any key is pressed or released.
When this is called, classes that might be interested in the state of one or more keys can use KeyPress::isKeyCurrentlyDown() to check whether their key has changed.
If your implementation returns true, then the key event is considered to have been consumed, and will not be passed on to any other components. If it returns false, then the key will be passed to other components that might want to use it.
| originatingComponent | the component that received the key event |
| isKeyDown | true if a key is being pressed, false if one is being released |
Reimplemented from KeyListener.
| void Button::paint | ( | Graphics & | g ) | [protected, virtual] |
Components can override this method to draw their content.
The paint() method gets called when a region of a component needs redrawing, either because the component's repaint() method has been called, or because something has happened on the screen that means a section of a window needs to be redrawn.
Any child components will draw themselves over whatever this method draws. If you need to paint over the top of your child components, you can also implement the paintOverChildren() method to do this.
If you want to cause a component to redraw itself, this is done asynchronously - calling the repaint() method marks a region of the component as "dirty", and the paint() method will automatically be called sometime later, by the message thread, to paint any bits that need refreshing. In Juce (and almost all modern UI frameworks), you never redraw something synchronously.
You should never need to call this method directly - to take a snapshot of the component you could use createComponentSnapshot() or paintEntireComponent().
| g | the graphics context that must be used to do the drawing operations. |
Reimplemented from Component.
| void Button::parentHierarchyChanged | ( | ) | [protected, virtual] |
Called to indicate that the component's parents have changed.
When a component is added or removed from its parent, this method will be called on all of its children (recursively - so all children of its children will also be called as well).
Subclasses can override this if they need to react to this in some way.
Reimplemented from Component.
| void Button::visibilityChanged | ( | ) | [protected, virtual] |
Called when this component's visiblility changes.
Reimplemented from Component.
| void Button::focusGained | ( | FocusChangeType | cause ) | [protected, virtual] |
Called to indicate that this component has just acquired the keyboard focus.
Reimplemented from Component.
| void Button::focusLost | ( | FocusChangeType | cause ) | [protected, virtual] |
Called to indicate that this component has just lost the keyboard focus.
Reimplemented from Component.
| void Button::enablementChanged | ( | ) | [protected, virtual] |
Callback to indicate that this component has been enabled or disabled.
This can be triggered by one of the component's parent components being enabled or disabled, as well as changes to the component itself.
The default implementation of this method does nothing; your class may wish to repaint itself or something when this happens.
Reimplemented from Component.
Reimplemented in ToolbarButton.
| void Button::applicationCommandInvoked | ( | const ApplicationCommandTarget::InvocationInfo & | info ) | [protected, virtual] |
Called when an app command is about to be invoked.
Implements ApplicationCommandManagerListener.
| void Button::applicationCommandListChanged | ( | ) | [protected, virtual] |
Called when commands are registered or deregistered from the command manager, or when commands are made active or inactive.
Note that if you're using this to watch for changes to whether a command is disabled, you'll need to make sure that ApplicationCommandManager::commandStatusChanged() is called whenever the status of your command might have changed.
Implements ApplicationCommandManagerListener.
| void Button::valueChanged | ( | Value & | value ) | [protected, virtual] |
Called when a Value object is changed.
Note that the Value object passed as a parameter may not be exactly the same object that you registered the listener with - it might be a copy that refers to the same underlying ValueSource. To find out, you can call Value::refersToSameSourceAs().
Implements Value::Listener.
