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);

    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,
                                       const Slider::SliderStyle,
                                       Slider&) = 0;
 
        virtual void drawLinearSliderBackground (Graphics&,
                                                 int x, int y, int width, int height,
                                                 float sliderPos,
                                                 float minSliderPos,
                                                 float maxSliderPos,
                                                 const Slider::SliderStyle style,
                                                 Slider&) = 0;
 
        virtual void drawLinearSliderThumb (Graphics&,
                                            int x, int y, int width, int height,
                                            float sliderPos,
                                            float minSliderPos,
                                            float maxSliderPos,
                                            const 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;
 
    //==============================================================================
   #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;
 
    std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
    void init (SliderStyle, TextEntryBoxPosition);
 
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Slider)
};
 
 
} // namespace juce