/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- * * The contents of this file are subject to the Netscape Public * License Version 1.1 (the "License"); you may not use this file * except in compliance with the License. You may obtain a copy of * the License at http://www.mozilla.org/NPL/ * * Software distributed under the License is distributed on an "AS * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or * implied. See the License for the specific language governing * rights and limitations under the License. * * The Original Code is mozilla.org code. * * The Initial Developer of the Original Code is Netscape * Communications Corporation. Portions created by Netscape are * Copyright (C) 1998 Netscape Communications Corporation. All * Rights Reserved. * * Contributor(s): */ #ifndef nsIView_h___ #define nsIView_h___ #include #include "nsISupports.h" #include "nsCoord.h" #include "nsEvent.h" struct nsGUIEvent; class nsIWidget; struct nsWidgetInitData; typedef void* nsNativeWidget; class nsIViewManager; class nsIRegion; class nsIRenderingContext; class nsTransform2D; class nsIFrame; class nsIViewObserver; class nsVoidArray; struct nsRect; //this is used by the view clipping APIs since the description of //a clip rect is different than a rect struct nsViewClip { nscoord mLeft; nscoord mRight; nscoord mTop; nscoord mBottom; }; // Enumerated type to indicate the visibility of a layer. // hide - the layer is not shown. // show - the layer is shown irrespective of the visibility of // the layer's parent. // inherit - the layer inherits its visibility from its parent. enum nsViewVisibility { nsViewVisibility_kHide = 0, nsViewVisibility_kShow = 1, nsViewVisibility_kInherit = 2 }; // IID for the nsIView interface #define NS_IVIEW_IID \ { 0xf0a21c40, 0xa7e1, 0x11d1, \ { 0xa8, 0x24, 0x00, 0x40, 0x95, 0x9a, 0x28, 0xc9 } } //---------------------------------------------------------------------- /** * View interface * * Views are NOT reference counted. Use the Destroy() member function to * destroy a frame. * * The lifetime of the view hierarchy is bounded by the lifetime of the * view manager that owns the views. */ class nsIView : public nsISupports { public: NS_DEFINE_STATIC_IID_ACCESSOR(NS_IVIEW_IID) /** * Initialize the view * @param aManager view manager that "owns" the view. The view does NOT * hold a reference to the view manager * @param aBounds initial bounds for view * @param aParent intended parent for view. this is not actually set in the * nsIView through this method. it is only used by the initialization * code to walk up the view tree, if necessary, to find resources. * @param aVisibilityFlag initial visibility state of view * @result The result of the initialization, NS_OK if no errors */ NS_IMETHOD Init(nsIViewManager* aManager, const nsRect &aBounds, const nsIView *aParent, nsViewVisibility aVisibilityFlag = nsViewVisibility_kShow) = 0; /** * Destroy the view. * * The view destroys its child views, and destroys and releases its * widget (if it has one). * * Also informs the view manager that the view is destroyed by calling * SetRootView(NULL) if the view is the root view and calling RemoveChild() * otherwise. */ NS_IMETHOD Destroy() = 0; /** * Get the view manager the "owns" the view * @result view manager */ NS_IMETHOD GetViewManager(nsIViewManager *&aViewMgr) const = 0; /** * Called to indicate that the specified rect of the view * needs to be drawn via the rendering context. The rect * is specified in view coordinates. * @param rc rendering context to paint into * @param rect damage area * @param aPaintFlags see nsIView.h for flag definitions * @return PR_TRUE if the entire clip region has been eliminated, else PR_FALSE */ NS_IMETHOD Paint(nsIRenderingContext& rc, const nsRect& rect, PRUint32 aPaintFlags, PRBool &aResult) = 0; /** * Called to indicate that the specified region of the view * needs to be drawn via the rendering context. The region * is specified in view coordinates. * @param rc rendering context to paint into * @param region damage area * @param aPaintFlags see nsIView.h for flag definitions * @return PR_TRUE if the entire clip region has been eliminated, else PR_FALSE */ NS_IMETHOD Paint(nsIRenderingContext& rc, const nsIRegion& region, PRUint32 aPaintFlags, PRBool &aResult) = 0; /** * Called to indicate that the specified event should be handled * by the view. This method should return nsEventStatus_eConsumeDoDefault * or nsEventStatus_eConsumeNoDefault if the event has been handled. * @param event event to process * @param aEventFlags see nsIView.h for flag definitions * @result processing status */ NS_IMETHOD HandleEvent(nsGUIEvent *event, PRUint32 aEventFlags, nsEventStatus* aStatus, PRBool aForceHandle, PRBool& aHandled) = 0; /** * Called to indicate that the position of the view has been changed. * The specified coordinates are in the parent view's coordinate space. * @param x new x position * @param y new y position */ NS_IMETHOD SetPosition(nscoord x, nscoord y) = 0; /** * Called to get the position of a view. * The specified coordinates are in the parent view's coordinate space. * @param x out parameter for x position * @param y out parameter for y position */ NS_IMETHOD GetPosition(nscoord *x, nscoord *y) const = 0; /** * Called to indicate that the dimensions of the view (actually the * width and height of the clip) have been changed. * @param width new width * @param height new height */ NS_IMETHOD SetDimensions(nscoord width, nscoord height, PRBool aPaint = PR_TRUE) = 0; NS_IMETHOD GetDimensions(nscoord *width, nscoord *height) const = 0; /** * Called to indicate that the dimensions and position of the view have * been changed. * @param aBounds new bounds */ NS_IMETHOD SetBounds(const nsRect &aBounds, PRBool aPaint = PR_TRUE) = 0; /** * Called to indicate that the dimensions and position of the view have * been changed. * @param aX new x position * @param aY new y position * @param aWidth new width * @param aHeight new height */ NS_IMETHOD SetBounds(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight, PRBool aPaint = PR_TRUE) = 0; /** * Called to get the dimensions and position of the view. * @param aBounds out parameter for bounds */ NS_IMETHOD GetBounds(nsRect &aBounds) const = 0; /** * Called to set the clip of the children of this view. * The clip is relative to the origin of the view. * All of the children of this view will be clipped using * the specified rectangle * @param aLeft new left position * @param aTop new top position * @param aRight new right position * @param aBottom new bottom position */ NS_IMETHOD SetChildClip(nscoord aLeft, nscoord aTop, nscoord aRight, nscoord aBottom) = 0; /** * Called to get the dimensions and position of the clip for the view. * @param aLeft left position * @param aTop top position * @param aRight right position * @param aBottom bottom position */ NS_IMETHOD GetChildClip(nscoord *aLeft, nscoord *aTop, nscoord *aRight, nscoord *aBottom) const = 0; /** * Called to indicate that the visibility of a view has been * changed. * @param visibility new visibility state */ NS_IMETHOD SetVisibility(nsViewVisibility aVisibility) = 0; /** * Called to query the visibility state of a view. * @result current visibility state */ NS_IMETHOD GetVisibility(nsViewVisibility &aVisibility) const = 0; /** * Called to set the Z-order parent of the view. This is the * parent from which we derive our Z-order grouping. It might not * be the same as the geometric parent. * @param aParent new parent */ NS_IMETHOD SetZParent(nsIView *aZParent) = 0; NS_IMETHOD GetZParent(nsIView *&aZParent) const = 0; /** * Called to indicate that the z-index of a view has been changed. * The z-index is relative to all siblings of the view. * @param zindex new z depth */ NS_IMETHOD SetZIndex(PRInt32 aZIndex) = 0; /** * Called to query the z-index of a view. * The z-index is relative to all siblings of the view. * @result current z depth */ NS_IMETHOD GetZIndex(PRInt32 &aZIndex) const = 0; /** * Indicate that the z-index of a view is "auto". An "auto" z-index * means that the view does not define a new stacking context, * which means that the z-indicies of the view's children are * relative to the view's siblings. * @param aAutoZIndex if true then z-index will be auto */ NS_IMETHOD SetAutoZIndex(PRBool aAutoZIndex) = 0; /** * Returns true if an auto z-index is set for this view. * @result current state of auto z-indexing */ NS_IMETHOD GetAutoZIndex(PRBool &aAutoZIndex) const = 0; /** * Set/Get whether the view "floats" above all other views, * which tells the compositor not to consider higher views in * the view hierarchy that would geometrically intersect with * this view. This is a hack, but it fixes some problems with * views that need to be drawn in front of all other views. * @result PR_TRUE if the view floats, PR_FALSE otherwise. */ NS_IMETHOD SetFloating(PRBool aFloatingView) = 0; NS_IMETHOD GetFloating(PRBool &aFloatingView) const = 0; /** * Called to set the parent of the view. This is the geometric parent * (from which we derive our coordinate system). * @param aParent new parent */ NS_IMETHOD SetParent(nsIView *aParent) = 0; /** * Called to query the parent of the view. * @result view's parent */ NS_IMETHOD GetParent(nsIView *&aParent) const = 0; /** * Called to query the next sibling of the view. * @result view's next sibling */ NS_IMETHOD GetNextSibling(nsIView *&aNextSibling) const = 0; /** * Called to set the next sibling of the view. * @param aNextSibling new next sibling */ NS_IMETHOD SetNextSibling(nsIView* aNextSibling) = 0; /** * Used to insert a child after the specified sibling. In general, * child insertion will happen through the view manager and it * will determine the ordering of children in the child list. * @param child to insert in this view's child list * @param sibling view to set as previous sibling of child * if nsnull, then child is inserted at head of list */ NS_IMETHOD InsertChild(nsIView *aChild, nsIView *aSibling) = 0; /** * Remove a child from the child list. The removal will be driven * through the view manager. * @param child to remove */ NS_IMETHOD RemoveChild(nsIView *aChild) = 0; /** * Get the number of children for this view. * @result child count */ NS_IMETHOD GetChildCount(PRInt32 &aCount) const = 0; /** * Get a child at a specific index. Could be replaced by some sort of * enumeration API. * @param index of desired child view * @result the view at index or nsnull if there is no such child */ NS_IMETHOD GetChild(PRInt32 index, nsIView*& aChild) const = 0; /** * Note: This didn't exist in 4.0. Called to set the opacity of a view. * A value of 0.0 means completely transparent. A value of 1.0 means * completely opaque. * @param opacity new opacity value */ NS_IMETHOD SetOpacity(float aOpacity) = 0; /** * Note: This didn't exist in 4.0. Called to set the opacity of a view. * A value of 0.0 means completely transparent. A value of 1.0 means * completely opaque. * @result view's opacity value */ NS_IMETHOD GetOpacity(float &aOpacity) const = 0; /** * Used to ask a view if it has any areas within its bounding box * that are transparent. This is not the same as opacity - opacity can * be set externally, transparency is a quality of the view itself. * @result Returns PR_TRUE if there are transparent areas, PR_FALSE otherwise. */ NS_IMETHOD HasTransparency(PRBool &aTransparent) const = 0; /** * Used set the transparency status of the content in a view. see * HasTransparency(). * @param aTransparent PR_TRUE if there are transparent areas, PR_FALSE otherwise. */ NS_IMETHOD SetContentTransparency(PRBool aTransparent) = 0; /** * Set the view's link to client owned data. * @param aData - data to associate with view. nsnull to disassociate */ NS_IMETHOD SetClientData(void *aData) = 0; /** * Query the view for it's link to client owned data. * @result data associated with view or nsnull if there is none. */ NS_IMETHOD GetClientData(void *&aData) const = 0; /** * Get the nearest widget in this view or a parent of this view and * the offset from the view that contains the widget to this view * @param aDx out parameter for x offset * @param aDy out parameter for y offset * @return widget (if there is one) closest to view */ NS_IMETHOD GetOffsetFromWidget(nscoord *aDx, nscoord *aDy, nsIWidget *&aWidget) = 0; /** * Gets the dirty region associated with this view. Used by the view * manager. */ NS_IMETHOD GetDirtyRegion(nsIRegion *&aRegion) const = 0; /** * Create a widget to associate with this view. This is a helper * function for SetWidget. * @param aWindowIID IID for Widget type that this view * should have associated with it. if nsull, then no * width will be created for this view * @param aWidgetInitData data used to initialize this view's widget before * its create is called. * @param aNative native window that will be used as parent of * aWindowIID. if nsnull, then parent will be derived from * parent view and it's ancestors * @return error status */ NS_IMETHOD CreateWidget(const nsIID &aWindowIID, nsWidgetInitData *aWidgetInitData = nsnull, nsNativeWidget aNative = nsnull, PRBool aEnableDragDrop = PR_TRUE) = 0; /** * Set the widget associated with this view. * @param aWidget widget to associate with view. It is an error * to associate a widget with more than one view. To disassociate * a widget from a view, use nsnull. If there are no more references * to the widget that may have been associated with the view, it will * be destroyed. * @return error status */ NS_IMETHOD SetWidget(nsIWidget *aWidget) = 0; /** * In 4.0, the "cutout" nature of a view is queryable. * If we believe that all cutout view have a native widget, this * could be a replacement. * @param aWidget out parameter for widget that this view contains, * or nsnull if there is none. */ NS_IMETHOD GetWidget(nsIWidget *&aWidget) const = 0; /** * Returns PR_TRUE if the view has a widget associated with it. * @param aHasWidget out parameter that indicates whether a view has a widget. */ NS_IMETHOD HasWidget(PRBool *aHasWidget) const = 0; /** * Output debug info to FILE * @param out output file handle * @param aIndent indentation depth */ NS_IMETHOD List(FILE* out = stdout, PRInt32 aIndent = 0) const = 0; /** * Set flags on view to allow customization of view behavior during * event handling * @param aFlags flags to be added to view */ NS_IMETHOD SetViewFlags(PRUint32 aFlags) = 0; /** * Remove flags from view to allow customization of view behavior during * event handling * @param aFlags flags to be removed from view */ NS_IMETHOD ClearViewFlags(PRUint32 aFlags) = 0; /** * Get flags on view to allow customization of view behavior during * event handling * @param aFlags out parameter for view flags */ NS_IMETHOD GetViewFlags(PRUint32 *aFlags) const = 0; /** * Used by the compositor for temporary marking of a view during * compositing. This will eventually replace GetScratchPoint above. */ NS_IMETHOD SetCompositorFlags(PRUint32 aFlags) = 0; NS_IMETHOD GetCompositorFlags(PRUint32 *aFlags) = 0; /** * Get the extents of the view tree from 'this' down. * 'this' is the coordinate system origin. * @param aExtents out paramemter for extents * @return error status */ NS_IMETHOD GetExtents(nsRect *aExtents) = 0; // XXX Temporary for Bug #19416 NS_IMETHOD IgnoreSetPosition(PRBool aShouldIgnore) = 0; /** * Sync your widget size and position with the view */ NS_IMETHOD SynchWidgetSizePosition() = 0; /** * Return a rectangle containing the view's bounds adjusted for it's ancestors clipping * @param aClippedRect views bounds adjusted for ancestors clipping. If aEmpty is TRUE it * aClippedRect is set to an empty rect. * @param aIsClipped returns with PR_TRUE if view's rectangle is clipped by an ancestor * @param aEmpty returns with PR_TRUE if view's rectangle is 'clipped out' */ NS_IMETHOD GetClippedRect(nsRect& aClippedRect, PRBool& aIsClipped, PRBool& aEmpty) const = 0; private: NS_IMETHOD_(nsrefcnt) AddRef(void) = 0; NS_IMETHOD_(nsrefcnt) Release(void) = 0; }; //this is passed down to child views during painting and event handling //so that a child can determine if it is hidden or shown when it's //visibility state is set to inherit #define NS_VIEW_FLAG_PARENT_HIDDEN 0x0001 //when painting, if we have determined that we need to do a combination //of front to back and back to front painting, this flag will be set //while in the back to front pass #define NS_VIEW_FLAG_BACK_TO_FRONT 0x0002 //during event propagation, see if parent views can handle the event #define NS_VIEW_FLAG_CHECK_PARENT 0x0004 //during event propagation, see if child views can handle the event #define NS_VIEW_FLAG_CHECK_CHILDREN 0x0008 //during event propagation, see if sibling views can handle the event #define NS_VIEW_FLAG_CHECK_SIBLINGS 0x0010 //passed down through the class hierarchy //to indicate that the clip is set by an //outer class #define NS_VIEW_FLAG_CLIP_SET 0x0020 //when painting, if we have determined that we need to do a combination //of front to back and back to front painting, this flag will be set //while in the front to back pass #define NS_VIEW_FLAG_FRONT_TO_BACK 0x0040 //temporary hack so that michael can work on the new //compositor and make checkins without busting the rest //of the world. #define NS_VIEW_FLAG_JUST_PAINT 0x0080 //the following are public flags accessed through the *ViewFlags methods. //Flag to determine whether the view will check if events can be handled //by its children or just handle the events itself #define NS_VIEW_PUBLIC_FLAG_DONT_CHECK_CHILDREN 0x0001 //the view is dying. #define NS_VIEW_PUBLIC_FLAG_DYING 0x0002 //the view is transparent #define NS_VIEW_PUBLIC_FLAG_TRANSPARENT 0x0004 //indicates that a view should not zoom values to/from widgets #define NS_VIEW_PUBLIC_FLAG_DONT_ZOOM 0x0008 //indicates that the view should not be bitblt'd when moved //or scrolled and instead must be repainted #define NS_VIEW_PUBLIC_FLAG_DONT_BITBLT 0x0010 // indicates that the view is using auto z-indexing #define NS_VIEW_PUBLIC_FLAG_AUTO_ZINDEX 0x0020 // indicatest hat the view is a floating view. #define NS_VIEW_PUBLIC_FLAG_FLOATING 0x0040 // set if our widget resized. #define NS_VIEW_PUBLIC_FLAG_WIDGET_RESIZED 0x0080 // set if our widget moved. #define NS_VIEW_PUBLIC_FLAG_WIDGET_MOVED 0x0100 // indicates that the view should clip its child views using ClipRect specified // by SetClip #define NS_VIEW_PUBLIC_FLAG_CLIPCHILDREN 0x0200 #endif