Home | History | Annotate | Download | only in platform
      1 /*
      2  * Copyright (C) 2004, 2006, 2007, 2008 Apple Inc. All rights reserved.
      3  * Copyright (C) 2009 Holger Hans Peter Freyther
      4  *
      5  * Redistribution and use in source and binary forms, with or without
      6  * modification, are permitted provided that the following conditions
      7  * are met:
      8  * 1. Redistributions of source code must retain the above copyright
      9  *    notice, this list of conditions and the following disclaimer.
     10  * 2. Redistributions in binary form must reproduce the above copyright
     11  *    notice, this list of conditions and the following disclaimer in the
     12  *    documentation and/or other materials provided with the distribution.
     13  *
     14  * THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER, INC. ``AS IS'' AND ANY
     15  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
     16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
     17  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE COMPUTER, INC. OR
     18  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
     19  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     20  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
     21  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
     22  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
     23  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     24  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     25  */
     26 
     27 #ifndef ScrollView_h
     28 #define ScrollView_h
     29 
     30 #include "IntRect.h"
     31 #include "Scrollbar.h"
     32 #include "ScrollableArea.h"
     33 #include "ScrollTypes.h"
     34 #include "Widget.h"
     35 
     36 #include <wtf/HashSet.h>
     37 
     38 #if PLATFORM(MAC) && defined __OBJC__
     39 @protocol WebCoreFrameScrollView;
     40 #endif
     41 
     42 #if PLATFORM(GTK)
     43 #include "GRefPtrGtk.h"
     44 typedef struct _GtkAdjustment GtkAdjustment;
     45 #endif
     46 
     47 #if PLATFORM(WX)
     48 class wxScrollWinEvent;
     49 #endif
     50 
     51 namespace WebCore {
     52 
     53 class HostWindow;
     54 class Scrollbar;
     55 
     56 class ScrollView : public Widget, public ScrollableArea {
     57 public:
     58     ~ScrollView();
     59 
     60     // ScrollableArea functions.  FrameView overrides the others.
     61     virtual int scrollSize(ScrollbarOrientation orientation) const;
     62     virtual int scrollPosition(Scrollbar*) const;
     63     virtual void setScrollOffset(const IntPoint&);
     64     virtual void didCompleteRubberBand(const IntSize&) const;
     65     virtual void notifyPageThatContentAreaWillPaint() const;
     66     virtual bool isScrollCornerVisible() const;
     67 
     68     // NOTE: This should only be called by the overriden setScrollOffset from ScrollableArea.
     69     virtual void scrollTo(const IntSize& newOffset);
     70 
     71     // The window thats hosts the ScrollView. The ScrollView will communicate scrolls and repaints to the
     72     // host window in the window's coordinate space.
     73     virtual HostWindow* hostWindow() const = 0;
     74 
     75     // Returns a clip rect in host window coordinates. Used to clip the blit on a scroll.
     76     virtual IntRect windowClipRect(bool clipToContents = true) const = 0;
     77 
     78     // Functions for child manipulation and inspection.
     79     const HashSet<RefPtr<Widget> >* children() const { return &m_children; }
     80     void addChild(PassRefPtr<Widget>);
     81     void removeChild(Widget*);
     82 
     83     // If the scroll view does not use a native widget, then it will have cross-platform Scrollbars. These functions
     84     // can be used to obtain those scrollbars.
     85     virtual Scrollbar* horizontalScrollbar() const { return m_horizontalScrollbar.get(); }
     86     virtual Scrollbar* verticalScrollbar() const { return m_verticalScrollbar.get(); }
     87     bool isScrollViewScrollbar(const Widget* child) const { return horizontalScrollbar() == child || verticalScrollbar() == child; }
     88 
     89     void positionScrollbarLayers();
     90 
     91     // Functions for setting and retrieving the scrolling mode in each axis (horizontal/vertical). The mode has values of
     92     // AlwaysOff, AlwaysOn, and Auto. AlwaysOff means never show a scrollbar, AlwaysOn means always show a scrollbar.
     93     // Auto means show a scrollbar only when one is needed.
     94     // Note that for platforms with native widgets, these modes are considered advisory. In other words the underlying native
     95     // widget may choose not to honor the requested modes.
     96     void setScrollbarModes(ScrollbarMode horizontalMode, ScrollbarMode verticalMode, bool horizontalLock = false, bool verticalLock = false);
     97     void setHorizontalScrollbarMode(ScrollbarMode mode, bool lock = false) { setScrollbarModes(mode, verticalScrollbarMode(), lock, verticalScrollbarLock()); }
     98     void setVerticalScrollbarMode(ScrollbarMode mode, bool lock = false) { setScrollbarModes(horizontalScrollbarMode(), mode, horizontalScrollbarLock(), lock); };
     99     void scrollbarModes(ScrollbarMode& horizontalMode, ScrollbarMode& verticalMode) const;
    100     ScrollbarMode horizontalScrollbarMode() const { ScrollbarMode horizontal, vertical; scrollbarModes(horizontal, vertical); return horizontal; }
    101     ScrollbarMode verticalScrollbarMode() const { ScrollbarMode horizontal, vertical; scrollbarModes(horizontal, vertical); return vertical; }
    102 
    103     void setHorizontalScrollbarLock(bool lock = true) { m_horizontalScrollbarLock = lock; }
    104     bool horizontalScrollbarLock() const { return m_horizontalScrollbarLock; }
    105     void setVerticalScrollbarLock(bool lock = true) { m_verticalScrollbarLock = lock; }
    106     bool verticalScrollbarLock() const { return m_verticalScrollbarLock; }
    107 
    108     void setScrollingModesLock(bool lock = true) { m_horizontalScrollbarLock = m_verticalScrollbarLock = lock; }
    109 
    110     virtual void setCanHaveScrollbars(bool);
    111     bool canHaveScrollbars() const { return horizontalScrollbarMode() != ScrollbarAlwaysOff || verticalScrollbarMode() != ScrollbarAlwaysOff; }
    112 
    113     virtual bool avoidScrollbarCreation() const { return false; }
    114 
    115     // By default you only receive paint events for the area that is visible. In the case of using a
    116     // tiled backing store, this function can be set, so that the view paints the entire contents.
    117     bool paintsEntireContents() const { return m_paintsEntireContents; }
    118     void setPaintsEntireContents(bool);
    119 
    120     // By default, paint events are clipped to the visible area.  If set to
    121     // false, paint events are no longer clipped.  paintsEntireContents() implies !clipsRepaints().
    122     bool clipsRepaints() const { return m_clipsRepaints; }
    123     void setClipsRepaints(bool);
    124 
    125     // By default programmatic scrolling is handled by WebCore and not by the UI application.
    126     // In the case of using a tiled backing store, this mode can be set, so that the scroll requests
    127     // are delegated to the UI application.
    128     bool delegatesScrolling() const { return m_delegatesScrolling; }
    129     void setDelegatesScrolling(bool);
    130 
    131     // Overridden by FrameView to create custom CSS scrollbars if applicable.
    132     virtual PassRefPtr<Scrollbar> createScrollbar(ScrollbarOrientation);
    133 
    134     // If the prohibits scrolling flag is set, then all scrolling in the view (even programmatic scrolling) is turned off.
    135     void setProhibitsScrolling(bool b) { m_prohibitsScrolling = b; }
    136     bool prohibitsScrolling() const { return m_prohibitsScrolling; }
    137 
    138     // Whether or not a scroll view will blit visible contents when it is scrolled. Blitting is disabled in situations
    139     // where it would cause rendering glitches (such as with fixed backgrounds or when the view is partially transparent).
    140     void setCanBlitOnScroll(bool);
    141     bool canBlitOnScroll() const;
    142 
    143     // The visible content rect has a location that is the scrolled offset of the document. The width and height are the viewport width
    144     // and height. By default the scrollbars themselves are excluded from this rectangle, but an optional boolean argument allows them to be
    145     // included.
    146     // In the situation the client is responsible for the scrolling (ie. with a tiled backing store) it is possible to use
    147     // the actualVisibleContentRect instead, though this must be updated manually, e.g after panning ends.
    148     IntRect visibleContentRect(bool includeScrollbars = false) const;
    149     IntRect actualVisibleContentRect() const { return m_actualVisibleContentRect.isEmpty() ? visibleContentRect() : m_actualVisibleContentRect; }
    150     void setActualVisibleContentRect(const IntRect& actualVisibleContentRect) { m_actualVisibleContentRect = actualVisibleContentRect; }
    151     int visibleWidth() const { return visibleContentRect().width(); }
    152     int visibleHeight() const { return visibleContentRect().height(); }
    153 
    154     // Functions for getting/setting the size webkit should use to layout the contents. By default this is the same as the visible
    155     // content size. Explicitly setting a layout size value will cause webkit to layout the contents using this size instead.
    156     int layoutWidth() const;
    157     int layoutHeight() const;
    158     IntSize fixedLayoutSize() const;
    159     void setFixedLayoutSize(const IntSize&);
    160     bool useFixedLayout() const;
    161     void setUseFixedLayout(bool enable);
    162 
    163     // Functions for getting/setting the size of the document contained inside the ScrollView (as an IntSize or as individual width and height
    164     // values).
    165     IntSize contentsSize() const; // Always at least as big as the visibleWidth()/visibleHeight().
    166     int contentsWidth() const { return contentsSize().width(); }
    167     int contentsHeight() const { return contentsSize().height(); }
    168     virtual void setContentsSize(const IntSize&);
    169 
    170 #if PLATFORM(ANDROID)
    171     int actualWidth() const;
    172     int actualHeight() const;
    173     int actualScrollX() const;
    174     int actualScrollY() const;
    175 #endif
    176 
    177     // Functions for querying the current scrolled position (both as a point, a size, or as individual X and Y values).
    178     IntPoint scrollPosition() const { return visibleContentRect().location(); }
    179     IntSize scrollOffset() const { return visibleContentRect().location() - IntPoint(); } // Gets the scrolled position as an IntSize. Convenient for adding to other sizes.
    180     IntPoint maximumScrollPosition() const; // The maximum position we can be scrolled to.
    181     IntPoint minimumScrollPosition() const; // The minimum position we can be scrolled to.
    182     // Adjust the passed in scroll position to keep it between the minimum and maximum positions.
    183     IntPoint adjustScrollPositionWithinRange(const IntPoint&) const;
    184     int scrollX() const { return scrollPosition().x(); }
    185     int scrollY() const { return scrollPosition().y(); }
    186 
    187     IntSize overhangAmount() const;
    188 
    189     void cacheCurrentScrollPosition() { m_cachedScrollPosition = scrollPosition(); }
    190     IntPoint cachedScrollPosition() const { return m_cachedScrollPosition; }
    191 
    192     // Functions for scrolling the view.
    193     void setScrollPosition(const IntPoint&);
    194     void scrollBy(const IntSize& s) { return setScrollPosition(scrollPosition() + s); }
    195 
    196     // This function scrolls by lines, pages or pixels.
    197     bool scroll(ScrollDirection, ScrollGranularity);
    198 
    199     // A logical scroll that just ends up calling the corresponding physical scroll() based off the document's writing mode.
    200     bool logicalScroll(ScrollLogicalDirection, ScrollGranularity);
    201 
    202     // Scroll the actual contents of the view (either blitting or invalidating as needed).
    203     void scrollContents(const IntSize& scrollDelta);
    204 
    205     // This gives us a means of blocking painting on our scrollbars until the first layout has occurred.
    206     void setScrollbarsSuppressed(bool suppressed, bool repaintOnUnsuppress = false);
    207     bool scrollbarsSuppressed() const { return m_scrollbarsSuppressed; }
    208 
    209     // Event coordinates are assumed to be in the coordinate space of a window that contains
    210     // the entire widget hierarchy. It is up to the platform to decide what the precise definition
    211     // of containing window is. (For example on Mac it is the containing NSWindow.)
    212     IntPoint windowToContents(const IntPoint&) const;
    213     IntPoint contentsToWindow(const IntPoint&) const;
    214     IntRect windowToContents(const IntRect&) const;
    215     IntRect contentsToWindow(const IntRect&) const;
    216 
    217     // Functions for converting to and from screen coordinates.
    218     IntRect contentsToScreen(const IntRect&) const;
    219     IntPoint screenToContents(const IntPoint&) const;
    220 
    221     // The purpose of this function is to answer whether or not the scroll view is currently visible. Animations and painting updates can be suspended if
    222     // we know that we are either not in a window right now or if that window is not visible.
    223     bool isOffscreen() const;
    224 
    225     // These functions are used to enable scrollbars to avoid window resizer controls that overlap the scroll view. This happens on Mac
    226     // for example.
    227     virtual IntRect windowResizerRect() const { return IntRect(); }
    228     bool containsScrollbarsAvoidingResizer() const;
    229     void adjustScrollbarsAvoidingResizerCount(int overlapDelta);
    230     void windowResizerRectChanged();
    231 
    232     virtual void setParent(ScrollView*); // Overridden to update the overlapping scrollbar count.
    233 
    234     // Called when our frame rect changes (or the rect/scroll position of an ancestor changes).
    235     virtual void frameRectsChanged();
    236 
    237     // Widget override to update our scrollbars and notify our contents of the resize.
    238     virtual void setFrameRect(const IntRect&);
    239     virtual void setBoundsSize(const IntSize&);
    240 
    241     // For platforms that need to hit test scrollbars from within the engine's event handlers (like Win32).
    242     Scrollbar* scrollbarAtPoint(const IntPoint& windowPoint);
    243 
    244     // This function exists for scrollviews that need to handle wheel events manually.
    245     // On Mac the underlying NSScrollView just does the scrolling, but on other platforms
    246     // (like Windows), we need this function in order to do the scroll ourselves.
    247     void wheelEvent(PlatformWheelEvent&);
    248 #if ENABLE(GESTURE_EVENTS)
    249     void gestureEvent(const PlatformGestureEvent&);
    250 #endif
    251 
    252     IntPoint convertChildToSelf(const Widget* child, const IntPoint& point) const
    253     {
    254         IntPoint newPoint = point;
    255         if (!isScrollViewScrollbar(child))
    256             newPoint = point - scrollOffset();
    257         newPoint.move(child->x(), child->y());
    258         return newPoint;
    259     }
    260 
    261     IntPoint convertSelfToChild(const Widget* child, const IntPoint& point) const
    262     {
    263         IntPoint newPoint = point;
    264         if (!isScrollViewScrollbar(child))
    265             newPoint = point + scrollOffset();
    266         newPoint.move(-child->x(), -child->y());
    267         return newPoint;
    268     }
    269 
    270     // Widget override. Handles painting of the contents of the view as well as the scrollbars.
    271     virtual void paint(GraphicsContext*, const IntRect&);
    272     void paintScrollbars(GraphicsContext*, const IntRect&);
    273 
    274     // Widget overrides to ensure that our children's visibility status is kept up to date when we get shown and hidden.
    275     virtual void show();
    276     virtual void hide();
    277     virtual void setParentVisible(bool);
    278 
    279     // Pan scrolling.
    280     static const int noPanScrollRadius = 15;
    281     void addPanScrollIcon(const IntPoint&);
    282     void removePanScrollIcon();
    283     void paintPanScrollIcon(GraphicsContext*);
    284 
    285     virtual bool isPointInScrollbarCorner(const IntPoint&);
    286     virtual bool scrollbarCornerPresent() const;
    287     virtual IntRect scrollCornerRect() const;
    288     virtual void paintScrollCorner(GraphicsContext*, const IntRect& cornerRect);
    289 
    290     virtual IntRect convertFromScrollbarToContainingView(const Scrollbar*, const IntRect&) const;
    291     virtual IntRect convertFromContainingViewToScrollbar(const Scrollbar*, const IntRect&) const;
    292     virtual IntPoint convertFromScrollbarToContainingView(const Scrollbar*, const IntPoint&) const;
    293     virtual IntPoint convertFromContainingViewToScrollbar(const Scrollbar*, const IntPoint&) const;
    294 
    295     bool containsScrollableAreaWithOverlayScrollbars() const { return m_containsScrollableAreaWithOverlayScrollbars; }
    296     void setContainsScrollableAreaWithOverlayScrollbars(bool contains) { m_containsScrollableAreaWithOverlayScrollbars = contains; }
    297 
    298 protected:
    299     ScrollView();
    300 
    301     virtual void repaintContentRectangle(const IntRect&, bool now = false);
    302     virtual void paintContents(GraphicsContext*, const IntRect& damageRect) = 0;
    303 
    304     void calculateOverhangAreasForPainting(IntRect& horizontalOverhangRect, IntRect& verticalOverhangRect);
    305     virtual void paintOverhangAreas(GraphicsContext*, const IntRect& horizontalOverhangArea, const IntRect& verticalOverhangArea, const IntRect& dirtyRect);
    306 
    307     virtual void contentsResized() = 0;
    308     virtual void visibleContentsResized() = 0;
    309 
    310     IntSize boundsSize() const { return m_boundsSize; }
    311     void setInitialBoundsSize(const IntSize&);
    312 
    313     // These functions are used to create/destroy scrollbars.
    314     void setHasHorizontalScrollbar(bool);
    315     void setHasVerticalScrollbar(bool);
    316 
    317     virtual void updateScrollCorner();
    318     virtual void invalidateScrollCornerRect(const IntRect&);
    319 
    320     // Scroll the content by blitting the pixels.
    321     virtual bool scrollContentsFastPath(const IntSize& scrollDelta, const IntRect& rectToScroll, const IntRect& clipRect);
    322     // Scroll the content by invalidating everything.
    323     virtual void scrollContentsSlowPath(const IntRect& updateRect);
    324 
    325     void setScrollOrigin(const IntPoint&, bool updatePositionAtAll, bool updatePositionSynchronously);
    326     IntPoint scrollOrigin() { return m_scrollOrigin; }
    327 
    328     // Subclassed by FrameView to check the writing-mode of the document.
    329     virtual bool isVerticalDocument() const { return true; }
    330     virtual bool isFlippedDocument() const { return false; }
    331 
    332 private:
    333     RefPtr<Scrollbar> m_horizontalScrollbar;
    334     RefPtr<Scrollbar> m_verticalScrollbar;
    335     ScrollbarMode m_horizontalScrollbarMode;
    336     ScrollbarMode m_verticalScrollbarMode;
    337 
    338     bool m_horizontalScrollbarLock;
    339     bool m_verticalScrollbarLock;
    340 
    341     bool m_prohibitsScrolling;
    342 
    343     HashSet<RefPtr<Widget> > m_children;
    344 
    345     // This bool is unused on Mac OS because we directly ask the platform widget
    346     // whether it is safe to blit on scroll.
    347     bool m_canBlitOnScroll;
    348 
    349     IntRect m_actualVisibleContentRect;
    350     IntSize m_scrollOffset; // FIXME: Would rather store this as a position, but we will wait to make this change until more code is shared.
    351     IntPoint m_cachedScrollPosition;
    352     IntSize m_fixedLayoutSize;
    353     IntSize m_contentsSize;
    354 
    355     int m_scrollbarsAvoidingResizer;
    356     bool m_scrollbarsSuppressed;
    357 
    358     bool m_inUpdateScrollbars;
    359     unsigned m_updateScrollbarsPass;
    360 
    361     IntPoint m_panScrollIconPoint;
    362     bool m_drawPanScrollIcon;
    363     bool m_useFixedLayout;
    364 
    365     bool m_paintsEntireContents;
    366     bool m_clipsRepaints;
    367     bool m_delegatesScrolling;
    368 
    369     bool m_containsScrollableAreaWithOverlayScrollbars;
    370 
    371     IntSize m_boundsSize;
    372 
    373     void init();
    374     void destroy();
    375 
    376     // Called to update the scrollbars to accurately reflect the state of the view.
    377     void updateScrollbars(const IntSize& desiredOffset);
    378 
    379     // Called when the scroll position within this view changes.  FrameView overrides this to generate repaint invalidations.
    380     virtual void repaintFixedElementsAfterScrolling() {}
    381 
    382     void platformInit();
    383     void platformDestroy();
    384     void platformAddChild(Widget*);
    385     void platformRemoveChild(Widget*);
    386     void platformSetScrollbarModes();
    387     void platformScrollbarModes(ScrollbarMode& horizontal, ScrollbarMode& vertical) const;
    388     void platformSetCanBlitOnScroll(bool);
    389     bool platformCanBlitOnScroll() const;
    390     IntRect platformVisibleContentRect(bool includeScrollbars) const;
    391     IntSize platformContentsSize() const;
    392     void platformSetContentsSize();
    393     IntRect platformContentsToScreen(const IntRect&) const;
    394     IntPoint platformScreenToContents(const IntPoint&) const;
    395     void platformSetScrollPosition(const IntPoint&);
    396     bool platformScroll(ScrollDirection, ScrollGranularity);
    397     void platformSetScrollbarsSuppressed(bool repaintOnUnsuppress);
    398     void platformRepaintContentRectangle(const IntRect&, bool now);
    399     bool platformIsOffscreen() const;
    400 
    401     void platformSetScrollOrigin(const IntPoint&, bool updatePositionAtAll, bool updatePositionSynchronously);
    402 
    403 #if PLATFORM(ANDROID)
    404     int platformActualWidth() const;
    405     int platformActualHeight() const;
    406     int platformActualScrollX() const;
    407     int platformActualScrollY() const;
    408 #endif
    409 
    410 #if PLATFORM(MAC) && defined __OBJC__
    411 public:
    412     NSView* documentView() const;
    413 
    414 private:
    415     NSScrollView<WebCoreFrameScrollView>* scrollView() const;
    416 #endif
    417 
    418 #if PLATFORM(GTK)
    419 public:
    420     void setGtkAdjustments(GtkAdjustment* hadj, GtkAdjustment* vadj, bool resetValues = true);
    421     void setHorizontalAdjustment(GtkAdjustment* hadj, bool resetValues = true);
    422     void setVerticalAdjustment(GtkAdjustment* vadj, bool resetValues = true);
    423     void setScrollOffset(const IntSize& offset) { m_scrollOffset = offset; }
    424 
    425 private:
    426     GRefPtr<GtkAdjustment> m_horizontalAdjustment;
    427     GRefPtr<GtkAdjustment> m_verticalAdjustment;
    428 #endif
    429 
    430 #if PLATFORM(WX)
    431 public:
    432     virtual void setPlatformWidget(wxWindow*);
    433     void adjustScrollbars(int x = -1, int y = -1, bool refresh = true);
    434 private:
    435     class ScrollViewPrivate;
    436     ScrollViewPrivate* m_data;
    437 #endif
    438 
    439 #ifdef ANDROID_CAPTURE_OFFSCREEN_PAINTS
    440 public:
    441     // capture parts of rect not contained by vis
    442     void platformOffscreenContentRectangle(const IntRect& vis,
    443         const IntRect& rect);
    444 #endif
    445 }; // class ScrollView
    446 
    447 } // namespace WebCore
    448 
    449 #endif // ScrollView_h
    450