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/. */
15 #include "nsWidgetInitData.h" // for nsWindowType
16 #include "nsIWidgetListener.h"
18 #include "mozilla/Attributes.h"
19 #include "mozilla/EventForwards.h"
20 #include "mozilla/UniquePtr.h"
28 } // namespace mozilla
31 * nsView's serve two main purposes: 1) a bridge between nsIFrame's and
32 * nsIWidget's, 2) linking the frame tree of a(n) (in-process) subdocument with
33 * its parent document frame tree. Historically views were used for more things,
34 * but their role has been reduced, and could be reduced to nothing in the
35 * future (bug 337801 tracks removing views). Views are generally associated
36 * with a frame. A view that does not have a frame is called an anonymous view.
37 * Some frames also have associated widgets (think os level windows). If a frame
38 * has a widget it must also have a view, but not all frames with views will
41 * Only four types of frames can have a view: root frames (ViewportFrame),
42 * subdocument frames (nsSubDocumentFrame),
43 * menu popup frames (nsMenuPopupFrame), and list control frames
44 * (nsListControlFrame). Root frames and subdocument frames have views to link
45 * the two documents together (the frame trees do not link up otherwise).
46 * Menu popup frames, and list control frames have views because
47 * they (sometimes) need to create widgets.
48 * Menu popup frames handles xul popups, which is anything
49 * where we need content to go over top the main window at an os level. List
50 * control frames handle select popups/dropdowns in non-e10s mode.
52 * The term "root view" refers to the root view of a document. Just like root
53 * frames, root views can have parent views. Only the root view of the root
54 * document in the process will not have a parent.
56 * All views are created by their frames except root views. Root views are
57 * special. Root views are created in nsDocumentViewer::MakeWindow before the
58 * root frame is created, so the root view will not have a frame very early in
61 * Subdocument frames have an anonymous (no frame associated
62 * with it) inner view that is a child of their "outer" view.
64 * On a subdocument frame the inner view serves as the parent of the
65 * root view of the subdocument. The outer and inner view of the subdocument
66 * frame belong to the subdocument frame and hence to the parent document. The
67 * root view of the subdocument belongs to the subdocument.
68 * nsLayoutUtils::GetCrossDocParentFrame and nsPresContext::GetParentPresContext
69 * depend on this view structure and are the main way that we traverse across
70 * the document boundary in layout.
72 * When the load of a new document is started in the subdocument, the creation
73 * of the new subdocument and destruction of the old subdocument are not
74 * linked. (This creation and destruction is handled in nsDocumentViewer.cpp.)
75 * This means that the old and new document will both exist at the same time
76 * during the loading of the new document. During this period the inner view of
77 * the subdocument parent will be the parent of two root views. This means that
78 * during this period there is a choice for which subdocument we draw,
79 * nsSubDocumentFrame::GetSubdocumentPresShellForPainting is what makes that
80 * choice. Note that this might not be a totally free choice, ie there might be
81 * hidden dependencies and bugs if the way we choose is changed.
83 * One thing that is special about the root view of a chrome window is that
84 * instead of creating a widget for the view, they can "attach" to the
85 * existing widget that was created by appshell code or something else. (see
86 * nsDocumentViewer::ShouldAttachToTopLevel)
89 // Enumerated type to indicate the visibility of a layer.
90 // hide - the layer is not shown.
91 // show - the layer is shown irrespective of the visibility of
92 // the layer's parent.
93 enum nsViewVisibility
{
94 nsViewVisibility_kHide
= 0,
95 nsViewVisibility_kShow
= 1
100 // Indicates that the view is using auto z-indexing
101 #define NS_VIEW_FLAG_AUTO_ZINDEX 0x0004
103 // Indicates that the view is a floating view.
104 #define NS_VIEW_FLAG_FLOATING 0x0008
106 //----------------------------------------------------------------------
111 * Views are NOT reference counted. Use the Destroy() member function to
114 * The lifetime of the view hierarchy is bounded by the lifetime of the
115 * view manager that owns the views.
117 * Most of the methods here are read-only. To set the corresponding properties
118 * of a view, go through nsViewManager.
121 class nsView final
: public nsIWidgetListener
{
123 friend class nsViewManager
;
125 typedef mozilla::LayoutDeviceIntRect LayoutDeviceIntRect
;
126 typedef mozilla::LayoutDeviceIntRegion LayoutDeviceIntRegion
;
128 void operator delete(void* ptr
) { ::operator delete(ptr
); }
131 * Get the view manager which "owns" the view.
132 * This method might require some expensive traversal work in the future. If
133 * you can get the view manager from somewhere else, do that instead.
134 * @result the view manager
136 nsViewManager
* GetViewManager() const { return mViewManager
; }
139 * Find the view for the given widget, if there is one.
140 * @return the view the widget belongs to, or null if the widget doesn't
141 * belong to any view.
143 static nsView
* GetViewFor(nsIWidget
* aWidget
);
148 * The view destroys its child views, and destroys and releases its
149 * widget (if it has one).
151 * Also informs the view manager that the view is destroyed by calling
152 * SetRootView(NULL) if the view is the root view and calling RemoveChild()
158 * Called to get the position of a view.
159 * The specified coordinates are relative to the parent view's origin, but
160 * are in appunits of this.
161 * This is the (0, 0) origin of the coordinate space established by this view.
162 * @param x out parameter for x position
163 * @param y out parameter for y position
165 nsPoint
GetPosition() const {
166 NS_ASSERTION(!IsRoot() || (mPosX
== 0 && mPosY
== 0),
167 "root views should always have explicit position of (0,0)");
168 return nsPoint(mPosX
, mPosY
);
172 * Called to get the dimensions and position of the view's bounds.
173 * The view's bounds (x,y) are relative to the origin of the parent view, but
174 * are in appunits of this.
175 * The view's bounds (x,y) might not be the same as the view's position,
176 * if the view has content above or to the left of its origin.
177 * @param aBounds out parameter for bounds
179 nsRect
GetBounds() const { return mDimBounds
; }
182 * The bounds of this view relative to this view. So this is the same as
183 * GetBounds except this is relative to this view instead of the parent view.
185 nsRect
GetDimensions() const {
186 nsRect r
= mDimBounds
;
187 r
.MoveBy(-mPosX
, -mPosY
);
192 * Get the offset between the coordinate systems of |this| and aOther.
193 * Adding the return value to a point in the coordinate system of |this|
194 * will transform the point to the coordinate system of aOther.
196 * The offset is expressed in appunits of |this|. So if you are getting the
197 * offset between views in different documents that might have different
198 * appunits per devpixel ratios you need to be careful how you use the
201 * If aOther is null, this will return the offset of |this| from the
202 * root of the viewmanager tree.
204 * This function is fastest when aOther is an ancestor of |this|.
206 * NOTE: this actually returns the offset from aOther to |this|, but
207 * that offset is added to transform _coordinates_ from |this| to aOther.
209 nsPoint
GetOffsetTo(const nsView
* aOther
) const;
212 * Get the offset between the origin of |this| and the origin of aWidget.
213 * Adding the return value to a point in the coordinate system of |this|
214 * will transform the point to the coordinate system of aWidget.
216 * The offset is expressed in appunits of |this|.
218 nsPoint
GetOffsetToWidget(nsIWidget
* aWidget
) const;
221 * Takes a point aPt that is in the coordinate system of |this|'s parent view
222 * and converts it to be in the coordinate system of |this| taking into
223 * account the offset and any app unit per dev pixel ratio differences.
225 nsPoint
ConvertFromParentCoords(nsPoint aPt
) const;
228 * Called to query the visibility state of a view.
229 * @result current visibility state
231 nsViewVisibility
GetVisibility() const { return mVis
; }
234 * Get whether the view "floats" above all other views,
235 * which tells the compositor not to consider higher views in
236 * the view hierarchy that would geometrically intersect with
237 * this view. This is a hack, but it fixes some problems with
238 * views that need to be drawn in front of all other views.
239 * @result true if the view floats, false otherwise.
241 bool GetFloating() const { return (mVFlags
& NS_VIEW_FLAG_FLOATING
) != 0; }
244 * Called to query the parent of the view.
245 * @result view's parent
247 nsView
* GetParent() const { return mParent
; }
250 * The view's first child is the child which is earliest in document order.
251 * @result first child
253 nsView
* GetFirstChild() const { return mFirstChild
; }
256 * Called to query the next sibling of the view.
257 * @result view's next sibling
259 nsView
* GetNextSibling() const { return mNextSibling
; }
262 * Set the view's frame.
264 void SetFrame(nsIFrame
* aRootFrame
) { mFrame
= aRootFrame
; }
267 * Retrieve the view's frame.
269 nsIFrame
* GetFrame() const { return mFrame
; }
272 * Get the nearest widget in this view or a parent of this view and
273 * the offset from the widget's origin to this view's origin
274 * @param aOffset - if non-null the offset from this view's origin to the
275 * widget's origin (usually positive) expressed in appunits of this will be
276 * returned in aOffset.
277 * @return the widget closest to this view; can be null because some view
278 * trees don't have widgets at all (e.g., printing), but if any view in the
279 * view tree has a widget, then it's safe to assume this will not return null
281 nsIWidget
* GetNearestWidget(nsPoint
* aOffset
) const;
284 * Create a widget to associate with this view. This variant of
285 * CreateWidget*() will look around in the view hierarchy for an
286 * appropriate parent widget for the view.
288 * @param aWidgetInitData data used to initialize this view's widget before
289 * its create is called.
290 * @return error status
292 nsresult
CreateWidget(nsWidgetInitData
* aWidgetInitData
= nullptr,
293 bool aEnableDragDrop
= true,
294 bool aResetVisibility
= true);
297 * Create a widget for this view with an explicit parent widget.
298 * |aParentWidget| must be nonnull. The other params are the same
299 * as for |CreateWidget()|.
301 nsresult
CreateWidgetForParent(nsIWidget
* aParentWidget
,
302 nsWidgetInitData
* aWidgetInitData
= nullptr,
303 bool aEnableDragDrop
= true,
304 bool aResetVisibility
= true);
307 * Create a popup widget for this view. Pass |aParentWidget| to
308 * explicitly set the popup's parent. If it's not passed, the view
309 * hierarchy will be searched for an appropriate parent widget. The
310 * other params are the same as for |CreateWidget()|, except that
311 * |aWidgetInitData| must be nonnull.
313 nsresult
CreateWidgetForPopup(nsWidgetInitData
* aWidgetInitData
,
314 nsIWidget
* aParentWidget
= nullptr,
315 bool aEnableDragDrop
= true,
316 bool aResetVisibility
= true);
319 * Destroys the associated widget for this view. If this method is
320 * not called explicitly, the widget when be destroyed when its
321 * view gets destroyed.
323 void DestroyWidget();
326 * Attach/detach a top level widget from this view. When attached, the view
327 * updates the widget's device context and allows the view to begin receiving
328 * gecko events. The underlying base window associated with the widget will
329 * continues to receive events it expects.
331 * An attached widget will not be destroyed when the view is destroyed,
332 * allowing the recycling of a single top level widget over multiple views.
334 * @param aWidget The widget to attach to / detach from.
336 nsresult
AttachToTopLevelWidget(nsIWidget
* aWidget
);
337 nsresult
DetachFromTopLevelWidget();
340 * Returns a flag indicating whether the view owns it's widget
341 * or is attached to an existing top level widget.
343 bool IsAttachedToTopLevel() const { return mWidgetIsTopLevel
; }
346 * In 4.0, the "cutout" nature of a view is queryable.
347 * If we believe that all cutout view have a native widget, this
348 * could be a replacement.
349 * @param aWidget out parameter for widget that this view contains,
350 * or nullptr if there is none.
352 nsIWidget
* GetWidget() const { return mWindow
; }
355 * The widget which we have attached a listener to can also have a "previous"
356 * listener set on it. This is to keep track of the last nsView when
357 * navigating to a new one so that we can continue to paint that if the new
358 * one isn't ready yet.
360 void SetPreviousWidget(nsIWidget
* aWidget
) { mPreviousWindow
= aWidget
; }
363 * Returns true if the view has a widget associated with it.
365 bool HasWidget() const { return mWindow
!= nullptr; }
367 void SetForcedRepaint(bool aForceRepaint
) { mForcedRepaint
= aForceRepaint
; }
369 void SetNeedsWindowPropertiesSync();
372 * Make aWidget direct its events to this view.
373 * The caller must call DetachWidgetEventHandler before this view
376 void AttachWidgetEventHandler(nsIWidget
* aWidget
);
378 * Stop aWidget directing its events to this view.
380 void DetachWidgetEventHandler(nsIWidget
* aWidget
);
384 * Output debug info to FILE
385 * @param out output file handle
386 * @param aIndent indentation depth
387 * NOTE: virtual so that debugging tools not linked into gklayout can access
390 virtual void List(FILE* out
, int32_t aIndent
= 0) const;
394 * @result true iff this is the root view for its view manager
398 LayoutDeviceIntRect
CalcWidgetBounds(nsWindowType aType
);
400 // This is an app unit offset to add when converting view coordinates to
401 // widget coordinates. It is the offset in view coordinates from widget
402 // origin (unlike views, widgets can't extend above or to the left of their
403 // origin) to view origin expressed in appunits of this.
404 nsPoint
ViewToWidgetOffset() const { return mViewToWidgetOffset
; }
407 * Called to indicate that the position of the view has been changed.
408 * The specified coordinates are in the parent view's coordinate space.
409 * @param x new x position
410 * @param y new y position
412 void SetPosition(nscoord aX
, nscoord aY
);
415 * Called to indicate that the z-index of a view has been changed.
416 * The z-index is relative to all siblings of the view.
417 * @param aAuto Indicate that the z-index of a view is "auto". An "auto"
418 * z-index means that the view does not define a new stacking
419 * context, which means that the z-indicies of the view's
420 * children are relative to the view's siblings.
421 * @param zindex new z depth
423 void SetZIndex(bool aAuto
, int32_t aZIndex
);
424 bool GetZIndexIsAuto() const {
425 return (mVFlags
& NS_VIEW_FLAG_AUTO_ZINDEX
) != 0;
427 int32_t GetZIndex() const { return mZIndex
; }
429 void SetParent(nsView
* aParent
) { mParent
= aParent
; }
430 void SetNextSibling(nsView
* aSibling
) {
431 NS_ASSERTION(aSibling
!= this, "Can't be our own sibling!");
432 mNextSibling
= aSibling
;
435 nsRegion
& GetDirtyRegion() {
437 NS_ASSERTION(!mParent
|| GetFloating(),
438 "Only display roots should have dirty regions");
439 mDirtyRegion
= mozilla::MakeUnique
<nsRegion
>();
441 return *mDirtyRegion
;
445 virtual mozilla::PresShell
* GetPresShell() override
;
446 virtual nsView
* GetView() override
{ return this; }
447 virtual bool WindowMoved(nsIWidget
* aWidget
, int32_t x
, int32_t y
) override
;
448 virtual bool WindowResized(nsIWidget
* aWidget
, int32_t aWidth
,
449 int32_t aHeight
) override
;
450 #if defined(MOZ_WIDGET_ANDROID)
451 virtual void DynamicToolbarMaxHeightChanged(
452 mozilla::ScreenIntCoord aHeight
) override
;
453 virtual void DynamicToolbarOffsetChanged(
454 mozilla::ScreenIntCoord aOffset
) override
;
456 virtual bool RequestWindowClose(nsIWidget
* aWidget
) override
;
457 MOZ_CAN_RUN_SCRIPT_BOUNDARY
458 virtual void WillPaintWindow(nsIWidget
* aWidget
) override
;
459 MOZ_CAN_RUN_SCRIPT_BOUNDARY
460 virtual bool PaintWindow(nsIWidget
* aWidget
,
461 LayoutDeviceIntRegion aRegion
) override
;
462 MOZ_CAN_RUN_SCRIPT_BOUNDARY
463 virtual void DidPaintWindow() override
;
464 virtual void DidCompositeWindow(
465 mozilla::layers::TransactionId aTransactionId
,
466 const mozilla::TimeStamp
& aCompositeStart
,
467 const mozilla::TimeStamp
& aCompositeEnd
) override
;
468 virtual void RequestRepaint() override
;
469 virtual bool ShouldNotBeVisible() override
;
470 MOZ_CAN_RUN_SCRIPT_BOUNDARY
471 virtual nsEventStatus
HandleEvent(mozilla::WidgetGUIEvent
* aEvent
,
472 bool aUseAttachedEvents
) override
;
473 virtual void SafeAreaInsetsChanged(const mozilla::ScreenIntMargin
&) override
;
477 nsPoint
GetOffsetTo(const nsView
* aOther
, const int32_t aAPD
) const;
478 nsIWidget
* GetNearestWidget(nsPoint
* aOffset
, const int32_t aAPD
) const;
480 bool IsPrimaryFramePaintSuppressed();
483 explicit nsView(nsViewManager
* aViewManager
= nullptr,
484 nsViewVisibility aVisibility
= nsViewVisibility_kShow
);
486 bool ForcedRepaint() { return mForcedRepaint
; }
488 // Do the actual work of ResetWidgetBounds, unconditionally. Don't
489 // call this method if we have no widget.
490 void DoResetWidgetBounds(bool aMoveOnly
, bool aInvalidateChangedSize
);
491 void InitializeWindow(bool aEnableDragDrop
, bool aResetVisibility
);
493 bool IsEffectivelyVisible();
496 * Called to indicate that the dimensions of the view have been changed.
497 * The x and y coordinates may be < 0, indicating that the view extends above
498 * or to the left of its origin position. The term 'dimensions' indicates it
499 * is relative to this view.
501 void SetDimensions(const nsRect
& aRect
, bool aPaint
= true,
502 bool aResizeWidget
= true);
505 * Called to indicate that the visibility of a view has been
507 * @param visibility new visibility state
509 void SetVisibility(nsViewVisibility visibility
);
512 * Set/Get whether the view "floats" above all other views,
513 * which tells the compositor not to consider higher views in
514 * the view hierarchy that would geometrically intersect with
515 * this view. This is a hack, but it fixes some problems with
516 * views that need to be drawn in front of all other views.
517 * @result true if the view floats, false otherwise.
519 void SetFloating(bool aFloatingView
);
521 // Helper function to get mouse grabbing off this view (by moving it to the
522 // parent, if we can)
523 void DropMouseGrabbing();
525 // Same as GetBounds but converts to parent appunits if they are different.
526 nsRect
GetBoundsInParentUnits() const;
528 bool HasNonEmptyDirtyRegion() {
529 return mDirtyRegion
&& !mDirtyRegion
->IsEmpty();
532 void InsertChild(nsView
* aChild
, nsView
* aSibling
);
533 void RemoveChild(nsView
* aChild
);
535 void ResetWidgetBounds(bool aRecurse
, bool aForceSync
);
536 void AssertNoWindow();
538 void NotifyEffectiveVisibilityChanged(bool aEffectivelyVisible
);
540 // Update the cached RootViewManager for all view manager descendents.
541 void InvalidateHierarchy();
543 nsViewManager
* mViewManager
;
545 nsCOMPtr
<nsIWidget
> mWindow
;
546 nsCOMPtr
<nsIWidget
> mPreviousWindow
;
547 nsView
* mNextSibling
;
550 mozilla::UniquePtr
<nsRegion
> mDirtyRegion
;
552 nsViewVisibility mVis
;
553 // position relative our parent view origin but in our appunits
554 nscoord mPosX
, mPosY
;
555 // relative to parent, but in our appunits
558 nsPoint mViewToWidgetOffset
;
560 bool mWidgetIsTopLevel
;
562 bool mNeedsWindowPropertiesSync
;