source/modules/juce_gui_basics/widgets/juce_Slider.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    By using JUCE, you agree to the terms of both the JUCE 7 End-User License
  11    Agreement and JUCE Privacy Policy.
  12
  13    End User License Agreement: www.juce.com/juce-7-licence
  14    Privacy Policy: www.juce.com/juce-privacy-policy
  15
  16    Or: You may also use this code under the terms of the GPL v3 (see
  17    www.gnu.org/licenses).
  18
  19    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  20    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  21    DISCLAIMED.
  22
  23   ==============================================================================
  24 */
  25
  26 namespace juce
  27 {
  28
  29 //==============================================================================
  30 /**
  31     A slider control for changing a value.
  32
  33     The slider can be horizontal, vertical, or rotary, and can optionally have
  34     a text-box inside it to show an editable display of the current value.
  35
  36     To use it, create a Slider object and use the setSliderStyle() method
  37     to set up the type you want. To set up the text-entry box, use setTextBoxStyle().
  38
  39     To define the values that it can be set to, see the setRange() and setValue() methods.
  40
  41     There are also lots of custom tweaks you can do by subclassing and overriding
  42     some of the virtual methods, such as changing the scaling, changing the format of
  43     the text display, custom ways of limiting the values, etc.
  44
  45     You can register Slider::Listener objects with a slider, and they'll be called when
  46     the value changes.
  47
  48     @see Slider::Listener
  49
  50     @tags{GUI}
  51 */
  52 class JUCE_API  Slider  : public Component,
  53                           public SettableTooltipClient
  54 {
  55 public:
  56     //==============================================================================
  57     /** The types of slider available.
  58
  59         @see setSliderStyle, setRotaryParameters
  60     */
  61     enum SliderStyle
  62     {
  63         LinearHorizontal,               /**< A traditional horizontal slider. */
  64         LinearVertical,                 /**< A traditional vertical slider. */
  65         LinearBar,                      /**< A horizontal bar slider with the text label drawn on top of it. */
  66         LinearBarVertical,              /**< A vertical bar slider with the text label drawn on top of it. */
  67         Rotary,                         /**< A rotary control that you move by dragging the mouse in a circular motion, like a knob.
  68                                              @see setRotaryParameters */
  69         RotaryHorizontalDrag,           /**< A rotary control that you move by dragging the mouse left-to-right.
  70                                              @see setRotaryParameters */
  71         RotaryVerticalDrag,             /**< A rotary control that you move by dragging the mouse up-and-down.
  72                                              @see setRotaryParameters */
  73         RotaryHorizontalVerticalDrag,   /**< A rotary control that you move by dragging the mouse up-and-down or left-to-right.
  74                                              @see setRotaryParameters */
  75         IncDecButtons,                  /**< A pair of buttons that increment or decrement the slider's value by the increment set in setRange(). */
  76
  77         TwoValueHorizontal,             /**< A horizontal slider that has two thumbs instead of one, so it can show a minimum and maximum value.
  78                                              @see setMinValue, setMaxValue */
  79         TwoValueVertical,               /**< A vertical slider that has two thumbs instead of one, so it can show a minimum and maximum value.
  80                                              @see setMinValue, setMaxValue */
  81
  82         ThreeValueHorizontal,           /**< A horizontal slider that has three thumbs instead of one, so it can show a minimum and maximum
  83                                              value, with the current value being somewhere between them.
  84                                              @see setMinValue, setMaxValue */
  85         ThreeValueVertical              /**< A vertical slider that has three thumbs instead of one, so it can show a minimum and maximum
  86                                              value, with the current value being somewhere between them.
  87                                              @see setMinValue, setMaxValue */
  88     };
  89
  90     /** The position of the slider's text-entry box.
  91         @see setTextBoxStyle
  92     */
  93     enum TextEntryBoxPosition
  94     {
  95         NoTextBox,              /**< Doesn't display a text box.  */
  96         TextBoxLeft,            /**< Puts the text box to the left of the slider, vertically centred.  */
  97         TextBoxRight,           /**< Puts the text box to the right of the slider, vertically centred.  */
  98         TextBoxAbove,           /**< Puts the text box above the slider, horizontally centred.  */
  99         TextBoxBelow            /**< Puts the text box below the slider, horizontally centred.  */
 100     };
 101
 102     /** Describes the type of mouse-dragging that is happening when a value is being changed.
 103         @see snapValue
 104      */
 105     enum DragMode
 106     {
 107         notDragging,            /**< Dragging is not active.  */
 108         absoluteDrag,           /**< The dragging corresponds directly to the value that is displayed.  */
 109         velocityDrag            /**< The dragging value change is relative to the velocity of the mouse movement.  */
 110     };
 111
 112     //==============================================================================
 113     /** Creates a slider.
 114         When created, you can set up the slider's style and range with setSliderStyle(), setRange(), etc.
 115     */
 116     Slider();
 117
 118     /** Creates a slider.
 119         When created, you can set up the slider's style and range with setSliderStyle(), setRange(), etc.
 120     */
 121     explicit Slider (const String& componentName);
 122
 123     /** Creates a slider with some explicit options. */
 124     Slider (SliderStyle style, TextEntryBoxPosition textBoxPosition);
 125
 126     /** Destructor. */
 127     ~Slider() override;
 128
 129     //==============================================================================
 130     /** Changes the type of slider interface being used.
 131
 132         @param newStyle         the type of interface
 133         @see setRotaryParameters, setVelocityBasedMode
 134     */
 135     void setSliderStyle (SliderStyle newStyle);
 136
 137     /** Returns the slider's current style.
 138         @see setSliderStyle
 139     */
 140     SliderStyle getSliderStyle() const noexcept;
 141
 142     //==============================================================================
 143     /** Structure defining rotary parameters for a slider */
 144     struct RotaryParameters
 145     {
 146         /** The angle (in radians, clockwise from the top) at which
 147             the slider's minimum value is represented.
 148         */
 149         float startAngleRadians;
 150
 151         /** The angle (in radians, clockwise from the top) at which
 152             the slider's maximum value is represented. This must be
 153             greater than startAngleRadians.
 154         */
 155         float endAngleRadians;
 156
 157         /** Determines what happens when a circular drag action rotates beyond
 158             the minimum or maximum angle. If true, the value will stop changing
 159             until the mouse moves back the way it came; if false, the value
 160             will snap back to the value nearest to the mouse. Note that this has
 161             no effect if the drag mode is vertical or horizontal.
 162         */
 163         bool stopAtEnd;
 164     };
 165
 166     /** Changes the properties of a rotary slider. */
 167     void setRotaryParameters (RotaryParameters newParameters) noexcept;
 168
 169     /** Changes the properties of a rotary slider. */
 170     void setRotaryParameters (float startAngleRadians,
 171                               float endAngleRadians,
 172                               bool stopAtEnd) noexcept;
 173
 174     /** Changes the properties of a rotary slider. */
 175     RotaryParameters getRotaryParameters() const noexcept;
 176
 177     /** Sets the distance the mouse has to move to drag the slider across
 178         the full extent of its range.
 179
 180         This only applies when in modes like RotaryHorizontalDrag, where it's using
 181         relative mouse movements to adjust the slider.
 182     */
 183     void setMouseDragSensitivity (int distanceForFullScaleDrag);
 184
 185     /** Returns the current sensitivity value set by setMouseDragSensitivity(). */
 186     int getMouseDragSensitivity() const noexcept;
 187
 188     //==============================================================================
 189     /** Changes the way the mouse is used when dragging the slider.
 190
 191         If true, this will turn on velocity-sensitive dragging, so that
 192         the faster the mouse moves, the bigger the movement to the slider. This
 193         helps when making accurate adjustments if the slider's range is quite large.
 194
 195         If false, the slider will just try to snap to wherever the mouse is.
 196     */
 197     void setVelocityBasedMode (bool isVelocityBased);
 198
 199     /** Returns true if velocity-based mode is active.
 200         @see setVelocityBasedMode
 201     */
 202     bool getVelocityBasedMode() const noexcept;
 203
 204     /** Changes aspects of the scaling used when in velocity-sensitive mode.
 205
 206         These apply when you've used setVelocityBasedMode() to turn on velocity mode,
 207         or if you're holding down ctrl.
 208
 209         @param sensitivity      higher values than 1.0 increase the range of acceleration used
 210         @param threshold        the minimum number of pixels that the mouse needs to move for it
 211                                 to be treated as a movement
 212         @param offset           values greater than 0.0 increase the minimum speed that will be used when
 213                                 the threshold is reached
 214         @param userCanPressKeyToSwapMode    if true, then the user can hold down the ctrl or command
 215                                 key to toggle velocity-sensitive mode
 216         @param modifiersToSwapModes  this is a set of modifier flags which will be tested when determining
 217                                 whether to enable/disable velocity-sensitive mode
 218     */
 219     void setVelocityModeParameters (double sensitivity = 1.0,
 220                                     int threshold = 1,
 221                                     double offset = 0.0,
 222                                     bool userCanPressKeyToSwapMode = true,
 223                                     ModifierKeys::Flags modifiersToSwapModes = ModifierKeys::ctrlAltCommandModifiers);
 224
 225     /** Returns the velocity sensitivity setting.
 226         @see setVelocityModeParameters
 227     */
 228     double getVelocitySensitivity() const noexcept;
 229
 230     /** Returns the velocity threshold setting.
 231         @see setVelocityModeParameters
 232     */
 233     int getVelocityThreshold() const noexcept;
 234
 235     /** Returns the velocity offset setting.
 236         @see setVelocityModeParameters
 237     */
 238     double getVelocityOffset() const noexcept;
 239
 240     /** Returns the velocity user key setting.
 241         @see setVelocityModeParameters
 242     */
 243     bool getVelocityModeIsSwappable() const noexcept;
 244
 245     //==============================================================================
 246     /** Sets up a skew factor to alter the way values are distributed.
 247
 248         You may want to use a range of values on the slider where more accuracy
 249         is required towards one end of the range, so this will logarithmically
 250         spread the values across the length of the slider.
 251
 252         If the factor is < 1.0, the lower end of the range will fill more of the
 253         slider's length; if the factor is > 1.0, the upper end of the range
 254         will be expanded instead. A factor of 1.0 doesn't skew it at all.
 255
 256         If symmetricSkew is true, the skew factor applies from the middle of the slider
 257         to each of its ends.
 258
 259         To set the skew position by using a mid-point, use the setSkewFactorFromMidPoint()
 260         method instead.
 261
 262         @see getSkewFactor, setSkewFactorFromMidPoint, isSymmetricSkew
 263     */
 264     void setSkewFactor (double factor, bool symmetricSkew = false);
 265
 266     /** Sets up a skew factor to alter the way values are distributed.
 267
 268         This allows you to specify the slider value that should appear in the
 269         centre of the slider's visible range.
 270
 271         @see setSkewFactor, getSkewFactor, isSymmetricSkew
 272      */
 273     void setSkewFactorFromMidPoint (double sliderValueToShowAtMidPoint);
 274
 275     /** Returns the current skew factor.
 276         See setSkewFactor for more info.
 277         @see setSkewFactor, setSkewFactorFromMidPoint, isSymmetricSkew
 278     */
 279     double getSkewFactor() const noexcept;
 280
 281     /** Returns the whether the skew is symmetric from the midpoint to both sides.
 282         See setSkewFactor for more info.
 283         @see getSkewFactor, setSkewFactor, setSkewFactorFromMidPoint
 284      */
 285     bool isSymmetricSkew() const noexcept;
 286
 287     //==============================================================================
 288     /** Used by setIncDecButtonsMode().
 289     */
 290     enum IncDecButtonMode
 291     {
 292         incDecButtonsNotDraggable,
 293         incDecButtonsDraggable_AutoDirection,
 294         incDecButtonsDraggable_Horizontal,
 295         incDecButtonsDraggable_Vertical
 296     };
 297
 298     /** When the style is IncDecButtons, this lets you turn on a mode where the mouse
 299         can be dragged on the buttons to drag the values.
 300
 301         By default this is turned off. When enabled, clicking on the buttons still works
 302         them as normal, but by holding down the mouse on a button and dragging it a little
 303         distance, it flips into a mode where the value can be dragged. The drag direction can
 304         either be set explicitly to be vertical or horizontal, or can be set to
 305         incDecButtonsDraggable_AutoDirection so that it depends on whether the buttons
 306         are side-by-side or above each other.
 307     */
 308     void setIncDecButtonsMode (IncDecButtonMode mode);
 309
 310     //==============================================================================
 311     /** Changes the location and properties of the text-entry box.
 312
 313         @param newPosition          where it should go (or NoTextBox to not have one at all)
 314         @param isReadOnly           if true, it's a read-only display
 315         @param textEntryBoxWidth    the width of the text-box in pixels. Make sure this leaves enough
 316                                     room for the slider as well!
 317         @param textEntryBoxHeight   the height of the text-box in pixels. Make sure this leaves enough
 318                                     room for the slider as well!
 319
 320         @see setTextBoxIsEditable, getValueFromText, getTextFromValue
 321     */
 322     void setTextBoxStyle (TextEntryBoxPosition newPosition,
 323                           bool isReadOnly,
 324                           int textEntryBoxWidth,
 325                           int textEntryBoxHeight);
 326
 327     /** Returns the status of the text-box.
 328         @see setTextBoxStyle
 329     */
 330     TextEntryBoxPosition getTextBoxPosition() const noexcept;
 331
 332     /** Returns the width used for the text-box.
 333         @see setTextBoxStyle
 334     */
 335     int getTextBoxWidth() const noexcept;
 336
 337     /** Returns the height used for the text-box.
 338         @see setTextBoxStyle
 339     */
 340     int getTextBoxHeight() const noexcept;
 341
 342     /** Makes the text-box editable.
 343
 344         By default this is true, and the user can enter values into the textbox,
 345         but it can be turned off if that's not suitable.
 346
 347         @see setTextBoxStyle, getValueFromText, getTextFromValue
 348     */
 349     void setTextBoxIsEditable (bool shouldBeEditable);
 350
 351     /** Returns true if the text-box is read-only.
 352         @see setTextBoxStyle
 353     */
 354     bool isTextBoxEditable() const noexcept;
 355
 356     /** If the text-box is editable, this will give it the focus so that the user can
 357         type directly into it.
 358         This is basically the effect as the user clicking on it.
 359     */
 360     void showTextBox();
 361
 362     /** If the text-box currently has focus and is being edited, this resets it and takes keyboard
 363         focus away from it.
 364
 365         @param discardCurrentEditorContents     if true, the slider's value will be left
 366                                                 unchanged; if false, the current contents of the
 367                                                 text editor will be used to set the slider position
 368                                                 before it is hidden.
 369     */
 370     void hideTextBox (bool discardCurrentEditorContents);
 371
 372
 373     //==============================================================================
 374     /** Changes the slider's current value.
 375
 376         This will trigger a callback to Slider::Listener::sliderValueChanged() for any listeners
 377         that are registered, and will synchronously call the valueChanged() method in case subclasses
 378         want to handle it.
 379
 380         @param newValue         the new value to set - this will be restricted by the
 381                                 minimum and maximum range, and will be snapped to the
 382                                 nearest interval if one has been set
 383         @param notification     can be one of the NotificationType values, to request
 384                                 a synchronous or asynchronous call to the valueChanged() method
 385                                 of any Slider::Listeners that are registered. A notification will
 386                                 only be sent if the Slider's value has changed.
 387     */
 388     void setValue (double newValue, NotificationType notification = sendNotificationAsync);
 389
 390     /** Returns the slider's current value. */
 391     double getValue() const;
 392
 393     /** Returns the Value object that represents the slider's current position.
 394         You can use this Value object to connect the slider's position to external values or setters,
 395         either by taking a copy of the Value, or by using Value::referTo() to make it point to
 396         your own Value object.
 397         @see Value, getMaxValue, getMinValueObject
 398     */
 399     Value& getValueObject() noexcept;
 400
 401     //==============================================================================
 402     /** Sets the limits that the slider's value can take.
 403
 404         @param newMinimum   the lowest value allowed
 405         @param newMaximum   the highest value allowed
 406         @param newInterval  the steps in which the value is allowed to increase - if this
 407                             is not zero, the value will always be (newMinimum + (newInterval * an integer)).
 408     */
 409     void setRange (double newMinimum,
 410                    double newMaximum,
 411                    double newInterval = 0);
 412
 413     /** Sets the limits that the slider's value can take.
 414
 415         @param newRange     the range to allow
 416         @param newInterval  the steps in which the value is allowed to increase - if this
 417                             is not zero, the value will always be (newMinimum + (newInterval * an integer)).
 418     */
 419     void setRange (Range<double> newRange, double newInterval);
 420
 421     /** Sets a NormalisableRange to use for the Slider values.
 422
 423         @param newNormalisableRange     the NormalisableRange to use
 424     */
 425     void setNormalisableRange (NormalisableRange<double> newNormalisableRange);
 426
 427     /** Returns the slider's range. */
 428     Range<double> getRange() const noexcept;
 429
 430     /** Returns the current maximum value.
 431         @see setRange, getRange
 432     */
 433     double getMaximum() const noexcept;
 434
 435     /** Returns the current minimum value.
 436         @see setRange, getRange
 437     */
 438     double getMinimum() const noexcept;
 439
 440     /** Returns the current step-size for values.
 441         @see setRange, getRange
 442     */
 443     double getInterval() const noexcept;
 444
 445     //==============================================================================
 446     /** For a slider with two or three thumbs, this returns the lower of its values.
 447
 448         For a two-value slider, the values are controlled with getMinValue() and getMaxValue().
 449         A slider with three values also uses the normal getValue() and setValue() methods to
 450         control the middle value.
 451
 452         @see setMinValue, getMaxValue, TwoValueHorizontal, TwoValueVertical, ThreeValueHorizontal, ThreeValueVertical
 453     */
 454     double getMinValue() const;
 455
 456     /** For a slider with two or three thumbs, this returns the lower of its values.
 457         You can use this Value object to connect the slider's position to external values or setters,
 458         either by taking a copy of the Value, or by using Value::referTo() to make it point to
 459         your own Value object.
 460         @see Value, getMinValue, getMaxValueObject
 461     */
 462     Value& getMinValueObject() noexcept;
 463
 464     /** For a slider with two or three thumbs, this sets the lower of its values.
 465
 466         This will trigger a callback to Slider::Listener::sliderValueChanged() for any listeners
 467         that are registered, and will synchronously call the valueChanged() method in case subclasses
 468         want to handle it.
 469
 470         @param newValue         the new value to set - this will be restricted by the
 471                                 minimum and maximum range, and will be snapped to the nearest
 472                                 interval if one has been set.
 473         @param notification     can be one of the NotificationType values, to request
 474                                 a synchronous or asynchronous call to the valueChanged() method
 475                                 of any Slider::Listeners that are registered. A notification will
 476                                 only be sent if this value has changed.
 477         @param allowNudgingOfOtherValues  if false, this value will be restricted to being below the
 478                                         max value (in a two-value slider) or the mid value (in a three-value
 479                                         slider). If true, then if this value goes beyond those values,
 480                                         it will push them along with it.
 481         @see getMinValue, setMaxValue, setValue
 482     */
 483     void setMinValue (double newValue,
 484                       NotificationType notification = sendNotificationAsync,
 485                       bool allowNudgingOfOtherValues = false);
 486
 487     /** For a slider with two or three thumbs, this returns the higher of its values.
 488
 489         For a two-value slider, the values are controlled with getMinValue() and getMaxValue().
 490         A slider with three values also uses the normal getValue() and setValue() methods to
 491         control the middle value.
 492
 493         @see getMinValue, TwoValueHorizontal, TwoValueVertical, ThreeValueHorizontal, ThreeValueVertical
 494     */
 495     double getMaxValue() const;
 496
 497     /** For a slider with two or three thumbs, this returns the higher of its values.
 498         You can use this Value object to connect the slider's position to external values or setters,
 499         either by taking a copy of the Value, or by using Value::referTo() to make it point to
 500         your own Value object.
 501         @see Value, getMaxValue, getMinValueObject
 502     */
 503     Value& getMaxValueObject() noexcept;
 504
 505     /** For a slider with two or three thumbs, this sets the lower of its values.
 506
 507         This will trigger a callback to Slider::Listener::sliderValueChanged() for any listeners
 508         that are registered, and will synchronously call the valueChanged() method in case subclasses
 509         want to handle it.
 510
 511         @param newValue         the new value to set - this will be restricted by the
 512                                 minimum and maximum range, and will be snapped to the nearest
 513                                 interval if one has been set.
 514         @param notification     can be one of the NotificationType values, to request
 515                                 a synchronous or asynchronous call to the valueChanged() method
 516                                 of any Slider::Listeners that are registered. A notification will
 517                                 only be sent if this value has changed.
 518         @param allowNudgingOfOtherValues  if false, this value will be restricted to being above the
 519                                         min value (in a two-value slider) or the mid value (in a three-value
 520                                         slider). If true, then if this value goes beyond those values,
 521                                         it will push them along with it.
 522         @see getMaxValue, setMinValue, setValue
 523     */
 524     void setMaxValue (double newValue,
 525                       NotificationType notification = sendNotificationAsync,
 526                       bool allowNudgingOfOtherValues = false);
 527
 528     /** For a slider with two or three thumbs, this sets the minimum and maximum thumb positions.
 529
 530         This will trigger a callback to Slider::Listener::sliderValueChanged() for any listeners
 531         that are registered, and will synchronously call the valueChanged() method in case subclasses
 532         want to handle it.
 533
 534         @param newMinValue      the new minimum value to set - this will be snapped to the
 535                                 nearest interval if one has been set.
 536         @param newMaxValue      the new minimum value to set - this will be snapped to the
 537                                 nearest interval if one has been set.
 538         @param notification     can be one of the NotificationType values, to request
 539                                 a synchronous or asynchronous call to the valueChanged() method
 540                                 of any Slider::Listeners that are registered. A notification will
 541                                 only be sent if one or more of the values has changed.
 542         @see setMaxValue, setMinValue, setValue
 543     */
 544     void setMinAndMaxValues (double newMinValue, double newMaxValue,
 545                              NotificationType notification = sendNotificationAsync);
 546
 547     //==============================================================================
 548     /** A class for receiving callbacks from a Slider.
 549
 550         To be told when a slider's value changes, you can register a Slider::Listener
 551         object using Slider::addListener().
 552
 553         @see Slider::addListener, Slider::removeListener
 554     */
 555     class JUCE_API  Listener
 556     {
 557     public:
 558         //==============================================================================
 559         /** Destructor. */
 560         virtual ~Listener() = default;
 561
 562         //==============================================================================
 563         /** Called when the slider's value is changed.
 564
 565             This may be caused by dragging it, or by typing in its text entry box,
 566             or by a call to Slider::setValue().
 567
 568             You can find out the new value using Slider::getValue().
 569
 570             @see Slider::valueChanged
 571         */
 572         virtual void sliderValueChanged (Slider* slider) = 0;
 573
 574         //==============================================================================
 575         /** Called when the slider is about to be dragged.
 576
 577             This is called when a drag begins, then it's followed by multiple calls
 578             to sliderValueChanged(), and then sliderDragEnded() is called after the
 579             user lets go.
 580
 581             @see sliderDragEnded, Slider::startedDragging
 582         */
 583         virtual void sliderDragStarted (Slider*) {}
 584
 585         /** Called after a drag operation has finished.
 586             @see sliderDragStarted, Slider::stoppedDragging
 587         */
 588         virtual void sliderDragEnded (Slider*) {}
 589     };
 590
 591     /** Adds a listener to be called when this slider's value changes. */
 592     void addListener (Listener* listener);
 593
 594     /** Removes a previously-registered listener. */
 595     void removeListener (Listener* listener);
 596
 597     //==============================================================================
 598     /** You can assign a lambda to this callback object to have it called when the slider value is changed. */
 599     std::function<void()> onValueChange;
 600
 601     /** You can assign a lambda to this callback object to have it called when the slider's drag begins. */
 602     std::function<void()> onDragStart;
 603
 604     /** You can assign a lambda to this callback object to have it called when the slider's drag ends. */
 605     std::function<void()> onDragEnd;
 606
 607     /** You can assign a lambda that will be used to convert textual values to the slider's normalised position. */
 608     std::function<double (const String&)> valueFromTextFunction;
 609
 610     /** You can assign a lambda that will be used to convert the slider's normalised position to a textual value. */
 611     std::function<String (double)> textFromValueFunction;
 612
 613     //==============================================================================
 614     /** This lets you choose whether double-clicking or single-clicking with a specified
 615         key modifier moves the slider to a given position.
 616
 617         By default this is turned off, but it's handy if you want either of these actions
 618         to act as a quick way of resetting a slider. Just pass in the value you want it to
 619         go to when double-clicked. By default the key modifier is the alt key but you can
 620         pass in another key modifier, or none to disable this behaviour.
 621
 622         @see getDoubleClickReturnValue
 623     */
 624     void setDoubleClickReturnValue (bool shouldDoubleClickBeEnabled,
 625                                     double valueToSetOnDoubleClick,
 626                                     ModifierKeys singleClickModifiers = ModifierKeys::altModifier);
 627
 628     /** Returns the values last set by setDoubleClickReturnValue() method.
 629         @see setDoubleClickReturnValue
 630     */
 631     double getDoubleClickReturnValue() const noexcept;
 632
 633     /** Returns true if double-clicking to reset to a default value is enabled.
 634         @see setDoubleClickReturnValue
 635     */
 636     bool isDoubleClickReturnEnabled() const noexcept;
 637
 638     //==============================================================================
 639     /** Tells the slider whether to keep sending change messages while the user
 640         is dragging the slider.
 641
 642         If set to true, a change message will only be sent when the user has
 643         dragged the slider and let go. If set to false (the default), then messages
 644         will be continuously sent as they drag it while the mouse button is still
 645         held down.
 646     */
 647     void setChangeNotificationOnlyOnRelease (bool onlyNotifyOnRelease);
 648
 649     /** This lets you change whether the slider thumb jumps to the mouse position
 650         when you click.
 651
 652         By default, this is true. If it's false, then the slider moves with relative
 653         motion when you drag it.
 654
 655         This only applies to linear bars, and won't affect two- or three- value
 656         sliders.
 657     */
 658     void setSliderSnapsToMousePosition (bool shouldSnapToMouse);
 659
 660     /** Returns true if setSliderSnapsToMousePosition() has been enabled. */
 661     bool getSliderSnapsToMousePosition() const noexcept;
 662
 663     /** If enabled, this gives the slider a pop-up bubble which appears while the
 664         slider is being dragged or hovered-over.
 665
 666         This can be handy if your slider doesn't have a text-box, so that users can
 667         see the value just when they're changing it.
 668
 669         If you pass a component as the parentComponentToUse parameter, the pop-up
 670         bubble will be added as a child of that component when it's needed. If you
 671         pass nullptr, the pop-up will be placed on the desktop instead (note that it's a
 672         transparent window, so if you're using an OS that can't do transparent windows
 673         you'll have to add it to a parent component instead).
 674
 675         By default the popup display shown when hovering will remain visible for 2 seconds,
 676         but it is possible to change this by passing a different hoverTimeout value. A
 677         value of -1 will cause the popup to remain until a mouseExit() occurs on the slider.
 678     */
 679     void setPopupDisplayEnabled (bool shouldShowOnMouseDrag,
 680                                  bool shouldShowOnMouseHover,
 681                                  Component* parentComponentToUse,
 682                                  int hoverTimeout = 2000);
 683
 684     /** If a popup display is enabled and is currently visible, this returns the component
 685         that is being shown, or nullptr if none is currently in use.
 686         @see setPopupDisplayEnabled
 687     */
 688     Component* getCurrentPopupDisplay() const noexcept;
 689
 690     /** If this is set to true, then right-clicking on the slider will pop-up
 691         a menu to let the user change the way it works.
 692
 693         By default this is turned off, but when turned on, the menu will include
 694         things like velocity sensitivity, and for rotary sliders, whether they
 695         use a linear or rotary mouse-drag to move them.
 696     */
 697     void setPopupMenuEnabled (bool menuEnabled);
 698
 699     /** This can be used to stop the mouse scroll-wheel from moving the slider.
 700         By default it's enabled.
 701     */
 702     void setScrollWheelEnabled (bool enabled);
 703
 704     /** Returns true if the scroll wheel can move the slider. */
 705     bool isScrollWheelEnabled() const noexcept;
 706
 707     /** Returns a number to indicate which thumb is currently being dragged by the mouse.
 708
 709         This will return 0 for the main thumb, 1 for the minimum-value thumb, 2 for
 710         the maximum-value thumb, or -1 if none is currently down.
 711     */
 712     int getThumbBeingDragged() const noexcept;
 713
 714     //==============================================================================
 715     /** Callback to indicate that the user is about to start dragging the slider.
 716         @see Slider::Listener::sliderDragStarted
 717     */
 718     virtual void startedDragging();
 719
 720     /** Callback to indicate that the user has just stopped dragging the slider.
 721         @see Slider::Listener::sliderDragEnded
 722     */
 723     virtual void stoppedDragging();
 724
 725     /** Callback to indicate that the user has just moved the slider.
 726         @see Slider::Listener::sliderValueChanged
 727     */
 728     virtual void valueChanged();
 729
 730     //==============================================================================
 731     /** Subclasses can override this to convert a text string to a value.
 732
 733         When the user enters something into the text-entry box, this method is
 734         called to convert it to a value.
 735         The default implementation just tries to convert it to a double.
 736
 737         @see getTextFromValue
 738     */
 739     virtual double getValueFromText (const String& text);
 740
 741     /** Turns the slider's current value into a text string.
 742
 743         Subclasses can override this to customise the formatting of the text-entry box.
 744
 745         The default implementation just turns the value into a string, using
 746         a number of decimal places based on the range interval. If a suffix string
 747         has been set using setTextValueSuffix(), this will be appended to the text.
 748
 749         @see getValueFromText
 750     */
 751     virtual String getTextFromValue (double value);
 752
 753     /** Sets a suffix to append to the end of the numeric value when it's displayed as
 754         a string.
 755
 756         This is used by the default implementation of getTextFromValue(), and is just
 757         appended to the numeric value. For more advanced formatting, you can override
 758         getTextFromValue() and do something else.
 759     */
 760     void setTextValueSuffix (const String& suffix);
 761
 762     /** Returns the suffix that was set by setTextValueSuffix(). */
 763     String getTextValueSuffix() const;
 764
 765     /** Returns the best number of decimal places to use when displaying this
 766         slider's value.
 767         It calculates the fewest decimal places needed to represent numbers with
 768         the slider's interval setting.
 769
 770         @see setNumDecimalPlacesToDisplay
 771     */
 772     int getNumDecimalPlacesToDisplay() const noexcept;
 773
 774     /** Modifies the best number of decimal places to use when displaying this
 775         slider's value.
 776
 777         @see getNumDecimalPlacesToDisplay
 778     */
 779     void setNumDecimalPlacesToDisplay (int decimalPlacesToDisplay);
 780
 781     //==============================================================================
 782     /** Allows a user-defined mapping of distance along the slider to its value.
 783
 784         The default implementation for this performs the skewing operation that
 785         can be set up in the setSkewFactor() method. Override it if you need
 786         some kind of custom mapping instead, but make sure you also implement the
 787         inverse function in valueToProportionOfLength().
 788
 789         @param proportion       a value 0 to 1.0, indicating a distance along the slider
 790         @returns                the slider value that is represented by this position
 791         @see valueToProportionOfLength
 792     */
 793     virtual double proportionOfLengthToValue (double proportion);
 794
 795     /** Allows a user-defined mapping of value to the position of the slider along its length.
 796
 797         The default implementation for this performs the skewing operation that
 798         can be set up in the setSkewFactor() method. Override it if you need
 799         some kind of custom mapping instead, but make sure you also implement the
 800         inverse function in proportionOfLengthToValue().
 801
 802         @param value            a valid slider value, between the range of values specified in
 803                                 setRange()
 804         @returns                a value 0 to 1.0 indicating the distance along the slider that
 805                                 represents this value
 806         @see proportionOfLengthToValue
 807     */
 808     virtual double valueToProportionOfLength (double value);
 809
 810     /** Returns the X or Y coordinate of a value along the slider's length.
 811
 812         If the slider is horizontal, this will be the X coordinate of the given
 813         value, relative to the left of the slider. If it's vertical, then this will
 814         be the Y coordinate, relative to the top of the slider.
 815
 816         If the slider is rotary, this will throw an assertion and return 0. If the
 817         value is out-of-range, it will be constrained to the length of the slider.
 818     */
 819     float getPositionOfValue (double value) const;
 820
 821     //==============================================================================
 822     /** This can be overridden to allow the slider to snap to user-definable values.
 823
 824         If overridden, it will be called when the user tries to move the slider to
 825         a given position, and allows a subclass to sanity-check this value, possibly
 826         returning a different value to use instead.
 827
 828         @param attemptedValue   the value the user is trying to enter
 829         @param dragMode         indicates whether the user is dragging with
 830                                 the mouse; notDragging if they are entering the value
 831                                 using the text box or other non-dragging interaction
 832         @returns                the value to use instead
 833     */
 834     virtual double snapValue (double attemptedValue, DragMode dragMode);
 835
 836
 837     //==============================================================================
 838     /** This can be called to force the text box to update its contents.
 839         (Not normally needed, as this is done automatically).
 840     */
 841     void updateText();
 842
 843     /** True if the slider moves horizontally. */
 844     bool isHorizontal() const noexcept;
 845     /** True if the slider moves vertically. */
 846     bool isVertical() const noexcept;
 847     /** True if the slider is in a rotary mode. */
 848     bool isRotary() const noexcept;
 849     /** True if the slider is in a linear bar mode. */
 850     bool isBar() const noexcept;
 851     /** True if the slider has two thumbs. */
 852     bool isTwoValue() const noexcept;
 853     /** True if the slider has three thumbs. */
 854     bool isThreeValue() const noexcept;
 855
 856     //==============================================================================
 857     /** A set of colour IDs to use to change the colour of various aspects of the slider.
 858
 859         These constants can be used either via the Component::setColour(), or LookAndFeel::setColour()
 860         methods.
 861
 862         @see Component::setColour, Component::findColour, LookAndFeel::setColour, LookAndFeel::findColour
 863     */
 864     enum ColourIds
 865     {
 866         backgroundColourId          = 0x1001200,  /**< A colour to use to fill the slider's background. */
 867         thumbColourId               = 0x1001300,  /**< The colour to draw the thumb with. It's up to the look
 868                                                        and feel class how this is used. */
 869         trackColourId               = 0x1001310,  /**< The colour to draw the groove that the thumb moves along. */
 870         rotarySliderFillColourId    = 0x1001311,  /**< For rotary sliders, this colour fills the outer curve. */
 871         rotarySliderOutlineColourId = 0x1001312,  /**< For rotary sliders, this colour is used to draw the outer curve's outline. */
 872
 873         textBoxTextColourId         = 0x1001400,  /**< The colour for the text in the text-editor box used for editing the value. */
 874         textBoxBackgroundColourId   = 0x1001500,  /**< The background colour for the text-editor box. */
 875         textBoxHighlightColourId    = 0x1001600,  /**< The text highlight colour for the text-editor box. */
 876         textBoxOutlineColourId      = 0x1001700   /**< The colour to use for a border around the text-editor box. */
 877     };
 878
 879     //==============================================================================
 880     /** A struct defining the placement of the slider area and the text box area
 881         relative to the bounds of the whole Slider component.
 882      */
 883     struct SliderLayout
 884     {
 885         Rectangle<int> sliderBounds;
 886         Rectangle<int> textBoxBounds;
 887     };
 888
 889     //==============================================================================
 890     /** An RAII class for sending slider listener drag messages.
 891
 892         This is useful if you are programmatically updating the slider's value and want
 893         to imitate a mouse event, for example in a custom AccessibilityHandler.
 894
 895         @see Slider::Listener
 896     */
 897     class JUCE_API  ScopedDragNotification
 898     {
 899     public:
 900         explicit ScopedDragNotification (Slider&);
 901         ~ScopedDragNotification();
 902
 903     private:
 904         Slider& sliderBeingDragged;
 905
 906         JUCE_DECLARE_NON_MOVEABLE (ScopedDragNotification)
 907         JUCE_DECLARE_NON_COPYABLE (ScopedDragNotification)
 908     };
 909
 910     //==============================================================================
 911     /** This abstract base class is implemented by LookAndFeel classes to provide
 912         slider drawing functionality.
 913     */
 914     struct JUCE_API  LookAndFeelMethods
 915     {
 916         virtual ~LookAndFeelMethods() = default;
 917
 918         //==============================================================================
 919         virtual void drawLinearSlider (Graphics&,
 920                                        int x, int y, int width, int height,
 921                                        float sliderPos,
 922                                        float minSliderPos,
 923                                        float maxSliderPos,
 924                                        const Slider::SliderStyle,
 925                                        Slider&) = 0;
 926
 927         virtual void drawLinearSliderBackground (Graphics&,
 928                                                  int x, int y, int width, int height,
 929                                                  float sliderPos,
 930                                                  float minSliderPos,
 931                                                  float maxSliderPos,
 932                                                  const Slider::SliderStyle style,
 933                                                  Slider&) = 0;
 934
 935         virtual void drawLinearSliderThumb (Graphics&,
 936                                             int x, int y, int width, int height,
 937                                             float sliderPos,
 938                                             float minSliderPos,
 939                                             float maxSliderPos,
 940                                             const Slider::SliderStyle,
 941                                             Slider&) = 0;
 942
 943         virtual int getSliderThumbRadius (Slider&) = 0;
 944
 945         virtual void drawRotarySlider (Graphics&,
 946                                        int x, int y, int width, int height,
 947                                        float sliderPosProportional,
 948                                        float rotaryStartAngle,
 949                                        float rotaryEndAngle,
 950                                        Slider&) = 0;
 951
 952         virtual Button* createSliderButton (Slider&, bool isIncrement) = 0;
 953         virtual Label* createSliderTextBox (Slider&) = 0;
 954
 955         virtual ImageEffectFilter* getSliderEffect (Slider&) = 0;
 956
 957         virtual Font getSliderPopupFont (Slider&) = 0;
 958         virtual int getSliderPopupPlacement (Slider&) = 0;
 959
 960         virtual SliderLayout getSliderLayout (Slider&) = 0;
 961     };
 962
 963     //==============================================================================
 964     /** @internal */
 965     void paint (Graphics&) override;
 966     /** @internal */
 967     void resized() override;
 968     /** @internal */
 969     void mouseDown (const MouseEvent&) override;
 970     /** @internal */
 971     void mouseUp (const MouseEvent&) override;
 972     /** @internal */
 973     void mouseDrag (const MouseEvent&) override;
 974     /** @internal */
 975     void mouseDoubleClick (const MouseEvent&) override;
 976     /** @internal */
 977     void mouseWheelMove (const MouseEvent&, const MouseWheelDetails&) override;
 978     /** @internal */
 979     void modifierKeysChanged (const ModifierKeys&) override;
 980     /** @internal */
 981     void lookAndFeelChanged() override;
 982     /** @internal */
 983     void enablementChanged() override;
 984     /** @internal */
 985     void focusOfChildComponentChanged (FocusChangeType) override;
 986     /** @internal */
 987     void colourChanged() override;
 988     /** @internal */
 989     void mouseMove (const MouseEvent&) override;
 990     /** @internal */
 991     void mouseExit (const MouseEvent&) override;
 992     /** @internal */
 993     void mouseEnter (const MouseEvent&) override;
 994     /** @internal */
 995     bool keyPressed (const KeyPress&) override;
 996
 997     //==============================================================================
 998    #ifndef DOXYGEN
 999     // These methods' bool parameters have changed: see the new method signature.
1000     [[deprecated]] void setValue (double, bool);
1001     [[deprecated]] void setValue (double, bool, bool);
1002     [[deprecated]] void setMinValue (double, bool, bool, bool);
1003     [[deprecated]] void setMinValue (double, bool, bool);
1004     [[deprecated]] void setMinValue (double, bool);
1005     [[deprecated]] void setMaxValue (double, bool, bool, bool);
1006     [[deprecated]] void setMaxValue (double, bool, bool);
1007     [[deprecated]] void setMaxValue (double, bool);
1008     [[deprecated]] void setMinAndMaxValues (double, double, bool, bool);
1009     [[deprecated]] void setMinAndMaxValues (double, double, bool);
1010    #endif
1011
1012 private:
1013     //==============================================================================
1014     JUCE_PUBLIC_IN_DLL_BUILD (class Pimpl)
1015     std::unique_ptr<Pimpl> pimpl;
1016
1017     std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
1018     void init (SliderStyle, TextEntryBoxPosition);
1019
1020     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Slider)
1021 };
1022
1023
1024 } // namespace juce