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