Class: TView

Declaration: View.h

Taxonomy Categories:

Member Functions:


Interface Category:

API.

Inherits From:

MGraphic, MEventTarget, MDelegatingNotifier, TViewCore

Inherited By:

TLayoutView TSimpleView TActivatibleView TActivationManagerView TPopUpMenu TSpinControllerView TBooleanControlGroup TDropDownTextControl TGraphicView TSpinField

Purpose:

An abstract base class that allows clients to allocate and draw into an amount of screen real estate. TViews are composed and used in a hierarchy: each TView has at most one parent view and can have multiple child views. TViews also provide mechanisms to transform their shape (allocated area) and location within their parent's coordinate system in interesting ways, and to draw and repair damage to drawn images.

Instantiation:

Always allocate on the heap.

Deriving Classes:

GetBounds is a pure virtual function and must be defined in derived classes. Classes deriving from TView should override DrawContents to draw the view. Other functions that can be and often are overridden in classes deriving from TView are: RefreshContents, if refresh appearance is different from the DrawContents appearance; HandleAfterConnectionToViewRoot and HandleBeforeDisconnectionFromViewRoot, to determine when the view is part of a rooted view hierarchy; DistributePositionalEvent, to intercept positional event distribution; and GetOpaquelyDrawnArea, to indicate to the system that the view does not fill its entire allocated area opaquely, which can be used for views that are partially or fully transparent or translucent.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TView::TView

  1. TView ()
  2. TView (const TGPoint & itsSizeInLocalCoords, const TGPoint & itsLocationInContainerCoords =TGPoint :: kOrigin, bool visible =true)
  3. TView (const TGArea & viewArea, const TGPoint & itsLocationInContainerCoords =TGPoint :: kOrigin, bool visible =true)

Interface Category:

API.

Purpose:

  1. Default constructor. Can be called by developer code to create a view with no initial allocated area.
  2. Constructs a view with the specified size (width and height), at the specified location relative to its parent's coordinate system, and with the specified semantic visibility.
  3. Constructs a view with the specified area, at the specified location relative to its parent's coordinate system, and with the specified semantic visibility.

Calling Context:

  1. Called by the stream-in operators and by clients when the view shape is not known at creation time.
  2. Called by clients to create a simple rectilinear view.
  3. Called by clients to create a view with a more interesting shape, as defined by the area parameter.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Views will not draw until they are connected into a rooted view hierarchy.

Member Function: TView::~TView

virtual ~ TView ()

Interface Category:

API.

Purpose:

Destructor. Deletes the view, any children of the view, and all other related storage, such as attributes which have been added to the view.

Calling Context:

Called to destroy a view. Called either by clients or by the View system.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::operator>>=

virtual TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator. Streams out all child views automatically.

Calling Context:

Called to stream out data. Called by clients or by the View system.

Parameters:

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator. Streams in all child views automatically.

Calling Context:

Called to stream in data. Called by clients or by the View system.

Parameters:

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws a TInvalidVersionError exception if the version of the view's streamed out data is different (and incompatible) with the versions that are known to the the streaming in view.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::Draw

