view/public/nsIView.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 nsIView_h___
  39 #define nsIView_h___
  40
  41 #include "nsCoord.h"
  42 #include "nsRect.h"
  43 #include "nsPoint.h"
  44 #include "nsIWidget.h"
  45
  46 class nsIViewManager;
  47 class nsIScrollableView;
  48 class nsViewManager;
  49 class nsView;
  50 class nsWeakView;
  51
  52 // Enumerated type to indicate the visibility of a layer.
  53 // hide - the layer is not shown.
  54 // show - the layer is shown irrespective of the visibility of
  55 //        the layer's parent.
  56 enum nsViewVisibility {
  57   nsViewVisibility_kHide = 0,
  58   nsViewVisibility_kShow = 1
  59 };
  60
  61 // IID for the nsIView interface
  62 // 1377A30E-99E6-42FA-9A2E-EEEC6B31B7B6
  63 #define NS_IVIEW_IID    \
  64 { 0x1377ae0e, 0x99e6, 0x42fa, \
  65 { 0x9a, 0x2e, 0xee, 0xec, 0x6b, 0x31, 0xb7, 0xb6 } }
  66
  67 // Public view flags are defined in this file
  68 #define NS_VIEW_FLAGS_PUBLIC              0x00FF
  69 // Private view flags are private to the view module,
  70 // and are defined in nsView.h
  71 #define NS_VIEW_FLAGS_PRIVATE             0xFF00
  72
  73 // Public view flags
  74
  75 // Indicates that the view is using auto z-indexing
  76 #define NS_VIEW_FLAG_AUTO_ZINDEX          0x0004
  77
  78 // Indicates that the view is a floating view.
  79 #define NS_VIEW_FLAG_FLOATING             0x0008
  80
  81 // If set it indicates that this view should be
  82 // displayed above z-index:auto views if this view
  83 // is z-index:auto also
  84 #define NS_VIEW_FLAG_TOPMOST              0x0010
  85
  86 // If set, the view disowns the widget and leaves it up
  87 // to other code to destroy it.
  88 #define NS_VIEW_DISOWNS_WIDGET             0x0020
  89
  90 // If set, the view should always invalidate its frame
  91 // during a scroll instead of doing a BitBlt.  This bit
  92 // is propagated down to children.
  93 #define NS_VIEW_FLAG_INVALIDATE_ON_SCROLL  0x0040
  94
  95 struct nsViewZIndex {
  96   PRBool mIsAuto;
  97   PRInt32 mZIndex;
  98   PRBool mIsTopmost;
  99
 100   nsViewZIndex(PRBool aIsAuto, PRInt32 aZIndex, PRBool aIsTopmost)
 101     : mIsAuto(aIsAuto), mZIndex(aZIndex), mIsTopmost(aIsTopmost) {}
 102 };
 103
 104 //----------------------------------------------------------------------
 105
 106 /**
 107  * View interface
 108  *
 109  * Views are NOT reference counted. Use the Destroy() member function to
 110  * destroy a view.
 111  *
 112  * The lifetime of the view hierarchy is bounded by the lifetime of the
 113  * view manager that owns the views.
 114  *
 115  * Most of the methods here are read-only. To set the corresponding properties
 116  * of a view, go through nsIViewManager.
 117  */
 118
 119 class nsIView
 120 {
 121 public:
 122   NS_DECLARE_STATIC_IID_ACCESSOR(NS_IVIEW_IID)
 123
 124   /**
 125    * See if this view is scrollable.
 126    * @result an nsIScrollableView* if the view is scrollable, or nsnull if not.
 127    */
 128   virtual nsIScrollableView* ToScrollableView() { return nsnull; }
 129
 130   /**
 131    * Find the view for the given widget, if there is one.
 132    * @return the view the widget belongs to, or null if the widget doesn't
 133    * belong to any view.
 134    */
 135   static nsIView* GetViewFor(nsIWidget* aWidget);
 136
 137   /**
 138    * Get the view manager which "owns" the view.
 139    * This method might require some expensive traversal work in the future. If you can get the
 140    * view manager from somewhere else, do that instead.
 141    * @result the view manager
 142    */
 143   nsIViewManager* GetViewManager() const
 144   { return reinterpret_cast<nsIViewManager*>(mViewManager); }
 145
 146   /**
 147    * Destroy the view.
 148    *
 149    * The view destroys its child views, and destroys and releases its
 150    * widget (if it has one).
 151    *
 152    * Also informs the view manager that the view is destroyed by calling
 153    * SetRootView(NULL) if the view is the root view and calling RemoveChild()
 154    * otherwise.
 155    */
 156   void Destroy();
 157
 158   /**
 159    * Called to get the position of a view.
 160    * The specified coordinates are in the parent view's coordinate space.
 161    * This is the (0, 0) origin of the coordinate space established by this view.
 162    * @param x out parameter for x position
 163    * @param y out parameter for y position
 164    */
 165   nsPoint GetPosition() const {
 166     // Call ExternalIsRoot here so that we can get to it from other
 167     // components
 168     NS_ASSERTION(!ExternalIsRoot() || (mPosX == 0 && mPosY == 0),
 169                  "root views should always have explicit position of (0,0)");
 170     return nsPoint(mPosX, mPosY);
 171   }
 172
 173   /**
 174    * Called to get the dimensions and position of the view's bounds.
 175    * The view's bounds (x,y) are in the coordinate space of the parent view.
 176    * The view's bounds (x,y) might not be the same as the view's position,
 177    * if the view has content above or to the left of its origin.
 178    * @param aBounds out parameter for bounds
 179    */
 180   nsRect GetBounds() const { return mDimBounds; }
 181
 182   /**
 183    * Get the offset between the coordinate systems of |this| and aOther.
 184    * Adding the return value to a point in the coordinate system of |this|
 185    * will transform the point to the coordinate system of aOther.
 186    *
 187    * If aOther is null, this will return the offset of |this| from the
 188    * root of the viewmanager tree.
 189    *
 190    * This function is fastest when aOther is an ancestor of |this|.
 191    *
 192    * NOTE: this actually returns the offset from aOther to |this|, but
 193    * that offset is added to transform _coordinates_ from |this| to aOther.
 194    */
 195   nsPoint GetOffsetTo(const nsIView* aOther) const;
 196
 197   /**
 198    * Get the screen position of the view.
 199    * @return the pixel position of the top-left of the view in screen
 200    * coordinates.
 201    */
 202   nsIntPoint GetScreenPosition() const;
 203
 204   /**
 205    * Called to query the visibility state of a view.
 206    * @result current visibility state
 207    */
 208   nsViewVisibility GetVisibility() const { return mVis; }
 209
 210   /**
 211    * Called to query the z-index of a view.
 212    * The z-index is relative to all siblings of the view.
 213    * @result mZIndex: explicit z-index value or 0 if none is set
 214    *         mIsAuto: PR_TRUE if the view is zindex:auto
 215    *         mIsTopMost: used when this view is zindex:auto
 216    *                     PR_TRUE if the view is topmost when compared
 217    *                     with another z-index:auto view
 218    */
 219   nsViewZIndex GetZIndex() const { return nsViewZIndex((mVFlags & NS_VIEW_FLAG_AUTO_ZINDEX) != 0,
 220                                                        mZIndex,
 221                                                        (mVFlags & NS_VIEW_FLAG_TOPMOST) != 0); }
 222
 223   /**
 224    * Get whether the view "floats" above all other views,
 225    * which tells the compositor not to consider higher views in
 226    * the view hierarchy that would geometrically intersect with
 227    * this view. This is a hack, but it fixes some problems with
 228    * views that need to be drawn in front of all other views.
 229    * @result PR_TRUE if the view floats, PR_FALSE otherwise.
 230    */
 231   PRBool GetFloating() const { return (mVFlags & NS_VIEW_FLAG_FLOATING) != 0; }
 232
 233   /**
 234    * Called to query the parent of the view.
 235    * @result view's parent
 236    */
 237   nsIView* GetParent() const { return reinterpret_cast<nsIView*>(mParent); }
 238
 239   /**
 240    * The view's first child is the child which is earliest in document order.
 241    * @result first child
 242    */
 243   nsIView* GetFirstChild() const { return reinterpret_cast<nsIView*>(mFirstChild); }
 244
 245   /**
 246    * Called to query the next sibling of the view.
 247    * @result view's next sibling
 248    */
 249   nsIView* GetNextSibling() const { return reinterpret_cast<nsIView*>(mNextSibling); }
 250
 251   /**
 252    * Set the view's link to client owned data.
 253    * @param aData - data to associate with view. nsnull to disassociate
 254    */
 255   void SetClientData(void *aData) { mClientData = aData; }
 256
 257   /**
 258    * Query the view for it's link to client owned data.
 259    * @result data associated with view or nsnull if there is none.
 260    */
 261   void* GetClientData() const { return mClientData; }
 262
 263   /**
 264    * Get the nearest widget in this view or a parent of this view and
 265    * the offset from the widget's origin to this view's origin
 266    * @param aOffset the offset from this view's origin to the widget's origin
 267    * (usually positive)
 268    * @return the widget closest to this view; can be null because some view trees
 269    * don't have widgets at all (e.g., printing), but if any view in the view tree
 270    * has a widget, then it's safe to assume this will not return null
 271    * XXX Remove this 'virtual' when gfx+widget are merged into gklayout;
 272    * Mac widget depends on this method, which is BOGUS!
 273    */
 274   virtual nsIWidget* GetNearestWidget(nsPoint* aOffset) const;
 275
 276   /**
 277    * Create a widget to associate with this view.
 278    * @param aWindowIID IID for Widget type that this view
 279    *        should have associated with it. if nsull, then no
 280    *        width will be created for this view
 281    * @param aWidgetInitData data used to initialize this view's widget before
 282    *        its create is called.
 283    * @param aNative native window that will be used as parent of
 284    *        aWindowIID. if nsnull, then parent will be derived from
 285    *        parent view and it's ancestors
 286    * @param aWindowType is either content, UI or inherit from parent window.
 287    *        This is used to expose what type of window this is to
 288    *        assistive technology like screen readers.
 289    * @param aParentWidget alternative parent to aNative used for popups. Must
 290    *        be null for non-popups.
 291    * @return error status
 292    */
 293   nsresult CreateWidget(const nsIID &aWindowIID,
 294                         nsWidgetInitData *aWidgetInitData = nsnull,
 295                         nsNativeWidget aNative = nsnull,
 296                         PRBool aEnableDragDrop = PR_TRUE,
 297                         PRBool aResetVisibility = PR_TRUE,
 298                         nsContentType aWindowType = eContentTypeInherit,
 299                         nsIWidget* aParentWidget = nsnull);
 300
 301   /**
 302    * In 4.0, the "cutout" nature of a view is queryable.
 303    * If we believe that all cutout view have a native widget, this
 304    * could be a replacement.
 305    * @param aWidget out parameter for widget that this view contains,
 306    *        or nsnull if there is none.
 307    */
 308   nsIWidget* GetWidget() const { return mWindow; }
 309
 310   /**
 311    * Returns PR_TRUE if the view has a widget associated with it.
 312    */
 313   PRBool HasWidget() const { return mWindow != nsnull; }
 314
 315   /**
 316    * If called, will make the view disown the widget and leave it up
 317    * to other code to destroy it.
 318    */
 319   void DisownWidget() {
 320     mVFlags |= NS_VIEW_DISOWNS_WIDGET;
 321   }
 322
 323   /**
 324    * If called, will make the view invalidate its frame instead of BitBlitting
 325    * it when there's a scroll.
 326    */
 327   void SetInvalidateFrameOnScroll()
 328   {
 329     mVFlags |= NS_VIEW_FLAG_INVALIDATE_ON_SCROLL;
 330   }
 331
 332   /**
 333    * Returns whether or not we should automatically fail to BitBlt when scrolling.
 334    * This is true if either we're marked to have invalidate on scroll or if some
 335    * ancestor does.
 336    */
 337   PRBool NeedsInvalidateFrameOnScroll() const;
 338
 339 #ifdef DEBUG
 340   /**
 341    * Output debug info to FILE
 342    * @param out output file handle
 343    * @param aIndent indentation depth
 344    * NOTE: virtual so that debugging tools not linked into gklayout can access it
 345    */
 346   virtual void List(FILE* out, PRInt32 aIndent = 0) const;
 347 #endif // DEBUG
 348
 349   /**
 350    * @result true iff this is the root view for its view manager
 351    */
 352   PRBool IsRoot() const;
 353
 354   virtual PRBool ExternalIsRoot() const;
 355
 356   void SetDeletionObserver(nsWeakView* aDeletionObserver);
 357 protected:
 358   friend class nsWeakView;
 359   nsViewManager     *mViewManager;
 360   nsView            *mParent;
 361   nsIWidget         *mWindow;
 362   nsView            *mNextSibling;
 363   nsView            *mFirstChild;
 364   void              *mClientData;
 365   PRInt32           mZIndex;
 366   nsViewVisibility  mVis;
 367   nscoord           mPosX, mPosY;
 368   nsRect            mDimBounds; // relative to parent
 369   float             mOpacity;
 370   PRUint32          mVFlags;
 371   nsWeakView*       mDeletionObserver;
 372
 373   virtual ~nsIView() {}
 374 };
 375
 376 NS_DEFINE_STATIC_IID_ACCESSOR(nsIView, NS_IVIEW_IID)
 377
 378 // nsWeakViews must *not* be used in heap!
 379 class nsWeakView
 380 {
 381 public:
 382   nsWeakView(nsIView* aView) : mPrev(nsnull), mView(aView)
 383   {
 384     if (mView) {
 385       mView->SetDeletionObserver(this);
 386     }
 387   }
 388
 389   ~nsWeakView()
 390   {
 391     if (mView) {
 392       NS_ASSERTION(mView->mDeletionObserver == this,
 393                    "nsWeakViews deleted in wrong order!");
 394       // Clear deletion observer temporarily.
 395       mView->SetDeletionObserver(nsnull);
 396       // Put back the previous deletion observer.
 397       mView->SetDeletionObserver(mPrev);
 398     }
 399   }
 400
 401   PRBool IsAlive() { return !!mView; }
 402
 403   nsIView* GetView() { return mView; }
 404
 405   void SetPrevious(nsWeakView* aWeakView) { mPrev = aWeakView; }
 406
 407   void Clear()
 408   {
 409     if (mPrev) {
 410       mPrev->Clear();
 411     }
 412     mView = nsnull;
 413   }
 414 private:
 415   static void* operator new(size_t) CPP_THROW_NEW { return 0; }
 416   static void operator delete(void*, size_t) {}
 417   nsWeakView* mPrev;
 418   nsIView*    mView;
 419 };
 420
 421 #endif