Class: TPrimitiveFrameView

Declaration: FrameView.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TWindow, MMouseEventHandler

Inherited By:

TBasicFrameView TStandardWindow

Purpose:

TPrimitiveFrameView is a base class that provides the default implementation of a frame for the Taligent human interface. The TPrimitiveFrameView wraps a TView and handles the displaying of a default frame when appropriate. The TPrimitiveFrameView notices when a TActivatibleView it contains becomes active, and grows to make room for the frame. The frame is displayed in its active visual state. A mouse click on the frame can switch the frame to its selected state. Selected frames can be moved or resized interactively. The frame view owns a TFrameViewInteractionPolicy, which controls how mouse clicks are processed. The frame calls functions in the policy object to handle selection, and the initiation of move and resize interactions.

Instantiation:

Always allocate on the heap.

Deriving Classes:

Derive classes from TPrimitiveFrameView to create a view that controls other views. Override HandleChildActivate and HandleChildDeactivate to enable items associated with the active state of the frame, such as menus. SetSelected may be overridden to update selection information in the container, although this may also be done by adopting an appropriate interaction policy. TBasicFrameView and TStandardWindow are derived from TPrimitiveFrameView.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

The TPrimitiveFrameView automatically grows when the frame is to be displayed around the wrapped view. The wrapped view is not resized when this happens; the frame grows outwards. This growth can cause problems for the frame's container if it calls GetAllocatedArea or related member functions for the frame view, for example when doing layout. The container should instead call GetInteriorAllocatedArea or GetInteriorAllocatedAreaInParent for the frame, or ask the wrapped view its size directly. Note that the wrapped view will return an origin relative to the frame view (i.e. 0,0), not relative to the container, but its size will be correct.

Member Function: TPrimitiveFrameView::TPrimitiveFrameView

TPrimitiveFrameView (TView * child)
TPrimitiveFrameView (const TPrimitiveFrameView &)
TPrimitiveFrameView ()

Interface Category:

API.

Purpose:

Creates a TPrimitiveFrameView and adopts the specified child view.
Copy constructor.
Default constructor.

Calling Context:

Called to create a TPrimitiveFrameView with the specified child view.
Called to copy an object. This constructor should not be used, since views do not support value semantics.
Called to create a TPrimitiveFrameView suitable for streaming into.

Parameters:

TView * child -The child view to adopt.
const TPrimitiveFrameView & -The object to be copied.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::~TPrimitiveFrameView

virtual ~ TPrimitiveFrameView ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::AdoptInteractionPolicy

virtual void AdoptInteractionPolicy (TFrameViewInteractionPolicy *)

Interface Category:

API.

Purpose:

Adopts the specified frame interaction policy for frame moving, resizing and selection. The interaction policy controls what happens when the frame is selected, moved or resized.

Calling Context:

Called to adopt a frame interaction policy. Call this function directly.

Parameters:

TFrameViewInteractionPolicy * -The frame policy to be adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::GetInteractionPolicy

virtual TFrameViewInteractionPolicy * GetInteractionPolicy ()

Interface Category:

API.

Purpose:

Returns the current frame interaction policy. If there is no current frame interaction policy, a default policy is created and returned.

Calling Context:

Called during event processing to obtain the current frame interaction policy. This function may also be called directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the current frame interaction policy.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::SetSelected

virtual void SetSelected (bool)

Interface Category:

API.

Purpose:

Enables or disables selection feedback for this view.

Calling Context:

Called by the interaction policy in response to a selection event. This function may also be called directly.

Parameters:

bool -If set to true, this view will appear selected to the user. If set to false, this view will not appear selected to the user.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::RequestMoveResizeInParent

void RequestMoveResizeInParent (const TGRect &, bool isLastRequest)

Interface Category:

API.

Purpose:

Requests a change in the size or location of the current view.

Calling Context:

Called by the interaction policy to change the size or location of the current view. This function may also be called directly.

Parameters:

const TGRect & -The new size of the current view.
bool isLastRequest -If set to true, indicates that this is the last request.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function may be overridden to constrain move or resize requests.

Member Function: TPrimitiveFrameView::GetInteriorAllocatedAreaInParent

virtual TGRect GetInteriorAllocatedAreaInParent () const

Interface Category:

API.

Purpose:

Returns the area allocated within the parent view for the interior of this frame. The parent view's coordinates are used. When the frame border has no thickness, the returned bounds are the same as those returned from GetAllocatedAreaInParent.

Calling Context:

Called during interactions to obtain the interior area currently allocated within the parent view. This function may also be called directly.

Parameters:

Takes no parameters.

Return Value:

Returns the interior area allocated within the parent view for this view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::GetInteriorAllocatedArea

virtual TGRect GetInteriorAllocatedArea () const

Interface Category:

API.

Purpose:

Returns the area allocated for the interior of this frame. The local view's coordinates are used. When the frame border has no thickness, the returned bounds are the same as those returned from GetAllocatedArea.

Calling Context:

Called during interactions and drawing to obtain the area allocated for the interior, in local coordinates. This function may also be called directly.

Parameters:

Takes no parameters.

Return Value:

Returns the interior area allocated view for this view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::GetBounds

virtual void GetBounds (TGArea & area) const

Interface Category:

API.

Purpose:

Fills in the specified parameter with the results of GetBounds. If there is no child view, a default location and size are returned.

Calling Context:

Called to obtain the bounds of the child view. Call this function directly.

Parameters:

