Bumping gaia.json for 8 gaia revision(s) a=gaia-bump
[gecko.git] / view / nsView.h
blob00cb7f37c3a0b1196c9cabdaae624bbcb2bd05a3
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #ifndef nsView_h__
7 #define nsView_h__
9 #include "nsCoord.h"
10 #include "nsRect.h"
11 #include "nsPoint.h"
12 #include "nsRegion.h"
13 #include "nsCRT.h"
14 #include "nsWidgetInitData.h" // for nsWindowType
15 #include "nsIWidgetListener.h"
16 #include "mozilla/EventForwards.h"
18 class nsViewManager;
19 class nsIWidget;
20 class nsIFrame;
22 // Enumerated type to indicate the visibility of a layer.
23 // hide - the layer is not shown.
24 // show - the layer is shown irrespective of the visibility of
25 // the layer's parent.
26 enum nsViewVisibility {
27 nsViewVisibility_kHide = 0,
28 nsViewVisibility_kShow = 1
31 // Public view flags
33 // Indicates that the view is using auto z-indexing
34 #define NS_VIEW_FLAG_AUTO_ZINDEX 0x0004
36 // Indicates that the view is a floating view.
37 #define NS_VIEW_FLAG_FLOATING 0x0008
39 //----------------------------------------------------------------------
41 /**
42 * View interface
44 * Views are NOT reference counted. Use the Destroy() member function to
45 * destroy a view.
47 * The lifetime of the view hierarchy is bounded by the lifetime of the
48 * view manager that owns the views.
50 * Most of the methods here are read-only. To set the corresponding properties
51 * of a view, go through nsViewManager.
54 class nsView MOZ_FINAL : public nsIWidgetListener
56 public:
57 friend class nsViewManager;
59 NS_DECL_AND_IMPL_ZEROING_OPERATOR_NEW
61 /**
62 * Get the view manager which "owns" the view.
63 * This method might require some expensive traversal work in the future. If you can get the
64 * view manager from somewhere else, do that instead.
65 * @result the view manager
67 nsViewManager* GetViewManager() const { return mViewManager; }
69 /**
70 * Find the view for the given widget, if there is one.
71 * @return the view the widget belongs to, or null if the widget doesn't
72 * belong to any view.
74 static nsView* GetViewFor(nsIWidget* aWidget);
76 /**
77 * Destroy the view.
79 * The view destroys its child views, and destroys and releases its
80 * widget (if it has one).
82 * Also informs the view manager that the view is destroyed by calling
83 * SetRootView(NULL) if the view is the root view and calling RemoveChild()
84 * otherwise.
86 void Destroy();
88 /**
89 * Called to get the position of a view.
90 * The specified coordinates are relative to the parent view's origin, but
91 * are in appunits of this.
92 * This is the (0, 0) origin of the coordinate space established by this view.
93 * @param x out parameter for x position
94 * @param y out parameter for y position
96 nsPoint GetPosition() const {
97 NS_ASSERTION(!IsRoot() || (mPosX == 0 && mPosY == 0),
98 "root views should always have explicit position of (0,0)");
99 return nsPoint(mPosX, mPosY);
103 * Called to get the dimensions and position of the view's bounds.
104 * The view's bounds (x,y) are relative to the origin of the parent view, but
105 * are in appunits of this.
106 * The view's bounds (x,y) might not be the same as the view's position,
107 * if the view has content above or to the left of its origin.
108 * @param aBounds out parameter for bounds
110 nsRect GetBounds() const { return mDimBounds; }
113 * The bounds of this view relative to this view. So this is the same as
114 * GetBounds except this is relative to this view instead of the parent view.
116 nsRect GetDimensions() const {
117 nsRect r = mDimBounds; r.MoveBy(-mPosX, -mPosY); return r;
121 * Get the offset between the coordinate systems of |this| and aOther.
122 * Adding the return value to a point in the coordinate system of |this|
123 * will transform the point to the coordinate system of aOther.
125 * The offset is expressed in appunits of |this|. So if you are getting the
126 * offset between views in different documents that might have different
127 * appunits per devpixel ratios you need to be careful how you use the
128 * result.
130 * If aOther is null, this will return the offset of |this| from the
131 * root of the viewmanager tree.
133 * This function is fastest when aOther is an ancestor of |this|.
135 * NOTE: this actually returns the offset from aOther to |this|, but
136 * that offset is added to transform _coordinates_ from |this| to aOther.
138 nsPoint GetOffsetTo(const nsView* aOther) const;
141 * Get the offset between the origin of |this| and the origin of aWidget.
142 * Adding the return value to a point in the coordinate system of |this|
143 * will transform the point to the coordinate system of aWidget.
145 * The offset is expressed in appunits of |this|.
147 nsPoint GetOffsetToWidget(nsIWidget* aWidget) const;
150 * Takes a point aPt that is in the coordinate system of |this|'s parent view
151 * and converts it to be in the coordinate system of |this| taking into
152 * account the offset and any app unit per dev pixel ratio differences.
154 nsPoint ConvertFromParentCoords(nsPoint aPt) const;
157 * Called to query the visibility state of a view.
158 * @result current visibility state
160 nsViewVisibility GetVisibility() const { return mVis; }
163 * Get whether the view "floats" above all other views,
164 * which tells the compositor not to consider higher views in
165 * the view hierarchy that would geometrically intersect with
166 * this view. This is a hack, but it fixes some problems with
167 * views that need to be drawn in front of all other views.
168 * @result true if the view floats, false otherwise.
170 bool GetFloating() const { return (mVFlags & NS_VIEW_FLAG_FLOATING) != 0; }
173 * Called to query the parent of the view.
174 * @result view's parent
176 nsView* GetParent() const { return mParent; }
179 * The view's first child is the child which is earliest in document order.
180 * @result first child
182 nsView* GetFirstChild() const { return mFirstChild; }
185 * Called to query the next sibling of the view.
186 * @result view's next sibling
188 nsView* GetNextSibling() const { return mNextSibling; }
191 * Set the view's frame.
193 void SetFrame(nsIFrame* aRootFrame) { mFrame = aRootFrame; }
196 * Retrieve the view's frame.
198 nsIFrame* GetFrame() const { return mFrame; }
201 * Get the nearest widget in this view or a parent of this view and
202 * the offset from the widget's origin to this view's origin
203 * @param aOffset - if non-null the offset from this view's origin to the
204 * widget's origin (usually positive) expressed in appunits of this will be
205 * returned in aOffset.
206 * @return the widget closest to this view; can be null because some view trees
207 * don't have widgets at all (e.g., printing), but if any view in the view tree
208 * has a widget, then it's safe to assume this will not return null
210 nsIWidget* GetNearestWidget(nsPoint* aOffset) const;
213 * Create a widget to associate with this view. This variant of
214 * CreateWidget*() will look around in the view hierarchy for an
215 * appropriate parent widget for the view.
217 * @param aWidgetInitData data used to initialize this view's widget before
218 * its create is called.
219 * @return error status
221 nsresult CreateWidget(nsWidgetInitData *aWidgetInitData = nullptr,
222 bool aEnableDragDrop = true,
223 bool aResetVisibility = true);
226 * Create a widget for this view with an explicit parent widget.
227 * |aParentWidget| must be nonnull. The other params are the same
228 * as for |CreateWidget()|.
230 nsresult CreateWidgetForParent(nsIWidget* aParentWidget,
231 nsWidgetInitData *aWidgetInitData = nullptr,
232 bool aEnableDragDrop = true,
233 bool aResetVisibility = true);
236 * Create a popup widget for this view. Pass |aParentWidget| to
237 * explicitly set the popup's parent. If it's not passed, the view
238 * hierarchy will be searched for an appropriate parent widget. The
239 * other params are the same as for |CreateWidget()|, except that
240 * |aWidgetInitData| must be nonnull.
242 nsresult CreateWidgetForPopup(nsWidgetInitData *aWidgetInitData,
243 nsIWidget* aParentWidget = nullptr,
244 bool aEnableDragDrop = true,
245 bool aResetVisibility = true);
248 * Destroys the associated widget for this view. If this method is
249 * not called explicitly, the widget when be destroyed when its
250 * view gets destroyed.
252 void DestroyWidget();
255 * Attach/detach a top level widget from this view. When attached, the view
256 * updates the widget's device context and allows the view to begin receiving
257 * gecko events. The underlying base window associated with the widget will
258 * continues to receive events it expects.
260 * An attached widget will not be destroyed when the view is destroyed,
261 * allowing the recycling of a single top level widget over multiple views.
263 * @param aWidget The widget to attach to / detach from.
265 nsresult AttachToTopLevelWidget(nsIWidget* aWidget);
266 nsresult DetachFromTopLevelWidget();
269 * Returns a flag indicating whether the view owns it's widget
270 * or is attached to an existing top level widget.
272 bool IsAttachedToTopLevel() const { return mWidgetIsTopLevel; }
275 * In 4.0, the "cutout" nature of a view is queryable.
276 * If we believe that all cutout view have a native widget, this
277 * could be a replacement.
278 * @param aWidget out parameter for widget that this view contains,
279 * or nullptr if there is none.
281 nsIWidget* GetWidget() const { return mWindow; }
284 * Returns true if the view has a widget associated with it.
286 bool HasWidget() const { return mWindow != nullptr; }
288 void SetForcedRepaint(bool aForceRepaint) {
289 mForcedRepaint = aForceRepaint;
293 * Make aWidget direct its events to this view.
294 * The caller must call DetachWidgetEventHandler before this view
295 * is destroyed.
297 void AttachWidgetEventHandler(nsIWidget* aWidget);
299 * Stop aWidget directing its events to this view.
301 void DetachWidgetEventHandler(nsIWidget* aWidget);
303 #ifdef DEBUG
305 * Output debug info to FILE
306 * @param out output file handle
307 * @param aIndent indentation depth
308 * NOTE: virtual so that debugging tools not linked into gklayout can access it
310 virtual void List(FILE* out, int32_t aIndent = 0) const;
311 #endif // DEBUG
314 * @result true iff this is the root view for its view manager
316 bool IsRoot() const;
318 nsIntRect CalcWidgetBounds(nsWindowType aType);
320 // This is an app unit offset to add when converting view coordinates to
321 // widget coordinates. It is the offset in view coordinates from widget
322 // origin (unlike views, widgets can't extend above or to the left of their
323 // origin) to view origin expressed in appunits of this.
324 nsPoint ViewToWidgetOffset() const { return mViewToWidgetOffset; }
327 * Called to indicate that the position of the view has been changed.
328 * The specified coordinates are in the parent view's coordinate space.
329 * @param x new x position
330 * @param y new y position
332 void SetPosition(nscoord aX, nscoord aY);
335 * Called to indicate that the z-index of a view has been changed.
336 * The z-index is relative to all siblings of the view.
337 * @param aAuto Indicate that the z-index of a view is "auto". An "auto" z-index
338 * means that the view does not define a new stacking context,
339 * which means that the z-indicies of the view's children are
340 * relative to the view's siblings.
341 * @param zindex new z depth
343 void SetZIndex(bool aAuto, int32_t aZIndex);
344 bool GetZIndexIsAuto() const { return (mVFlags & NS_VIEW_FLAG_AUTO_ZINDEX) != 0; }
345 int32_t GetZIndex() const { return mZIndex; }
347 void SetParent(nsView *aParent) { mParent = aParent; }
348 void SetNextSibling(nsView *aSibling)
350 NS_ASSERTION(aSibling != this, "Can't be our own sibling!");
351 mNextSibling = aSibling;
354 nsRegion* GetDirtyRegion() {
355 if (!mDirtyRegion) {
356 NS_ASSERTION(!mParent || GetFloating(),
357 "Only display roots should have dirty regions");
358 mDirtyRegion = new nsRegion();
359 NS_ASSERTION(mDirtyRegion, "Out of memory!");
361 return mDirtyRegion;
364 // nsIWidgetListener
365 virtual nsIPresShell* GetPresShell() MOZ_OVERRIDE;
366 virtual nsView* GetView() MOZ_OVERRIDE { return this; }
367 virtual bool WindowMoved(nsIWidget* aWidget, int32_t x, int32_t y) MOZ_OVERRIDE;
368 virtual bool WindowResized(nsIWidget* aWidget, int32_t aWidth, int32_t aHeight) MOZ_OVERRIDE;
369 virtual bool RequestWindowClose(nsIWidget* aWidget) MOZ_OVERRIDE;
370 virtual void WillPaintWindow(nsIWidget* aWidget) MOZ_OVERRIDE;
371 virtual bool PaintWindow(nsIWidget* aWidget, nsIntRegion aRegion) MOZ_OVERRIDE;
372 virtual void DidPaintWindow() MOZ_OVERRIDE;
373 virtual void DidCompositeWindow() MOZ_OVERRIDE;
374 virtual void RequestRepaint() MOZ_OVERRIDE;
375 virtual nsEventStatus HandleEvent(mozilla::WidgetGUIEvent* aEvent,
376 bool aUseAttachedEvents) MOZ_OVERRIDE;
378 virtual ~nsView();
380 nsPoint GetOffsetTo(const nsView* aOther, const int32_t aAPD) const;
381 nsIWidget* GetNearestWidget(nsPoint* aOffset, const int32_t aAPD) const;
383 private:
384 explicit nsView(nsViewManager* aViewManager = nullptr,
385 nsViewVisibility aVisibility = nsViewVisibility_kShow);
387 bool ForcedRepaint() { return mForcedRepaint; }
389 // Do the actual work of ResetWidgetBounds, unconditionally. Don't
390 // call this method if we have no widget.
391 void DoResetWidgetBounds(bool aMoveOnly, bool aInvalidateChangedSize);
392 void InitializeWindow(bool aEnableDragDrop, bool aResetVisibility);
394 bool IsEffectivelyVisible();
397 * Called to indicate that the dimensions of the view have been changed.
398 * The x and y coordinates may be < 0, indicating that the view extends above
399 * or to the left of its origin position. The term 'dimensions' indicates it
400 * is relative to this view.
402 void SetDimensions(const nsRect &aRect, bool aPaint = true,
403 bool aResizeWidget = true);
406 * Called to indicate that the visibility of a view has been
407 * changed.
408 * @param visibility new visibility state
410 void SetVisibility(nsViewVisibility visibility);
413 * Set/Get whether the view "floats" above all other views,
414 * which tells the compositor not to consider higher views in
415 * the view hierarchy that would geometrically intersect with
416 * this view. This is a hack, but it fixes some problems with
417 * views that need to be drawn in front of all other views.
418 * @result true if the view floats, false otherwise.
420 void SetFloating(bool aFloatingView);
422 // Helper function to get mouse grabbing off this view (by moving it to the
423 // parent, if we can)
424 void DropMouseGrabbing();
426 // Same as GetBounds but converts to parent appunits if they are different.
427 nsRect GetBoundsInParentUnits() const;
429 bool HasNonEmptyDirtyRegion() {
430 return mDirtyRegion && !mDirtyRegion->IsEmpty();
433 void InsertChild(nsView *aChild, nsView *aSibling);
434 void RemoveChild(nsView *aChild);
436 void ResetWidgetBounds(bool aRecurse, bool aForceSync);
437 void AssertNoWindow();
439 void NotifyEffectiveVisibilityChanged(bool aEffectivelyVisible);
441 // Update the cached RootViewManager for all view manager descendents,
442 // If the hierarchy is being removed, aViewManagerParent points to the view
443 // manager for the hierarchy's old parent, and will have its mouse grab
444 // released if it points to any view in this view hierarchy.
445 void InvalidateHierarchy(nsViewManager *aViewManagerParent);
447 nsViewManager *mViewManager;
448 nsView *mParent;
449 nsIWidget *mWindow;
450 nsView *mNextSibling;
451 nsView *mFirstChild;
452 nsIFrame *mFrame;
453 nsRegion *mDirtyRegion;
454 int32_t mZIndex;
455 nsViewVisibility mVis;
456 // position relative our parent view origin but in our appunits
457 nscoord mPosX, mPosY;
458 // relative to parent, but in our appunits
459 nsRect mDimBounds;
460 // in our appunits
461 nsPoint mViewToWidgetOffset;
462 uint32_t mVFlags;
463 bool mWidgetIsTopLevel;
464 bool mForcedRepaint;
467 #endif