source/modules/juce_gui_basics/layout/juce_ScrollBar.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 scrollbar component.
  32
  33     To use a scrollbar, set up its total range using the setRangeLimits() method - this
  34     sets the range of values it can represent. Then you can use setCurrentRange() to
  35     change the position and size of the scrollbar's 'thumb'.
  36
  37     Registering a ScrollBar::Listener with the scrollbar will allow you to find out when
  38     the user moves it, and you can use the getCurrentRangeStart() to find out where
  39     they moved it to.
  40
  41     The scrollbar will adjust its own visibility according to whether its thumb size
  42     allows it to actually be scrolled.
  43
  44     For most purposes, it's probably easier to use a Viewport or ListBox
  45     instead of handling a scrollbar directly.
  46
  47     @see ScrollBar::Listener
  48
  49     @tags{GUI}
  50 */
  51 class JUCE_API  ScrollBar  : public Component,
  52                              public AsyncUpdater,
  53                              private Timer
  54 {
  55 public:
  56     //==============================================================================
  57     /** Creates a Scrollbar.
  58         @param isVertical      specifies whether the bar should be a vertical or horizontal
  59     */
  60     ScrollBar (bool isVertical);
  61
  62     /** Destructor. */
  63     ~ScrollBar() override;
  64
  65     //==============================================================================
  66     /** Returns true if the scrollbar is vertical, false if it's horizontal. */
  67     bool isVertical() const noexcept                                { return vertical; }
  68
  69     /** Changes the scrollbar's direction.
  70
  71         You'll also need to resize the bar appropriately - this just changes its internal
  72         layout.
  73
  74         @param shouldBeVertical     true makes it vertical; false makes it horizontal.
  75     */
  76     void setOrientation (bool shouldBeVertical);
  77
  78     /** Tells the scrollbar whether to make itself invisible when not needed.
  79
  80         The default behaviour is for a scrollbar to become invisible when the thumb
  81         fills the whole of its range (i.e. when it can't be moved). Setting this
  82         value to false forces the bar to always be visible.
  83         @see autoHides()
  84     */
  85     void setAutoHide (bool shouldHideWhenFullRange);
  86
  87     /** Returns true if this scrollbar is set to auto-hide when its thumb is as big
  88         as its maximum range.
  89         @see setAutoHide
  90     */
  91     bool autoHides() const noexcept;
  92
  93     //==============================================================================
  94     /** Sets the minimum and maximum values that the bar will move between.
  95
  96         The bar's thumb will always be constrained so that the entire thumb lies
  97         within this range.
  98
  99         @param newRangeLimit    the new range.
 100         @param notification     whether to send a notification of the change to listeners.
 101                                 A notification will only be sent if the range has changed.
 102
 103         @see setCurrentRange
 104     */
 105     void setRangeLimits (Range<double> newRangeLimit,
 106                          NotificationType notification = sendNotificationAsync);
 107
 108     /** Sets the minimum and maximum values that the bar will move between.
 109
 110         The bar's thumb will always be constrained so that the entire thumb lies
 111         within this range.
 112
 113         @param minimum         the new range minimum.
 114         @param maximum         the new range maximum.
 115         @param notification    whether to send a notification of the change to listeners.
 116                                A notification will only be sent if the range has changed.
 117
 118         @see setCurrentRange
 119     */
 120     void setRangeLimits (double minimum, double maximum,
 121                          NotificationType notification = sendNotificationAsync);
 122
 123     /** Returns the current limits on the thumb position.
 124         @see setRangeLimits
 125     */
 126     Range<double> getRangeLimit() const noexcept                    { return totalRange; }
 127
 128     /** Returns the lower value that the thumb can be set to.
 129
 130         This is the value set by setRangeLimits().
 131     */
 132     double getMinimumRangeLimit() const noexcept                    { return totalRange.getStart(); }
 133
 134     /** Returns the upper value that the thumb can be set to.
 135
 136         This is the value set by setRangeLimits().
 137     */
 138     double getMaximumRangeLimit() const noexcept                    { return totalRange.getEnd(); }
 139
 140     //==============================================================================
 141     /** Changes the position of the scrollbar's 'thumb'.
 142
 143         This sets both the position and size of the thumb - to just set the position without
 144         changing the size, you can use setCurrentRangeStart().
 145
 146         If this method call actually changes the scrollbar's position, it will trigger an
 147         asynchronous call to ScrollBar::Listener::scrollBarMoved() for all the listeners that
 148         are registered.
 149
 150         The notification parameter can be used to optionally send or inhibit a callback to
 151         any scrollbar listeners.
 152
 153         @returns true if the range was changed, or false if nothing was changed.
 154         @see getCurrentRange. setCurrentRangeStart
 155     */
 156     bool setCurrentRange (Range<double> newRange,
 157                           NotificationType notification = sendNotificationAsync);
 158
 159     /** Changes the position of the scrollbar's 'thumb'.
 160
 161         This sets both the position and size of the thumb - to just set the position without
 162         changing the size, you can use setCurrentRangeStart().
 163
 164         @param newStart     the top (or left) of the thumb, in the range
 165                             getMinimumRangeLimit() <= newStart <= getMaximumRangeLimit(). If the
 166                             value is beyond these limits, it will be clipped.
 167         @param newSize      the size of the thumb, such that
 168                             getMinimumRangeLimit() <= newStart + newSize <= getMaximumRangeLimit(). If the
 169                             size is beyond these limits, it will be clipped.
 170         @param notification specifies if and how a callback should be made to any listeners
 171                             if the range actually changes
 172         @see setCurrentRangeStart, getCurrentRangeStart, getCurrentRangeSize
 173     */
 174     void setCurrentRange (double newStart, double newSize,
 175                           NotificationType notification = sendNotificationAsync);
 176
 177     /** Moves the bar's thumb position.
 178
 179         This will move the thumb position without changing the thumb size. Note
 180         that the maximum thumb start position is (getMaximumRangeLimit() - getCurrentRangeSize()).
 181
 182         If this method call actually changes the scrollbar's position, it will trigger an
 183         asynchronous call to ScrollBar::Listener::scrollBarMoved() for all the listeners that
 184         are registered.
 185
 186         @see setCurrentRange
 187     */
 188     void setCurrentRangeStart (double newStart,
 189                                NotificationType notification = sendNotificationAsync);
 190
 191     /** Returns the current thumb range.
 192         @see getCurrentRange, setCurrentRange
 193     */
 194     Range<double> getCurrentRange() const noexcept                  { return visibleRange; }
 195
 196     /** Returns the position of the top of the thumb.
 197         @see getCurrentRange, setCurrentRangeStart
 198     */
 199     double getCurrentRangeStart() const noexcept                    { return visibleRange.getStart(); }
 200
 201     /** Returns the current size of the thumb.
 202         @see getCurrentRange, setCurrentRange
 203     */
 204     double getCurrentRangeSize() const noexcept                     { return visibleRange.getLength(); }
 205
 206     //==============================================================================
 207     /** Sets the amount by which the up and down buttons will move the bar.
 208
 209         The value here is in terms of the total range, and is added or subtracted
 210         from the thumb position when the user clicks an up/down (or left/right) button.
 211     */
 212     void setSingleStepSize (double newSingleStepSize) noexcept;
 213
 214     /** Returns the current step size.
 215         @see setSingleStepSize
 216     */
 217     double getSingleStepSize() const noexcept                       { return singleStepSize; }
 218
 219     /** Moves the scrollbar by a number of single-steps.
 220
 221         This will move the bar by a multiple of its single-step interval (as
 222         specified using the setSingleStepSize() method).
 223
 224         A positive value here will move the bar down or to the right, a negative
 225         value moves it up or to the left.
 226
 227         @param howManySteps    the number of steps to move the scrollbar
 228         @param notification    whether to send a notification of the change to listeners.
 229                                A notification will only be sent if the position has changed.
 230
 231         @returns true if the scrollbar's position actually changed.
 232     */
 233     bool moveScrollbarInSteps (int howManySteps,
 234                                NotificationType notification = sendNotificationAsync);
 235
 236     /** Moves the scroll bar up or down in pages.
 237
 238         This will move the bar by a multiple of its current thumb size, effectively
 239         doing a page-up or down.
 240
 241         A positive value here will move the bar down or to the right, a negative
 242         value moves it up or to the left.
 243
 244         @param howManyPages    the number of pages to move the scrollbar
 245         @param notification    whether to send a notification of the change to listeners.
 246                                A notification will only be sent if the position has changed.
 247
 248         @returns true if the scrollbar's position actually changed.
 249     */
 250     bool moveScrollbarInPages (int howManyPages,
 251                                NotificationType notification = sendNotificationAsync);
 252
 253     /** Scrolls to the top (or left).
 254         This is the same as calling setCurrentRangeStart (getMinimumRangeLimit());
 255
 256         @param notification    whether to send a notification of the change to listeners.
 257                                A notification will only be sent if the position has changed.
 258
 259         @returns true if the scrollbar's position actually changed.
 260     */
 261     bool scrollToTop (NotificationType notification = sendNotificationAsync);
 262
 263     /** Scrolls to the bottom (or right).
 264         This is the same as calling setCurrentRangeStart (getMaximumRangeLimit() - getCurrentRangeSize());
 265
 266         @param notification    whether to send a notification of the change to listeners.
 267                                A notification will only be sent if the position has changed.
 268
 269         @returns true if the scrollbar's position actually changed.
 270     */
 271     bool scrollToBottom (NotificationType notification = sendNotificationAsync);
 272
 273     /** Changes the delay before the up and down buttons autorepeat when they are held
 274         down.
 275
 276         For an explanation of what the parameters are for, see Button::setRepeatSpeed().
 277
 278         @see Button::setRepeatSpeed
 279     */
 280     void setButtonRepeatSpeed (int initialDelayInMillisecs,
 281                                int repeatDelayInMillisecs,
 282                                int minimumDelayInMillisecs = -1);
 283
 284     //==============================================================================
 285     /** A set of colour IDs to use to change the colour of various aspects of the component.
 286
 287         These constants can be used either via the Component::setColour(), or LookAndFeel::setColour()
 288         methods.
 289
 290         @see Component::setColour, Component::findColour, LookAndFeel::setColour, LookAndFeel::findColour
 291     */
 292     enum ColourIds
 293     {
 294         backgroundColourId          = 0x1000300,    /**< The background colour of the scrollbar. */
 295         thumbColourId               = 0x1000400,    /**< A base colour to use for the thumb. The look and feel will probably use variations on this colour. */
 296         trackColourId               = 0x1000401     /**< A base colour to use for the slot area of the bar. The look and feel will probably use variations on this colour. */
 297     };
 298
 299     //==============================================================================
 300     /**
 301         A class for receiving events from a ScrollBar.
 302
 303         You can register a ScrollBar::Listener with a ScrollBar using the ScrollBar::addListener()
 304         method, and it will be called when the bar's position changes.
 305
 306         @see ScrollBar::addListener, ScrollBar::removeListener
 307     */
 308     class JUCE_API  Listener
 309     {
 310     public:
 311         /** Destructor. */
 312         virtual ~Listener() = default;
 313
 314         /** Called when a ScrollBar is moved.
 315
 316             @param scrollBarThatHasMoved    the bar that has moved
 317             @param newRangeStart            the new range start of this bar
 318         */
 319         virtual void scrollBarMoved (ScrollBar* scrollBarThatHasMoved,
 320                                      double newRangeStart) = 0;
 321     };
 322
 323     /** Registers a listener that will be called when the scrollbar is moved. */
 324     void addListener (Listener* listener);
 325
 326     /** Deregisters a previously-registered listener. */
 327     void removeListener (Listener* listener);
 328
 329     //==============================================================================
 330     /** This abstract base class is implemented by LookAndFeel classes to provide
 331         scrollbar-drawing functionality.
 332     */
 333     struct JUCE_API  LookAndFeelMethods
 334     {
 335         virtual ~LookAndFeelMethods() = default;
 336
 337         virtual bool areScrollbarButtonsVisible() = 0;
 338
 339         /** Draws one of the buttons on a scrollbar.
 340
 341             @param g                    the context to draw into
 342             @param scrollbar            the bar itself
 343             @param width                the width of the button
 344             @param height               the height of the button
 345             @param buttonDirection      the direction of the button, where 0 = up, 1 = right, 2 = down, 3 = left
 346             @param isScrollbarVertical  true if it's a vertical bar, false if horizontal
 347             @param isMouseOverButton    whether the mouse is currently over the button (also true if it's held down)
 348             @param isButtonDown         whether the mouse button's held down
 349         */
 350         virtual void drawScrollbarButton (Graphics& g,
 351                                           ScrollBar& scrollbar,
 352                                           int width, int height,
 353                                           int buttonDirection,
 354                                           bool isScrollbarVertical,
 355                                           bool isMouseOverButton,
 356                                           bool isButtonDown) = 0;
 357
 358         /** Draws the thumb area of a scrollbar.
 359
 360             @param g                    the context to draw into
 361             @param scrollbar            the bar itself
 362             @param x                    the x position of the left edge of the thumb area to draw in
 363             @param y                    the y position of the top edge of the thumb area to draw in
 364             @param width                the width of the thumb area to draw in
 365             @param height               the height of the thumb area to draw in
 366             @param isScrollbarVertical  true if it's a vertical bar, false if horizontal
 367             @param thumbStartPosition   for vertical bars, the y coordinate of the top of the
 368                                         thumb, or its x position for horizontal bars
 369             @param thumbSize            for vertical bars, the height of the thumb, or its width for
 370                                         horizontal bars. This may be 0 if the thumb shouldn't be drawn.
 371             @param isMouseOver          whether the mouse is over the thumb area, also true if the mouse is
 372                                         currently dragging the thumb
 373             @param isMouseDown          whether the mouse is currently dragging the scrollbar
 374         */
 375         virtual void drawScrollbar (Graphics& g, ScrollBar& scrollbar,
 376                                     int x, int y, int width, int height,
 377                                     bool isScrollbarVertical,
 378                                     int thumbStartPosition,
 379                                     int thumbSize,
 380                                     bool isMouseOver,
 381                                     bool isMouseDown) = 0;
 382
 383         /** Returns the component effect to use for a scrollbar */
 384         virtual ImageEffectFilter* getScrollbarEffect() = 0;
 385
 386         /** Returns the minimum length in pixels to use for a scrollbar thumb. */
 387         virtual int getMinimumScrollbarThumbSize (ScrollBar&) = 0;
 388
 389         /** Returns the default thickness to use for a scrollbar. */
 390         virtual int getDefaultScrollbarWidth() = 0;
 391
 392         /** Returns the length in pixels to use for a scrollbar button. */
 393         virtual int getScrollbarButtonSize (ScrollBar&) = 0;
 394     };
 395
 396     //==============================================================================
 397     /** @internal */
 398     bool keyPressed (const KeyPress&) override;
 399     /** @internal */
 400     void mouseWheelMove (const MouseEvent&, const MouseWheelDetails&) override;
 401     /** @internal */
 402     void lookAndFeelChanged() override;
 403     /** @internal */
 404     void mouseDown (const MouseEvent&) override;
 405     /** @internal */
 406     void mouseDrag (const MouseEvent&) override;
 407     /** @internal */
 408     void mouseUp   (const MouseEvent&) override;
 409     /** @internal */
 410     void paint (Graphics&) override;
 411     /** @internal */
 412     void resized() override;
 413     /** @internal */
 414     void parentHierarchyChanged() override;
 415     /** @internal */
 416     void setVisible (bool) override;
 417
 418 private:
 419     //==============================================================================
 420     Range<double> totalRange { 0.0, 1.0 }, visibleRange { 0.0, 1.0 };
 421     double singleStepSize = 0.1, dragStartRange = 0;
 422     int thumbAreaStart = 0, thumbAreaSize = 0, thumbStart = 0, thumbSize = 0;
 423     int dragStartMousePos = 0, lastMousePos = 0;
 424     int initialDelayInMillisecs = 100, repeatDelayInMillisecs = 50, minimumDelayInMillisecs = 10;
 425     bool vertical, isDraggingThumb = false, autohides = true, userVisibilityFlag = false;
 426     class ScrollbarButton;
 427     std::unique_ptr<ScrollbarButton> upButton, downButton;
 428     ListenerList<Listener> listeners;
 429
 430     std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
 431     void handleAsyncUpdate() override;
 432     void updateThumbPosition();
 433     void timerCallback() override;
 434     bool getVisibility() const noexcept;
 435
 436     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ScrollBar)
 437 };
 438
 439
 440 } // namespace juce