juce/source/src/gui/components/layout/juce_ScrollBar.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_SCROLLBAR_JUCEHEADER__
  27 #define __JUCE_SCROLLBAR_JUCEHEADER__
  28
  29 #include "../../../events/juce_AsyncUpdater.h"
  30 #include "../../../maths/juce_Range.h"
  31 #include "../../../events/juce_Timer.h"
  32 #include "../buttons/juce_Button.h"
  33
  34
  35 //==============================================================================
  36 /**
  37     A scrollbar component.
  38
  39     To use a scrollbar, set up its total range using the setRangeLimits() method - this
  40     sets the range of values it can represent. Then you can use setCurrentRange() to
  41     change the position and size of the scrollbar's 'thumb'.
  42
  43     Registering a ScrollBar::Listener with the scrollbar will allow you to find out when
  44     the user moves it, and you can use the getCurrentRangeStart() to find out where
  45     they moved it to.
  46
  47     The scrollbar will adjust its own visibility according to whether its thumb size
  48     allows it to actually be scrolled.
  49
  50     For most purposes, it's probably easier to use a ViewportContainer or ListBox
  51     instead of handling a scrollbar directly.
  52
  53     @see ScrollBar::Listener
  54 */
  55 class JUCE_API  ScrollBar  : public Component,
  56                              public AsyncUpdater,
  57                              private Timer
  58 {
  59 public:
  60     //==============================================================================
  61     /** Creates a Scrollbar.
  62
  63         @param isVertical           whether it should be a vertical or horizontal bar
  64         @param buttonsAreVisible    whether to show the up/down or left/right buttons
  65     */
  66     ScrollBar (bool isVertical,
  67                bool buttonsAreVisible = true);
  68
  69     /** Destructor. */
  70     ~ScrollBar();
  71
  72     //==============================================================================
  73     /** Returns true if the scrollbar is vertical, false if it's horizontal. */
  74     bool isVertical() const noexcept                                { return vertical; }
  75
  76     /** Changes the scrollbar's direction.
  77
  78         You'll also need to resize the bar appropriately - this just changes its internal
  79         layout.
  80
  81         @param shouldBeVertical     true makes it vertical; false makes it horizontal.
  82     */
  83     void setOrientation (bool shouldBeVertical);
  84
  85     /** Shows or hides the scrollbar's buttons. */
  86     void setButtonVisibility (bool buttonsAreVisible);
  87
  88     /** Tells the scrollbar whether to make itself invisible when not needed.
  89
  90         The default behaviour is for a scrollbar to become invisible when the thumb
  91         fills the whole of its range (i.e. when it can't be moved). Setting this
  92         value to false forces the bar to always be visible.
  93         @see autoHides()
  94     */
  95     void setAutoHide (bool shouldHideWhenFullRange);
  96
  97     /** Returns true if this scrollbar is set to auto-hide when its thumb is as big
  98         as its maximum range.
  99         @see setAutoHide
 100     */
 101     bool autoHides() const noexcept;
 102
 103     //==============================================================================
 104     /** Sets the minimum and maximum values that the bar will move between.
 105
 106         The bar's thumb will always be constrained so that the entire thumb lies
 107         within this range.
 108
 109         @see setCurrentRange
 110     */
 111     void setRangeLimits (const Range<double>& newRangeLimit);
 112
 113     /** Sets the minimum and maximum values that the bar will move between.
 114
 115         The bar's thumb will always be constrained so that the entire thumb lies
 116         within this range.
 117
 118         @see setCurrentRange
 119     */
 120     void setRangeLimits (double minimum, double maximum);
 121
 122     /** Returns the current limits on the thumb position.
 123         @see setRangeLimits
 124     */
 125     const Range<double> getRangeLimit() const noexcept              { return totalRange; }
 126
 127     /** Returns the lower value that the thumb can be set to.
 128
 129         This is the value set by setRangeLimits().
 130     */
 131     double getMinimumRangeLimit() const noexcept                    { return totalRange.getStart(); }
 132
 133     /** Returns the upper value that the thumb can be set to.
 134
 135         This is the value set by setRangeLimits().
 136     */
 137     double getMaximumRangeLimit() const noexcept                    { return totalRange.getEnd(); }
 138
 139     //==============================================================================
 140     /** Changes the position of the scrollbar's 'thumb'.
 141
 142         If this method call actually changes the scrollbar's position, it will trigger an
 143         asynchronous call to ScrollBar::Listener::scrollBarMoved() for all the listeners that
 144         are registered.
 145
 146         @see getCurrentRange. setCurrentRangeStart
 147     */
 148     void setCurrentRange (const Range<double>& newRange);
 149
 150     /** Changes the position of the scrollbar's 'thumb'.
 151
 152         This sets both the position and size of the thumb - to just set the position without
 153         changing the size, you can use setCurrentRangeStart().
 154
 155         If this method call actually changes the scrollbar's position, it will trigger an
 156         asynchronous call to ScrollBar::Listener::scrollBarMoved() for all the listeners that
 157         are registered.
 158
 159         @param newStart     the top (or left) of the thumb, in the range
 160                             getMinimumRangeLimit() <= newStart <= getMaximumRangeLimit(). If the
 161                             value is beyond these limits, it will be clipped.
 162         @param newSize      the size of the thumb, such that
 163                             getMinimumRangeLimit() <= newStart + newSize <= getMaximumRangeLimit(). If the
 164                             size is beyond these limits, it will be clipped.
 165         @see setCurrentRangeStart, getCurrentRangeStart, getCurrentRangeSize
 166     */
 167     void setCurrentRange (double newStart, double newSize);
 168
 169     /** Moves the bar's thumb position.
 170
 171         This will move the thumb position without changing the thumb size. Note
 172         that the maximum thumb start position is (getMaximumRangeLimit() - getCurrentRangeSize()).
 173
 174         If this method call actually changes the scrollbar's position, it will trigger an
 175         asynchronous call to ScrollBar::Listener::scrollBarMoved() for all the listeners that
 176         are registered.
 177
 178         @see setCurrentRange
 179     */
 180     void setCurrentRangeStart (double newStart);
 181
 182     /** Returns the current thumb range.
 183         @see getCurrentRange, setCurrentRange
 184     */
 185     const Range<double> getCurrentRange() const noexcept            { return visibleRange; }
 186
 187     /** Returns the position of the top of the thumb.
 188         @see getCurrentRange, setCurrentRangeStart
 189     */
 190     double getCurrentRangeStart() const noexcept                    { return visibleRange.getStart(); }
 191
 192     /** Returns the current size of the thumb.
 193         @see getCurrentRange, setCurrentRange
 194     */
 195     double getCurrentRangeSize() const noexcept                     { return visibleRange.getLength(); }
 196
 197     //==============================================================================
 198     /** Sets the amount by which the up and down buttons will move the bar.
 199
 200         The value here is in terms of the total range, and is added or subtracted
 201         from the thumb position when the user clicks an up/down (or left/right) button.
 202     */
 203     void setSingleStepSize (double newSingleStepSize);
 204
 205     /** Moves the scrollbar by a number of single-steps.
 206
 207         This will move the bar by a multiple of its single-step interval (as
 208         specified using the setSingleStepSize() method).
 209
 210         A positive value here will move the bar down or to the right, a negative
 211         value moves it up or to the left.
 212     */
 213     void moveScrollbarInSteps (int howManySteps);
 214
 215     /** Moves the scroll bar up or down in pages.
 216
 217         This will move the bar by a multiple of its current thumb size, effectively
 218         doing a page-up or down.
 219
 220         A positive value here will move the bar down or to the right, a negative
 221         value moves it up or to the left.
 222     */
 223     void moveScrollbarInPages (int howManyPages);
 224
 225     /** Scrolls to the top (or left).
 226
 227         This is the same as calling setCurrentRangeStart (getMinimumRangeLimit());
 228     */
 229     void scrollToTop();
 230
 231     /** Scrolls to the bottom (or right).
 232
 233         This is the same as calling setCurrentRangeStart (getMaximumRangeLimit() - getCurrentRangeSize());
 234     */
 235     void scrollToBottom();
 236
 237     /** Changes the delay before the up and down buttons autorepeat when they are held
 238         down.
 239
 240         For an explanation of what the parameters are for, see Button::setRepeatSpeed().
 241
 242         @see Button::setRepeatSpeed
 243     */
 244     void setButtonRepeatSpeed (int initialDelayInMillisecs,
 245                                int repeatDelayInMillisecs,
 246                                int minimumDelayInMillisecs = -1);
 247
 248     //==============================================================================
 249     /** A set of colour IDs to use to change the colour of various aspects of the component.
 250
 251         These constants can be used either via the Component::setColour(), or LookAndFeel::setColour()
 252         methods.
 253
 254         @see Component::setColour, Component::findColour, LookAndFeel::setColour, LookAndFeel::findColour
 255     */
 256     enum ColourIds
 257     {
 258         backgroundColourId          = 0x1000300,    /**< The background colour of the scrollbar. */
 259         thumbColourId               = 0x1000400,    /**< A base colour to use for the thumb. The look and feel will probably use variations on this colour. */
 260         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. */
 261     };
 262
 263     //==============================================================================
 264     /**
 265         A class for receiving events from a ScrollBar.
 266
 267         You can register a ScrollBar::Listener with a ScrollBar using the ScrollBar::addListener()
 268         method, and it will be called when the bar's position changes.
 269
 270         @see ScrollBar::addListener, ScrollBar::removeListener
 271     */
 272     class JUCE_API  Listener
 273     {
 274     public:
 275         /** Destructor. */
 276         virtual ~Listener() {}
 277
 278         /** Called when a ScrollBar is moved.
 279
 280             @param scrollBarThatHasMoved    the bar that has moved
 281             @param newRangeStart            the new range start of this bar
 282         */
 283         virtual void scrollBarMoved (ScrollBar* scrollBarThatHasMoved,
 284                                      double newRangeStart) = 0;
 285     };
 286
 287     /** Registers a listener that will be called when the scrollbar is moved. */
 288     void addListener (Listener* listener);
 289
 290     /** Deregisters a previously-registered listener. */
 291     void removeListener (Listener* listener);
 292
 293     //==============================================================================
 294     /** @internal */
 295     bool keyPressed (const KeyPress& key);
 296     /** @internal */
 297     void mouseWheelMove (const MouseEvent& e, float wheelIncrementX, float wheelIncrementY);
 298     /** @internal */
 299     void lookAndFeelChanged();
 300     /** @internal */
 301     void handleAsyncUpdate();
 302     /** @internal */
 303     void mouseDown (const MouseEvent& e);
 304     /** @internal */
 305     void mouseDrag (const MouseEvent& e);
 306     /** @internal */
 307     void mouseUp   (const MouseEvent& e);
 308     /** @internal */
 309     void paint (Graphics& g);
 310     /** @internal */
 311     void resized();
 312
 313 private:
 314     //==============================================================================
 315     Range <double> totalRange, visibleRange;
 316     double singleStepSize, dragStartRange;
 317     int thumbAreaStart, thumbAreaSize, thumbStart, thumbSize;
 318     int dragStartMousePos, lastMousePos;
 319     int initialDelayInMillisecs, repeatDelayInMillisecs, minimumDelayInMillisecs;
 320     bool vertical, isDraggingThumb, autohides;
 321     class ScrollbarButton;
 322     friend class ScopedPointer<ScrollbarButton>;
 323     ScopedPointer<ScrollbarButton> upButton, downButton;
 324     ListenerList <Listener> listeners;
 325
 326     void updateThumbPosition();
 327     void timerCallback();
 328
 329     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ScrollBar);
 330 };
 331
 332 /** This typedef is just for compatibility with old code - newer code should use the ScrollBar::Listener class directly. */
 333 typedef ScrollBar::Listener ScrollBarListener;
 334
 335
 336 #endif   // __JUCE_SCROLLBAR_JUCEHEADER__