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