2008-10-10 Darin Fisher <darin@chromium.org>
[WebKit-https.git] / WebCore / platform / ScrollView.h
1 /*
2  * Copyright (C) 2004, 2006, 2007, 2008 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 COMPUTER, 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 COMPUTER, 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 ScrollView_h
27 #define ScrollView_h
28
29 #include "IntRect.h"
30 #include "Scrollbar.h"
31 #include "ScrollbarClient.h"
32 #include "ScrollTypes.h"
33 #include "Widget.h"
34
35 #include <wtf/HashSet.h>
36
37 #if PLATFORM(MAC) && defined __OBJC__
38 @protocol WebCoreFrameScrollView;
39 #endif
40
41 #if PLATFORM(GTK)
42 typedef struct _GtkAdjustment GtkAdjustment;
43 #endif
44
45 #if PLATFORM(WX)
46 class wxScrollWinEvent;
47 #endif
48
49 // DANGER WILL ROBINSON! THIS FILE IS UNDERGOING HEAVY REFACTORING.
50 // Everything is changing!
51 // Port authors should wait until this refactoring is complete before attempting to implement this interface.
52 namespace WebCore {
53
54 class HostWindow;
55 class PlatformWheelEvent;
56 class Scrollbar;
57
58 class ScrollView : public Widget, public ScrollbarClient {
59 public:
60     ScrollView();
61     ~ScrollView();
62
63     // ScrollbarClient method.  FrameView overrides the other two.
64     virtual void valueChanged(Scrollbar*);
65     
66     // The window thats hosts the ScrollView.  The ScrollView will communicate scrolls and repaints to the
67     // host window in the window's coordinate space.
68     virtual HostWindow* hostWindow() const = 0;
69
70     // Returns a clip rect in host window coordinates.  Used to clip the blit on a scroll.
71     virtual IntRect windowClipRect(bool clipToContents = true) const = 0;
72
73     // Methods for child manipulation and inspection.
74     const HashSet<Widget*>* children() const { return &m_children; }
75     void addChild(Widget*);
76     void removeChild(Widget*);
77     
78     // If the scroll view does not use a native widget, then it will have cross-platform Scrollbars.  These methods
79     // can be used to obtain those scrollbars.
80     Scrollbar* horizontalScrollbar() const { return m_horizontalScrollbar.get(); }
81     Scrollbar* verticalScrollbar() const { return m_verticalScrollbar.get(); }
82     bool isScrollViewScrollbar(const Widget* child) const { return horizontalScrollbar() == child || verticalScrollbar() == child; }
83
84     // Methods for setting and retrieving the scrolling mode in each axis (horizontal/vertical).  The mode has values of
85     // AlwaysOff, AlwaysOn, and Auto.  AlwaysOff means never show a scrollbar, AlwaysOn means always show a scrollbar.
86     // Auto means show a scrollbar only when one is needed.
87     // Note that for platforms with native widgets, these modes are considered advisory.  In other words the underlying native
88     // widget may choose not to honor the requested modes.
89     void setScrollbarModes(ScrollbarMode horizontalMode, ScrollbarMode verticalMode);
90     void setHorizontalScrollbarMode(ScrollbarMode mode) { setScrollbarModes(mode, verticalScrollbarMode()); }
91     void setVerticalScrollbarMode(ScrollbarMode mode) { setScrollbarModes(horizontalScrollbarMode(), mode); }
92     void scrollbarModes(ScrollbarMode& horizontalMode, ScrollbarMode& verticalMode) const;
93     ScrollbarMode horizontalScrollbarMode() const { ScrollbarMode horizontal, vertical; scrollbarModes(horizontal, vertical); return horizontal; }
94     ScrollbarMode verticalScrollbarMode() const { ScrollbarMode horizontal, vertical; scrollbarModes(horizontal, vertical); return vertical; }
95     virtual void setCanHaveScrollbars(bool flag);
96     bool canHaveScrollbars() const { return horizontalScrollbarMode() != ScrollbarAlwaysOff || verticalScrollbarMode() != ScrollbarAlwaysOff; }
97
98     // If the prohibits scrolling flag is set, then all scrolling in the view (even programmatic scrolling) is turned off.
99     void setProhibitsScrolling(bool b) { m_prohibitsScrolling = b; }
100     bool prohibitsScrolling() const { return m_prohibitsScrolling; }
101
102     // Whether or not a scroll view will blit visible contents when it is scrolled.  Blitting is disabled in situations
103     // where it would cause rendering glitches (such as with fixed backgrounds or when the view is partially transparent).
104     void setCanBlitOnScroll(bool);
105     bool canBlitOnScroll() const { return m_canBlitOnScroll; }
106
107     // The visible content rect has a location that is the scrolled offset of the document. The width and height are the viewport width
108     // and height.  By default the scrollbars themselves are excluded from this rectangle, but an optional boolean argument allows them to be
109     // included.
110     IntRect visibleContentRect(bool includeScrollbars = false) const;
111     int visibleWidth() const { return visibleContentRect().width(); }
112     int visibleHeight() const { return visibleContentRect().height(); }
113     
114     // Methods for getting/setting the size of the document contained inside the ScrollView (as an IntSize or as individual width and height
115     // values).
116     IntSize contentsSize() const;
117     int contentsWidth() const { return contentsSize().width(); }
118     int contentsHeight() const { return contentsSize().height(); }
119     void setContentsSize(const IntSize&);
120    
121     // Methods for querying the current scrolled position (both as a point, a size, or as individual X and Y values).
122     IntPoint scrollPosition() const { return visibleContentRect().location(); }
123     IntSize scrollOffset() const { return visibleContentRect().location() - IntPoint(); } // Gets the scrolled position as an IntSize. Convenient for adding to other sizes.
124     IntPoint maximumScrollPosition() const; // The maximum position we can be scrolled to.
125     int scrollX() const { return scrollPosition().x(); }
126     int scrollY() const { return scrollPosition().y(); }
127     
128     // Methods for scrolling the view.  setScrollPosition is the only method that really scrolls the view.  The other two methods are helper functions
129     // that ultimately end up calling setScrollPosition.
130     void setScrollPosition(const IntPoint&);
131     void scrollBy(const IntSize& s) { return setScrollPosition(scrollPosition() + s); }
132     void scrollRectIntoViewRecursively(const IntRect&);
133     
134     // This method scrolls by lines, pages or pixels.
135     bool scroll(ScrollDirection, ScrollGranularity);
136         
137     // Scroll the actual contents of the view (either blitting or invalidating as needed).
138     void scrollContents(const IntSize& scrollDelta);
139
140     // This gives us a means of blocking painting on our scrollbars until the first layout has occurred.
141     void setScrollbarsSuppressed(bool suppressed, bool repaintOnUnsuppress = false);
142     bool scrollbarsSuppressed() const { return m_scrollbarsSuppressed; }
143
144     // Event coordinates are assumed to be in the coordinate space of a window that contains
145     // the entire widget hierarchy. It is up to the platform to decide what the precise definition
146     // of containing window is. (For example on Mac it is the containing NSWindow.)
147     IntPoint windowToContents(const IntPoint&) const;
148     IntPoint contentsToWindow(const IntPoint&) const;
149     IntRect windowToContents(const IntRect&) const;
150     IntRect contentsToWindow(const IntRect&) const;
151
152     // Methods for converting to and from screen coordinates.
153     IntRect contentsToScreen(const IntRect&) const;
154     IntPoint screenToContents(const IntPoint&) const;
155
156     // The purpose of this method is to answer whether or not the scroll view is currently visible.  Animations and painting updates can be suspended if
157     // we know that we are either not in a window right now or if that window is not visible.
158     bool isOffscreen() const;
159     
160     // These methods are used to enable scrollbars to avoid window resizer controls that overlap the scroll view.  This happens on Mac
161     // for example.
162     virtual IntRect windowResizerRect() const { return IntRect(); }
163     bool containsScrollbarsAvoidingResizer() const;
164     void adjustScrollbarsAvoidingResizerCount(int overlapDelta);
165     virtual void setParent(ScrollView*); // Overridden to update the overlapping scrollbar count.
166
167     // Called when our frame rect changes (or the rect/scroll position of an ancestor changes).
168     virtual void frameRectsChanged() const;
169     
170     // Widget override to update our scrollbars and notify our contents of the resize.
171     virtual void setFrameRect(const IntRect&);
172
173     // For platforms that need to hit test scrollbars from within the engine's event handlers (like Win32).
174     Scrollbar* scrollbarUnderMouse(const PlatformMouseEvent& mouseEvent);
175
176     // This method exists for scrollviews that need to handle wheel events manually.
177     // On Mac the underlying NSScrollView just does the scrolling, but on other platforms
178     // (like Windows), we need this method in order to do the scroll ourselves.
179     void wheelEvent(PlatformWheelEvent&);
180
181     IntPoint convertChildToSelf(const Widget* child, const IntPoint& point) const
182     {
183         IntPoint newPoint = point;
184         if (!isScrollViewScrollbar(child))
185             newPoint = point - scrollOffset();
186         newPoint.move(child->x(), child->y());
187         return newPoint;
188     }
189
190     IntPoint convertSelfToChild(const Widget* child, const IntPoint& point) const
191     {
192         IntPoint newPoint = point;
193         if (!isScrollViewScrollbar(child))
194             newPoint = point + scrollOffset();
195         newPoint.move(-child->x(), -child->y());
196         return newPoint;
197     }
198
199     // Widget override.  Handles painting of the contents of the view as well as the scrollbars.
200     virtual void paint(GraphicsContext*, const IntRect&);
201
202     // Widget overrides to ensure that our children's visibility status is kept up to date when we get shown and hidden.
203     virtual void show();
204     virtual void hide();
205     virtual void setParentVisible(bool);
206     
207     // Pan scrolling methods.
208     void addPanScrollIcon(const IntPoint&);
209     void removePanScrollIcon();
210
211     virtual bool scrollbarCornerPresent() const;
212
213 protected:
214     virtual void repaintContentRectangle(const IntRect&, bool now = false);
215     virtual void paintContents(GraphicsContext*, const IntRect& damageRect) = 0;
216     
217     virtual void contentsResized() = 0;
218     virtual void visibleContentsResized() = 0;
219     
220     // These methods are used to create/destroy scrollbars.
221     void setHasHorizontalScrollbar(bool);
222     void setHasVerticalScrollbar(bool);
223
224 private:
225     RefPtr<Scrollbar> m_horizontalScrollbar;
226     RefPtr<Scrollbar> m_verticalScrollbar;
227     ScrollbarMode m_horizontalScrollbarMode;
228     ScrollbarMode m_verticalScrollbarMode;
229     bool m_prohibitsScrolling;
230
231     HashSet<Widget*> m_children;
232     bool m_canBlitOnScroll;
233     IntSize m_scrollOffset; // FIXME: Would rather store this as a position, but we will wait to make this change until more code is shared.
234     IntSize m_contentsSize;
235
236     int m_scrollbarsAvoidingResizer;
237     bool m_scrollbarsSuppressed;
238
239     bool m_inUpdateScrollbars;
240
241     IntPoint m_panScrollIconPoint;
242     bool m_drawPanScrollIcon;
243
244     void init();
245     void destroy();
246
247     // Called to update the scrollbars to accurately reflect the state of the view.
248     void updateScrollbars(const IntSize& desiredOffset);
249
250     void platformInit();
251     void platformDestroy();
252     void platformAddChild(Widget*);
253     void platformRemoveChild(Widget*);
254     void platformSetScrollbarModes();
255     void platformScrollbarModes(ScrollbarMode& horizontal, ScrollbarMode& vertical) const;
256     void platformSetCanBlitOnScroll();
257     IntRect platformVisibleContentRect(bool includeScrollbars) const;
258     IntSize platformContentsSize() const;
259     void platformSetContentsSize();
260     IntRect platformContentsToScreen(const IntRect&) const;
261     IntPoint platformScreenToContents(const IntPoint&) const;
262     void platformSetScrollPosition(const IntPoint&);
263     bool platformScroll(ScrollDirection, ScrollGranularity);
264     void platformSetScrollbarsSuppressed(bool repaintOnUnsuppress);
265     void platformRepaintContentRectangle(const IntRect&, bool now);
266     bool platformIsOffscreen() const;
267     bool platformHandleHorizontalAdjustment(const IntSize&);
268     bool platformHandleVerticalAdjustment(const IntSize&);
269     bool platformHasHorizontalAdjustment() const;
270     bool platformHasVerticalAdjustment() const;
271
272 #if PLATFORM(MAC) && defined __OBJC__
273 public:
274     NSView* documentView() const;
275
276 private:
277     NSScrollView<WebCoreFrameScrollView>* scrollView() const;
278 #endif
279
280 #if PLATFORM(QT)
281 private:
282     bool rootPreventsBlitting() const { return root()->m_widgetsThatPreventBlitting > 0; }
283     unsigned m_widgetsThatPreventBlitting;
284 #else
285     bool rootPreventsBlitting() const { return false; }
286 #endif
287
288 #if PLATFORM(GTK)
289 public:
290     void setGtkAdjustments(GtkAdjustment* hadj, GtkAdjustment* vadj);
291     GtkAdjustment* m_horizontalAdjustment;
292     GtkAdjustment* m_verticalAdjustment;
293     void setScrollOffset(const IntSize& offset) { m_scrollOffset = offset; }
294 #endif
295
296 #if PLATFORM(WX)
297 public:
298     virtual void setPlatformWidget(wxWindow*);
299
300 private:
301     void adjustScrollbars(int x = -1, int y = -1, bool refresh = true);
302     class ScrollViewPrivate;
303     ScrollViewPrivate* m_data;
304 #endif
305
306 }; // class ScrollView
307
308 } // namespace WebCore
309
310 #endif // ScrollView_h