1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/layout/generic/nsIScrollableFrame.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,312 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +/*
1.10 + * interface that provides scroll APIs implemented by scrollable frames
1.11 + */
1.12 +
1.13 +#ifndef nsIScrollFrame_h___
1.14 +#define nsIScrollFrame_h___
1.15 +
1.16 +#include "nsCoord.h"
1.17 +#include "ScrollbarStyles.h"
1.18 +#include "mozilla/gfx/Point.h"
1.19 +#include "nsIScrollbarOwner.h"
1.20 +#include "Units.h"
1.21 +
1.22 +#define NS_DEFAULT_VERTICAL_SCROLL_DISTANCE 3
1.23 +#define NS_DEFAULT_HORIZONTAL_SCROLL_DISTANCE 5
1.24 +
1.25 +class nsBoxLayoutState;
1.26 +class nsIScrollPositionListener;
1.27 +class nsIFrame;
1.28 +class nsPresContext;
1.29 +class nsIContent;
1.30 +class nsRenderingContext;
1.31 +class nsIAtom;
1.32 +
1.33 +/**
1.34 + * Interface for frames that are scrollable. This interface exposes
1.35 + * APIs for examining scroll state, observing changes to scroll state,
1.36 + * and triggering scrolling.
1.37 + */
1.38 +class nsIScrollableFrame : public nsIScrollbarOwner {
1.39 +public:
1.40 + typedef mozilla::CSSIntPoint CSSIntPoint;
1.41 +
1.42 + NS_DECL_QUERYFRAME_TARGET(nsIScrollableFrame)
1.43 +
1.44 + /**
1.45 + * Get the frame for the content that we are scrolling within
1.46 + * this scrollable frame.
1.47 + */
1.48 + virtual nsIFrame* GetScrolledFrame() const = 0;
1.49 +
1.50 + /**
1.51 + * Get the styles (NS_STYLE_OVERFLOW_SCROLL, NS_STYLE_OVERFLOW_HIDDEN,
1.52 + * or NS_STYLE_OVERFLOW_AUTO) governing the horizontal and vertical
1.53 + * scrollbars for this frame.
1.54 + */
1.55 + virtual mozilla::ScrollbarStyles GetScrollbarStyles() const = 0;
1.56 +
1.57 + enum { HORIZONTAL = 0x01, VERTICAL = 0x02 };
1.58 + /**
1.59 + * Return the scrollbars which are visible. It's OK to call this during reflow
1.60 + * of the scrolled contents, in which case it will reflect the current
1.61 + * assumptions about scrollbar visibility.
1.62 + */
1.63 + virtual uint32_t GetScrollbarVisibility() const = 0;
1.64 + /**
1.65 + * Returns the directions in which scrolling is perceived to be allowed.
1.66 + * A direction is perceived to be allowed if there is a visible scrollbar
1.67 + * for that direction or if the scroll range is at least one device pixel.
1.68 + */
1.69 + uint32_t GetPerceivedScrollingDirections() const;
1.70 + /**
1.71 + * Return the actual sizes of all possible scrollbars. Returns 0 for scrollbar
1.72 + * positions that don't have a scrollbar or where the scrollbar is not visible.
1.73 + * Do not call this while this frame's descendants are being reflowed, it won't be
1.74 + * accurate.
1.75 + */
1.76 + virtual nsMargin GetActualScrollbarSizes() const = 0;
1.77 + /**
1.78 + * Return the sizes of all scrollbars assuming that any scrollbars that could
1.79 + * be visible due to overflowing content, are. This can be called during reflow
1.80 + * of the scrolled contents.
1.81 + */
1.82 + virtual nsMargin GetDesiredScrollbarSizes(nsBoxLayoutState* aState) = 0;
1.83 + /**
1.84 + * Return the sizes of all scrollbars assuming that any scrollbars that could
1.85 + * be visible due to overflowing content, are. This can be called during reflow
1.86 + * of the scrolled contents.
1.87 + */
1.88 + virtual nsMargin GetDesiredScrollbarSizes(nsPresContext* aPresContext,
1.89 + nsRenderingContext* aRC) = 0;
1.90 + /**
1.91 + * Return the width for non-disappearing scrollbars.
1.92 + */
1.93 + virtual nscoord GetNondisappearingScrollbarWidth(nsPresContext* aPresContext,
1.94 + nsRenderingContext* aRC) = 0;
1.95 + /**
1.96 + * GetScrolledRect is designed to encapsulate deciding which
1.97 + * directions of overflow should be reachable by scrolling and which
1.98 + * should not. Callers should NOT depend on it having any particular
1.99 + * behavior (although nsXULScrollFrame currently does).
1.100 + *
1.101 + * This should only be called when the scrolled frame has been
1.102 + * reflowed with the scroll port size given in mScrollPort.
1.103 + *
1.104 + * Currently it allows scrolling down and to the right for
1.105 + * nsHTMLScrollFrames with LTR directionality and for all
1.106 + * nsXULScrollFrames, and allows scrolling down and to the left for
1.107 + * nsHTMLScrollFrames with RTL directionality.
1.108 + */
1.109 + virtual nsRect GetScrolledRect() const = 0;
1.110 + /**
1.111 + * Get the area of the scrollport relative to the origin of this frame's
1.112 + * border-box.
1.113 + * This is the area of this frame minus border and scrollbars.
1.114 + */
1.115 + virtual nsRect GetScrollPortRect() const = 0;
1.116 + /**
1.117 + * Get the offset of the scrollport origin relative to the scrolled
1.118 + * frame origin. Typically the position will be non-negative.
1.119 + * This will always be a multiple of device pixels.
1.120 + */
1.121 + virtual nsPoint GetScrollPosition() const = 0;
1.122 + /**
1.123 + * As GetScrollPosition(), but uses the top-right as origin for RTL frames.
1.124 + */
1.125 + virtual nsPoint GetLogicalScrollPosition() const = 0;
1.126 + /**
1.127 + * Get the area that must contain the scroll position. Typically
1.128 + * (but not always, e.g. for RTL content) x and y will be 0, and
1.129 + * width or height will be nonzero if the content can be scrolled in
1.130 + * that direction. Since scroll positions must be a multiple of
1.131 + * device pixels, the range extrema will also be a multiple of
1.132 + * device pixels.
1.133 + */
1.134 + virtual nsRect GetScrollRange() const = 0;
1.135 + /**
1.136 + * Get the size of the scroll port to use when clamping the scroll
1.137 + * position.
1.138 + */
1.139 + virtual nsSize GetScrollPositionClampingScrollPortSize() const = 0;
1.140 + /**
1.141 + * Get the element resolution.
1.142 + */
1.143 + virtual gfxSize GetResolution() const = 0;
1.144 + /**
1.145 + * Set the element resolution.
1.146 + */
1.147 + virtual void SetResolution(const gfxSize& aResolution) = 0;
1.148 + /**
1.149 + * Return how much we would try to scroll by in each direction if
1.150 + * asked to scroll by one "line" vertically and horizontally.
1.151 + */
1.152 + virtual nsSize GetLineScrollAmount() const = 0;
1.153 + /**
1.154 + * Return how much we would try to scroll by in each direction if
1.155 + * asked to scroll by one "page" vertically and horizontally.
1.156 + */
1.157 + virtual nsSize GetPageScrollAmount() const = 0;
1.158 +
1.159 + /**
1.160 + * When a scroll operation is requested, we ask for instant, smooth or normal
1.161 + * scrolling. SMOOTH will only be smooth if smooth scrolling is actually
1.162 + * enabled. INSTANT is always synchronous, NORMAL can be asynchronous.
1.163 + * If an INSTANT request happens while a smooth or async scroll is already in
1.164 + * progress, the async scroll is interrupted and we instantly scroll to the
1.165 + * destination.
1.166 + */
1.167 + enum ScrollMode { INSTANT, SMOOTH, NORMAL };
1.168 + /**
1.169 + * @note This method might destroy the frame, pres shell and other objects.
1.170 + * Clamps aScrollPosition to GetScrollRange and sets the scroll position
1.171 + * to that value.
1.172 + * @param aRange If non-null, specifies area which contains aScrollPosition
1.173 + * and can be used for choosing a performance-optimized scroll position.
1.174 + * Any point within this area can be chosen.
1.175 + * The choosen point will be as close as possible to aScrollPosition.
1.176 + */
1.177 + virtual void ScrollTo(nsPoint aScrollPosition, ScrollMode aMode,
1.178 + const nsRect* aRange = nullptr) = 0;
1.179 + /**
1.180 + * @note This method might destroy the frame, pres shell and other objects.
1.181 + * Scrolls to a particular position in integer CSS pixels.
1.182 + * Keeps the exact current horizontal or vertical position if the current
1.183 + * position, rounded to CSS pixels, matches aScrollPosition. If
1.184 + * aScrollPosition.x/y is different from the current CSS pixel position,
1.185 + * makes sure we only move in the direction given by the difference.
1.186 + * Ensures that GetScrollPositionCSSPixels (the scroll position after
1.187 + * rounding to CSS pixels) will be exactly aScrollPosition.
1.188 + * The scroll mode is INSTANT.
1.189 + */
1.190 + virtual void ScrollToCSSPixels(const CSSIntPoint& aScrollPosition) = 0;
1.191 + /**
1.192 + * @note This method might destroy the frame, pres shell and other objects.
1.193 + * Scrolls to a particular position in float CSS pixels.
1.194 + * This does not guarantee that GetScrollPositionCSSPixels equals
1.195 + * aScrollPosition afterward. It tries to scroll as close to
1.196 + * aScrollPosition as possible while scrolling by an integer
1.197 + * number of layer pixels (so the operation is fast and looks clean).
1.198 + * The scroll mode is INSTANT.
1.199 + */
1.200 + virtual void ScrollToCSSPixelsApproximate(const mozilla::CSSPoint& aScrollPosition,
1.201 + nsIAtom *aOrigin = nullptr) = 0;
1.202 +
1.203 + /**
1.204 + * Returns the scroll position in integer CSS pixels, rounded to the nearest
1.205 + * pixel.
1.206 + */
1.207 + virtual CSSIntPoint GetScrollPositionCSSPixels() = 0;
1.208 + /**
1.209 + * When scrolling by a relative amount, we can choose various units.
1.210 + */
1.211 + enum ScrollUnit { DEVICE_PIXELS, LINES, PAGES, WHOLE };
1.212 + /**
1.213 + * @note This method might destroy the frame, pres shell and other objects.
1.214 + * Modifies the current scroll position by aDelta units given by aUnit,
1.215 + * clamping it to GetScrollRange. If WHOLE is specified as the unit,
1.216 + * content is scrolled all the way in the direction(s) given by aDelta.
1.217 + * @param aOverflow if non-null, returns the amount that scrolling
1.218 + * was clamped by in each direction (how far we moved the scroll position
1.219 + * to bring it back into the legal range). This is never negative. The
1.220 + * values are in device pixels.
1.221 + */
1.222 + virtual void ScrollBy(nsIntPoint aDelta, ScrollUnit aUnit, ScrollMode aMode,
1.223 + nsIntPoint* aOverflow = nullptr, nsIAtom *aOrigin = nullptr) = 0;
1.224 + /**
1.225 + * @note This method might destroy the frame, pres shell and other objects.
1.226 + * This tells the scroll frame to try scrolling to the scroll
1.227 + * position that was restored from the history. This must be called
1.228 + * at least once after state has been restored. It is called by the
1.229 + * scrolled frame itself during reflow, but sometimes state can be
1.230 + * restored after reflows are done...
1.231 + * XXX should we take an aMode parameter here? Currently it's instant.
1.232 + */
1.233 + virtual void ScrollToRestoredPosition() = 0;
1.234 +
1.235 + /**
1.236 + * Add a scroll position listener. This listener must be removed
1.237 + * before it is destroyed.
1.238 + */
1.239 + virtual void AddScrollPositionListener(nsIScrollPositionListener* aListener) = 0;
1.240 + /**
1.241 + * Remove a scroll position listener.
1.242 + */
1.243 + virtual void RemoveScrollPositionListener(nsIScrollPositionListener* aListener) = 0;
1.244 +
1.245 + /**
1.246 + * Internal method used by scrollbars to notify their scrolling
1.247 + * container of changes.
1.248 + */
1.249 + virtual void CurPosAttributeChanged(nsIContent* aChild) = 0;
1.250 +
1.251 + /**
1.252 + * Allows the docshell to request that the scroll frame post an event
1.253 + * after being restored from history.
1.254 + */
1.255 + NS_IMETHOD PostScrolledAreaEventForCurrentArea() = 0;
1.256 +
1.257 + /**
1.258 + * Returns true if this scrollframe is being "actively scrolled".
1.259 + * This basically means that we should allocate resources in the
1.260 + * expectation that scrolling is going to happen.
1.261 + */
1.262 + virtual bool IsScrollingActive() = 0;
1.263 + /**
1.264 + * Returns true if the scrollframe is currently processing an async
1.265 + * or smooth scroll.
1.266 + */
1.267 + virtual bool IsProcessingAsyncScroll() = 0;
1.268 + /**
1.269 + * Call this when the layer(s) induced by active scrolling are being
1.270 + * completely redrawn.
1.271 + */
1.272 + virtual void ResetScrollPositionForLayerPixelAlignment() = 0;
1.273 + /**
1.274 + * Was the current presentation state for this frame restored from history?
1.275 + */
1.276 + virtual bool DidHistoryRestore() const = 0;
1.277 + /**
1.278 + * Was the current resolution set by the user or just default initialized?
1.279 + */
1.280 + virtual bool IsResolutionSet() const = 0;
1.281 + /**
1.282 + * Clear the flag so that DidHistoryRestore() returns false until the next
1.283 + * RestoreState call.
1.284 + * @see nsIStatefulFrame::RestoreState
1.285 + */
1.286 + virtual void ClearDidHistoryRestore() = 0;
1.287 + /**
1.288 + * Determine if the passed in rect is nearly visible according to the image
1.289 + * visibility heuristics for how close it is to the visible scrollport.
1.290 + */
1.291 + virtual bool IsRectNearlyVisible(const nsRect& aRect) = 0;
1.292 + /**
1.293 + * Returns the origin passed in to the last ScrollToImpl call that took
1.294 + * effect.
1.295 + */
1.296 + virtual nsIAtom* OriginOfLastScroll() = 0;
1.297 + /**
1.298 + * Returns the current generation counter for the scroll. This counter
1.299 + * increments every time the scroll position is set.
1.300 + */
1.301 + virtual uint32_t CurrentScrollGeneration() = 0;
1.302 + /**
1.303 + * Clears the "origin of last scroll" property stored in this frame, if
1.304 + * the generation counter passed in matches the current scroll generation
1.305 + * counter.
1.306 + */
1.307 + virtual void ResetOriginIfScrollAtGeneration(uint32_t aGeneration) = 0;
1.308 + /**
1.309 + * Determine whether it is desirable to be able to asynchronously scroll this
1.310 + * scroll frame.
1.311 + */
1.312 + virtual bool WantAsyncScroll() const = 0;
1.313 +};
1.314 +
1.315 +#endif
