third_party/WebKit/Source/platform/scroll/ScrollableArea.h

   1 /*
   2  * Copyright (C) 2008, 2011 Apple Inc. All Rights Reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  * 1. Redistributions of source code must retain the above copyright
   8  *    notice, this list of conditions and the following disclaimer.
   9  * 2. Redistributions in binary form must reproduce the above copyright
  10  *    notice, this list of conditions and the following disclaimer in the
  11  *    documentation and/or other materials provided with the distribution.
  12  *
  13  * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
  14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  16  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR
  17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  18  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  19  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  20  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
  21  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  23  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24  */
  25
  26 #ifndef ScrollableArea_h
  27 #define ScrollableArea_h
  28
  29 #include "platform/PlatformExport.h"
  30 #include "platform/RuntimeEnabledFeatures.h"
  31 #include "platform/geometry/DoublePoint.h"
  32 #include "platform/heap/Handle.h"
  33 #include "platform/scroll/ScrollAnimator.h"
  34 #include "platform/scroll/ScrollTypes.h"
  35 #include "platform/scroll/Scrollbar.h"
  36 #include "wtf/Noncopyable.h"
  37 #include "wtf/Vector.h"
  38
  39 namespace blink {
  40
  41 class DoubleRect;
  42 class FloatPoint;
  43 class GraphicsLayer;
  44 class HostWindow;
  45 class PlatformWheelEvent;
  46 class ProgrammaticScrollAnimator;
  47 struct ScrollAlignment;
  48 class ScrollAnimator;
  49 class WebCompositorAnimationTimeline;
  50
  51 enum ScrollBehavior {
  52     ScrollBehaviorAuto,
  53     ScrollBehaviorInstant,
  54     ScrollBehaviorSmooth,
  55 };
  56
  57 enum IncludeScrollbarsInRect {
  58     ExcludeScrollbars,
  59     IncludeScrollbars,
  60 };
  61
  62 #if ENABLE(OILPAN)
  63 // Oilpan: Using the transition type WillBeGarbageCollectedMixin is
  64 // problematic non-Oilpan as the type expands to DummyBase, exporting it
  65 // also from 'platform' as a result. Bringing about duplicate DummyBases
  66 // as core also exports same; with component build linking fails as a
  67 // result. Hence the workaround of not using a transition type.
  68 class PLATFORM_EXPORT ScrollableArea : public GarbageCollectedMixin {
  69 #else
  70 class PLATFORM_EXPORT ScrollableArea {
  71 #endif
  72     WTF_MAKE_NONCOPYABLE(ScrollableArea);
  73 public:
  74     static int pixelsPerLineStep();
  75     static float minFractionToStepWhenPaging();
  76     static int maxOverlapBetweenPages();
  77
  78     // Convert a non-finite scroll value (Infinity, -Infinity, NaN) to 0 as
  79     // per http://dev.w3.org/csswg/cssom-view/#normalize-non_finite-values.
  80     static double normalizeNonFiniteScroll(double value) { return std::isfinite(value) ? value : 0.0; }
  81
  82     // The window that hosts the ScrollableArea. The ScrollableArea will communicate scrolls and repaints to the
  83     // host window in the window's coordinate space.
  84     virtual HostWindow* hostWindow() const { return 0; }
  85
  86     virtual ScrollResultOneDimensional userScroll(ScrollDirectionPhysical, ScrollGranularity, float delta = 1);
  87
  88     virtual void setScrollPosition(const DoublePoint&, ScrollType, ScrollBehavior = ScrollBehaviorInstant);
  89     virtual void scrollBy(const DoubleSize&, ScrollType, ScrollBehavior = ScrollBehaviorInstant);
  90     void setScrollPositionSingleAxis(ScrollbarOrientation, double, ScrollType, ScrollBehavior = ScrollBehaviorInstant);
  91
  92     // Scrolls the area so that the given rect, given in the document's content coordinates, such that it's
  93     // visible in the area. Returns the new location of the input rect relative once again to the document.
  94     // Note, in the case of a Document container, such as FrameView, the output will always be the input rect
  95     // since scrolling it can't change the location of content relative to the document, unlike an overflowing
  96     // element.
  97     virtual LayoutRect scrollIntoView(const LayoutRect& rectInContent, const ScrollAlignment& alignX, const ScrollAlignment& alignY);
  98
  99     // Scrolls the area so that the given rect, given in the area's content coordinates, such that it's
 100     // cenetered in the second rect, which is given relative to the area's origin.
 101     void scrollIntoRect(const LayoutRect& rectInContent, const FloatRect& targetRectInFrame);
 102
 103     static bool scrollBehaviorFromString(const String&, ScrollBehavior&);
 104
 105     bool inLiveResize() const { return m_inLiveResize; }
 106     void willStartLiveResize();
 107     void willEndLiveResize();
 108
 109     void contentAreaWillPaint() const;
 110     void mouseEnteredContentArea() const;
 111     void mouseExitedContentArea() const;
 112     void mouseMovedInContentArea() const;
 113     void mouseEnteredScrollbar(Scrollbar*) const;
 114     void mouseExitedScrollbar(Scrollbar*) const;
 115     void contentAreaDidShow() const;
 116     void contentAreaDidHide() const;
 117
 118     void finishCurrentScrollAnimations() const;
 119
 120     virtual void didAddScrollbar(Scrollbar*, ScrollbarOrientation);
 121     virtual void willRemoveScrollbar(Scrollbar*, ScrollbarOrientation);
 122
 123     virtual void contentsResized();
 124
 125     bool hasOverlayScrollbars() const;
 126     void setScrollbarOverlayStyle(ScrollbarOverlayStyle);
 127     ScrollbarOverlayStyle scrollbarOverlayStyle() const { return static_cast<ScrollbarOverlayStyle>(m_scrollbarOverlayStyle); }
 128
 129     // This getter will create a ScrollAnimator if it doesn't already exist.
 130     ScrollAnimator* scrollAnimator() const;
 131
 132     // This getter will return null if the ScrollAnimator hasn't been created yet.
 133     ScrollAnimator* existingScrollAnimator() const { return m_animators ? m_animators->scrollAnimator.get() : 0; }
 134
 135     ProgrammaticScrollAnimator* programmaticScrollAnimator() const;
 136     ProgrammaticScrollAnimator* existingProgrammaticScrollAnimator() const
 137     {
 138         return m_animators ? m_animators->programmaticScrollAnimator.get() : 0;
 139     }
 140
 141     const IntPoint& scrollOrigin() const { return m_scrollOrigin; }
 142     bool scrollOriginChanged() const { return m_scrollOriginChanged; }
 143
 144
 145     // This is used to determine whether the incoming fractional scroll offset should
 146     // be truncated to integer. Current rule is that if preferCompositingToLCDTextEnabled()
 147     // is disabled (which is true on low-dpi device by default) we should do the truncation.
 148     // The justification is that non-composited elements using fractional scroll offsets
 149     // is causing too much nasty bugs but does not add too benefit on low-dpi devices.
 150     virtual bool shouldUseIntegerScrollOffset() const { return !RuntimeEnabledFeatures::fractionalScrollOffsetsEnabled(); }
 151
 152     virtual bool isActive() const = 0;
 153     virtual int scrollSize(ScrollbarOrientation) const = 0;
 154     virtual void invalidateScrollbar(Scrollbar*, const IntRect&);
 155     virtual bool isScrollCornerVisible() const = 0;
 156     virtual IntRect scrollCornerRect() const = 0;
 157     virtual void invalidateScrollCorner(const IntRect&);
 158     virtual void getTickmarks(Vector<IntRect>&) const { }
 159
 160     // Convert points and rects between the scrollbar and its containing view.
 161     // The client needs to implement these in order to be aware of layout effects
 162     // like CSS transforms.
 163     virtual IntRect convertFromScrollbarToContainingView(const Scrollbar* scrollbar, const IntRect& scrollbarRect) const
 164     {
 165         return scrollbar->Widget::convertToContainingView(scrollbarRect);
 166     }
 167     virtual IntRect convertFromContainingViewToScrollbar(const Scrollbar* scrollbar, const IntRect& parentRect) const
 168     {
 169         return scrollbar->Widget::convertFromContainingView(parentRect);
 170     }
 171     virtual IntPoint convertFromScrollbarToContainingView(const Scrollbar* scrollbar, const IntPoint& scrollbarPoint) const
 172     {
 173         return scrollbar->Widget::convertToContainingView(scrollbarPoint);
 174     }
 175     virtual IntPoint convertFromContainingViewToScrollbar(const Scrollbar* scrollbar, const IntPoint& parentPoint) const
 176     {
 177         return scrollbar->Widget::convertFromContainingView(parentPoint);
 178     }
 179
 180     virtual Scrollbar* horizontalScrollbar() const { return 0; }
 181     virtual Scrollbar* verticalScrollbar() const { return 0; }
 182
 183     // scrollPosition is relative to the scrollOrigin. i.e. If the page is RTL
 184     // then scrollPosition will be negative. By default, scrollPositionDouble()
 185     // just call into scrollPosition(). Subclass can override scrollPositionDouble()
 186     // to return floating point precision scrolloffset.
 187     // FIXME: Remove scrollPosition(). crbug.com/414283.
 188     virtual IntPoint scrollPosition() const = 0;
 189     virtual DoublePoint scrollPositionDouble() const { return DoublePoint(scrollPosition()); }
 190     virtual IntPoint minimumScrollPosition() const = 0;
 191     virtual DoublePoint minimumScrollPositionDouble() const { return DoublePoint(minimumScrollPosition()); }
 192     virtual IntPoint maximumScrollPosition() const = 0;
 193     virtual DoublePoint maximumScrollPositionDouble() const { return DoublePoint(maximumScrollPosition()); }
 194
 195     virtual DoubleRect visibleContentRectDouble(IncludeScrollbarsInRect = ExcludeScrollbars) const;
 196     virtual IntRect visibleContentRect(IncludeScrollbarsInRect = ExcludeScrollbars) const;
 197     virtual int visibleHeight() const { return visibleContentRect().height(); }
 198     virtual int visibleWidth() const { return visibleContentRect().width(); }
 199     virtual IntSize contentsSize() const = 0;
 200     virtual IntPoint lastKnownMousePosition() const { return IntPoint(); }
 201
 202     virtual bool shouldSuspendScrollAnimations() const { return true; }
 203     virtual void scrollbarStyleChanged() { }
 204     virtual void scrollbarVisibilityChanged() { }
 205     virtual bool scrollbarsCanBeActive() const = 0;
 206
 207     // Returns the bounding box of this scrollable area, in the coordinate system of the enclosing scroll view.
 208     virtual IntRect scrollableAreaBoundingBox() const = 0;
 209
 210     virtual bool scrollAnimatorEnabled() const { return false; }
 211
 212     // NOTE: Only called from Internals for testing.
 213     void setScrollOffsetFromInternals(const IntPoint&);
 214
 215     IntPoint clampScrollPosition(const IntPoint&) const;
 216     DoublePoint clampScrollPosition(const DoublePoint&) const;
 217
 218     // Let subclasses provide a way of asking for and servicing scroll
 219     // animations.
 220     bool scheduleAnimation();
 221     virtual void serviceScrollAnimations(double monotonicTime);
 222     virtual void updateCompositorScrollAnimations();
 223     virtual void registerForAnimation() { }
 224     virtual void deregisterForAnimation() { }
 225
 226     void notifyCompositorAnimationFinished(int groupId);
 227
 228     virtual bool usesCompositedScrolling() const { return false; }
 229
 230     // Returns true if the GraphicsLayer tree needs to be rebuilt.
 231     virtual bool updateAfterCompositingChange() { return false; }
 232
 233     virtual bool userInputScrollable(ScrollbarOrientation) const = 0;
 234     virtual bool shouldPlaceVerticalScrollbarOnLeft() const = 0;
 235
 236     // Convenience functions
 237     int scrollPosition(ScrollbarOrientation orientation) { return orientation == HorizontalScrollbar ? scrollPosition().x() : scrollPosition().y(); }
 238     int minimumScrollPosition(ScrollbarOrientation orientation) { return orientation == HorizontalScrollbar ? minimumScrollPosition().x() : minimumScrollPosition().y(); }
 239     int maximumScrollPosition(ScrollbarOrientation orientation) { return orientation == HorizontalScrollbar ? maximumScrollPosition().x() : maximumScrollPosition().y(); }
 240     int clampScrollPosition(ScrollbarOrientation orientation, int pos)  { return std::max(std::min(pos, maximumScrollPosition(orientation)), minimumScrollPosition(orientation)); }
 241
 242     bool hasVerticalBarDamage() const { return !m_verticalBarDamage.isEmpty(); }
 243     bool hasHorizontalBarDamage() const { return !m_horizontalBarDamage.isEmpty(); }
 244     const IntRect& verticalBarDamage() const { return m_verticalBarDamage; }
 245     const IntRect& horizontalBarDamage() const { return m_horizontalBarDamage; }
 246
 247     void addScrollbarDamage(Scrollbar* scrollbar, const IntRect& rect)
 248     {
 249         if (scrollbar == horizontalScrollbar())
 250             m_horizontalBarDamage.unite(rect);
 251         else
 252             m_verticalBarDamage.unite(rect);
 253     }
 254
 255     void resetScrollbarDamage()
 256     {
 257         m_verticalBarDamage = IntRect();
 258         m_horizontalBarDamage = IntRect();
 259     }
 260
 261     virtual GraphicsLayer* layerForContainer() const;
 262     virtual GraphicsLayer* layerForScrolling() const { return 0; }
 263     virtual GraphicsLayer* layerForHorizontalScrollbar() const { return 0; }
 264     virtual GraphicsLayer* layerForVerticalScrollbar() const { return 0; }
 265     virtual GraphicsLayer* layerForScrollCorner() const { return 0; }
 266     bool hasLayerForHorizontalScrollbar() const;
 267     bool hasLayerForVerticalScrollbar() const;
 268     bool hasLayerForScrollCorner() const;
 269
 270     void layerForScrollingDidChange(WebCompositorAnimationTimeline*);
 271
 272     void cancelScrollAnimation();
 273     void cancelProgrammaticScrollAnimation();
 274
 275     virtual ~ScrollableArea();
 276
 277     virtual void invalidateScrollbarRect(Scrollbar*, const IntRect&) = 0;
 278     virtual void invalidateScrollCornerRect(const IntRect&) = 0;
 279
 280     // Returns the default scroll style this area should scroll with when not
 281     // explicitly specified. E.g. The scrolling behavior of an element can be
 282     // specified in CSS.
 283     virtual ScrollBehavior scrollBehaviorStyle() const { return ScrollBehaviorInstant; }
 284
 285     // TODO(bokan): This is only used in FrameView to check scrollability but is
 286     // needed here to allow RootFrameViewport to preserve wheelHandler
 287     // semantics. Not sure why it's FrameView specific, it could probably be
 288     // generalized to other types of ScrollableAreas.
 289     virtual bool isScrollable() { return true; }
 290
 291     // TODO(bokan): FrameView::setScrollPosition uses updateScrollbars to scroll
 292     // which bails out early if its already in updateScrollbars, the effect being
 293     // that programmatic scrolls (i.e. setScrollPosition) are disabled when in
 294     // updateScrollbars. Expose this here to allow RootFrameViewport to match the
 295     // semantics for now but it should be cleaned up at the source.
 296     virtual bool isProgrammaticallyScrollable() { return true; }
 297
 298     // Subtracts space occupied by this ScrollableArea's scrollbars.
 299     // Does nothing if overlay scrollbars are enabled.
 300     IntSize excludeScrollbars(const IntSize&) const;
 301
 302     // Need to promptly let go of owned animator objects.
 303     EAGERLY_FINALIZE();
 304     DEFINE_INLINE_VIRTUAL_TRACE() { }
 305
 306 protected:
 307     ScrollableArea();
 308
 309     void setScrollOrigin(const IntPoint&);
 310     void resetScrollOriginChanged() { m_scrollOriginChanged = false; }
 311
 312     // Needed to let the animators call scrollPositionChanged.
 313     friend class ScrollAnimator;
 314     friend class ProgrammaticScrollAnimator;
 315     void scrollPositionChanged(const DoublePoint&, ScrollType);
 316
 317     void clearScrollAnimators();
 318
 319 private:
 320     void programmaticScrollHelper(const DoublePoint&, ScrollBehavior);
 321     void userScrollHelper(const DoublePoint&, ScrollBehavior);
 322
 323     // This function should be overriden by subclasses to perform the actual
 324     // scroll of the content. By default the DoublePoint version will just
 325     // call into the IntPoint version. If fractional scroll is needed, one
 326     // can override the DoublePoint version to take advantage of the double
 327     // precision scroll offset.
 328     // FIXME: Remove the IntPoint version. And change the function to
 329     // take DoubleSize. crbug.com/414283.
 330     virtual void setScrollOffset(const IntPoint&, ScrollType) = 0;
 331     virtual void setScrollOffset(const DoublePoint& offset, ScrollType scrollType)
 332     {
 333         setScrollOffset(flooredIntPoint(offset), scrollType);
 334     }
 335
 336     virtual int lineStep(ScrollbarOrientation) const;
 337     virtual int pageStep(ScrollbarOrientation) const;
 338     virtual int documentStep(ScrollbarOrientation) const;
 339     virtual float pixelStep(ScrollbarOrientation) const;
 340
 341     // Stores the paint invalidations for the scrollbars during layout.
 342     IntRect m_horizontalBarDamage;
 343     IntRect m_verticalBarDamage;
 344
 345     struct ScrollableAreaAnimators {
 346         OwnPtr<ScrollAnimator> scrollAnimator;
 347         OwnPtr<ProgrammaticScrollAnimator> programmaticScrollAnimator;
 348     };
 349
 350     mutable OwnPtr<ScrollableAreaAnimators> m_animators;
 351
 352     unsigned m_inLiveResize : 1;
 353
 354     unsigned m_scrollbarOverlayStyle : 2; // ScrollbarOverlayStyle
 355
 356     unsigned m_scrollOriginChanged : 1;
 357
 358     // There are 8 possible combinations of writing mode and direction. Scroll origin will be non-zero in the x or y axis
 359     // if there is any reversed direction or writing-mode. The combinations are:
 360     // writing-mode / direction     scrollOrigin.x() set    scrollOrigin.y() set
 361     // horizontal-tb / ltr          NO                      NO
 362     // horizontal-tb / rtl          YES                     NO
 363     // horizontal-bt / ltr          NO                      YES
 364     // horizontal-bt / rtl          YES                     YES
 365     // vertical-lr / ltr            NO                      NO
 366     // vertical-lr / rtl            NO                      YES
 367     // vertical-rl / ltr            YES                     NO
 368     // vertical-rl / rtl            YES                     YES
 369     IntPoint m_scrollOrigin;
 370 };
 371
 372 } // namespace blink
 373
 374 #endif // ScrollableArea_h