juce_Slider.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  Slider  : public Component,
                          public SettableTooltipClient
{
public:
    //==============================================================================
    enum SliderStyle
    {
        LinearHorizontal,               
        LinearVertical,                 
        LinearBar,                      
        LinearBarVertical,              
        Rotary,                         
        RotaryHorizontalDrag,           
        RotaryVerticalDrag,             
        RotaryHorizontalVerticalDrag,   
        IncDecButtons,                  
        TwoValueHorizontal,             
        TwoValueVertical,               
        ThreeValueHorizontal,           
        ThreeValueVertical              
    };
 
    enum TextEntryBoxPosition
    {
        NoTextBox,              
        TextBoxLeft,            
        TextBoxRight,           
        TextBoxAbove,           
        TextBoxBelow            
    };
 
    enum DragMode
    {
        notDragging,            
        absoluteDrag,           
        velocityDrag            
    };
 
    //==============================================================================
    Slider();
 
    explicit Slider (const String& componentName);
 
    Slider (SliderStyle style, TextEntryBoxPosition textBoxPosition);
 
    ~Slider() override;
 
    //==============================================================================
    void setSliderStyle (SliderStyle newStyle);
 
    SliderStyle getSliderStyle() const noexcept;
 
    //==============================================================================
    struct RotaryParameters
    {
        float startAngleRadians;
 
        float endAngleRadians;
 
        bool stopAtEnd;
    };
 
    void setRotaryParameters (RotaryParameters newParameters) noexcept;
 
    void setRotaryParameters (float startAngleRadians,
                              float endAngleRadians,
                              bool stopAtEnd) noexcept;
 
    RotaryParameters getRotaryParameters() const noexcept;
 
    void setMouseDragSensitivity (int distanceForFullScaleDrag);
 
    int getMouseDragSensitivity() const noexcept;
 
    //==============================================================================
    void setVelocityBasedMode (bool isVelocityBased);
 
    bool getVelocityBasedMode() const noexcept;
 
    void setVelocityModeParameters (double sensitivity = 1.0,
                                    int threshold = 1,
                                    double offset = 0.0,
                                    bool userCanPressKeyToSwapMode = true,
                                    ModifierKeys::Flags modifiersToSwapModes = ModifierKeys::ctrlAltCommandModifiers);
 
    double getVelocitySensitivity() const noexcept;
 
    int getVelocityThreshold() const noexcept;
 
    double getVelocityOffset() const noexcept;
 
    bool getVelocityModeIsSwappable() const noexcept;
 
    //==============================================================================
    void setSkewFactor (double factor, bool symmetricSkew = false);
 
    void setSkewFactorFromMidPoint (double sliderValueToShowAtMidPoint);
 
    double getSkewFactor() const noexcept;
 
    bool isSymmetricSkew() const noexcept;
 
    //==============================================================================
    enum IncDecButtonMode
    {
        incDecButtonsNotDraggable,
        incDecButtonsDraggable_AutoDirection,
        incDecButtonsDraggable_Horizontal,
        incDecButtonsDraggable_Vertical
    };
 
    void setIncDecButtonsMode (IncDecButtonMode mode);
 
    //==============================================================================
    void setTextBoxStyle (TextEntryBoxPosition newPosition,
                          bool isReadOnly,
                          int textEntryBoxWidth,
                          int textEntryBoxHeight);
 
    TextEntryBoxPosition getTextBoxPosition() const noexcept;
 
    int getTextBoxWidth() const noexcept;
 
    int getTextBoxHeight() const noexcept;
 
    void setTextBoxIsEditable (bool shouldBeEditable);
 
    bool isTextBoxEditable() const noexcept;
 
    void showTextBox();
 
    void hideTextBox (bool discardCurrentEditorContents);
 
 
    //==============================================================================
    void setValue (double newValue, NotificationType notification = sendNotificationAsync);
 
    double getValue() const;
 
    Value& getValueObject() noexcept;
 
    //==============================================================================
    void setRange (double newMinimum,
                   double newMaximum,
                   double newInterval = 0);
 
    void setRange (Range<double> newRange, double newInterval);
 
    void setNormalisableRange (NormalisableRange<double> newNormalisableRange);
 
    NormalisableRange<double> getNormalisableRange() const noexcept;
 
    Range<double> getRange() const noexcept;
 
    double getMaximum() const noexcept;
 
    double getMinimum() const noexcept;
 
    double getInterval() const noexcept;
 
    //==============================================================================
    double getMinValue() const;
 
    Value& getMinValueObject() noexcept;
 
    void setMinValue (double newValue,
                      NotificationType notification = sendNotificationAsync,
                      bool allowNudgingOfOtherValues = false);
 
    double getMaxValue() const;
 
    Value& getMaxValueObject() noexcept;
 
    void setMaxValue (double newValue,
                      NotificationType notification = sendNotificationAsync,
                      bool allowNudgingOfOtherValues = false);
 
    void setMinAndMaxValues (double newMinValue, double newMaxValue,
                             NotificationType notification = sendNotificationAsync);
 
    //==============================================================================
    class JUCE_API  Listener
    {
    public:
        //==============================================================================
        virtual ~Listener() = default;
 
        //==============================================================================
        virtual void sliderValueChanged (Slider* slider) = 0;
 
        //==============================================================================
        virtual void sliderDragStarted (Slider*) {}
 
        virtual void sliderDragEnded (Slider*) {}
    };
 
    void addListener (Listener* listener);
 
    void removeListener (Listener* listener);
 
    //==============================================================================
    std::function<void()> onValueChange;
 
    std::function<void()> onDragStart;
 
    std::function<void()> onDragEnd;
 
    std::function<double (const String&)> valueFromTextFunction;
 
    std::function<String (double)> textFromValueFunction;
 
    //==============================================================================
    void setDoubleClickReturnValue (bool shouldDoubleClickBeEnabled,
                                    double valueToSetOnDoubleClick,
                                    ModifierKeys singleClickModifiers = ModifierKeys::altModifier);
 
    double getDoubleClickReturnValue() const noexcept;
 
    bool isDoubleClickReturnEnabled() const noexcept;
 
    //==============================================================================
    void setChangeNotificationOnlyOnRelease (bool onlyNotifyOnRelease);
 
    void setSliderSnapsToMousePosition (bool shouldSnapToMouse);
 
    bool getSliderSnapsToMousePosition() const noexcept;
 
    void setPopupDisplayEnabled (bool shouldShowOnMouseDrag,
                                 bool shouldShowOnMouseHover,
                                 Component* parentComponentToUse,
                                 int hoverTimeout = 2000);
 
    Component* getCurrentPopupDisplay() const noexcept;
 
    void setPopupMenuEnabled (bool menuEnabled);
 
    void setScrollWheelEnabled (bool enabled);
 
    bool isScrollWheelEnabled() const noexcept;
 
    int getThumbBeingDragged() const noexcept;
 
    //==============================================================================
    virtual void startedDragging();
 
    virtual void stoppedDragging();
 
    virtual void valueChanged();
 
    //==============================================================================
    virtual double getValueFromText (const String& text);
 
    virtual String getTextFromValue (double value);
 
    void setTextValueSuffix (const String& suffix);
 
    String getTextValueSuffix() const;
 
    int getNumDecimalPlacesToDisplay() const noexcept;
 
    void setNumDecimalPlacesToDisplay (int decimalPlacesToDisplay);
 
    //==============================================================================
    virtual double proportionOfLengthToValue (double proportion);
 
    virtual double valueToProportionOfLength (double value);
 
    float getPositionOfValue (double value) const;
 
    //==============================================================================
    virtual double snapValue (double attemptedValue, DragMode dragMode);
 
 
    //==============================================================================
    void updateText();
 
    bool isHorizontal() const noexcept;
    bool isVertical() const noexcept;
    bool isRotary() const noexcept;
    bool isBar() const noexcept;
    bool isTwoValue() const noexcept;
    bool isThreeValue() const noexcept;
 
    //==============================================================================
    enum ColourIds
    {
        backgroundColourId          = 0x1001200,  
        thumbColourId               = 0x1001300,  
        trackColourId               = 0x1001310,  
        rotarySliderFillColourId    = 0x1001311,  
        rotarySliderOutlineColourId = 0x1001312,  
        textBoxTextColourId         = 0x1001400,  
        textBoxBackgroundColourId   = 0x1001500,  
        textBoxHighlightColourId    = 0x1001600,  
        textBoxOutlineColourId      = 0x1001700   
    };
 
    //==============================================================================
    struct SliderLayout
    {
        Rectangle<int> sliderBounds;
        Rectangle<int> textBoxBounds;
    };
 
    //==============================================================================
    class JUCE_API  ScopedDragNotification
    {
    public:
        explicit ScopedDragNotification (Slider&);
        ~ScopedDragNotification();
 
    private:
        Slider& sliderBeingDragged;
 
        JUCE_DECLARE_NON_MOVEABLE (ScopedDragNotification)
        JUCE_DECLARE_NON_COPYABLE (ScopedDragNotification)
    };
 
    //==============================================================================
    struct JUCE_API  LookAndFeelMethods
    {
        virtual ~LookAndFeelMethods() = default;
 
        //==============================================================================
        virtual void drawLinearSlider (Graphics&,
                                       int x, int y, int width, int height,
                                       float sliderPos,
                                       float minSliderPos,
                                       float maxSliderPos,
                                       Slider::SliderStyle,
                                       Slider&) = 0;
 
        virtual void drawLinearSliderBackground (Graphics&,
                                                 int x, int y, int width, int height,
                                                 float sliderPos,
                                                 float minSliderPos,
                                                 float maxSliderPos,
                                                 Slider::SliderStyle,
                                                 Slider&) = 0;
 
        virtual void drawLinearSliderOutline (Graphics&,
                                              int x, int y, int width, int height,
                                              Slider::SliderStyle,
                                              Slider&) = 0;
 
        virtual void drawLinearSliderThumb (Graphics&,
                                            int x, int y, int width, int height,
                                            float sliderPos,
                                            float minSliderPos,
                                            float maxSliderPos,
                                            Slider::SliderStyle,
                                            Slider&) = 0;
 
        virtual int getSliderThumbRadius (Slider&) = 0;
 
        virtual void drawRotarySlider (Graphics&,
                                       int x, int y, int width, int height,
                                       float sliderPosProportional,
                                       float rotaryStartAngle,
                                       float rotaryEndAngle,
                                       Slider&) = 0;
 
        virtual Button* createSliderButton (Slider&, bool isIncrement) = 0;
        virtual Label* createSliderTextBox (Slider&) = 0;
 
        virtual ImageEffectFilter* getSliderEffect (Slider&) = 0;
 
        virtual Font getSliderPopupFont (Slider&) = 0;
        virtual int getSliderPopupPlacement (Slider&) = 0;
 
        virtual SliderLayout getSliderLayout (Slider&) = 0;
    };
 
    //==============================================================================
    void paint (Graphics&) override;
    void resized() override;
    void mouseDown (const MouseEvent&) override;
    void mouseUp (const MouseEvent&) override;
    void mouseDrag (const MouseEvent&) override;
    void mouseDoubleClick (const MouseEvent&) override;
    void mouseWheelMove (const MouseEvent&, const MouseWheelDetails&) override;
    void modifierKeysChanged (const ModifierKeys&) override;
    void lookAndFeelChanged() override;
    void enablementChanged() override;
    void focusOfChildComponentChanged (FocusChangeType) override;
    void colourChanged() override;
    void mouseMove (const MouseEvent&) override;
    void mouseExit (const MouseEvent&) override;
    void mouseEnter (const MouseEvent&) override;
    bool keyPressed (const KeyPress&) override;
    std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
 
    //==============================================================================
   #ifndef DOXYGEN
    // These methods' bool parameters have changed: see the new method signature.
    [[deprecated]] void setValue (double, bool);
    [[deprecated]] void setValue (double, bool, bool);
    [[deprecated]] void setMinValue (double, bool, bool, bool);
    [[deprecated]] void setMinValue (double, bool, bool);
    [[deprecated]] void setMinValue (double, bool);
    [[deprecated]] void setMaxValue (double, bool, bool, bool);
    [[deprecated]] void setMaxValue (double, bool, bool);
    [[deprecated]] void setMaxValue (double, bool);
    [[deprecated]] void setMinAndMaxValues (double, double, bool, bool);
    [[deprecated]] void setMinAndMaxValues (double, double, bool);
   #endif
 
private:
    //==============================================================================
    JUCE_PUBLIC_IN_DLL_BUILD (class Pimpl)
    std::unique_ptr<Pimpl> pimpl;
 
    void init (SliderStyle, TextEntryBoxPosition);
 
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Slider)
};
 
 
} // namespace juce