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