Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
MCollectible
Inherited By:
None.
Purpose:
Represents the root of a hierarchy of views. It maintains state related to the hierarchy as a whole. Because views own their children, and because the view root owns its single child view, deleting the view root frees the entire view hierarchy.
When a view is adopted into the view root and is visible, the view root automatically creates an instance of TSystemWindow that tracks the position, boundary, and visibility of the topmost view.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
None.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
- TViewRoot (TRequestProcessor * queueToAlias)
- TViewRoot (TRequestProcessor * queueToAlias, TViewRootCore * specialCoreToAdopt)
Interface Category:
API.
Purpose:
- Constructor that provides the primary way to create a view root.
- Constructor that is called internally to create a view root. Developers won't use this under normal circumstances.
Calling Context:
- Called to create the view root. The request processor (queue) must be created before the view root can be created.
- Called to create a view root instance with a specialized view root core.
Parameters:
- TRequestProcessor * queueToAlias -The request processor that serves this view root.
- TRequestProcessor * queueToAlias -The request processor that serves this view root.
- TViewRootCore * specialCoreToAdopt -A special version of the view root core to use.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual ~ TViewRoot ()
Interface Category:
API.
Purpose:
Destructor. This function deletes its adopted view (if any) and destroys any associated SystemWindow instances.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TViewRoot::operator<<=
virtual TStream & operator <<= (TStream & fromwhere)
Interface Category:
API.
Purpose:
Stream-in operator.
Calling Context:
Called to stream in data.
Parameters:
- TStream & fromwhere -The stream the object streams itself in from.
Return Value:
Returns a reference to the stream the object streams itself in from.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TViewRoot::operator>>=
virtual TStream & operator >>=(TStream & towhere) const
Interface Category:
API.
Purpose:
Stream-out operator.
Calling Context:
Called to stream out data.
Parameters:
- TStream & towhere -The stream the object streams itself out to.
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: TViewRoot::AdoptChild
- virtual void AdoptChild (TView *)
- virtual void AdoptChild (TView *, TSystemLayerSurrogate& layer)
Interface Category:
API.
Purpose:
- Adopts the specified view as the topmost view in the hierarchy. If there was already a topmost view in the hierarchy, an exception is thrown.
- Adopts the specified view in the specified layer as the topmost view in the hierarchy. If there already was a topmost view in the hierarchy, an exception is thrown.
Calling Context:
- Called from the same thread as the view root.
- Called from the same thread as the view root. The given layer must already exist.
Parameters:
- TView * -The view that is adopted as the topmost view in the hierarchy.
- TView * -The view that is adopted as the topmost view in the hierarchy.
- TSystemLayerSurrogate& layer -The layer in which to put the system window created by the view root that corresponds to the adopted view.
Return Value:
None.
Exceptions:
Throws TViewAdoptionRefusedException if the view root already has a child. It is most likely a programming error when the client tries to adopt an existing adopted child (one that has already been adopted) and this helps catch that bug. Throws TViewException with the type kChildAlreadyOwned if the child that is passed in is already owned by some other view or view root.
Concurrency:
Not multithread safe.
Other Considerations:
See Exceptions for more information.
Member Function: TViewRoot::GetChild
virtual const TView * GetChild () const
Interface Category:
API.
Purpose:
Retrieves the topmost view in the hierarchy.
Calling Context:
Called from the same thread as the view root.
Parameters:
Return Value:
Returns a pointer to the topmost view in the hierarchy, or NIL if there is no top view. Be careful when using the returned view. If the view root is subsequently deleted, this topmost view is also be deleted (unless it has been orphaned), and the pointer that was returned for it will point to a dead object. You can use this view to create a view handle and instead hold onto the handle.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TViewRoot::OrphanChild
virtual TView * OrphanChild ()
Interface Category:
API.
Purpose:
Removes the topmost view from the hierarchy and returns a pointer to it. As a side effect, any system window that was created by the view root is deleted. When this operation completes, the view root has no hierarchy, and no longer refers to the topmost view in any way.
Calling Context:
Called from the same thread as the view root.
Parameters:
Return Value:
Returns the topmost view in the hierarchy, or NIL if there is none.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TViewRoot::SetHierarchyLayer
virtual void SetHierarchyLayer (TSystemLayerSurrogate& layer)
Interface Category:
API.
Purpose:
Changes the layer of the system window that's associated with the topmost view in the hierarchy. This function has no effect if there is no associated system window (for example, the view root does not contain a view hierarchy).
Calling Context:
Called from the same thread as the view root.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TViewRoot::BringToFront
virtual void BringToFront ()
Interface Category:
API.
Purpose:
Brings the system window associated with the view hierarchy to the front of its layer. This function has no effect if there is no associated system window (for example, the view root does not contain a view hierarchy).
Calling Context:
Called from the same thread as the view root.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This interface is subject to change in future versions.
Member Function: TViewRoot::SendToBack
virtual void SendToBack ()
Interface Category:
API.
Purpose:
Sends the system window associated with the view hierarchy to the bottom of its layer. This function has no effect if there is no associated system window (for example, the view root does not contain a view hierarchy).
Calling Context:
Called from the same thread as the view root.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This interface is subject to change in future versions.
Member Function: TViewRoot::MoveBehind
virtual void MoveBehind (const TViewRoot &)
Interface Category:
API.
Purpose:
Moves the system window associated with this view hierarchy behind the system window associated with the specified view hierarchy. This function does nothing if either the current view root or the view root passed in have no child views.
Calling Context:
Called from the view root thread, which should be the same thread as the view root parameter.
Parameters:
- const TViewRoot & -The reference to another view hierarchy to move behind.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This interface is subject to change in future versions.
Member Function: TViewRoot::SetVisibility
virtual void SetVisibility (bool visible)
Interface Category:
API.
Purpose:
Sets the visibility of the entire view hierarchy. This function does not change the visibility status of individual views in the hierarchy (for example, does not force all descendant views to be visible if they were marked as invisible).
Calling Context:
Called from the thread of the view root.
Parameters:
- bool visible -The flag indicating whether or not to make the view hierarchy visible. true makes the entire hierarchy visible; false makes the entire hierarchy invisible.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This interface is subject to change in future versions.
Member Function: TViewRoot::GetRequestProcessor
virtual TRequestProcessor * GetRequestProcessor ()
Interface Category:
API.
Purpose:
Retrieves the request processor from which the view root gets its requests.
Calling Context:
Called from the same thread as the view root.
Parameters:
Return Value:
Returns the request processor that services this view root. Can return NIL if the view root was resurrected and there has been no SetRequestProcessor call for it since it was resurrected.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TViewRoot::GetSystemWindow
TSystemWindow * GetSystemWindow ()
Interface Category:
API.
Purpose:
Returns the system window associated with the view root (for example, the window associated with the topmost view in the view hierarchy). Other interesting information can be derived from the system window, such as the associated port.
Calling Context:
Called from the same thread as the view root.
Parameters:
Return Value:
Returns the system window that is associated with the view hierarchy. It returns NIL if there is no system window associated with the hierarchy. Typically, this occurs when the view root has no child view.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Do not change the system window in any way using the returned pointer.
Member Function: TViewRoot::SetBuffering
void SetBuffering (bool bufferingOn)
Interface Category:
API.
Purpose:
Controls the buffering of view damage repair for the entire view hierarchy. By default, view roots buffer drawing during damage repair so there is no apparent flickering or extra drawing.
Calling Context:
Called from the same thread as the view hierarchy.
Parameters:
- bool bufferingOn -The flag indicating whether or not to buffer damage repair. If the flag is true, view roots do the buffering, which is the default condition. If the flag is false, then buffering of damage repair is turned off. This generally results in drawing that is less smooth.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TViewRoot::ChildAllocatedAreaChanged
virtual void ChildAllocatedAreaChanged (const TGArea & oldGlobal, const TGArea & newGlobal)
Interface Category:
API.
Purpose:
Called indirectly by the child view to tell the view root that the allocated area of the child has changed. This member function is not typically called by developers.
Calling Context:
Called internally by the View system.
Parameters:
- const TGArea & oldGlobal -The old area of the view in global coordinates.
- const TGArea & newGlobal -The new area of the view in global coordinates.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Likely to be removed from future versions of the View system. Do not depend on this function!
Member Function: TViewRoot::GetViewRootCore
virtual TViewRootCore * GetViewRootCore () const
Interface Category:
API.
Purpose:
Returns the view root core associated with the view root. This function is not intended for used by developers.
Calling Context:
Called internally by the View system.
Parameters:
Return Value:
Returns the view root core instance associated with the view hierarchy.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Likely to be removed from future versions of the View system. Do not depend on this function!
Member Function: TViewRoot::SetRefreshClipping
void SetRefreshClipping (bool)
Interface Category:
API.
Purpose:
Controls whether damage repair is clipped to the damage area. By default, when damage is repaired, only the actually damaged areas are redrawn. If you call this function with clippingFlag set to false, each view that contains damage is asked to be redrawn, and they draw themselves in their entirety. Setting the refresh clipping to false is occasionally useful during debugging and performance analysis to understand how much drawing is actually being performed.
Calling Context:
Called by developer code to change the status of clipping damage repair to the damaged area.
Parameters:
- bool - The Boolean flag that indicates whether or not to clip the areas that are drawn during damage repair to the actual area of damage.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TViewRoot::SetRequestProcessor
virtual void SetRequestProcessor (TRequestProcessor * processorAlias)
Interface Category:
API.
Purpose:
Sets the request processor from which the view root gets its requests. This function should be used very infrequently.
Calling Context:
Called from the same thread as the view root by developer code.
Parameters:
- TRequestProcessor * processorAlias -A pointer to the request processor to set up for servicing this view root.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
You will typically only need to call this function if you have streamed in a new view root.
Member Function: TViewRoot::HandleSystemWindowDamaged
virtual void HandleSystemWindowDamaged (const TNotification &)
Interface Category:
API.
Purpose:
Provides notification of system window damage. Developers do not need to be concerned about this member function.
Calling Context:
Called from the request queue in response to damage events from the window server.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Developers should not call this, nor override this member function in derived classes.
Member Function: TViewRoot::RemoveInterest
virtual void RemoveInterest (const TInterest &)
Interface Category:
API.
Purpose:
Used internally to remove notification of changes to TViewRoot.
Calling Context:
Call this function directly.
Parameters:
- const TInterest & -The interest for which notification is to be removed.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TViewRoot::RegisterInterest
virtual void RegisterInterest (ViewRootNotificationMemberFunction, const TInterest &)
Interface Category:
API.
Purpose:
Used internally to register interest for notification of changes to TViewRoot.
Calling Context:
Call this function directly.
Parameters:
- ViewRootNotificationMemberFunction -The function to be notified.
- const TInterest & -The interest for which notification is to be added.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.