juce_Button.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   By using JUCE, you agree to the terms of both the JUCE 7 End-User License
   Agreement and JUCE Privacy Policy.
 
   End User License Agreement: www.juce.com/juce-7-licence
   Privacy Policy: www.juce.com/juce-privacy-policy
 
   Or: You may also use this code under the terms of the GPL v3 (see
   www.gnu.org/licenses).
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{
 
//==============================================================================
class JUCE_API  Button  : public Component,
                          public SettableTooltipClient
{
protected:
    //==============================================================================
    explicit Button (const String& buttonName);
 
public:
    ~Button() override;
 
    //==============================================================================
    void setButtonText (const String& newText);

    const String& getButtonText() const               { return text; }
 
    //==============================================================================
    bool isDown() const noexcept;

    bool isOver() const noexcept;
 
    //==============================================================================
    void setToggleable (bool shouldBeToggleable);

    bool isToggleable() const noexcept                          { return canBeToggled || clickTogglesState; }

    void setToggleState (bool shouldBeOn, NotificationType notification);

    bool getToggleState() const noexcept                        { return isOn.getValue(); }

    Value& getToggleStateValue() noexcept                       { return isOn; }

    void setClickingTogglesState (bool shouldAutoToggleOnClick) noexcept;

    bool getClickingTogglesState() const noexcept               { return clickTogglesState; }
 
    //==============================================================================
    void setRadioGroupId (int newGroupId, NotificationType notification = sendNotification);

    int getRadioGroupId() const noexcept                        { return radioGroupId; }
 
    //==============================================================================
    class JUCE_API  Listener
    {
    public:
        virtual ~Listener() = default;

        virtual void buttonClicked (Button*) = 0;

        virtual void buttonStateChanged (Button*)  {}
    };

    void addListener (Listener* newListener);

    void removeListener (Listener* listener);
 
    //==============================================================================
    std::function<void()> onClick;

    std::function<void()> onStateChange;
 
    //==============================================================================
    virtual void triggerClick();
 
    //==============================================================================
    void setCommandToTrigger (ApplicationCommandManager* commandManagerToUse,
                              CommandID commandID,
                              bool generateTooltip);

    CommandID getCommandID() const noexcept             { return commandID; }
 
    //==============================================================================
    void addShortcut (const KeyPress&);

    void clearShortcuts();

    bool isRegisteredForShortcut (const KeyPress&) const;
 
    //==============================================================================
    void setRepeatSpeed (int initialDelayInMillisecs,
                         int repeatDelayInMillisecs,
                         int minimumDelayInMillisecs = -1) noexcept;

    void setTriggeredOnMouseDown (bool isTriggeredOnMouseDown) noexcept;

    bool getTriggeredOnMouseDown() const noexcept;

    uint32 getMillisecondsSinceButtonDown() const noexcept;
 
    //==============================================================================
    void setTooltip (const String& newTooltip) override;
 
    //==============================================================================
    enum ConnectedEdgeFlags
    {
        ConnectedOnLeft = 1,
        ConnectedOnRight = 2,
        ConnectedOnTop = 4,
        ConnectedOnBottom = 8
    };

    void setConnectedEdges (int connectedEdgeFlags);

    int getConnectedEdgeFlags() const noexcept          { return connectedEdgeFlags; }

    bool isConnectedOnLeft() const noexcept             { return (connectedEdgeFlags & ConnectedOnLeft) != 0; }

    bool isConnectedOnRight() const noexcept            { return (connectedEdgeFlags & ConnectedOnRight) != 0; }

    bool isConnectedOnTop() const noexcept              { return (connectedEdgeFlags & ConnectedOnTop) != 0; }

    bool isConnectedOnBottom() const noexcept           { return (connectedEdgeFlags & ConnectedOnBottom) != 0; }
 
 
    //==============================================================================
    enum ButtonState
    {
        buttonNormal,
        buttonOver,
        buttonDown
    };

    void setState (ButtonState newState);

    ButtonState getState() const noexcept               { return buttonState; }
 
    //==============================================================================
    struct JUCE_API  LookAndFeelMethods
    {
        virtual ~LookAndFeelMethods() = default;
 
        virtual void drawButtonBackground (Graphics&, Button&, const Colour& backgroundColour,
                                           bool shouldDrawButtonAsHighlighted, bool shouldDrawButtonAsDown) = 0;
 
        virtual Font getTextButtonFont (TextButton&, int buttonHeight) = 0;
        virtual int getTextButtonWidthToFitText (TextButton&, int buttonHeight) = 0;

        virtual void drawButtonText (Graphics&, TextButton&,
                                     bool shouldDrawButtonAsHighlighted, bool shouldDrawButtonAsDown) = 0;

        virtual void drawToggleButton (Graphics&, ToggleButton&,
                                       bool shouldDrawButtonAsHighlighted, bool shouldDrawButtonAsDown) = 0;
 
        virtual void changeToggleButtonWidthToFitText (ToggleButton&) = 0;
 
        virtual void drawTickBox (Graphics&, Component&, float x, float y, float w, float h,
                                  bool ticked, bool isEnabled,
                                  bool shouldDrawButtonAsHighlighted, bool shouldDrawButtonAsDown) = 0;
 
        virtual void drawDrawableButton (Graphics&, DrawableButton&,
                                         bool shouldDrawButtonAsHighlighted, bool shouldDrawButtonAsDown) = 0;
    };
 
    //==============================================================================
   #ifndef DOXYGEN
    [[deprecated ("This method's parameters have changed.")]]
    void setToggleState (bool, bool);
   #endif
 
protected:
    //==============================================================================
    virtual void clicked();

    virtual void clicked (const ModifierKeys& modifiers);

    virtual void paintButton (Graphics& g,
                              bool shouldDrawButtonAsHighlighted,
                              bool shouldDrawButtonAsDown) = 0;

    virtual void buttonStateChanged();
 
    //==============================================================================
    virtual void internalClickCallback (const ModifierKeys&);
    void handleCommandMessage (int commandId) override;
    void mouseEnter (const MouseEvent&) override;
    void mouseExit (const MouseEvent&) override;
    void mouseDown (const MouseEvent&) override;
    void mouseDrag (const MouseEvent&) override;
    void mouseUp (const MouseEvent&) override;
    bool keyPressed (const KeyPress&) override;
    using Component::keyStateChanged;
    void paint (Graphics&) override;
    void parentHierarchyChanged() override;
    void visibilityChanged() override;
    void focusGained (FocusChangeType) override;
    void focusLost (FocusChangeType) override;
    void enablementChanged() override;
 
private:
    //==============================================================================
    Array<KeyPress> shortcuts;
    WeakReference<Component> keySource;
    String text;
    ListenerList<Listener> buttonListeners;
 
    struct CallbackHelper;
    std::unique_ptr<CallbackHelper> callbackHelper;
    uint32 buttonPressTime = 0, lastRepeatTime = 0;
    ApplicationCommandManager* commandManagerToUse = nullptr;
    int autoRepeatDelay = -1, autoRepeatSpeed = 0, autoRepeatMinimumDelay = -1;
    int radioGroupId = 0, connectedEdgeFlags = 0;
    CommandID commandID = {};
    ButtonState buttonState = buttonNormal, lastStatePainted = buttonNormal;
 
    Value isOn;
    bool canBeToggled = false;
    bool lastToggleState = false;
    bool clickTogglesState = false;
    bool needsToRelease = false;
    bool needsRepainting = false;
    bool isKeyDown = false;
    bool triggerOnMouseDown = false;
    bool generateTooltip = false;
 
    std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
    void checkToggleableState (bool wasToggleable);
 
    void repeatTimerCallback();
    bool keyStateChangedCallback();
    void applicationCommandListChangeCallback();
    void updateAutomaticTooltip (const ApplicationCommandInfo&);
 
    ButtonState updateState();
    ButtonState updateState (bool isOver, bool isDown);
    bool isShortcutPressed() const;
    void turnOffOtherButtonsInGroup (NotificationType click, NotificationType state);
 
    void flashButtonState();
    void sendClickMessage (const ModifierKeys&);
    void sendStateMessage();
    void setToggleState (bool shouldBeOn, NotificationType click, NotificationType state);
 
    bool isMouseSourceOver (const MouseEvent& e);
 
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Button)
};
 
 
} // namespace juce