view/nsViewManager.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 nsViewManager_h___
   7 #define nsViewManager_h___
   8
   9 #include "nscore.h"
  10 #include "nsView.h"
  11 #include "nsCOMPtr.h"
  12 #include "nsCRT.h"
  13 #include "nsTArray.h"
  14 #include "nsDeviceContext.h"
  15 #include "nsTArray.h"
  16 #include "mozilla/Attributes.h"
  17 #include "mozilla/EventForwards.h"
  18
  19 class nsIWidget;
  20 struct nsRect;
  21 class nsRegion;
  22 class nsDeviceContext;
  23
  24 namespace mozilla {
  25 class PresShell;
  26 }  // namespace mozilla
  27
  28 class nsViewManager final {
  29   ~nsViewManager();
  30
  31  public:
  32   friend class nsView;
  33
  34   typedef mozilla::LayoutDeviceIntRect LayoutDeviceIntRect;
  35   typedef mozilla::LayoutDeviceIntRegion LayoutDeviceIntRegion;
  36
  37   NS_INLINE_DECL_REFCOUNTING(nsViewManager)
  38
  39   nsViewManager();
  40
  41   /**
  42    * Initialize the ViewManager
  43    * Note: this instance does not hold a reference to the presshell
  44    * because it holds a reference to this instance.
  45    * @result The result of the initialization, NS_OK if no errors
  46    */
  47   nsresult Init(nsDeviceContext* aContext);
  48
  49   /**
  50    * Create an ordinary view
  51    * @param aBounds initial bounds for view
  52    *        XXX We should eliminate this parameter; you can set the bounds
  53    *        after CreateView
  54    * @param aParent intended parent for view. this is not actually set in the
  55    *        nsView through this method. it is only used by the initialization
  56    *        code to walk up the view tree, if necessary, to find resources.
  57    *        XXX We should eliminate this parameter!
  58    * @param aVisibilityFlag initial visibility state of view
  59    *        XXX We should eliminate this parameter; you can set it after
  60    *        CreateView
  61    * @result The new view.  Never null.
  62    */
  63   nsView* CreateView(const nsRect& aBounds, nsView* aParent,
  64                      nsViewVisibility aVisibilityFlag = nsViewVisibility_kShow);
  65
  66   /**
  67    * Get the root of the view tree.
  68    * @result the root view
  69    */
  70   nsView* GetRootView() { return mRootView; }
  71
  72   /**
  73    * Set the root of the view tree. Does not destroy the current root view.
  74    * aView may have a parent view managed by a different view manager.
  75    * aView may have a widget (anything but printing) or may not (printing).
  76    * @param aView view to set as root
  77    */
  78   void SetRootView(nsView* aView);
  79
  80   /**
  81    * Get the dimensions of the root window. The dimensions are in
  82    * twips
  83    * @param aWidth out parameter for width of window in twips
  84    * @param aHeight out parameter for height of window in twips
  85    */
  86   void GetWindowDimensions(nscoord* aWidth, nscoord* aHeight);
  87
  88   /**
  89    * Set the dimensions of the root window.
  90    * Called if the root window is resized. The dimensions are in
  91    * twips
  92    * @param aWidth of window in twips
  93    * @param aHeight of window in twips
  94    */
  95   void SetWindowDimensions(nscoord aWidth, nscoord aHeight,
  96                            bool aDelayResize = false);
  97
  98   /**
  99    * Do any resizes that are pending.
 100    */
 101   void FlushDelayedResize(bool aDoReflow);
 102
 103   /**
 104    * Called to inform the view manager that the entire area of a view
 105    * is dirty and needs to be redrawn.
 106    * @param aView view to paint. should be root view
 107    */
 108   void InvalidateView(nsView* aView);
 109
 110   /**
 111    * Called to inform the view manager that some portion of a view is dirty and
 112    * needs to be redrawn. The rect passed in should be in the view's coordinate
 113    * space. Does not check for paint suppression.
 114    * @param aView view to paint. should be root view
 115    * @param rect rect to mark as damaged
 116    */
 117   void InvalidateViewNoSuppression(nsView* aView, const nsRect& aRect);
 118
 119   /**
 120    * Called to inform the view manager that it should invalidate all views.
 121    */
 122   void InvalidateAllViews();
 123
 124   /**
 125    * Called to dispatch an event to the appropriate view. Often called
 126    * as a result of receiving a mouse or keyboard event from the widget
 127    * event system.
 128    * @param aEvent event to dispatch
 129    * @param aViewTarget dispatch the event to this view
 130    * @param aStatus event handling status
 131    */
 132   MOZ_CAN_RUN_SCRIPT
 133   void DispatchEvent(mozilla::WidgetGUIEvent* aEvent, nsView* aViewTarget,
 134                      nsEventStatus* aStatus);
 135
 136   /**
 137    * Given a parent view, insert another view as its child.
 138    * aSibling and aAbove control the "document order" for the insertion.
 139    * If aSibling is null, the view is inserted at the end of the document order
 140    * if aAfter is true, otherwise it is inserted at the beginning.
 141    * If aSibling is non-null, then if aAfter is true, the view is inserted
 142    * after the sibling in document order (appearing above the sibling unless
 143    * overriden by z-order).
 144    * If it is false, the view is inserted before the sibling.
 145    * The view manager generates the appopriate dirty regions.
 146    * @param aParent parent view
 147    * @param aChild child view
 148    * @param aSibling sibling view
 149    * @param aAfter after or before in the document order
 150    */
 151   void InsertChild(nsView* aParent, nsView* aChild, nsView* aSibling,
 152                    bool aAfter);
 153
 154   /**
 155    * Remove a specific child view from its parent. This will NOT remove its
 156    * placeholder if there is one. The view manager generates the appropriate
 157    * dirty regions.
 158    * @param aParent parent view
 159    * @param aChild child view
 160    */
 161   void RemoveChild(nsView* aChild);
 162
 163   /**
 164    * Move a view to the specified position, provided in parent coordinates.
 165    * The new position is the (0, 0) origin for the view's coordinate system.
 166    * The view's bounds may extend above or to the left of this point.
 167    * The view manager generates the appropriate dirty regions.
 168    * @param aView view to move
 169    * @param aX x value for new view position
 170    * @param aY y value for new view position
 171    */
 172   void MoveViewTo(nsView* aView, nscoord aX, nscoord aY);
 173
 174   /**
 175    * Resize a view. In addition to setting the width and height, you can
 176    * set the x and y of its bounds relative to its position. Negative x and y
 177    * will let the view extend above and to the left of the (0,0) point in its
 178    * coordinate system.
 179    * The view manager generates the appropriate dirty regions.
 180    * @param aView view to move
 181    * @param the new bounds relative to the current position
 182    * @param RepaintExposedAreaOnly
 183    *     if true Repaint only the expanded or contracted region,
 184    *     if false Repaint the union of the old and new rectangles.
 185    */
 186   void ResizeView(nsView* aView, const nsRect& aRect,
 187                   bool aRepaintExposedAreaOnly = false);
 188
 189   /**
 190    * Set the visibility of a view. Hidden views have the effect of hiding
 191    * their descendants as well. This does not affect painting, so layout
 192    * is responsible for ensuring that content in hidden views is not
 193    * painted nor handling events. It does affect the visibility of widgets;
 194    * if a view is hidden, descendant views with widgets have their widgets
 195    * hidden.
 196    * The view manager generates the appropriate dirty regions.
 197    * @param aView view to change visibility state of
 198    * @param visible new visibility state
 199    */
 200   void SetViewVisibility(nsView* aView, nsViewVisibility aVisible);
 201
 202   /**
 203    * Set the z-index of a view. Positive z-indices mean that a view
 204    * is above its parent in z-order. Negative z-indices mean that a
 205    * view is below its parent.
 206    * The view manager generates the appropriate dirty regions.
 207    * @param aAutoZIndex indicate that the z-index of a view is "auto". An
 208    *     "auto" z-index means that the view does not define a new stacking
 209    *     context, which means that the z-indicies of the view's children are
 210    *     relative to the view's siblings.
 211    * @param aView view to change z depth of
 212    * @param aZindex explicit z depth
 213    */
 214   void SetViewZIndex(nsView* aView, bool aAutoZIndex, int32_t aZindex);
 215
 216   /**
 217    * Set whether the view "floats" above all other views,
 218    * which tells the compositor not to consider higher views in
 219    * the view hierarchy that would geometrically intersect with
 220    * this view. This is a hack, but it fixes some problems with
 221    * views that need to be drawn in front of all other views.
 222    */
 223   void SetViewFloating(nsView* aView, bool aFloatingView);
 224
 225   /**
 226    * Set the presshell associated with this manager
 227    * @param aPresShell - new presshell
 228    */
 229   void SetPresShell(mozilla::PresShell* aPresShell) { mPresShell = aPresShell; }
 230
 231   /**
 232    * Get the pres shell associated with this manager
 233    */
 234   mozilla::PresShell* GetPresShell() const { return mPresShell; }
 235
 236   /**
 237    * Get the device context associated with this manager
 238    */
 239   nsDeviceContext* GetDeviceContext() const { return mContext; }
 240
 241   /**
 242    * A stack class for disallowing changes that would enter painting. For
 243    * example, popup widgets shouldn't be resized during reflow, since doing so
 244    * might cause synchronous painting inside reflow which is forbidden.
 245    * While refresh is disabled, widget geometry changes are deferred and will
 246    * be handled later, either from the refresh driver or from an NS_WILL_PAINT
 247    * event.
 248    * We don't want to defer widget geometry changes all the time. Resizing a
 249    * popup from script doesn't need to be deferred, for example, especially
 250    * since popup widget geometry is observable from script and expected to
 251    * update synchronously.
 252    */
 253   class MOZ_STACK_CLASS AutoDisableRefresh {
 254    public:
 255     explicit AutoDisableRefresh(nsViewManager* aVM) {
 256       if (aVM) {
 257         mRootVM = aVM->IncrementDisableRefreshCount();
 258       }
 259     }
 260     ~AutoDisableRefresh() {
 261       if (mRootVM) {
 262         mRootVM->DecrementDisableRefreshCount();
 263       }
 264     }
 265
 266    private:
 267     AutoDisableRefresh(const AutoDisableRefresh& aOther);
 268     const AutoDisableRefresh& operator=(const AutoDisableRefresh& aOther);
 269
 270     RefPtr<nsViewManager> mRootVM;
 271   };
 272
 273  private:
 274   friend class AutoDisableRefresh;
 275
 276   nsViewManager* IncrementDisableRefreshCount();
 277   void DecrementDisableRefreshCount();
 278
 279  public:
 280   /**
 281    * Retrieve the widget at the root of the nearest enclosing
 282    * view manager whose root view has a widget.
 283    */
 284   void GetRootWidget(nsIWidget** aWidget);
 285
 286   /**
 287    * Indicate whether the viewmanager is currently painting
 288    *
 289    * @param aPainting true if the viewmanager is painting
 290    *                  false otherwise
 291    */
 292   void IsPainting(bool& aIsPainting);
 293
 294   /**
 295    * Retrieve the time of the last user event. User events
 296    * include mouse and keyboard events. The viewmanager
 297    * saves the time of the last user event.
 298    *
 299    * @param aTime Last user event time in microseconds
 300    */
 301   void GetLastUserEventTime(uint32_t& aTime);
 302
 303   /**
 304    * Find the nearest display root view for the view aView. This is the view for
 305    * the nearest enclosing popup or the root view for the root document.
 306    */
 307   static nsView* GetDisplayRootFor(nsView* aView);
 308
 309   /**
 310    * Flush the accumulated dirty region to the widget and update widget
 311    * geometry.
 312    */
 313   MOZ_CAN_RUN_SCRIPT void ProcessPendingUpdates();
 314
 315   /**
 316    * Just update widget geometry without flushing the dirty region
 317    */
 318   MOZ_CAN_RUN_SCRIPT void UpdateWidgetGeometry();
 319
 320   int32_t AppUnitsPerDevPixel() const {
 321     return mContext->AppUnitsPerDevPixel();
 322   }
 323
 324  private:
 325   static uint32_t gLastUserEventTime;
 326
 327   /* Update the cached RootViewManager pointer on this view manager. */
 328   void InvalidateHierarchy();
 329   void FlushPendingInvalidates();
 330
 331   MOZ_CAN_RUN_SCRIPT
 332   void ProcessPendingUpdatesForView(nsView* aView,
 333                                     bool aFlushDirtyRegion = true);
 334   void ProcessPendingUpdatesRecurse(
 335       nsView* aView, AutoTArray<nsCOMPtr<nsIWidget>, 1>& aWidgets);
 336   MOZ_CAN_RUN_SCRIPT
 337   void ProcessPendingUpdatesPaint(nsIWidget* aWidget);
 338
 339   void FlushDirtyRegionToWidget(nsView* aView);
 340   /**
 341    * Call WillPaint() on all view observers under this vm root.
 342    */
 343   MOZ_CAN_RUN_SCRIPT_BOUNDARY void CallWillPaintOnObservers();
 344   void ReparentChildWidgets(nsView* aView, nsIWidget* aNewWidget);
 345   void ReparentWidgets(nsView* aView, nsView* aParent);
 346   void InvalidateWidgetArea(nsView* aWidgetView,
 347                             const nsRegion& aDamagedRegion);
 348
 349   void InvalidateViews(nsView* aView);
 350
 351   // aView is the view for aWidget and aRegion is relative to aWidget.
 352   MOZ_CAN_RUN_SCRIPT
 353   void Refresh(nsView* aView, const LayoutDeviceIntRegion& aRegion);
 354
 355   // Utilities
 356
 357   bool IsViewInserted(nsView* aView);
 358
 359   /**
 360    * Intersects aRect with aView's bounds and then transforms it from aView's
 361    * coordinate system to the coordinate system of the widget attached to
 362    * aView.
 363    */
 364   LayoutDeviceIntRect ViewToWidget(nsView* aView, const nsRect& aRect) const;
 365
 366   MOZ_CAN_RUN_SCRIPT_BOUNDARY
 367   void DoSetWindowDimensions(nscoord aWidth, nscoord aHeight, bool aDoReflow);
 368   bool ShouldDelayResize() const;
 369
 370   bool IsPainting() const { return RootViewManager()->mPainting; }
 371
 372   void SetPainting(bool aPainting) { RootViewManager()->mPainting = aPainting; }
 373
 374   void InvalidateView(nsView* aView, const nsRect& aRect);
 375
 376   nsViewManager* RootViewManager() const { return mRootViewManager; }
 377   bool IsRootVM() const { return this == RootViewManager(); }
 378
 379   // Whether synchronous painting is allowed at the moment. For example,
 380   // widget geometry changes can cause synchronous painting, so they need to
 381   // be deferred while refresh is disabled.
 382   bool IsPaintingAllowed() {
 383     return RootViewManager()->mRefreshDisableCount == 0;
 384   }
 385
 386   MOZ_CAN_RUN_SCRIPT void WillPaintWindow(nsIWidget* aWidget);
 387   MOZ_CAN_RUN_SCRIPT
 388   bool PaintWindow(nsIWidget* aWidget, const LayoutDeviceIntRegion& aRegion);
 389   MOZ_CAN_RUN_SCRIPT void DidPaintWindow();
 390
 391   // Call this when you need to let the viewmanager know that it now has
 392   // pending updates.
 393   void PostPendingUpdate();
 394
 395   RefPtr<nsDeviceContext> mContext;
 396   mozilla::PresShell* mPresShell;
 397
 398   // The size for a resize that we delayed until the root view becomes
 399   // visible again.
 400   nsSize mDelayedResize;
 401
 402   nsView* mRootView;
 403   // mRootViewManager is a strong ref unless it equals |this|.  It's
 404   // never null (if we have no ancestors, it will be |this|).
 405   nsViewManager* mRootViewManager;
 406
 407   // The following members should not be accessed directly except by
 408   // the root view manager.  Some have accessor functions to enforce
 409   // this, as noted.
 410
 411   int32_t mRefreshDisableCount;
 412   // Use IsPainting() and SetPainting() to access mPainting.
 413   bool mPainting;
 414   bool mRecursiveRefreshPending;
 415   bool mHasPendingWidgetGeometryChanges;
 416
 417   // from here to public should be static and locked... MMP
 418
 419   // list of view managers
 420   static nsTArray<nsViewManager*>* gViewManagers;
 421 };
 422
 423 /**
 424    Invalidation model:
 425
 426    1) Callers call into the view manager and ask it to invalidate a view.
 427
 428    2) The view manager finds the "right" widget for the view, henceforth called
 429       the root widget.
 430
 431    3) The view manager traverses descendants of the root widget and for each
 432       one that needs invalidation stores the rect to invalidate on the widget's
 433       view (batching).
 434
 435    4) The dirty region is flushed to the right widget when
 436       ProcessPendingUpdates is called from the RefreshDriver.
 437
 438    It's important to note that widgets associated to views outside this view
 439    manager can end up being invalidated during step 3.  Therefore, the end of a
 440    view update batch really needs to traverse the entire view tree, to ensure
 441    that those invalidates happen.
 442
 443    To cope with this, invalidation processing and should only happen on the
 444    root viewmanager.
 445 */
 446
 447 #endif  // nsViewManager_h___