TGArea & area -Parameter to be filled in with the child's bounds.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If there is no child view, a default bounds of TGRect(0,0,80,80) is returned.

Member Function: TPrimitiveFrameView::SetAllocatedAreaInParent

virtual void SetAllocatedAreaInParent (const TGArea &)

Interface Category:

API.

Purpose:

Sets the allocated area for the default state of this frame. For a TPrimitiveFrameView, this corresponds to the allocated area of the child view. This is an overridden function which automatically resizes the child view when the wrapping frame is resized.

Calling Context:

Called to set the area occupied by this frame. Call this function directly.

Parameters:

const TGArea & -The new area for this frame, specified in the parent view's coordinates.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::SetAllocatedArea

virtual void SetAllocatedArea (const TGArea &)
virtual void SetAllocatedArea (const TGRect &)

Interface Category:

API.

Purpose:

Automatically resizes the child view when the wrapping frame is resized. Sets the allocated area for the default state of this frame. For a TPrimitiveFrameView, this corresponds to the allocated area of the child view.

Calling Context:

Called during border state transitions to reset the area occupied by this frame. This function may also be called directly.

Parameters:

const TGArea & -The new area for this frame, specified in the parent view's coordinates.
const TGRect & -The new rectangle for this frame, specified in the parent view's coordinates.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::MouseDown

virtual bool MouseDown (TMouseDownEvent &)

Interface Category:

API.

Purpose:

Called if a mouse button has been pressed within the bounds of this view to select, move, or resize this frame. Returns true if the event was handled.

Calling Context:

Called by event distribution when a mouse button is pressed within the bounds of this view to select, move, or resize this frame. This function is not normally called directly.

Parameters:

TMouseDownEvent & -The mouse event.

Return Value:

Returns true if the event was handled.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::operator=

TPrimitiveFrameView & operator =(const TPrimitiveFrameView &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

This function should not be called, since views do not support value semantics.

Parameters:

const TPrimitiveFrameView & -The object to be copied.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called by Flatten to stream out this object. Only call this function directly from an override; use ::Flatten instead to preserve essential context information when this view is streamed.

Parameters:

TStream & -The destination stream.

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: TPrimitiveFrameView::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Called by Resurrect to recreate an object from a stream. Only call this function directly from an override; use ::Flatten instead to preserve essential context information when this view is streamed.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The source stream.

Return Value:

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

Exceptions:

Throws a TInvalidVersionError if the version of the object on the stream is unknown to the version of the shared library installed.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::DrawContents

virtual void DrawContents (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws the contents of the frame border. If the frame is not active or selected, the frame has no thickness so nothing is drawn. If the port parameter indicates that printing is being done, the frame is not drawn.

Calling Context:

Called by the View system to draw the contents of this view.

Parameters:

TGrafPort & port -Represents the graphics state and rendering device.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function is protected.

Member Function: TPrimitiveFrameView::HandleAllocatedAreaChanged

virtual void HandleAllocatedAreaChanged (const TGArea & area)

Interface Category:

API.

Purpose:

Handles the change in the area allocated to a view. Updates the boundaries of the frame border and the contained child view.

Calling Context:

Called by the View system when the area changes.

Parameters:

const TGArea & area -The area, specified in local coordinates.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function is protected.

Member Function: TPrimitiveFrameView::HandleChildActivate

virtual void HandleChildActivate ()

Interface Category:

API.

Purpose:

Sets this frame's state to reflect that it is active.

Calling Context:

Called asynchronously after a view within this frame's scope has been activated. This function is not normally called directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function is protected.

Member Function: TPrimitiveFrameView::HandleChildDeactivate

virtual void HandleChildDeactivate ()

Interface Category:

API.

Purpose:

Sets this frame's state to reflect that it is not active.

Calling Context:

Called asynchronously after a view within this frame's scope has been deactivated. This function is not normally called directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function is protected.

Member Function: TPrimitiveFrameView::AdoptActivatibleChild

virtual void AdoptActivatibleChild (TActivatibleView *)

Interface Category:

API.

Purpose:

Adopts the specified child view, orphaning any previously adopted child. The new view is set as the default active child for the frame.

Calling Context:

Called to adopt the specified child view. Call this function directly.

Parameters:

TActivatibleView * -The child view to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::HandleRequestMoveResizeInParent

virtual void HandleRequestMoveResizeInParent (const TGRect &, bool isLastRequest)

Interface Category:

API.

Purpose:

Handles Requests to change the size or location of the current view.

Calling Context:

Called by RequestMoveResizeInParent to actually change the size or location of the current view. This function is not normally called directly.

Parameters:

const TGRect & -The new size of the current view.
bool isLastRequest -If set to true, indicates that this is the last request.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::AdoptChild

virtual void AdoptChild (TView *)

Interface Category:

API.

Purpose:

Adopts the specified child view. Deletes any previous child.

Calling Context:

Call this function directly.

Parameters:

TView * -The view to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveFrameView::GetOpaquelyDrawnArea

virtual void GetOpaquelyDrawnArea (TGArea & opaqueArea)

Interface Category:

API.

Purpose:

A View system override that returns the area of the view guaranteed to be opaquely drawn. The default for this class returns the empty area.

Calling Context:

Called by the View system for view refresh processing. This function may also be called directly.

Parameters:

TGArea & opaqueArea -The area guaranteed to be opaquely drawn, specified in local coordinates.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Deriving classes may choose to override this member function.

Click the icon to mail questions or corrections about this material to Taligent personnel.