source/modules/juce_gui_basics/layout/juce_Viewport.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 Viewport is used to contain a larger child component, and allows the child
  32     to be automatically scrolled around.
  33
  34     To use a Viewport, just create one and set the component that goes inside it
  35     using the setViewedComponent() method. When the child component changes size,
  36     the Viewport will adjust its scrollbars accordingly.
  37
  38     A subclass of the viewport can be created which will receive calls to its
  39     visibleAreaChanged() method when the subcomponent changes position or size.
  40
  41
  42     @tags{GUI}
  43 */
  44 class JUCE_API  Viewport  : public Component,
  45                             private ComponentListener,
  46                             private ScrollBar::Listener
  47 {
  48 public:
  49     //==============================================================================
  50     /** Creates a Viewport.
  51
  52         The viewport is initially empty - use the setViewedComponent() method to
  53         add a child component for it to manage.
  54     */
  55     explicit Viewport (const String& componentName = String());
  56
  57     /** Destructor. */
  58     ~Viewport() override;
  59
  60     //==============================================================================
  61     /** Sets the component that this viewport will contain and scroll around.
  62
  63         This will add the given component to this Viewport and position it at (0, 0).
  64
  65         (Don't add or remove any child components directly using the normal
  66         Component::addChildComponent() methods).
  67
  68         @param newViewedComponent   the component to add to this viewport, or null to remove
  69                                     the current component.
  70         @param deleteComponentWhenNoLongerNeeded    if true, the component will be deleted
  71                                     automatically when the viewport is deleted or when a different
  72                                     component is added. If false, the caller must manage the lifetime
  73                                     of the component
  74         @see getViewedComponent
  75     */
  76     void setViewedComponent (Component* newViewedComponent,
  77                              bool deleteComponentWhenNoLongerNeeded = true);
  78
  79     /** Returns the component that's currently being used inside the Viewport.
  80
  81         @see setViewedComponent
  82     */
  83     Component* getViewedComponent() const noexcept                  { return contentComp.get(); }
  84
  85     //==============================================================================
  86     /** Changes the position of the viewed component.
  87
  88         The inner component will be moved so that the pixel at the top left of
  89         the viewport will be the pixel at position (xPixelsOffset, yPixelsOffset)
  90         within the inner component.
  91
  92         This will update the scrollbars and might cause a call to visibleAreaChanged().
  93
  94         @see getViewPositionX, getViewPositionY, setViewPositionProportionately
  95     */
  96     void setViewPosition (int xPixelsOffset, int yPixelsOffset);
  97
  98     /** Changes the position of the viewed component.
  99
 100         The inner component will be moved so that the pixel at the top left of
 101         the viewport will be the pixel at the specified coordinates within the
 102         inner component.
 103
 104         This will update the scrollbars and might cause a call to visibleAreaChanged().
 105
 106         @see getViewPositionX, getViewPositionY, setViewPositionProportionately
 107     */
 108     void setViewPosition (Point<int> newPosition);
 109
 110     /** Changes the view position as a proportion of the distance it can move.
 111
 112         The values here are from 0.0 to 1.0 - where (0, 0) would put the
 113         visible area in the top-left, and (1, 1) would put it as far down and
 114         to the right as it's possible to go whilst keeping the child component
 115         on-screen.
 116     */
 117     void setViewPositionProportionately (double proportionX, double proportionY);
 118
 119     /** If the specified position is at the edges of the viewport, this method scrolls
 120         the viewport to bring that position nearer to the centre.
 121
 122         Call this if you're dragging an object inside a viewport and want to make it scroll
 123         when the user approaches an edge. You might also find Component::beginDragAutoRepeat()
 124         useful when auto-scrolling.
 125
 126         @param mouseX       the x position, relative to the Viewport's top-left
 127         @param mouseY       the y position, relative to the Viewport's top-left
 128         @param distanceFromEdge     specifies how close to an edge the position needs to be
 129                             before the viewport should scroll in that direction
 130         @param maximumSpeed the maximum number of pixels that the viewport is allowed
 131                             to scroll by.
 132         @returns            true if the viewport was scrolled
 133     */
 134     bool autoScroll (int mouseX, int mouseY, int distanceFromEdge, int maximumSpeed);
 135
 136     /** Returns the position within the child component of the top-left of its visible area. */
 137     Point<int> getViewPosition() const noexcept             { return lastVisibleArea.getPosition(); }
 138
 139     /** Returns the visible area of the child component, relative to its top-left */
 140     Rectangle<int> getViewArea() const noexcept             { return lastVisibleArea; }
 141
 142     /** Returns the position within the child component of the top-left of its visible area.
 143         @see getViewWidth, setViewPosition
 144     */
 145     int getViewPositionX() const noexcept                   { return lastVisibleArea.getX(); }
 146
 147     /** Returns the position within the child component of the top-left of its visible area.
 148         @see getViewHeight, setViewPosition
 149     */
 150     int getViewPositionY() const noexcept                   { return lastVisibleArea.getY(); }
 151
 152     /** Returns the width of the visible area of the child component.
 153
 154         This may be less than the width of this Viewport if there's a vertical scrollbar
 155         or if the child component is itself smaller.
 156     */
 157     int getViewWidth() const noexcept                       { return lastVisibleArea.getWidth(); }
 158
 159     /** Returns the height of the visible area of the child component.
 160
 161         This may be less than the height of this Viewport if there's a horizontal scrollbar
 162         or if the child component is itself smaller.
 163     */
 164     int getViewHeight() const noexcept                      { return lastVisibleArea.getHeight(); }
 165
 166     /** Returns the width available within this component for the contents.
 167
 168         This will be the width of the viewport component minus the width of a
 169         vertical scrollbar (if visible).
 170     */
 171     int getMaximumVisibleWidth() const;
 172
 173     /** Returns the height available within this component for the contents.
 174
 175         This will be the height of the viewport component minus the space taken up
 176         by a horizontal scrollbar (if visible).
 177     */
 178     int getMaximumVisibleHeight() const;
 179
 180     //==============================================================================
 181     /** Callback method that is called when the visible area changes.
 182
 183         This will be called when the visible area is moved either be scrolling or
 184         by calls to setViewPosition(), etc.
 185     */
 186     virtual void visibleAreaChanged (const Rectangle<int>& newVisibleArea);
 187
 188     /** Callback method that is called when the viewed component is added, removed or swapped. */
 189     virtual void viewedComponentChanged (Component* newComponent);
 190
 191     //==============================================================================
 192     /** Turns scrollbars on or off.
 193
 194         If set to false, the scrollbars won't ever appear. When true (the default)
 195         they will appear only when needed.
 196
 197         The allowVerticalScrollingWithoutScrollbar parameters allow you to enable
 198         mouse-wheel scrolling even when there the scrollbars are hidden. When the
 199         scrollbars are visible, these parameters are ignored.
 200     */
 201     void setScrollBarsShown (bool showVerticalScrollbarIfNeeded,
 202                              bool showHorizontalScrollbarIfNeeded,
 203                              bool allowVerticalScrollingWithoutScrollbar = false,
 204                              bool allowHorizontalScrollingWithoutScrollbar = false);
 205
 206     /** Changes where the scroll bars are positioned
 207
 208         If verticalScrollbarOnRight is set to true, then the vertical scrollbar will
 209         appear on the right side of the view port's content (this is the default),
 210         otherwise it will be on the left side of the content.
 211
 212         If horizontalScrollbarAtBottom is set to true, then the horizontal scrollbar
 213         will appear at the bottom of the view port's content (this is the default),
 214         otherwise it will be at the top.
 215     */
 216     void setScrollBarPosition (bool verticalScrollbarOnRight,
 217                                bool horizontalScrollbarAtBottom);
 218
 219     /** True if the vertical scrollbar will appear on the right side of the content */
 220     bool isVerticalScrollbarOnTheRight() const noexcept         { return vScrollbarRight; }
 221
 222     /** True if the horizontal scrollbar will appear at the bottom of the content */
 223     bool isHorizontalScrollbarAtBottom() const noexcept         { return hScrollbarBottom; }
 224
 225     /** True if the vertical scrollbar is enabled.
 226         @see setScrollBarsShown
 227     */
 228     bool isVerticalScrollBarShown() const noexcept              { return showVScrollbar; }
 229
 230     /** True if the horizontal scrollbar is enabled.
 231         @see setScrollBarsShown
 232     */
 233     bool isHorizontalScrollBarShown() const noexcept            { return showHScrollbar; }
 234
 235     /** Changes the width of the scrollbars.
 236         If this isn't specified, the default width from the LookAndFeel class will be used.
 237         @see LookAndFeel::getDefaultScrollbarWidth
 238     */
 239     void setScrollBarThickness (int thickness);
 240
 241     /** Returns the thickness of the scrollbars.
 242         @see setScrollBarThickness
 243     */
 244     int getScrollBarThickness() const;
 245
 246     /** Changes the distance that a single-step click on a scrollbar button
 247         will move the viewport.
 248     */
 249     void setSingleStepSizes (int stepX, int stepY);
 250
 251     /** Returns a reference to the scrollbar component being used.
 252         Handy if you need to customise the bar somehow.
 253     */
 254     ScrollBar& getVerticalScrollBar() noexcept                  { return *verticalScrollBar; }
 255
 256     /** Returns a reference to the scrollbar component being used.
 257         Handy if you need to customise the bar somehow.
 258     */
 259     ScrollBar& getHorizontalScrollBar() noexcept                { return *horizontalScrollBar; }
 260
 261     /** Re-instantiates the scrollbars, which is only really useful if you've overridden createScrollBarComponent(). */
 262     void recreateScrollbars();
 263
 264     /** True if there's any off-screen content that could be scrolled vertically,
 265         or false if everything is currently visible.
 266     */
 267     bool canScrollVertically() const noexcept;
 268
 269     /** True if there's any off-screen content that could be scrolled horizontally,
 270         or false if everything is currently visible.
 271     */
 272     bool canScrollHorizontally() const noexcept;
 273
 274     /** Enables or disables drag-to-scroll functionality for mouse sources in the viewport.
 275
 276         If your viewport contains a Component that you don't want to receive mouse events when the
 277         user is drag-scrolling, you can disable this with the Component::setViewportIgnoreDragFlag()
 278         method.
 279     */
 280     [[deprecated ("Use setScrollOnDragMode instead.")]]
 281     void setScrollOnDragEnabled (bool shouldScrollOnDrag)
 282     {
 283         setScrollOnDragMode (shouldScrollOnDrag ? ScrollOnDragMode::all : ScrollOnDragMode::never);
 284     }
 285
 286     /** Returns true if drag-to-scroll functionality is enabled for mouse input sources. */
 287     [[deprecated ("Use getScrollOnDragMode instead.")]]
 288     bool isScrollOnDragEnabled() const noexcept { return getScrollOnDragMode() == ScrollOnDragMode::all; }
 289
 290     enum class ScrollOnDragMode
 291     {
 292         never,          /**< Dragging will never scroll the viewport. */
 293         nonHover,       /**< Dragging will only scroll the viewport if the input source cannot hover. */
 294         all             /**< Dragging will always scroll the viewport. */
 295     };
 296
 297     /** Sets the current scroll-on-drag mode. The default is ScrollOnDragMode::nonHover.
 298
 299         If your viewport contains a Component that you don't want to receive mouse events when the
 300         user is drag-scrolling, you can disable this with the Component::setViewportIgnoreDragFlag()
 301         method.
 302     */
 303     void setScrollOnDragMode (ScrollOnDragMode scrollOnDragMode);
 304
 305     /** Returns the current scroll-on-drag mode. */
 306     ScrollOnDragMode getScrollOnDragMode() const { return scrollOnDragMode; }
 307
 308     /** Returns true if the user is currently dragging-to-scroll.
 309         @see setScrollOnDragEnabled
 310     */
 311     bool isCurrentlyScrollingOnDrag() const noexcept;
 312
 313     //==============================================================================
 314     /** @internal */
 315     void resized() override;
 316     /** @internal */
 317     void scrollBarMoved (ScrollBar*, double newRangeStart) override;
 318     /** @internal */
 319     void mouseWheelMove (const MouseEvent&, const MouseWheelDetails&) override;
 320     /** @internal */
 321     void mouseDown (const MouseEvent& e) override;
 322     /** @internal */
 323     bool keyPressed (const KeyPress&) override;
 324     /** @internal */
 325     void componentMovedOrResized (Component&, bool wasMoved, bool wasResized) override;
 326     /** @internal */
 327     void lookAndFeelChanged() override;
 328     /** @internal */
 329     bool useMouseWheelMoveIfNeeded (const MouseEvent&, const MouseWheelDetails&);
 330     /** @internal */
 331     static bool respondsToKey (const KeyPress&);
 332
 333 protected:
 334     //==============================================================================
 335     /** Creates the Scrollbar components that will be added to the Viewport.
 336         Subclasses can override this if they need to customise the scrollbars in some way.
 337     */
 338     virtual ScrollBar* createScrollBarComponent (bool isVertical);
 339
 340 private:
 341     //==============================================================================
 342     class AccessibilityIgnoredComponent : public Component
 343     {
 344         std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override
 345         {
 346             return createIgnoredAccessibilityHandler (*this);
 347         }
 348     };
 349
 350     std::unique_ptr<ScrollBar> verticalScrollBar, horizontalScrollBar;
 351     AccessibilityIgnoredComponent contentHolder;
 352     WeakReference<Component> contentComp;
 353     Rectangle<int> lastVisibleArea;
 354     int scrollBarThickness = 0;
 355     int singleStepX = 16, singleStepY = 16;
 356     ScrollOnDragMode scrollOnDragMode = ScrollOnDragMode::nonHover;
 357     bool showHScrollbar = true, showVScrollbar = true, deleteContent = true;
 358     bool customScrollBarThickness = false;
 359     bool allowScrollingWithoutScrollbarV = false, allowScrollingWithoutScrollbarH = false;
 360     bool vScrollbarRight = true, hScrollbarBottom = true;
 361
 362     struct DragToScrollListener;
 363     std::unique_ptr<DragToScrollListener> dragToScrollListener;
 364
 365     Point<int> viewportPosToCompPos (Point<int>) const;
 366
 367     void updateVisibleArea();
 368     void deleteOrRemoveContentComp();
 369
 370     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Viewport)
 371 };
 372
 373 } // namespace juce