1 : /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 : /* ***** BEGIN LICENSE BLOCK *****
3 : * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 : *
5 : * The contents of this file are subject to the Mozilla Public License Version
6 : * 1.1 (the "License"); you may not use this file except in compliance with
7 : * the License. You may obtain a copy of the License at
8 : * http://www.mozilla.org/MPL/
9 : *
10 : * Software distributed under the License is distributed on an "AS IS" basis,
11 : * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 : * for the specific language governing rights and limitations under the
13 : * License.
14 : *
15 : * The Original Code is mozilla.org code.
16 : *
17 : * The Initial Developer of the Original Code is
18 : * Netscape Communications Corporation.
19 : * Portions created by the Initial Developer are Copyright (C) 1998
20 : * the Initial Developer. All Rights Reserved.
21 : *
22 : * Contributor(s):
23 : *
24 : * Alternatively, the contents of this file may be used under the terms of
25 : * either of the GNU General Public License Version 2 or later (the "GPL"),
26 : * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
27 : * in which case the provisions of the GPL or the LGPL are applicable instead
28 : * of those above. If you wish to allow use of your version of this file only
29 : * under the terms of either the GPL or the LGPL, and not to allow others to
30 : * use your version of this file under the terms of the MPL, indicate your
31 : * decision by deleting the provisions above and replace them with the notice
32 : * and other provisions required by the GPL or the LGPL. If you do not delete
33 : * the provisions above, a recipient may use your version of this file under
34 : * the terms of any one of the MPL, the GPL or the LGPL.
35 : *
36 : * ***** END LICENSE BLOCK ***** */
37 :
38 : /*
39 : * interface that provides scroll APIs implemented by scrollable frames
40 : */
41 :
42 : #ifndef nsIScrollFrame_h___
43 : #define nsIScrollFrame_h___
44 :
45 : #include "nsISupports.h"
46 : #include "nsCoord.h"
47 : #include "nsPresContext.h"
48 : #include "nsIFrame.h" // to get nsIBox, which is a typedef
49 :
50 : #define NS_DEFAULT_VERTICAL_SCROLL_DISTANCE 3
51 :
52 : class nsBoxLayoutState;
53 : class nsIScrollPositionListener;
54 :
55 : /**
56 : * Interface for frames that are scrollable. This interface exposes
57 : * APIs for examining scroll state, observing changes to scroll state,
58 : * and triggering scrolling.
59 : */
60 0 : class nsIScrollableFrame : public nsQueryFrame {
61 : public:
62 :
63 : NS_DECL_QUERYFRAME_TARGET(nsIScrollableFrame)
64 :
65 : /**
66 : * Get the frame for the content that we are scrolling within
67 : * this scrollable frame.
68 : */
69 : virtual nsIFrame* GetScrolledFrame() const = 0;
70 :
71 : typedef nsPresContext::ScrollbarStyles ScrollbarStyles;
72 : /**
73 : * Get the styles (NS_STYLE_OVERFLOW_SCROLL, NS_STYLE_OVERFLOW_HIDDEN,
74 : * or NS_STYLE_OVERFLOW_AUTO) governing the horizontal and vertical
75 : * scrollbars for this frame.
76 : */
77 : virtual ScrollbarStyles GetScrollbarStyles() const = 0;
78 :
79 : enum { HORIZONTAL = 0x01, VERTICAL = 0x02 };
80 : /**
81 : * Return the scrollbars which are visible. It's OK to call this during reflow
82 : * of the scrolled contents, in which case it will reflect the current
83 : * assumptions about scrollbar visibility.
84 : */
85 : virtual PRUint32 GetScrollbarVisibility() const = 0;
86 : /**
87 : * Return the actual sizes of all possible scrollbars. Returns 0 for scrollbar
88 : * positions that don't have a scrollbar or where the scrollbar is not visible.
89 : * Do not call this while this frame's descendants are being reflowed, it won't be
90 : * accurate.
91 : */
92 : virtual nsMargin GetActualScrollbarSizes() const = 0;
93 : /**
94 : * Return the sizes of all scrollbars assuming that any scrollbars that could
95 : * be visible due to overflowing content, are. This can be called during reflow
96 : * of the scrolled contents.
97 : */
98 : virtual nsMargin GetDesiredScrollbarSizes(nsBoxLayoutState* aState) = 0;
99 : /**
100 : * Return the sizes of all scrollbars assuming that any scrollbars that could
101 : * be visible due to overflowing content, are. This can be called during reflow
102 : * of the scrolled contents.
103 : */
104 : virtual nsMargin GetDesiredScrollbarSizes(nsPresContext* aPresContext,
105 : nsRenderingContext* aRC) = 0;
106 :
107 : /**
108 : * Get the area of the scrollport relative to the origin of this frame's
109 : * border-box.
110 : * This is the area of this frame minus border and scrollbars.
111 : */
112 : virtual nsRect GetScrollPortRect() const = 0;
113 : /**
114 : * Get the offset of the scrollport origin relative to the scrolled
115 : * frame origin. Typically the position will be non-negative.
116 : * This will always be a multiple of device pixels.
117 : */
118 : virtual nsPoint GetScrollPosition() const = 0;
119 : /**
120 : * Get the area that must contain the scroll position. Typically
121 : * (but not always, e.g. for RTL content) x and y will be 0, and
122 : * width or height will be nonzero if the content can be scrolled in
123 : * that direction. Since scroll positions must be a multiple of
124 : * device pixels, the range extrema will also be a multiple of
125 : * device pixels.
126 : */
127 : virtual nsRect GetScrollRange() const = 0;
128 :
129 : /**
130 : * Return how much we would try to scroll by in each direction if
131 : * asked to scroll by one "line" vertically and horizontally.
132 : */
133 : virtual nsSize GetLineScrollAmount() const = 0;
134 : /**
135 : * Return how much we would try to scroll by in each direction if
136 : * asked to scroll by one "page" vertically and horizontally.
137 : */
138 : virtual nsSize GetPageScrollAmount() const = 0;
139 :
140 : /**
141 : * When a scroll operation is requested, we ask for instant, smooth or normal
142 : * scrolling. SMOOTH will only be smooth if smooth scrolling is actually
143 : * enabled. INSTANT is always synchronous, NORMAL can be asynchronous.
144 : * If an INSTANT request happens while a smooth or async scroll is already in
145 : * progress, the async scroll is interrupted and we instantly scroll to the
146 : * destination.
147 : */
148 : enum ScrollMode { INSTANT, SMOOTH, NORMAL };
149 : /**
150 : * Clamps aScrollPosition to GetScrollRange and sets the scroll position
151 : * to that value.
152 : */
153 : virtual void ScrollTo(nsPoint aScrollPosition, ScrollMode aMode) = 0;
154 : /**
155 : * When scrolling by a relative amount, we can choose various units.
156 : */
157 : enum ScrollUnit { DEVICE_PIXELS, LINES, PAGES, WHOLE };
158 : /**
159 : * Modifies the current scroll position by aDelta units given by aUnit,
160 : * clamping it to GetScrollRange. If WHOLE is specified as the unit,
161 : * content is scrolled all the way in the direction(s) given by aDelta.
162 : * @param aOverflow if non-null, returns the amount that scrolling
163 : * was clamped by in each direction (how far we moved the scroll position
164 : * to bring it back into the legal range). This is never negative. The
165 : * values are in device pixels.
166 : */
167 : virtual void ScrollBy(nsIntPoint aDelta, ScrollUnit aUnit, ScrollMode aMode,
168 : nsIntPoint* aOverflow = nsnull, nsIAtom *aOrigin = nsnull) = 0;
169 : /**
170 : * This tells the scroll frame to try scrolling to the scroll
171 : * position that was restored from the history. This must be called
172 : * at least once after state has been restored. It is called by the
173 : * scrolled frame itself during reflow, but sometimes state can be
174 : * restored after reflows are done...
175 : * XXX should we take an aMode parameter here? Currently it's instant.
176 : */
177 : virtual void ScrollToRestoredPosition() = 0;
178 :
179 : /**
180 : * Add a scroll position listener. This listener must be removed
181 : * before it is destroyed.
182 : */
183 : virtual void AddScrollPositionListener(nsIScrollPositionListener* aListener) = 0;
184 : /**
185 : * Remove a scroll position listener.
186 : */
187 : virtual void RemoveScrollPositionListener(nsIScrollPositionListener* aListener) = 0;
188 :
189 : /**
190 : * Obtain the XUL box for the horizontal or vertical scrollbar, or null
191 : * if there is no such box. Avoid using this, but may be useful for
192 : * setting up a scrollbar mediator if you want to redirect scrollbar
193 : * input.
194 : */
195 : virtual nsIBox* GetScrollbarBox(bool aVertical) = 0;
196 :
197 : /**
198 : * Internal method used by scrollbars to notify their scrolling
199 : * container of changes.
200 : */
201 : virtual void CurPosAttributeChanged(nsIContent* aChild) = 0;
202 :
203 : /**
204 : * Allows the docshell to request that the scroll frame post an event
205 : * after being restored from history.
206 : */
207 : NS_IMETHOD PostScrolledAreaEventForCurrentArea() = 0;
208 :
209 : /**
210 : * Returns true if this scrollframe is being "actively scrolled".
211 : * This basically means that we should allocate resources in the
212 : * expectation that scrolling is going to happen.
213 : */
214 : virtual bool IsScrollingActive() = 0;
215 : };
216 :
217 : #endif
|