view/public/nsIViewManager.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef nsIViewManager_h___
  39 #define nsIViewManager_h___
  40
  41 #include "nscore.h"
  42 #include "nsIView.h"
  43 #include "nsColor.h"
  44 #include "nsEvent.h"
  45 #include "nsIRenderingContext.h"
  46
  47 class nsIScrollableView;
  48 class nsIWidget;
  49 struct nsRect;
  50 class nsRegion;
  51 class nsIDeviceContext;
  52 class nsIViewObserver;
  53
  54 enum nsRectVisibility {
  55   nsRectVisibility_kVisible,
  56   nsRectVisibility_kAboveViewport,
  57   nsRectVisibility_kBelowViewport,
  58   nsRectVisibility_kLeftOfViewport,
  59   nsRectVisibility_kRightOfViewport,
  60   nsRectVisibility_kZeroAreaRect
  61 };
  62
  63 // 7eae119d-9fc8-482d-92ec-145eef228a4a
  64 #define NS_IVIEWMANAGER_IID   \
  65 { 0x7eae119d, 0x9fc8, 0x482d, \
  66   { 0x92, 0xec, 0x14, 0x5e, 0xef, 0x22, 0x8a, 0x4a } }
  67
  68 class nsIViewManager : public nsISupports
  69 {
  70 public:
  71
  72   NS_DECLARE_STATIC_IID_ACCESSOR(NS_IVIEWMANAGER_IID)
  73   /**
  74    * Initialize the ViewManager
  75    * Note: this instance does not hold a reference to the viewobserver
  76    * because it holds a reference to this instance.
  77    * @result The result of the initialization, NS_OK if no errors
  78    */
  79   NS_IMETHOD  Init(nsIDeviceContext* aContext) = 0;
  80
  81   /**
  82    * Create an ordinary view
  83    * @param aBounds initial bounds for view
  84    *        XXX We should eliminate this parameter; you can set the bounds after CreateView
  85    * @param aParent intended parent for view. this is not actually set in the
  86    *        nsIView through this method. it is only used by the initialization
  87    *        code to walk up the view tree, if necessary, to find resources.
  88    *        XXX We should eliminate this parameter!
  89    * @param aVisibilityFlag initial visibility state of view
  90    *        XXX We should eliminate this parameter; you can set it after CreateView
  91    * @result The new view
  92    */
  93   NS_IMETHOD_(nsIView*) CreateView(const nsRect& aBounds,
  94                                    const nsIView* aParent,
  95                                    nsViewVisibility aVisibilityFlag = nsViewVisibility_kShow) = 0;
  96
  97   /**
  98    * Create an scrollable view
  99    * @param aBounds initial bounds for view
 100    *        XXX We should eliminate this parameter; you can set the bounds after CreateScrollableView
 101    * @param aParent intended parent for view. this is not actually set in the
 102    *        nsIView through this method. it is only used by the initialization
 103    *        code to walk up the view tree, if necessary, to find resources.
 104    *        XXX We should eliminate this parameter!
 105    * @result The new view
 106    */
 107   NS_IMETHOD_(nsIScrollableView*) CreateScrollableView(const nsRect& aBounds,
 108                                                        const nsIView* aParent) = 0;
 109
 110   /**
 111    * Get the root of the view tree.
 112    * @result the root view
 113    */
 114   NS_IMETHOD  GetRootView(nsIView *&aView) = 0;
 115
 116   /**
 117    * Set the root of the view tree. Does not destroy the current root view.
 118    * aView may have a parent view managed by a different view manager.
 119    * aView may have a widget (anything but printing) or may not (printing).
 120    * @param aView view to set as root
 121    */
 122   NS_IMETHOD  SetRootView(nsIView *aView) = 0;
 123
 124   /**
 125    * Get the dimensions of the root window. The dimensions are in
 126    * twips
 127    * @param aWidth out parameter for width of window in twips
 128    * @param aHeight out parameter for height of window in twips
 129    */
 130   NS_IMETHOD  GetWindowDimensions(nscoord *aWidth, nscoord *aHeight) = 0;
 131
 132   /**
 133    * Set the dimensions of the root window.
 134    * Called if the root window is resized. The dimensions are in
 135    * twips
 136    * @param aWidth of window in twips
 137    * @param aHeight of window in twips
 138    */
 139   NS_IMETHOD  SetWindowDimensions(nscoord aWidth, nscoord aHeight) = 0;
 140
 141   /**
 142    * Do any resizes that are pending.
 143    */
 144   NS_IMETHOD  FlushDelayedResize() = 0;
 145
 146   /**
 147    * Called to force a redrawing of any dirty areas.
 148    */
 149   // XXXbz why is this exposed?  Shouldn't update view batches handle this?
 150   // It's not like Composite() does what's expected inside a view update batch
 151   // anyway, since dirty areas may not have been invalidated on the widget yet
 152   // and widget changes may not have been propagated yet.  Maybe this should
 153   // call FlushPendingInvalidates()?
 154   NS_IMETHOD  Composite(void) = 0;
 155
 156   /**
 157    * Called to inform the view manager that the entire area of a view
 158    * is dirty and needs to be redrawn.
 159    * @param aView view to paint. should be root view
 160    * @param aUpdateFlags see bottom of nsIViewManager.h for description
 161    */
 162   NS_IMETHOD  UpdateView(nsIView *aView, PRUint32 aUpdateFlags) = 0;
 163
 164   /**
 165    * Called to inform the view manager that some portion of a view
 166    * is dirty and needs to be redrawn. The rect passed in
 167    * should be in the view's coordinate space.
 168    * @param aView view to paint. should be root view
 169    * @param rect rect to mark as damaged
 170    * @param aUpdateFlags see bottom of nsIViewManager.h for description
 171    */
 172   NS_IMETHOD  UpdateView(nsIView *aView, const nsRect &aRect, PRUint32 aUpdateFlags) = 0;
 173
 174   /**
 175    * Called to inform the view manager that it should redraw all views.
 176    * @param aView view to paint. should be root view
 177    * @param aUpdateFlags see bottom of nsIViewManager.h for description
 178    */
 179   NS_IMETHOD  UpdateAllViews(PRUint32 aUpdateFlags) = 0;
 180
 181   /**
 182    * Called to dispatch an event to the appropriate view. Often called
 183    * as a result of receiving a mouse or keyboard event from the widget
 184    * event system.
 185    * @param event event to dispatch
 186    * @result event handling status
 187    */
 188   NS_IMETHOD  DispatchEvent(nsGUIEvent *aEvent, nsEventStatus* aStatus) = 0;
 189
 190   /**
 191    * Used to grab/capture all mouse events for a specific view,
 192    * irrespective of the cursor position at which the
 193    * event occurred.
 194    * @param aView view to capture mouse events
 195    * @result event handling status
 196    */
 197   NS_IMETHOD  GrabMouseEvents(nsIView *aView, PRBool& aResult) = 0;
 198
 199   /**
 200    * Get the current view, if any, that's capturing mouse events.
 201    * @result view that is capturing mouse events or nsnull
 202    */
 203   NS_IMETHOD  GetMouseEventGrabber(nsIView *&aView) = 0;
 204
 205   /**
 206    * Given a parent view, insert another view as its child.
 207    * aSibling and aAbove control the "document order" for the insertion.
 208    * If aSibling is null, the view is inserted at the end of the document order
 209    * if aAfter is PR_TRUE, otherwise it is inserted at the beginning.
 210    * If aSibling is non-null, then if aAfter is PR_TRUE, the view is inserted
 211    * after the sibling in document order (appearing above the sibling unless
 212    * overriden by z-order).
 213    * If it is PR_FALSE, the view is inserted before the sibling.
 214    * The view manager generates the appopriate dirty regions.
 215    * @param aParent parent view
 216    * @param aChild child view
 217    * @param aSibling sibling view
 218    * @param aAfter after or before in the document order
 219    */
 220   NS_IMETHOD  InsertChild(nsIView *aParent, nsIView *aChild, nsIView *aSibling,
 221                           PRBool aAfter) = 0;
 222
 223   /**
 224    * Remove a specific child view from its parent. This will NOT remove its placeholder
 225    * if there is one.
 226    * The view manager generates the appropriate dirty regions.
 227    * @param aParent parent view
 228    * @param aChild child view
 229    */
 230   NS_IMETHOD  RemoveChild(nsIView *aChild) = 0;
 231
 232   /**
 233    * Move a view to the specified position, provided in parent coordinates.
 234    * The new position is the (0, 0) origin for the view's coordinate system.
 235    * The view's bounds may extend above or to the left of this point.
 236    * The view manager generates the appropriate dirty regions.
 237    * @param aView view to move
 238    * @param aX x value for new view position
 239    * @param aY y value for new view position
 240    */
 241   NS_IMETHOD  MoveViewTo(nsIView *aView, nscoord aX, nscoord aY) = 0;
 242
 243   /**
 244    * Resize a view. In addition to setting the width and height, you can
 245    * set the x and y of its bounds relative to its position. Negative x and y
 246    * will let the view extend above and to the left of the (0,0) point in its
 247    * coordinate system.
 248    * The view manager generates the appropriate dirty regions.
 249    * @param aView view to move
 250    * @param the new bounds relative to the current position
 251    * @param RepaintExposedAreaOnly
 252    *     if PR_TRUE Repaint only the expanded or contracted region,
 253    *     if PR_FALSE Repaint the union of the old and new rectangles.
 254    */
 255   NS_IMETHOD  ResizeView(nsIView *aView, const nsRect &aRect,
 256                          PRBool aRepaintExposedAreaOnly = PR_FALSE) = 0;
 257
 258   /**
 259    * Set the visibility of a view.
 260    * The view manager generates the appropriate dirty regions.
 261    * @param aView view to change visibility state of
 262    * @param visible new visibility state
 263    */
 264   NS_IMETHOD  SetViewVisibility(nsIView *aView, nsViewVisibility aVisible) = 0;
 265
 266   /**
 267    * Set the z-index of a view. Positive z-indices mean that a view
 268    * is above its parent in z-order. Negative z-indices mean that a
 269    * view is below its parent.
 270    * The view manager generates the appropriate dirty regions.
 271    * @param aAutoZIndex indicate that the z-index of a view is "auto". An "auto" z-index
 272    * means that the view does not define a new stacking context,
 273    * which means that the z-indicies of the view's children are
 274    * relative to the view's siblings.
 275    * @param aView view to change z depth of
 276    * @param aZindex explicit z depth
 277    * @param aTopMost used when this view is z-index:auto to compare against
 278    *        other z-index:auto views.
 279    *        PR_TRUE if the view should be topmost when compared with
 280    *        other z-index:auto views.
 281    */
 282   NS_IMETHOD  SetViewZIndex(nsIView *aView, PRBool aAutoZIndex, PRInt32 aZindex, PRBool aTopMost = PR_FALSE) = 0;
 283
 284   /**
 285    * Set whether the view "floats" above all other views,
 286    * which tells the compositor not to consider higher views in
 287    * the view hierarchy that would geometrically intersect with
 288    * this view. This is a hack, but it fixes some problems with
 289    * views that need to be drawn in front of all other views.
 290    */
 291   NS_IMETHOD  SetViewFloating(nsIView *aView, PRBool aFloatingView) = 0;
 292
 293   /**
 294    * Set the view observer associated with this manager
 295    * @param aObserver - new observer
 296    * @result error status
 297    */
 298   NS_IMETHOD SetViewObserver(nsIViewObserver *aObserver) = 0;
 299
 300   /**
 301    * Get the view observer associated with this manager
 302    * @param aObserver - out parameter for observer
 303    * @result error status
 304    */
 305   NS_IMETHOD GetViewObserver(nsIViewObserver *&aObserver) = 0;
 306
 307   /**
 308    * Get the device context associated with this manager
 309    * @result device context
 310    */
 311   NS_IMETHOD  GetDeviceContext(nsIDeviceContext *&aContext) = 0;
 312
 313   /**
 314    * prevent the view manager from refreshing.
 315    * @return error status
 316    */
 317   // XXXbz callers of this function don't seem to realize that it disables
 318   // refresh for the entire view manager hierarchy.... Maybe it shouldn't do
 319   // that?
 320   NS_IMETHOD DisableRefresh(void) = 0;
 321
 322   /**
 323    * allow the view manager to refresh. this may cause a synchronous
 324    * paint to occur inside the call.
 325    * @param aUpdateFlags see bottom of nsIViewManager.h for description
 326    * @return error status
 327    */
 328   NS_IMETHOD EnableRefresh(PRUint32 aUpdateFlags) = 0;
 329
 330   class NS_STACK_CLASS UpdateViewBatch {
 331   public:
 332     UpdateViewBatch() {}
 333   /**
 334    * prevents the view manager from refreshing. allows UpdateView()
 335    * to notify widgets of damaged regions that should be repainted
 336    * when the batch is ended. Call EndUpdateViewBatch on this object
 337    * before it is destroyed
 338    * @return error status
 339    */
 340     UpdateViewBatch(nsIViewManager* aVM) {
 341       if (aVM) {
 342         mRootVM = aVM->BeginUpdateViewBatch();
 343       }
 344     }
 345     ~UpdateViewBatch() {
 346       NS_ASSERTION(!mRootVM, "Someone forgot to call EndUpdateViewBatch!");
 347     }
 348
 349     /**
 350      * See the constructor, this lets you "fill in" a blank UpdateViewBatch.
 351      */
 352     void BeginUpdateViewBatch(nsIViewManager* aVM) {
 353       NS_ASSERTION(!mRootVM, "already started a batch!");
 354       if (aVM) {
 355         mRootVM = aVM->BeginUpdateViewBatch();
 356       }
 357     }
 358
 359   /**
 360    * allow the view manager to refresh any damaged areas accumulated
 361    * after the BeginUpdateViewBatch() call.  this may cause a
 362    * synchronous paint to occur inside the call if aUpdateFlags
 363    * NS_VMREFRESH_IMMEDIATE is set.
 364    *
 365    * If this is not the outermost view batch command, then this does
 366    * nothing except that the specified flags are remembered. When the
 367    * outermost batch finally ends, we merge together all the flags for the
 368    * inner batches in the following way:
 369    * -- If any batch specified NS_VMREFRESH_IMMEDIATE, then we use that flag
 370    * (i.e. there is a synchronous paint under the last EndUpdateViewBatch)
 371    * -- Otherwise if any batch specified NS_VMREFERSH_DEFERRED, then we use
 372    * that flag (i.e. invalidation is deferred until the processing of an
 373    * Invalidate PLEvent)
 374    * -- Otherwise all batches specified NS_VMREFRESH_NO_SYNC and we honor
 375    * that; all widgets are invalidated normally and will be painted the next
 376    * time the toolkit chooses to update them.
 377    *
 378    * @param aUpdateFlags see bottom of nsIViewManager.h for
 379    * description @return error status
 380    */
 381     void EndUpdateViewBatch(PRUint32 aUpdateFlags) {
 382       if (!mRootVM)
 383         return;
 384       mRootVM->EndUpdateViewBatch(aUpdateFlags);
 385       mRootVM = nsnull;
 386     }
 387
 388   private:
 389     UpdateViewBatch(const UpdateViewBatch& aOther);
 390     const UpdateViewBatch& operator=(const UpdateViewBatch& aOther);
 391
 392     nsCOMPtr<nsIViewManager> mRootVM;
 393   };
 394
 395 private:
 396   friend class UpdateViewBatch;
 397
 398   virtual nsIViewManager* BeginUpdateViewBatch(void) = 0;
 399   NS_IMETHOD EndUpdateViewBatch(PRUint32 aUpdateFlags) = 0;
 400
 401 public:
 402
 403   /**
 404    * set the view that is is considered to be the root scrollable
 405    * view for the document.
 406    * @param aScrollable root scrollable view
 407    * @return error status
 408    */
 409   NS_IMETHOD SetRootScrollableView(nsIScrollableView *aScrollable) = 0;
 410
 411   /**
 412    * get the view that is is considered to be the root scrollable
 413    * view for the document.
 414    * @param aScrollable out parameter for root scrollable view
 415    * @return error status
 416    */
 417   NS_IMETHOD GetRootScrollableView(nsIScrollableView **aScrollable) = 0;
 418
 419   /**
 420    * Retrieve the widget at the root of the view manager. This is the
 421    * widget associated with the root view, if the root view exists and has
 422    * a widget.
 423    */
 424   NS_IMETHOD GetWidget(nsIWidget **aWidget) = 0;
 425
 426   /**
 427    * Force update of view manager widget
 428    * Callers should use UpdateView(view, NS_VMREFRESH_IMMEDIATE) in most cases instead
 429    * @result error status
 430    */
 431   // XXXbz Callers seem to be confused about this one... and it doesn't play
 432   // right with view update batching at all (will miss updates).  Maybe this
 433   // should call FlushPendingInvalidates()?
 434   NS_IMETHOD ForceUpdate() = 0;
 435
 436   /**
 437    * Indicate whether the viewmanager is currently painting
 438    *
 439    * @param aPainting PR_TRUE if the viewmanager is painting
 440    *                  PR_FALSE otherwise
 441    */
 442   NS_IMETHOD IsPainting(PRBool& aIsPainting)=0;
 443
 444   /**
 445    * Set the default background color that the view manager should use
 446    * to paint otherwise unowned areas. If the color isn't known, just set
 447    * it to zero (which means 'transparent' since the color is RGBA).
 448    *
 449    * @param aColor the default background color
 450    */
 451   NS_IMETHOD SetDefaultBackgroundColor(nscolor aColor)=0;
 452
 453   /**
 454    * Retrieve the default background color.
 455    *
 456    * @param aColor the default background color
 457    */
 458   NS_IMETHOD GetDefaultBackgroundColor(nscolor* aColor)=0;
 459
 460   /**
 461    * Retrieve the time of the last user event. User events
 462    * include mouse and keyboard events. The viewmanager
 463    * saves the time of the last user event.
 464    *
 465    * @param aTime Last user event time in microseconds
 466    */
 467   NS_IMETHOD GetLastUserEventTime(PRUint32& aTime)=0;
 468
 469   /**
 470    * Determine if a rectangle specified in the view's coordinate system
 471    * is completely, or partially visible.
 472    * @param aView view that aRect coordinates are specified relative to
 473    * @param aRect rectangle in twips to test for visibility
 474    * @param aMinTwips is the min. pixel rows or cols at edge of screen
 475    *                  needed for object to be counted visible
 476    * @param aRectVisibility returns eVisible if the rect is visible,
 477    *                        otherwise it returns an enum indicating why not
 478    */
 479   NS_IMETHOD GetRectVisibility(nsIView *aView, const nsRect &aRect,
 480                                PRUint16 aMinTwips,
 481                                nsRectVisibility *aRectVisibility)=0;
 482
 483   /**
 484    * Dispatch a mouse move event based on the most recent mouse
 485    * position.  This is used when the contents of the page moved
 486    * (aFromScroll is false) or scrolled (aFromScroll is true).
 487    */
 488   NS_IMETHOD SynthesizeMouseMove(PRBool aFromScroll)=0;
 489
 490 };
 491
 492 NS_DEFINE_STATIC_IID_ACCESSOR(nsIViewManager, NS_IVIEWMANAGER_IID)
 493
 494 // Paint timing mode flags
 495
 496 // intermediate: do no special timing processing; repaint when the
 497 // toolkit issues an expose event (which will happen *before* PLEvent
 498 // processing). This is essentially the default.
 499 #define NS_VMREFRESH_NO_SYNC            0
 500
 501 // least immediate: we suppress invalidation, storing dirty areas in
 502 // views, and post an Invalidate PLEvent. The Invalidate event gets
 503 // processed after toolkit events such as window resize events!
 504 // This is only usable with EndUpdateViewBatch and EnableRefresh.
 505 #define NS_VMREFRESH_DEFERRED           0x0001
 506
 507 // most immediate: force a call to nsViewManager::Composite, which
 508 // synchronously updates the window(s) right away before returning
 509 #define NS_VMREFRESH_IMMEDIATE          0x0002
 510
 511 //animate scroll operation
 512 #define NS_VMREFRESH_SMOOTHSCROLL       0x0008
 513
 514 #endif  // nsIViewManager_h___