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