virtual void Draw (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws a still image of this view to the specified port. The word still is used to distinguish this kind of drawing from the appearance a view might have when animated. Think of this function as drawing the view as it would appear if printed. Draw first performs some initialization and then calls the DrawContents member function (which you can override) for this view and all of its children. Drawing is a synchronous operation; for example, if the children lie in a thread other than their parent's, the parent's Draw function waits until the child thread is doing nothing, calls the child's DrawContents function, and then allows the child to continue its asynchronous execution.

Calling Context:

Called to draw a still image of this view, given a port. Called by clients.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::GetGrafPort

virtual TGrafPort * GetGrafPort () const

Interface Category:

API.

Purpose:

Retrieves the default graf port associated with this view. The default graf port is the port associated with the display device. Conceptually, it is the one on which the view repairs damage. The first time it is called, this function creates a special graf port that can be used to draw asynchronously to the view. This is a relatively expensive operation in its memory usage. Subsequent calls to the same view return the same pointer as the first one; thus, there is no additional memory overhead. It is valid to draw into the port that is returned as long as the view or any of its ancestors are not orphaned. The view can change its shape, its location, its place in the front to back ordering of its siblings, or any other changes in the view hierarchy can occur and the port will still be correct to draw into.

Calling Context:

Called by clients to get the TGrafPort instance associated with this view that can be used for direct drawing (as opposed to drawing via invalidation where DrawContents gets called by the system to repair damage on the screen).

Parameters:

Return Value:

Returns the TGrafPort for this view, or NIL if this view isn't part of a rooted view hierarchy.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

To get a useful TGrafPort object, call this member function after the view has been connected to a rooted view hierarchy. The TGrafPort becomes invalid should the view (or one of its hierarchy parents) become disconnected from the view root. The returned TGrafPort is only useful for the view from which it came.

Member Function: TView::GetEventReceiver

virtual TStandardEventReceiver * GetEventReceiver () const

Interface Category:

API.

Purpose:

Allows developers to retrieve the event receiver that's associated with this view. This is most often used when a view wishes to register for keyboard events, as the registration is through the event receiver. Be sure to call this function after the view is connected to a rooted view hierarchy, otherwise the event receiver that's returned will be NIL.

Calling Context:

Called by clients to get the event receiver instance associated with this view hierarchy.

Parameters:

Return Value:

The event receiver associated with this view, or NIL if the view isn't part of a rooted view hierarchy.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::GetBounds

virtual void GetBounds (TGArea & area) const

Interface Category:

API.

Purpose:

Returns the bounds of this view. This is a pure virtual member function and must be defined in classes deriving from TView. The bounds returned by this member function are entirely up to the semantics of the class deriving from TView. The bounds of the view represent how large the view thinks it is, which is separate from how much area its parent has allocated for it. Also, the bounds remains the same size (typically) when the allocated area for the view is scaled or rotated.

Calling Context:

Called by clients and by the View system to determine how large this view thinks it is.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::GetGeometricBounds

virtual TGRect GetGeometricBounds () const

Interface Category:

API.

Purpose:

Overrides MGraphic's GetGeometricBounds function and determines the bounds of this view based strictly on its area.

Calling Context:

Called by clients and by the View system to determine the bounds of this view based strictly on its area.

Parameters:

Return Value:

Returns the bounding box of this view, in parent relative coordinates.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function might become obsolete in the future.

Member Function: TView::GetLooseFitBounds

virtual TGRect GetLooseFitBounds (const TGrafPort * =NIL) const

Interface Category:

API.

Purpose:

Overrides MGraphic's GetLooseFitBounds function and determines the bounds of this view based strictly on its area.

Calling Context:

Called by clients and by the View system to determine the bounds of this view based strictly on its area.

Parameters:

Return Value:

Returns the bounding box of this view, in parent relative coordinates.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function might become obsolete in the future.

Member Function: TView::GetAllocatedArea

  1. virtual void GetAllocatedArea (TGArea &) const
  2. virtual TGRect GetAllocatedArea () const

Interface Category:

API.

Purpose:

  1. Returns the view relative area that's allocated for this view.
  2. Convenience function that returns the bounding box of this view's allocated area, in view relative coordinates.

Calling Context:

  1. Called by clients and by the View system to determine the view relative allocated area for this view.
  2. Called by clients and by the View system to determine the bounding box for this view's allocated area.

Parameters:

Return Value:

  1. Returns the allocated area of this view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::GetAllocatedAreaInParent

  1. virtual void GetAllocatedAreaInParent (TGArea &) const
  2. virtual TGRect GetAllocatedAreaInParent () const

Interface Category:

API.

Purpose:

  1. Retrieves the allocated area for this view in its parent's coordinate system.
  2. Retrieves the bounding box of the allocated area for this view in its parent's coordinate system.

Calling Context:

  1. Called by clients and by the View system to determine the allocated area of this view in its parent's coordinate system.
  2. Called by clients and by the View system to determine the bounding box of the allocated area of this view in its parent's coordinate system.

Parameters:

Return Value:

  1. Returns the allocated area of this view in its parent's coordinate system.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This interface might be obsoleted in the future.

Member Function: TView::SetAllocatedArea

  1. virtual void SetAllocatedArea (const TGArea &)
  2. virtual void SetAllocatedArea (const TGRect &)

Interface Category:

API.

Purpose:

  1. Sets the area that's allocated to this view to the specified area. The area is in view relative coordinates.
  2. Sets the area that's allocated to this view to the specified rectangle. The rectangle is in view relative coordinates.

Calling Context:

  1. Called by clients to set the shape (allocated area) of this view. Can be called at any time once the view has been constructed.
  2. Called by clients to set the shape (allocated area) of this view. Can be called at any time once the view has been constructed.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Both forms of this function call the HandleSetAllocatedArea(const TGArea& area) function on the view. You can override this function in derived classes to have it take some action when the view changes shape. HandleSetAllocatedArea calls the HandleChildAreaChanged(const TView& child) function in the view's parent (if the view has one), which the parent view can override and use to notice when one of its children changes shape. The second form of this interface might become obsolete in the future. These operations cause the view to become damaged and refreshed if the view is visible and connected to a view hierarchy. This is a convenient function for TView derived classes to override if they want to take some special action when the view's allocated area changes, such as when child views are resized to fit within the new area.

Member Function: TView::SetAllocatedAreaInParent

virtual void SetAllocatedAreaInParent (const TGArea &)

Interface Category:

API.

Purpose:

Sets the area that is allocated to this view to the specified area. The area is in the view's parent's coordinate system. This function is a more efficient way to get the net effect of using SetAllocatedArea followed by a TranslateAllocatedAreaInParentTo. To use this function, compute the area where you want the view to appear in the parent's coordinate system, and pass that area to this function.

Calling Context:

Called by clients to set the shape (allocated area) of this view. Can be called at any time once the view has been constructed.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function calls the HandleSetAllocatedArea(const TGArea& area) function on the view. You can override HandleSetAllocatedArea in derived classes to take some action when the view changes shape. It calls the HandleChildAreaChanged(const TView& child) function in the view's parent (if the view has one), which the parent view can override and use to notice when one of its children changes shape. The area that is passed in to HandleSetAllocatedArea is in view relative coordinates. This function also calls the HandleSetTransform function on the view, and the HandleChildTransformChanged function on the view's parent (if there is one), and the view or its parent can override these functions to take some special action when the view's transformation changes.

Member Function: TView::TransformAllocatedAreaInParentBy

virtual void TransformAllocatedAreaInParentBy (const TGrafMatrix &)

Interface Category:

API.

Purpose:

Concatenates the given TGrafMatrix instance onto the existing transformation for this view. If the view is visible on the screen, this function causes the view and any newly exposed areas to be repaired (refreshed).

Calling Context:

Called by clients and by the View system to adjust the transformation of this view relative to its parent.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function calls the HandleSetTransform(const TGrafMatrix&) function on the view and the HandleChildTransformChanged(const TView& child) function on the view's parent (if there is one). The view or its parent can override these functions to take some special action when the view's transformation changes.

Member Function: TView::TranslateAllocatedAreaInParentBy

virtual void TranslateAllocatedAreaInParentBy (const TGPoint &)

Interface Category:

API.

Purpose:

Translates the allocated area for this view by the specified amount. The view appears to move relative to its parent. If the view is visible on the screen, this function causes the view and any newly exposed areas to be repaired.

Calling Context:

Called by clients to translate (move) this view's position in its parent's coordinate system.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function calls the HandleSetTransform(const TGrafMatrix&) function on the view and the HandleChildTransformChanged(const TView& child) function on the view's parent (if there is one). The view or its parent can override these functions to take some special action when the view's transformation changes.

Member Function: TView::TranslateAllocatedAreaInParentTo

virtual void TranslateAllocatedAreaInParentTo (const TGPoint &)

Interface Category:

API.

Purpose:

Translates (moves) this view to a particular place in its parent's coordinate system. If the view was visible, this function causes damage repair for newly exposed areas of the view and portions of the screen occluded by the view. The translation is relative to the upper-left corner of the bounding box of the view's allocated area in the view's parent's coordinate system.

Calling Context:

Called by clients to move this view to a particular place.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function calls the HandleSetTransform(const TGrafMatrix&) function on the view and the HandleChildTransformChanged(const TView& child) function on the view's parent (if there is one). The view or its parent can override these functions to take some special action when the view's transformation changes.

Member Function: TView::ScaleAllocatedAreaInParentBy

virtual void ScaleAllocatedAreaInParentBy (const TGPoint &, const TGPoint & centerOfScaling =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Scales the allocated area of this view. The view's internal coordinate system and bounds are unaffected. If the view was visible, this function causes the view and the newly exposed areas to be refreshed. The view appears to shrink or expand proportionately.

Calling Context:

Called by clients to change the scaling of this view.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function calls the HandleSetTransform(const TGrafMatrix&) function on the view and the HandleChildTransformChanged(const TView& child) function on the view's parent (if there is one). The view or its parent can override these functions to take some special action when the view's transformation changes.

Member Function: TView::RotateAllocatedAreaInParentBy

virtual void RotateAllocatedAreaInParentBy (GDegrees clockwise, const TGPoint & centerOfRotation =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Rotates this view's allocated area. The view is repaired (refreshed) if it was visible, and any newly exposed areas are also repaired. The view appears to rotate relative to the centerOfRotation point.

Calling Context:

Called by clients to change the orientation of the view.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function calls the HandleSetTransform(const TGrafMatrix&) function on the view and the HandleChildTransformChanged(const TView& child) function on the view's parent (if there is one). The view or its parent can override these functions to take some special action when the view's transformation changes.

Member Function: TView::TransformBy

virtual void TransformBy (const TGrafMatrix &)

Interface Category:

API.

Purpose:

Provides a reasonable definition of the inherited pure virtual function from MGraphic. Clients can override this to provide more interesting definitions of the internal transforms of a view. Default implementation just invokes TView::TransformAllocatedAreaInParentBy.

Calling Context:

Called from MGraphic internally and possibly client code, although that usage is discouraged.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This interface is likely to change in the future, and should not typically be used by client code.

Member Function: TView::GetVisibility

virtual bool GetVisibility () const

Interface Category:

API.

Purpose:

Returns the semantic visibility of this view. This value only indicates whether this view would be visible if it was not completely occluded by siblings and if all of its parent views are also semantically visible.

Calling Context:

Called by clients and by the View system to determine if this view is visible.

Parameters:

Return Value:

Returns true if this view is not marked as semantically invisible.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Might change or become obsolete in the future.

Member Function: TView::SetVisibility

virtual void SetVisibility (bool visible =true)

Interface Category:

API.

Purpose:

Changes the semantic visibility of this view. If the view becomes visible, it is repaired (refreshed). If the view becomes invisible, its previously visible area is refreshed to make the newly exposed areas appear on the display. The visibility affects the view and all of its children. Thus, if the view is marked as invisible, it and all of its children disappear. (However, marking the view visible does not make semantically invisible children visible.)

Calling Context:

Called by clients to change the semantic visibility of this view.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Calls HandleSetVisibility(bool visibility) on the view and HandleChildVisibilityChanged(const TView& child) on the view's parent, if there is a parent. Developers can override these functions in derived classes to notice when a view's visibility changes and take some appropriate action.

Member Function: TView::BringToFront

virtual void BringToFront ()

Interface Category:

API.

Purpose:

Brings this view to the front of all of its sibling views.

Calling Context:

Called by clients to make this view be on top of all of its siblings.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If the view has a parent view, HandleChildOrderChanged(const TView& child) is called on the parent view. Developers can override this function to take some special action when there is a change to the front-to-back order of the parent's children.

Member Function: TView::SendToBack

virtual void SendToBack ()

Interface Category:

API.

Purpose:

Sends this view to the bottom of all of its sibling views.

Calling Context:

Called by clients to move this view to the bottom of all of its siblings.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If the view has a parent view, HandleChildOrderChanged(const TView& child) is called on the parent view. Developers can override this function to take some special action when the front-to-back order of the parent's children changes.

Member Function: TView::MoveBehind

virtual void MoveBehind (const TView & sibling)

Interface Category:

API.

Purpose:

Moves this view behind (below) the specified view. sibling should be a view that has the same parent as this view.

Calling Context:

Called by clients to position this view behind another view in the sibling stacking order.

Parameters:

Return Value:

None.

Exceptions:

Throws TViewException of type kInvalidChild if the child passed in as the parameter is not a child of the same parent.

Concurrency:

Not multithread safe.

Other Considerations:

If the view has a parent view, HandleChildOrderChanged(const TView& child) is called on the parent view. Developers can override this function to take some special action when the front-to-back order of the parent's children changes.

Member Function: TView::LocalToGlobal

  1. void LocalToGlobal (TGPoint & pointToTransform) const
  2. void LocalToGlobal (TGArea & areaToTransform) const

Interface Category:

API.

Purpose:

  1. Transforms a point from this view's local coordinates to global coordinates.
  2. Transforms an area from this view's local coordinates to global coordinates.

Calling Context:

  1. Called by clients and the View system to map points from local to global coordinates.
  2. Called by clients and the View system to map areas from local to global coordinates.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::GlobalToLocal

  1. void GlobalToLocal (TGPoint & pointToTransform) const
  2. void GlobalToLocal (TGArea & areaToTransform) const

Interface Category:

API.

Purpose:

  1. Transforms a point from global coordinates to view relative coordinates.
  2. Transforms an area from global coordinates to view relative coordinates.

Calling Context:

  1. Called by clients and the View system to map global points to view relative points.
  2. Called by clients and the View system to map global areas to view relative areas.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::LocalToParent

  1. void LocalToParent (TGPoint & pointToTransform) const
  2. void LocalToParent (TGArea & areaToTransform) const

Interface Category:

API.

Purpose:

  1. Transforms a point in view relative coordinates to this view's parent's coordinate system.
  2. Transforms an area in view relative coordinates to this view's parent's coordinate system.

Calling Context:

  1. Called by clients and the View system to transform a point from this view's to this view's parent's coordinate system.
  2. Called by clients and the View system to transform an area from this view's to this view's parent's coordinate system.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::ParentToLocal

  1. void ParentToLocal (TGPoint & pointToTransform) const
  2. void ParentToLocal (TGArea & areaToTransform) const

Interface Category:

API.

Purpose:

  1. Transforms a point in this view's parent's coordinates to this view's coordinates.
  2. Transforms an area in this view's parent's coordinates to this view's coordinates.

Calling Context:

  1. Called by clients and the View system to transform points from the view's parent's coordinate system to the view's coordinate system.
  2. Called by clients and the View system to transform areas from the view's parent's coordinate system to the view's coordinate system.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::AdoptChild

virtual void AdoptChild (TView * child)

Interface Category:

API.

Purpose:

Adopts the specified view as a child of this view. The child is adopted as the top-most sibling in the sibling stacking order. If the adopted view is semantically visible, and the adopting view is visible on screen, the adopted view is drawn via the damage repair mechanism. If you retain a pointer to the adopted child, you must be careful how and when you use it. Because the semantics of this operation are adoption, deleting the adopting view or one of its ancestors also destroys the adopted child.

Calling Context:

Called by clients to add a view as a child of this view (to build a view hierarchy).

Parameters:

Return Value:

None.

Exceptions:

Throws TViewChildException of type kChildAlreadyOwned if the child being adopted is already owned by some other view. It can also throw TViewAdoptionRefusedException in derived classes where the derived class has extra constraints on the set of children it will hold (such as a fixed number of children). The view derived class view's override of AdoptChild enforces its policy on its child views; the View system, by default, has no such policy on TView or TSimpleView. The view root does have a policy of only one child in the view root, and it throws the TViewAdoptionRefusedException if there already is a child present.

Concurrency:

Not multithread safe.

Other Considerations:

This function calls HandleAfterConnectionToViewRoot on the child and all of its children if the view was adopted into a rooted view hierarchy. This function then calls HandleAfterAdoption on the adopted child. It calls HandleNumberOfChildrenChanged on the adopting parent.

Member Function: TView::OrphanChild

virtual TView * OrphanChild (TView & child)

Interface Category:

API.

Purpose:

Removes a view from its parent (this view). If the child was visible on screen, the child is removed, and the area that the child covered is repaired (refreshed) by the damage repair mechanism. The child view must really be a child of this view.

Calling Context:

Called by clients and by the View system to remove a view from a view hierarchy.

Parameters:

Return Value:

Returns the child that was orphaned. The client is responsible for destroying the orphaned view.

Exceptions:

Throws TViewException of type kInvalidChild if the child parameter is not really a child of the view.

Concurrency:

Not multithread safe.

Other Considerations:

This function calls HandleBeforeOrphaning on the child. Developers with derived classes can override this function to take appropriate action before the view is orphaned. The function then calls HandleBeforeDisconnectionFromViewRoot on the child and all of its children if the view was connected, directly or indirectly, to a view root at the time the child was orphaned, but before the orphaning actually takes place.

Member Function: TView::DrawContents

virtual void DrawContents (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws the contents of this view. As TView is an abstract base class, this function really just provides the place for developers to define how derived classes draw their contents. Developers will almost always want to provide an implementation of this function in their classes that derive from TView.

Calling Context:

Called by the View system to draw the contents of this view. Recursion on child views is handled by the View system; this operation should only draw the contents of the view itself.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The port is clipped to the bounds of the view if the view's NeedsClipping function returns true. See the description of RefreshContents for a description of how to obtain the clipping area and printing flag if you need to optimize your drawing or to draw differently if printing.

Member Function: TView::RefreshContents

virtual void RefreshContents (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws the contents of this view during damage repair. As TView is an abstract base class, this function really just provides a place for developers to control the drawing during damage repair. Default implementation just calls DrawContents, so most developers will not need to override this member function in derived classes. Certain classes might want to improve performance by only drawing those portions of the view's contents that have actually received damage. Other views might need to draw themselves differently when being rendered for printing than when being rendered for the screen. (For example, the views might want to not draw the selection highlight when printing.) There are a couple of classes that can be used to obtain the necessary information. TLocalClipAreaSnapshot, which is defined in LocalClipAreaSnapshot.h, is instantiated by passing a reference to a TGrafPort to its constructor. Once you have created the instance of the TLocalClipAreaSnapshot, you obtain the current clip area from it using the GetClipArea function, which returns a TGArea as its return value. TLocalClipAreaSnapshot transforms the area into view coordinates, so you don't have to call GlobalToLocal on it. The area that is returned accurately reflects the clip area at the instant it is returned, but it should never be relied upon as being completely accurate. Normally, you would use it as a hint to help you limit your drawing, but it does not guarantee the exact clip area. Typically, you will want to obtain this value once in your function body, and cache the resulting value, as it can be somewhat expensive to obtain over and over. TPrintingFlagSnapshot, defined in PrintingFlagSnapshot.h, is also instantiated by passing in a reference to a TGrafPort to its constructor. It defines a function called IsPrintingPort, which takes no arguments and returns a Boolean result that indicates whether the port is a printing port or not. Like TLocalClipAreaSnapshot, you will typically cache the returned value for the duration of your RefreshContents or DrawContents function as it can be somewhat expensive to obtain this value repeatedly. Because both classes take a graf port reference (instead of a pointer) in their constructors, you can be sure that they don't hold onto the port, meaning that they make a copy of the pertinent data.

Calling Context:

Called by the View system during damage repair. The port is set up as in DrawContents. However, it is also clipped to the area to be repaired if the view's NeedsClipping function returned true. Developers can use this fact to optimize their drawing if they so choose.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If you have a real need to get other information from the TGrafState that is associated with the TGrafPort parameter, you must use code like the following. You must limit the scope of the TGrafState accessor to the minimal range possible. Failure to do this will cause deadlock! The proper idiom is: // declare some variable outside to hold the value { TGrafStateAccessor grafState(&port); // only get whatever data you need out } You must put the TGrafStateAccessor inside its own block, and you must do the minimal work to get the information you need and get out of the block. For example, if the TLocalClipAreaSnapshot class did not exist you could do the following ( This is only an example! Do not use this in_ real_ code! Use the TLocalClipAreaSnapshot instead!): TGArea clipArea; { TGrafStateAccessor grafState( &port ); clipArea =*grafState.GetClipState()->GetClipArea(); } // Use the clip area outside of the block. These two accessor classes should cover all the needs that most developers will have for getting information from the TGrafPort parameter.

Member Function: TView::Invalidate

  1. virtual void Invalidate ()
  2. virtual void Invalidate (const TGArea & invalidArea)

Interface Category:

API.

Purpose:

  1. Invalidates (marks as damaged and in need of repair) this entire view.
  2. Invalidates (marks as damaged and in need of repair) an area of this view. The area is interpreted relative to the view's coordinate system.

Calling Context:

  1. Called by clients and the View system to invalidate this entire view.
  2. Called by clients and the View system to invalidate a portion of this view.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The View system can make certain internal optimizations once you have called the first form of this function on a view. When you want to invalidate the whole view, it is best to call the Invalidate function as soon as you possibly can; this allows the View system to skip computing and generating damage for subsequent operations to the view and all of its descendants. It is much preferable to use a single call to the Invalidate function first before making a large number of changes, as opposed to marking the view invisible, doing the changes, and marking it visible again.

Member Function: TView::Validate

  1. virtual void Validate ()
  2. virtual void Validate (const TGArea & validArea)

Interface Category:

API.

Purpose:

  1. Validates this entire view. Clients can call this when they have repaired damage themselves, or guaranteed that the view's appearance is up to date.
  2. Validates a particular area of this view. The area is view relative.

Calling Context:

  1. Called by clients or the View system to indicate that this view is no longer damaged.
  2. Called by clients or the View system to indicate that a portion of this view is no longer damaged.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::DistributePositionalEvent

virtual bool DistributePositionalEvent (TEvent & theEvent, const TGPoint & local)

Interface Category:

API.

Purpose:

Distributes positional events to the top-most child of this view that contains the specified point. If the view has no children, or if no child contained the point, this function invokes DispatchEvent to invoke the event handler. The return value is true if the event was handled by some child view, or if the view itself handled the event (for example, DispatchEvent returned true). If some of the children of the view contained the point, but all of their DistributePositionalEvent functions returned false, the view's DispatchEvent function is called to let the view try to handle the event. When DispatchEvent is called it typically results in a call to the view's MouseDown, MouseUp, or MouseMoved function. The value returned from these functions is the value the DispatchEvent function returns. This value indicates whether the view handled the event or not. Clients can override this function if they want to circumvent the event distribution process, or if they want to get a shot at handling the event if no child wanted to handle it. In this latter case, the overriding function should call the base DistributePositionalEvent. If DistributePositionalEvent returns false, they should check the point to see if it is in a place that the view would like to handle. If so, call DispatchEvent and return whatever value DispatchEvent returns.

Calling Context:

Called by the View system to direct positional events to the correct view.

Parameters:

Return Value:

Returns true if the event was handled by this view or one of its children.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::InvalidateAll

  1. virtual void InvalidateAll ()
  2. virtual void InvalidateAll (const TGArea & invalidArea)

Interface Category:

API.

Purpose:

  1. Invalidates (marks as damaged and in need of repair) this entire view and all of its children.
  2. Invalidates (marks as damaged and in need of repair) an area of this view. The area is interpreted relative to the view's coordinate system. The area of damage includes both the view and all of its children.

Calling Context:

  1. Called by clients to indicate that this view and its children are invalid and need repairing.
  2. Called by clients to indicate that an area of this view and its children are invalid and need repairing.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This interface might become obsolete in the future. It currently does nothing different from the corresponding Invalidate functions.

Member Function: TView::HandleChildOrderChanged

virtual void HandleChildOrderChanged (TView & child)

Interface Category:

API.

Purpose:

Called by the View system when there is a change to the front-to-back order of a view's children. By default, it does nothing; derived classes can override to notice when the order of the view's children changes.

Calling Context:

Called by the View system when there is a change in the order of the child view within the parent's hierarchy. Derived classes can override this member function when they want to know when things have changed. The derived function should call the base class version at some point during its execution.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is called outside of the scope of the view hierarchy lock.

Member Function: TView::HandleNumberofChildrenChanged

virtual void HandleNumberofChildrenChanged ()

Interface Category:

API.

Purpose:

Handles updating the view hierarchy when the number of child views changes.

Calling Context:

Called by the View system for a parent view when the number of its child views changes. Derived classes can override this member function when they want to know when things have changed. The derived function should call the base class version at some point during its execution.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is called outside of the scope of the view hierarchy lock.

Member Function: TView::HandleBeforeOrphaning

virtual void HandleBeforeOrphaning ()

Interface Category:

API.

Purpose:

Handles the impending orphaning of a child view.

Calling Context:

Called by the View system when a child view is about to be orphaned. Derived classes can override this member function when they want to know when things have changed. The derived function should call the base class version at some point during its execution.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is called outside of the scope of the view hierarchy lock.

Member Function: TView::HandleAfterAdoption

virtual void HandleAfterAdoption ()

Interface Category:

API.

Purpose:

Handles the adoption of a child view.

Calling Context:

Called by the View system after the child view has been adopted. Derived classes can override this member function when they want to know when things have changed. The derived function should call the base class version at some point during its execution.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is called outside of the scope of the view hierarchy lock.

Member Function: TView::HandleVisibilityChanged

virtual void HandleVisibilityChanged (bool newVisibility)

Interface Category:

API.

Purpose:

Handles a change in visibility condition for a child view.

Calling Context:

Called by the View system when there is a change in the visibility of the child view within the parent's hierarchy. Derived classes can override this member function when they want to know when things have changed. The derived function should call the base class version at some point during its execution.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is called outside of the scope of the view hierarchy lock.

Member Function: TView::HandleTransformChanged

virtual void HandleTransformChanged (const TGrafMatrix & newTransform)

Interface Category:

API.

Purpose:

Handles a change in the transform for a child view.

Calling Context:

Called by the View system when there is a change in the transform for the child view. Derived classes can override this member function when they want to know when things have changed. The derived function should call the base class version at some point during its execution.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is called outside of the scope of the view hierarchy lock.

Member Function: TView::HandleAllocatedAreaChanged

virtual void HandleAllocatedAreaChanged (const TGArea & newArea)

Interface Category:

API.

Purpose:

Handles a change to the allocated area for a child view.

Calling Context:

Called by the View system when there is a change to the allocated area of the child view. Derived classes can override this member function when they want to know when things have changed. The derived function should call the base class version at some point during its execution.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is called outside of the scope of the view hierarchy lock.

Member Function: TView::HandleBeforeDisconnectionFromViewRoot

virtual void HandleBeforeDisconnectionFromViewRoot ()

Interface Category:

API.

Purpose:

Called by the View system when a view is about to be disconnected from a rooted view hierarchy. The disconnection has not yet taken place, so you can take whatever housekeeping actions you need to before the connection to the view root is severed. All views from the point of disconnection on down have this function called on them, with child views being called before parent views.

Calling Context:

Called by the View system before the view is disconnected (directly or indirectly) from the view root.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is useful for anyone using input in views.

Member Function: TView::HandleAfterConnectionToViewRoot

virtual void HandleAfterConnectionToViewRoot ()

Interface Category:

API.

Purpose:

The function is called by the View system after a view is connected to a rooted view hierarchy. The connection has occurred by the time this function is called. As such, you can get things like the request processor, the direct drawing GrafPort, and the event receiver. All views from the point of connection on down have this function called on them, with parent views getting called before child views.

Calling Context:

Called by the View system after the view is connected (directly or indirectly) to the view root.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is useful for anyone using input in views.

Member Function: TView::GetOpaquelyDrawnArea

virtual void GetOpaquelyDrawnArea (TGArea & opaqueArea)

Interface Category:

API.

Purpose:

Indicates how much of the allocated area of the view draws opaquely. As the default, the entire allocated area is expected to be drawn opaquely. If you donÕt want to draw the entire allocated area opaquely, e.g., to leave parts or all of the allocated area transparent or translucent, then use this function in a derived class to override the default GetOpaquelyDrawnArea value. It returns the area that this view draws opaquely. If the opaque area is very complicated (e.g. text) it is recommended to return a smaller, simpler area. The returned area can be empty.

Calling Context:

Called by the View system to determine the area that the view actually draws opaquely, and for optimizing damage generation and repair.

Parameters:

Return Value:

None

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function must be defined by clients who do not completely draw their allocated area opaquely. They use this function to override the default GetOpaquelyDrawnArea value, as it returns the area that they actually draw opaquely. The function returns an empty area if the view draws nothing or draws everything with an opacity factor less than 1.0 (translucently).

Member Function: TView::ContainsPoint

virtual bool ContainsPoint (const TGPoint & localPoint)

Interface Category:

API.

Purpose:

Returns a Boolean value that indicates whether the visible area of the view contains the specified point. The point is expressed in view relative coordinates. If any occluding direct or ancestral sibling view also contains the point, this function returns false because the visible area of the view did not contain the point.

Calling Context:

Called by clients and by the View system.

Parameters:

Return Value:

Returns true if the visible area of the view contains the specified point; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::DoesDrawQuickly

virtual bool DoesDrawQuickly ()

Interface Category:

API.

Purpose:

Called by the View system to enable certain optimizations. Its default implementation returns true. If the view cannot repair its damage in a reasonably short amount of time, and this damage might confuse the users into thinking that nothing is going on or the system is hung, then override this function to return false. As a guideline, if the view cannot repair its damage within two seconds on a low end platform, have this function return false.

Calling Context:

Called by the View system.

Parameters:

Return Value:

Returns true if the view can repair its own exposure damage is less than two seconds. Clients with views that take longer than two seconds should override this function to return false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Quick is subjective. The concrete interpretation of quick is currently less than two seconds on a slow or loaded platform.

Member Function: TView::NeedsClipping

virtual bool NeedsClipping ()

Interface Category:

API.

Purpose:

Checks during the drawing operation whether the view needs to be clipped to fit within its bounds. By default, this returns true to force the View system to check that the view fits its bounds. If your view can guarantee that it and its children will draw within its allocated area, override this function to return false. The View system can use this fact to optimize drawing.

Calling Context:

Called by the View system. Derived classes can override this and set the returned value to false, but they must ensure that the view (or its children) does not draw beyond its bounds.

Parameters:

Return Value:

Returns true if the view clipped to its allocated area during a draw operation; this is the default return value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::HandleChildVisibilityChanged

virtual void HandleChildVisibilityChanged (const TView & child)

Interface Category:

API.

Purpose:

Called by the View system on the view's parent when the view is altered in some way. The child parameter refers to the child view, and it is this view that has changed visibility. Derived classes can override this member function when they want to know when things have changed. The derived function should call the base class version at some point during its execution. This function is called after the action has occurred, and it is called outside of the scope of the View system's view hierarchy lock. As a result, you do not have to be concerned with the other functions that you can and cannot call from this function.

Calling Context:

Called by the View system when there is a change to the visibility of the child view.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is called outside of the scope of the view hierarchy lock.

Member Function: TView::HandleChildTransformChanged

virtual void HandleChildTransformChanged (const TView & child)

Interface Category:

API.

Purpose:

Called by the View system on the view's parent when the view is altered in some way. The child parameter refers to the child view, and it is this view for which the transform has changed. Derived classes can override this member function when they want to know when things have changed. The derived function should call the base class version at some point during its execution. This function is called after the action has occurred, and it is called outside of the scope of the View system's view hierarchy lock. As a result, you do not have to be concerned with the other functions that you can and cannot call from this function.

Calling Context:

Called by the View system when there is a change to the transform of the child view.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is called outside of the scope of the view hierarchy lock.

Member Function: TView::HandleChildAreaChanged

virtual void HandleChildAreaChanged (const TView & child)

Interface Category:

API.

Purpose:

Called by the View system on the view's parent when the view is altered in some way. The child parameter refers to the child view, and it is this view for which the area has changed. Derived classes can override this member function when they want to know when things have changed. The derived function should call the base class version at some point during its execution. This function is called after the action has occurred, and it is called outside of the scope of the View system's view hierarchy lock. As a result, you do not have to be concerned with the other functions that you can and cannot call from this function.

Calling Context:

Called by the View system when there is a change to the area of the child view.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is called outside of the scope of the view hierarchy lock.

Member Function: TView::GetRequestProcessor

virtual TRequestProcessor * GetRequestProcessor () const

Interface Category:

API.

Purpose:

Returns the request processor that's used for this view.

Calling Context:

Called by TView derived classes to get the request queue for this view.

Parameters:

Return Value:

The request queue for the view, and the view's hierarchy. Returns NIL if the view isn't part of a rooted view hierarchy, or if the view root doesn't have a request processor of its own.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TView::SetAllocatedAreaTransformInParent

virtual void SetAllocatedAreaTransformInParent (const TGrafMatrix & transform)

Interface Category:

API.

Purpose:

Utility function to set the transform for this view. May cause view damage to be generated if the view is visible and the new transform is different from the old transform.

Calling Context:

Called by the View system when this view's transformation matrix is changed.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function calls the HandleSetTransform(const TGrafMatrix&) function on the view and the HandleChildTransformChanged(const TView& child) function on the view's parent, if there is one. The view or its parent can override these functions to take some special action when the view's transformation changes.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.