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 "nsWidgetInitData.h" // for nsWindowType
  15 #include "nsIWidgetListener.h"
  16 #include "mozilla/EventForwards.h"
  17
  18 class nsViewManager;
  19 class nsIWidget;
  20 class nsIFrame;
  21
  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
  29 };
  30
  31 // Public view flags
  32
  33 // Indicates that the view is using auto z-indexing
  34 #define NS_VIEW_FLAG_AUTO_ZINDEX          0x0004
  35
  36 // Indicates that the view is a floating view.
  37 #define NS_VIEW_FLAG_FLOATING             0x0008
  38
  39 //----------------------------------------------------------------------
  40
  41 /**
  42  * View interface
  43  *
  44  * Views are NOT reference counted. Use the Destroy() member function to
  45  * destroy a view.
  46  *
  47  * The lifetime of the view hierarchy is bounded by the lifetime of the
  48  * view manager that owns the views.
  49  *
  50  * Most of the methods here are read-only. To set the corresponding properties
  51  * of a view, go through nsViewManager.
  52  */
  53
  54 class nsView MOZ_FINAL : public nsIWidgetListener
  55 {
  56 public:
  57   friend class nsViewManager;
  58
  59   NS_DECL_AND_IMPL_ZEROING_OPERATOR_NEW
  60
  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
  66    */
  67   nsViewManager* GetViewManager() const { return mViewManager; }
  68
  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.
  73    */
  74   static nsView* GetViewFor(nsIWidget* aWidget);
  75
  76   /**
  77    * Destroy the view.
  78    *
  79    * The view destroys its child views, and destroys and releases its
  80    * widget (if it has one).
  81    *
  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.
  85    */
  86   void Destroy();
  87
  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
  95    */
  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);
 100   }
 101
 102   /**
 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
 109    */
 110   nsRect GetBounds() const { return mDimBounds; }
 111
 112   /**
 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.
 115    */
 116   nsRect GetDimensions() const {
 117     nsRect r = mDimBounds; r.MoveBy(-mPosX, -mPosY); return r;
 118   }
 119
 120   /**
 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.
 124    *
 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.
 129    *
 130    * If aOther is null, this will return the offset of |this| from the
 131    * root of the viewmanager tree.
 132    *
 133    * This function is fastest when aOther is an ancestor of |this|.
 134    *
 135    * NOTE: this actually returns the offset from aOther to |this|, but
 136    * that offset is added to transform _coordinates_ from |this| to aOther.
 137    */
 138   nsPoint GetOffsetTo(const nsView* aOther) const;
 139
 140   /**
 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.
 144    *
 145    * The offset is expressed in appunits of |this|.
 146    */
 147   nsPoint GetOffsetToWidget(nsIWidget* aWidget) const;
 148
 149   /**
 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.
 153    */
 154   nsPoint ConvertFromParentCoords(nsPoint aPt) const;
 155
 156   /**
 157    * Called to query the visibility state of a view.
 158    * @result current visibility state
 159    */
 160   nsViewVisibility GetVisibility() const { return mVis; }
 161
 162   /**
 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.
 169    */
 170   bool GetFloating() const { return (mVFlags & NS_VIEW_FLAG_FLOATING) != 0; }
 171
 172   /**
 173    * Called to query the parent of the view.
 174    * @result view's parent
 175    */
 176   nsView* GetParent() const { return mParent; }
 177
 178   /**
 179    * The view's first child is the child which is earliest in document order.
 180    * @result first child
 181    */
 182   nsView* GetFirstChild() const { return mFirstChild; }
 183
 184   /**
 185    * Called to query the next sibling of the view.
 186    * @result view's next sibling
 187    */
 188   nsView* GetNextSibling() const { return mNextSibling; }
 189
 190   /**
 191    * Set the view's frame.
 192    */
 193   void SetFrame(nsIFrame* aRootFrame) { mFrame = aRootFrame; }
 194
 195   /**
 196    * Retrieve the view's frame.
 197    */
 198   nsIFrame* GetFrame() const { return mFrame; }
 199
 200   /**
 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
 209    */
 210   nsIWidget* GetNearestWidget(nsPoint* aOffset) const;
 211
 212   /**
 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.
 216    *
 217    * @param aWidgetInitData data used to initialize this view's widget before
 218    *        its create is called.
 219    * @return error status
 220    */
 221   nsresult CreateWidget(nsWidgetInitData *aWidgetInitData = nullptr,
 222                         bool aEnableDragDrop = true,
 223                         bool aResetVisibility = true);
 224
 225   /**
 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()|.
 229    */
 230   nsresult CreateWidgetForParent(nsIWidget* aParentWidget,
 231                                  nsWidgetInitData *aWidgetInitData = nullptr,
 232                                  bool aEnableDragDrop = true,
 233                                  bool aResetVisibility = true);
 234
 235   /**
 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.
 241    */
 242   nsresult CreateWidgetForPopup(nsWidgetInitData *aWidgetInitData,
 243                                 nsIWidget* aParentWidget = nullptr,
 244                                 bool aEnableDragDrop = true,
 245                                 bool aResetVisibility = true);
 246
 247   /**
 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.
 251    */
 252   void DestroyWidget();
 253
 254   /**
 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.
 259    *
 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.
 262    *
 263    * @param aWidget The widget to attach to / detach from.
 264    */
 265   nsresult AttachToTopLevelWidget(nsIWidget* aWidget);
 266   nsresult DetachFromTopLevelWidget();
 267
 268   /**
 269    * Returns a flag indicating whether the view owns it's widget
 270    * or is attached to an existing top level widget.
 271    */
 272   bool IsAttachedToTopLevel() const { return mWidgetIsTopLevel; }
 273
 274   /**
 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.
 280    */
 281   nsIWidget* GetWidget() const { return mWindow; }
 282
 283   /**
 284    * Returns true if the view has a widget associated with it.
 285    */
 286   bool HasWidget() const { return mWindow != nullptr; }
 287
 288   void SetForcedRepaint(bool aForceRepaint) {
 289     mForcedRepaint = aForceRepaint;
 290   }
 291
 292   /**
 293    * Make aWidget direct its events to this view.
 294    * The caller must call DetachWidgetEventHandler before this view
 295    * is destroyed.
 296    */
 297   void AttachWidgetEventHandler(nsIWidget* aWidget);
 298   /**
 299    * Stop aWidget directing its events to this view.
 300    */
 301   void DetachWidgetEventHandler(nsIWidget* aWidget);
 302
 303 #ifdef DEBUG
 304   /**
 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
 309    */
 310   virtual void List(FILE* out, int32_t aIndent = 0) const;
 311 #endif // DEBUG
 312
 313   /**
 314    * @result true iff this is the root view for its view manager
 315    */
 316   bool IsRoot() const;
 317
 318   nsIntRect CalcWidgetBounds(nsWindowType aType);
 319
 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; }
 325
 326   /**
 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
 331    */
 332   void SetPosition(nscoord aX, nscoord aY);
 333
 334   /**
 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
 342    */
 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; }
 346
 347   void SetParent(nsView *aParent) { mParent = aParent; }
 348   void SetNextSibling(nsView *aSibling)
 349   {
 350     NS_ASSERTION(aSibling != this, "Can't be our own sibling!");
 351     mNextSibling = aSibling;
 352   }
 353
 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!");
 360     }
 361     return mDirtyRegion;
 362   }
 363
 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;
 377
 378   virtual ~nsView();
 379
 380   nsPoint GetOffsetTo(const nsView* aOther, const int32_t aAPD) const;
 381   nsIWidget* GetNearestWidget(nsPoint* aOffset, const int32_t aAPD) const;
 382
 383 private:
 384   explicit nsView(nsViewManager* aViewManager = nullptr,
 385                   nsViewVisibility aVisibility = nsViewVisibility_kShow);
 386
 387   bool ForcedRepaint() { return mForcedRepaint; }
 388
 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);
 393
 394   bool IsEffectivelyVisible();
 395
 396   /**
 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.
 401    */
 402   void SetDimensions(const nsRect &aRect, bool aPaint = true,
 403                      bool aResizeWidget = true);
 404
 405   /**
 406    * Called to indicate that the visibility of a view has been
 407    * changed.
 408    * @param visibility new visibility state
 409    */
 410   void SetVisibility(nsViewVisibility visibility);
 411
 412   /**
 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.
 419    */
 420   void SetFloating(bool aFloatingView);
 421
 422   // Helper function to get mouse grabbing off this view (by moving it to the
 423   // parent, if we can)
 424   void DropMouseGrabbing();
 425
 426   // Same as GetBounds but converts to parent appunits if they are different.
 427   nsRect GetBoundsInParentUnits() const;
 428
 429   bool HasNonEmptyDirtyRegion() {
 430     return mDirtyRegion && !mDirtyRegion->IsEmpty();
 431   }
 432
 433   void InsertChild(nsView *aChild, nsView *aSibling);
 434   void RemoveChild(nsView *aChild);
 435
 436   void ResetWidgetBounds(bool aRecurse, bool aForceSync);
 437   void AssertNoWindow();
 438
 439   void NotifyEffectiveVisibilityChanged(bool aEffectivelyVisible);
 440
 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);
 446
 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;
 465 };
 466
 467 #endif