view/nsView.h

   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/. */
   5
   6 #ifndef nsView_h__
   7 #define nsView_h__
   8
   9 #include "nsCoord.h"
  10 #include "nsRect.h"
  11 #include "nsPoint.h"
  12 #include "nsRegion.h"
  13 #include "nsCRT.h"
  14 #include "nsCOMPtr.h"
  15 #include "nsIWidgetListener.h"
  16 #include "Units.h"
  17 #include "mozilla/Attributes.h"
  18 #include "mozilla/EventForwards.h"
  19 #include "mozilla/UniquePtr.h"
  20
  21 class nsViewManager;
  22 class nsIWidget;
  23 class nsIFrame;
  24
  25 namespace mozilla {
  26 class PresShell;
  27 namespace widget {
  28 struct InitData;
  29 enum class TransparencyMode : uint8_t;
  30 enum class WindowType : uint8_t;
  31 }  // namespace widget
  32 }  // namespace mozilla
  33
  34 /**
  35  * nsView's serve two main purposes: 1) a bridge between nsIFrame's and
  36  * nsIWidget's, 2) linking the frame tree of a(n) (in-process) subdocument with
  37  * its parent document frame tree. Historically views were used for more things,
  38  * but their role has been reduced, and could be reduced to nothing in the
  39  * future (bug 337801 tracks removing views). Views are generally associated
  40  * with a frame. A view that does not have a frame is called an anonymous view.
  41  * Some frames also have associated widgets (think os level windows). If a frame
  42  * has a widget it must also have a view, but not all frames with views will
  43  * have widgets.
  44  *
  45  * Only four types of frames can have a view: root frames (ViewportFrame),
  46  * subdocument frames (nsSubDocumentFrame),
  47  * menu popup frames (nsMenuPopupFrame), and list control frames
  48  * (nsListControlFrame). Root frames and subdocument frames have views to link
  49  * the two documents together (the frame trees do not link up otherwise).
  50  * Menu popup frames, and list control frames have views because
  51  * they (sometimes) need to create widgets.
  52  * Menu popup frames handles xul popups, which is anything
  53  * where we need content to go over top the main window at an os level. List
  54  * control frames handle select popups/dropdowns in non-e10s mode.
  55  *
  56  * The term "root view" refers to the root view of a document. Just like root
  57  * frames, root views can have parent views. Only the root view of the root
  58  * document in the process will not have a parent.
  59  *
  60  * All views are created by their frames except root views. Root views are
  61  * special. Root views are created in nsDocumentViewer::MakeWindow before the
  62  * root frame is created, so the root view will not have a frame very early in
  63  * document creation.
  64  *
  65  * Subdocument frames have an anonymous (no frame associated
  66  * with it) inner view that is a child of their "outer" view.
  67  *
  68  * On a subdocument frame the inner view serves as the parent of the
  69  * root view of the subdocument. The outer and inner view of the subdocument
  70  * frame belong to the subdocument frame and hence to the parent document. The
  71  * root view of the subdocument belongs to the subdocument.
  72  * nsLayoutUtils::GetCrossDocParentFrame and nsPresContext::GetParentPresContext
  73  * depend on this view structure and are the main way that we traverse across
  74  * the document boundary in layout.
  75  *
  76  * When the load of a new document is started in the subdocument, the creation
  77  * of the new subdocument and destruction of the old subdocument are not
  78  * linked. (This creation and destruction is handled in nsDocumentViewer.cpp.)
  79  * This means that the old and new document will both exist at the same time
  80  * during the loading of the new document. During this period the inner view of
  81  * the subdocument parent will be the parent of two root views. This means that
  82  * during this period there is a choice for which subdocument we draw,
  83  * nsSubDocumentFrame::GetSubdocumentPresShellForPainting is what makes that
  84  * choice. Note that this might not be a totally free choice, ie there might be
  85  * hidden dependencies and bugs if the way we choose is changed.
  86  *
  87  * One thing that is special about the root view of a chrome window is that
  88  * instead of creating a widget for the view, they can "attach" to the
  89  * existing widget that was created by appshell code or something else. (see
  90  * nsDocumentViewer::ShouldAttachToTopLevel)
  91  */
  92
  93 // Enumerated type to indicate the visibility of a layer.
  94 // hide - the layer is not shown.
  95 // show - the layer is shown irrespective of the visibility of
  96 //        the layer's parent.
  97 enum class ViewVisibility : uint8_t { Hide = 0, Show = 1 };
  98
  99 // Public view flags
 100
 101 // Indicates that the view is a floating view.
 102 #define NS_VIEW_FLAG_FLOATING 0x0008
 103
 104 //----------------------------------------------------------------------
 105
 106 /**
 107  * View interface
 108  *
 109  * Views are NOT reference counted. Use the Destroy() member function to
 110  * destroy a view.
 111  *
 112  * The lifetime of the view hierarchy is bounded by the lifetime of the
 113  * view manager that owns the views.
 114  *
 115  * Most of the methods here are read-only. To set the corresponding properties
 116  * of a view, go through nsViewManager.
 117  */
 118
 119 class nsView final : public nsIWidgetListener {
 120  public:
 121   friend class nsViewManager;
 122
 123   typedef mozilla::LayoutDeviceIntRect LayoutDeviceIntRect;
 124   typedef mozilla::LayoutDeviceIntRegion LayoutDeviceIntRegion;
 125
 126   void operator delete(void* ptr) { ::operator delete(ptr); }
 127
 128   /**
 129    * Get the view manager which "owns" the view.
 130    * This method might require some expensive traversal work in the future. If
 131    * you can get the view manager from somewhere else, do that instead.
 132    * @result the view manager
 133    */
 134   nsViewManager* GetViewManager() const { return mViewManager; }
 135
 136   /**
 137    * Find the view for the given widget, if there is one.
 138    * @return the view the widget belongs to, or null if the widget doesn't
 139    * belong to any view.
 140    */
 141   static nsView* GetViewFor(const nsIWidget* aWidget);
 142
 143   /**
 144    * Destroy the view.
 145    *
 146    * The view destroys its child views, and destroys and releases its
 147    * widget (if it has one).
 148    *
 149    * Also informs the view manager that the view is destroyed by calling
 150    * SetRootView(NULL) if the view is the root view and calling RemoveChild()
 151    * otherwise.
 152    */
 153   void Destroy();
 154
 155   /**
 156    * Called to get the position of a view.
 157    * The specified coordinates are relative to the parent view's origin, but
 158    * are in appunits of this.
 159    * This is the (0, 0) origin of the coordinate space established by this view.
 160    * @param x out parameter for x position
 161    * @param y out parameter for y position
 162    */
 163   nsPoint GetPosition() const {
 164     NS_ASSERTION(!IsRoot() || (mPosX == 0 && mPosY == 0),
 165                  "root views should always have explicit position of (0,0)");
 166     return nsPoint(mPosX, mPosY);
 167   }
 168
 169   /**
 170    * Called to get the dimensions and position of the view's bounds.
 171    * The view's bounds (x,y) are relative to the origin of the parent view, but
 172    * are in appunits of this.
 173    * The view's bounds (x,y) might not be the same as the view's position,
 174    * if the view has content above or to the left of its origin.
 175    * @param aBounds out parameter for bounds
 176    */
 177   nsRect GetBounds() const { return mDimBounds; }
 178
 179   /**
 180    * The bounds of this view relative to this view. So this is the same as
 181    * GetBounds except this is relative to this view instead of the parent view.
 182    */
 183   nsRect GetDimensions() const {
 184     nsRect r = mDimBounds;
 185     r.MoveBy(-mPosX, -mPosY);
 186     return r;
 187   }
 188
 189   /**
 190    * Get the offset between the coordinate systems of |this| and aOther.
 191    * Adding the return value to a point in the coordinate system of |this|
 192    * will transform the point to the coordinate system of aOther.
 193    *
 194    * The offset is expressed in appunits of |this|. So if you are getting the
 195    * offset between views in different documents that might have different
 196    * appunits per devpixel ratios you need to be careful how you use the
 197    * result.
 198    *
 199    * If aOther is null, this will return the offset of |this| from the
 200    * root of the viewmanager tree.
 201    *
 202    * This function is fastest when aOther is an ancestor of |this|.
 203    *
 204    * NOTE: this actually returns the offset from aOther to |this|, but
 205    * that offset is added to transform _coordinates_ from |this| to aOther.
 206    */
 207   nsPoint GetOffsetTo(const nsView* aOther) const;
 208
 209   /**
 210    * Get the offset between the origin of |this| and the origin of aWidget.
 211    * Adding the return value to a point in the coordinate system of |this|
 212    * will transform the point to the coordinate system of aWidget.
 213    *
 214    * The offset is expressed in appunits of |this|.
 215    */
 216   nsPoint GetOffsetToWidget(nsIWidget* aWidget) const;
 217
 218   /**
 219    * Called to query the visibility state of a view.
 220    * @result current visibility state
 221    */
 222   ViewVisibility GetVisibility() const { return mVis; }
 223
 224   /**
 225    * Get whether the view "floats" above all other views,
 226    * which tells the compositor not to consider higher views in
 227    * the view hierarchy that would geometrically intersect with
 228    * this view. This is a hack, but it fixes some problems with
 229    * views that need to be drawn in front of all other views.
 230    * @result true if the view floats, false otherwise.
 231    */
 232   bool GetFloating() const { return (mVFlags & NS_VIEW_FLAG_FLOATING) != 0; }
 233
 234   /**
 235    * Called to query the parent of the view.
 236    * @result view's parent
 237    */
 238   nsView* GetParent() const { return mParent; }
 239
 240   /**
 241    * The view's first child is the child which is earliest in document order.
 242    * @result first child
 243    */
 244   nsView* GetFirstChild() const { return mFirstChild; }
 245
 246   /**
 247    * Called to query the next sibling of the view.
 248    * @result view's next sibling
 249    */
 250   nsView* GetNextSibling() const { return mNextSibling; }
 251
 252   /**
 253    * Set the view's frame.
 254    */
 255   void SetFrame(nsIFrame* aRootFrame) { mFrame = aRootFrame; }
 256
 257   /**
 258    * Retrieve the view's frame.
 259    */
 260   nsIFrame* GetFrame() const { return mFrame; }
 261
 262   /**
 263    * Get the nearest widget in this view or a parent of this view and
 264    * the offset from the widget's origin to this view's origin
 265    * @param aOffset - if non-null the offset from this view's origin to the
 266    * widget's origin (usually positive) expressed in appunits of this will be
 267    * returned in aOffset.
 268    * @return the widget closest to this view; can be null because some view
 269    * trees don't have widgets at all (e.g., printing), but if any view in the
 270    * view tree has a widget, then it's safe to assume this will not return null
 271    */
 272   nsIWidget* GetNearestWidget(nsPoint* aOffset) const;
 273
 274   /**
 275    * Create a widget to associate with this view.  This variant of
 276    * CreateWidget*() will look around in the view hierarchy for an
 277    * appropriate parent widget for the view.
 278    *
 279    * @param aWidgetInitData data used to initialize this view's widget before
 280    *        its create is called.
 281    * @return error status
 282    */
 283   nsresult CreateWidget(mozilla::widget::InitData* aWidgetInitData = nullptr,
 284                         bool aEnableDragDrop = true,
 285                         bool aResetVisibility = true);
 286
 287   /**
 288    * Create a widget for this view with an explicit parent widget.
 289    * |aParentWidget| must be nonnull.  The other params are the same
 290    * as for |CreateWidget()|.
 291    */
 292   nsresult CreateWidgetForParent(nsIWidget* aParentWidget,
 293                                  mozilla::widget::InitData* = nullptr,
 294                                  bool aEnableDragDrop = true,
 295                                  bool aResetVisibility = true);
 296
 297   /**
 298    * Create a popup widget for this view.  Pass |aParentWidget| to
 299    * explicitly set the popup's parent.  If it's not passed, the view
 300    * hierarchy will be searched for an appropriate parent widget.  The
 301    * other params are the same as for |CreateWidget()|, except that
 302    * |aWidgetInitData| must be nonnull.
 303    */
 304   nsresult CreateWidgetForPopup(mozilla::widget::InitData*,
 305                                 nsIWidget* aParentWidget = nullptr);
 306
 307   /**
 308    * Destroys the associated widget for this view.  If this method is
 309    * not called explicitly, the widget when be destroyed when its
 310    * view gets destroyed.
 311    */
 312   void DestroyWidget();
 313
 314   /**
 315    * Attach/detach a top level widget from this view. When attached, the view
 316    * updates the widget's device context and allows the view to begin receiving
 317    * gecko events. The underlying base window associated with the widget will
 318    * continues to receive events it expects.
 319    *
 320    * An attached widget will not be destroyed when the view is destroyed,
 321    * allowing the recycling of a single top level widget over multiple views.
 322    *
 323    * @param aWidget The widget to attach to / detach from.
 324    */
 325   nsresult AttachToTopLevelWidget(nsIWidget* aWidget);
 326   nsresult DetachFromTopLevelWidget();
 327
 328   /**
 329    * Returns a flag indicating whether the view owns it's widget
 330    * or is attached to an existing top level widget.
 331    */
 332   bool IsAttachedToTopLevel() const { return mWidgetIsTopLevel; }
 333
 334   /**
 335    * In 4.0, the "cutout" nature of a view is queryable.
 336    * If we believe that all cutout view have a native widget, this
 337    * could be a replacement.
 338    * @param aWidget out parameter for widget that this view contains,
 339    *        or nullptr if there is none.
 340    */
 341   nsIWidget* GetWidget() const { return mWindow; }
 342
 343   /**
 344    * The widget which we have attached a listener to can also have a "previous"
 345    * listener set on it. This is to keep track of the last nsView when
 346    * navigating to a new one so that we can continue to paint that if the new
 347    * one isn't ready yet.
 348    */
 349   void SetPreviousWidget(nsIWidget* aWidget) { mPreviousWindow = aWidget; }
 350
 351   /**
 352    * Returns true if the view has a widget associated with it.
 353    */
 354   bool HasWidget() const { return mWindow != nullptr; }
 355
 356   void SetForcedRepaint(bool aForceRepaint) { mForcedRepaint = aForceRepaint; }
 357
 358   void SetNeedsWindowPropertiesSync();
 359
 360   /**
 361    * Make aWidget direct its events to this view.
 362    * The caller must call DetachWidgetEventHandler before this view
 363    * is destroyed.
 364    */
 365   void AttachWidgetEventHandler(nsIWidget* aWidget);
 366   /**
 367    * Stop aWidget directing its events to this view.
 368    */
 369   void DetachWidgetEventHandler(nsIWidget* aWidget);
 370
 371 #ifdef DEBUG
 372   /**
 373    * Output debug info to FILE
 374    * @param out output file handle
 375    * @param aIndent indentation depth
 376    * NOTE: virtual so that debugging tools not linked into gklayout can access
 377    * it
 378    */
 379   virtual void List(FILE* out, int32_t aIndent = 0) const;
 380 #endif  // DEBUG
 381
 382   /**
 383    * @result true iff this is the root view for its view manager
 384    */
 385   bool IsRoot() const;
 386
 387   LayoutDeviceIntRect CalcWidgetBounds(mozilla::widget::WindowType,
 388                                        mozilla::widget::TransparencyMode);
 389
 390   LayoutDeviceIntRect RecalcWidgetBounds();
 391
 392   // This is an app unit offset to add when converting view coordinates to
 393   // widget coordinates.  It is the offset in view coordinates from widget
 394   // origin (unlike views, widgets can't extend above or to the left of their
 395   // origin) to view origin expressed in appunits of this.
 396   nsPoint ViewToWidgetOffset() const { return mViewToWidgetOffset; }
 397
 398   /**
 399    * Called to indicate that the position of the view has been changed.
 400    * The specified coordinates are in the parent view's coordinate space.
 401    * @param x new x position
 402    * @param y new y position
 403    */
 404   void SetPosition(nscoord aX, nscoord aY);
 405   void SetParent(nsView* aParent) { mParent = aParent; }
 406   void SetNextSibling(nsView* aSibling) {
 407     NS_ASSERTION(aSibling != this, "Can't be our own sibling!");
 408     mNextSibling = aSibling;
 409   }
 410
 411   nsRegion& GetDirtyRegion() {
 412     if (!mDirtyRegion) {
 413       NS_ASSERTION(!mParent || GetFloating(),
 414                    "Only display roots should have dirty regions");
 415       mDirtyRegion = mozilla::MakeUnique<nsRegion>();
 416     }
 417     return *mDirtyRegion;
 418   }
 419
 420   // nsIWidgetListener
 421   virtual mozilla::PresShell* GetPresShell() override;
 422   virtual nsView* GetView() override { return this; }
 423   virtual bool WindowMoved(nsIWidget* aWidget, int32_t x, int32_t y,
 424                            ByMoveToRect) override;
 425   virtual bool WindowResized(nsIWidget* aWidget, int32_t aWidth,
 426                              int32_t aHeight) override;
 427 #if defined(MOZ_WIDGET_ANDROID)
 428   virtual void DynamicToolbarMaxHeightChanged(
 429       mozilla::ScreenIntCoord aHeight) override;
 430   virtual void DynamicToolbarOffsetChanged(
 431       mozilla::ScreenIntCoord aOffset) override;
 432 #endif
 433   virtual bool RequestWindowClose(nsIWidget* aWidget) override;
 434   MOZ_CAN_RUN_SCRIPT_BOUNDARY
 435   virtual void WillPaintWindow(nsIWidget* aWidget) override;
 436   MOZ_CAN_RUN_SCRIPT_BOUNDARY
 437   virtual bool PaintWindow(nsIWidget* aWidget,
 438                            LayoutDeviceIntRegion aRegion) override;
 439   MOZ_CAN_RUN_SCRIPT_BOUNDARY
 440   virtual void DidPaintWindow() override;
 441   virtual void DidCompositeWindow(
 442       mozilla::layers::TransactionId aTransactionId,
 443       const mozilla::TimeStamp& aCompositeStart,
 444       const mozilla::TimeStamp& aCompositeEnd) override;
 445   virtual void RequestRepaint() override;
 446   virtual bool ShouldNotBeVisible() override;
 447   MOZ_CAN_RUN_SCRIPT_BOUNDARY
 448   virtual nsEventStatus HandleEvent(mozilla::WidgetGUIEvent* aEvent,
 449                                     bool aUseAttachedEvents) override;
 450   virtual void SafeAreaInsetsChanged(const mozilla::ScreenIntMargin&) override;
 451
 452   virtual ~nsView();
 453
 454   nsPoint GetOffsetTo(const nsView* aOther, const int32_t aAPD) const;
 455   nsIWidget* GetNearestWidget(nsPoint* aOffset, const int32_t aAPD) const;
 456
 457   bool IsPrimaryFramePaintSuppressed();
 458
 459  private:
 460   explicit nsView(nsViewManager* = nullptr,
 461                   ViewVisibility = ViewVisibility::Show);
 462
 463   bool ForcedRepaint() { return mForcedRepaint; }
 464
 465   // Do the actual work of ResetWidgetBounds, unconditionally.  Don't
 466   // call this method if we have no widget.
 467   void DoResetWidgetBounds(bool aMoveOnly, bool aInvalidateChangedSize);
 468   void InitializeWindow(bool aEnableDragDrop, bool aResetVisibility);
 469
 470   bool IsEffectivelyVisible();
 471
 472   /**
 473    * Called to indicate that the dimensions of the view have been changed.
 474    * The x and y coordinates may be < 0, indicating that the view extends above
 475    * or to the left of its origin position. The term 'dimensions' indicates it
 476    * is relative to this view.
 477    */
 478   void SetDimensions(const nsRect& aRect, bool aPaint = true,
 479                      bool aResizeWidget = true);
 480
 481   /**
 482    * Called to indicate that the visibility of a view has been
 483    * changed.
 484    * @param visibility new visibility state
 485    */
 486   void SetVisibility(ViewVisibility visibility);
 487
 488   /**
 489    * Set/Get whether the view "floats" above all other views,
 490    * which tells the compositor not to consider higher views in
 491    * the view hierarchy that would geometrically intersect with
 492    * this view. This is a hack, but it fixes some problems with
 493    * views that need to be drawn in front of all other views.
 494    * @result true if the view floats, false otherwise.
 495    */
 496   void SetFloating(bool aFloatingView);
 497
 498   // Helper function to get mouse grabbing off this view (by moving it to the
 499   // parent, if we can)
 500   void DropMouseGrabbing();
 501
 502   bool HasNonEmptyDirtyRegion() {
 503     return mDirtyRegion && !mDirtyRegion->IsEmpty();
 504   }
 505
 506   void InsertChild(nsView* aChild, nsView* aSibling);
 507   void RemoveChild(nsView* aChild);
 508
 509   void ResetWidgetBounds(bool aRecurse, bool aForceSync);
 510   void AssertNoWindow();
 511
 512   void NotifyEffectiveVisibilityChanged(bool aEffectivelyVisible);
 513
 514   // Update the cached RootViewManager for all view manager descendents.
 515   void InvalidateHierarchy();
 516
 517   nsViewManager* mViewManager;
 518   nsView* mParent;
 519   nsCOMPtr<nsIWidget> mWindow;
 520   nsCOMPtr<nsIWidget> mPreviousWindow;
 521   nsView* mNextSibling;
 522   nsView* mFirstChild;
 523   nsIFrame* mFrame;
 524   mozilla::UniquePtr<nsRegion> mDirtyRegion;
 525   ViewVisibility mVis;
 526   // position relative our parent view origin but in our appunits
 527   nscoord mPosX, mPosY;
 528   // relative to parent, but in our appunits
 529   nsRect mDimBounds;
 530   // in our appunits
 531   nsPoint mViewToWidgetOffset;
 532   uint32_t mVFlags;
 533   bool mWidgetIsTopLevel;
 534   bool mForcedRepaint;
 535   bool mNeedsWindowPropertiesSync;
 536 };
 537
 538 #endif