Class: TCanvasView

Declaration: GrafEdit.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TContentView, MToolHandler

Inherited By:

TStandardCanvasView

Purpose:

Abstract base class for all GrafEdit views.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Must be derived from. See TStandardCanvasView for a specific example.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TCanvasView::TCanvasView

TCanvasView ()
TCanvasView (const TCanvasView &)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators and by constructors of derived classes.
Called to copy an object.

Parameters:

Takes no parameters.
const TCanvasView & -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::~TCanvasView

virtual ~ TCanvasView ()

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: TCanvasView::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Returns a unique value that can assist in identifying the object or comparing it to other objects.

Calling Context:

Called to generate a hash value.

Parameters:

Takes no parameters.

Return Value:

long -The hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::operator=

TCanvasView & operator =(const TCanvasView &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TCanvasView & -The object to be copied.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream the object is streamed 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: TCanvasView::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The stream the object is streamed in from.

Return Value:

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

Exceptions:

Throws TStandardException (kStreamBadVersion,0) if streaming in a version other than kOriginalVersion. Passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::DrawContents

virtual void DrawContents (TGrafPort &) const

Interface Category:

API.

Purpose:

Called when the object needs to be redrawn. The object should implement DrawContents to draw itself into the provided port.

Calling Context:

Called by the View system framework.

Parameters:

TGrafPort & -The port that the object draws itself into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::CreateToolTarget

virtual MToolTarget * CreateToolTarget ( const TTypeDescription & targetType, const TGPoint &) const

Interface Category:

API.

Purpose:

Creates a target for the current simple cursor tool to use. Provides reasonable default implementation for many GrafEdit applications.

Calling Context:

Called by the Cursor Tools framework.

Parameters:

const TTypeDescription & targetType -The required target type.
const TGPoint & -The location at which the cursor tool is beginning the interaction.

Return Value:

A target of the required type corresponding to the location of the cursor tool.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The default implementation is to return the current selection if the location hits the current selection, or to create a new selection of a single graphic that the location hits otherwise. If the location hits no graphics, then an empty selection is returned.

Member Function: TCanvasView::CreateToolInteractor

virtual TToolInteractor * CreateToolInteractor (const TGPoint &, const TToken &) const

Interface Category:

API.

Purpose:

Creates a tool interactor for the current delegating cursor tool to use. Provides a reasonable default implementation for many GrafEdit applications.

Calling Context:

Called by the Cursor Tools framework.

Parameters:

const TGPoint & -The location at which the cursor tool is beginning the interaction.
const TToken & -A hint that describes the current delegating tool type (Arrow, for example).

Return Value:

A tool interactor that implements the interaction that the view wants to associated with the delegating tool of the specified type at the specified location.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The default implementation is to examine hit graphics from front to back including SRT feedbackers, asking each to create a tool interactor until one does. If one creates a tool interactor, then that interactor is returned. Otherwise, a default TCanvasSelectionInteractor interactor is created and returned. Derived classes typically override this function to change the selection strategy.

Member Function: TCanvasView::SupportsFeedback

virtual bool SupportsFeedback () const

Interface Category:

API.

Purpose:

Tells the Cursor Tools framework if the object supports tool interaction feedback. Provides a reasonable default implementation for most GrafEdit applications.

Calling Context:

Called by tool interactors.

Parameters:

Takes no parameters.

Return Value:

Returns true if the object supports tool interaction feedback. .

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::AdoptFeedbackGraphic

virtual void AdoptFeedbackGraphic (MGraphic *, const TGArea & total, const TGArea & changed)

Interface Category:

API.

Purpose:

Draws and assumes ownership of a feedback graphic. Provides a reasonable default implementation for most GrafEdit applications.

Calling Context:

Called by tool interactors.

Parameters:

MGraphic * -The feedback graphic.
const TGArea & total -The total area of the feedback graphic.
const TGArea & changed -The area that differs from the most recent feedback graphic.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The default implementation is to adopt the graphic and invalidate the changed area. The invalidate causes the changed area to be redrawn via DrawContents, at which time the feedback graphic is drawn on top of all canvas graphics. Tool interactors call this MToolHandler function to specify the current graphic feedback to provide during interaction. Often, the graphic changes slightly between successive events of interaction. The changed area is specified to avoid redrawing the entire graphic when a small portion differs from the graphic of the prior event.

Member Function: TCanvasView::OrphanFeedbackGraphic

virtual MGraphic * OrphanFeedbackGraphic (bool repair)

Interface Category:

API.

Purpose:

Erases any prior feedback graphic and orphans its ownership. Provides a reasonable default implementation for most GrafEdit applications.

Calling Context:

Called by tool interactors.

Parameters:

bool repair -true if the orphaned graphic should be erased.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The default implementation is to orphan the last feedback graphic that was adopted and to invalidate its total area if the repair parameter is true. Invalidation results in drawing the area without the feedback graphic, for example, erasing it.

Member Function: TCanvasView::EnumerateGraphics

virtual void EnumerateGraphics (TCanvasGraphicFilter &, TCanvasGraphicFunnel &) const

Interface Category:

API.

Purpose:

Parses canvas graphics in the underlying representation filtered through the filter and processed by the funnel.

Calling Context:

Called by clients to do something with each canvas graphic in the underlying representation.

Parameters:

TCanvasGraphicFilter & -An object that can reject canvas graphics from consideration based on an encoded criterion.
TCanvasGraphicFunnel & -An object that is called to process each canvas graphic that passes that the filter does not reject.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes override to implement the way that canvas graphics are enumerated, abstracting storage access protocol from clients.

Member Function: TCanvasView::DrawBackground

virtual void DrawBackground (TGrafPort &) const

Interface Category:

API.

Purpose:

Draws the background that appears behind all canvas graphics.

Calling Context:

Called as the first step in TCanvasView::DrawContents.

Parameters:

TGrafPort & -The port to draw into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The default implementation is to draw a background color.

Member Function: TCanvasView::DrawGraphics

virtual void DrawGraphics (TGrafPort &) const

Interface Category:

API.

Purpose:

Draws the canvas graphics in the representation.

Calling Context:

Called in TCanvasView::DrawContents.

Parameters:

TGrafPort & -The port to draw into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The default implementation is to call EnumerateGraphics with a TCanvasBackToFrontFilter filter (of printing) or a TCanvasTopSelectionDrawingFilter filter if not, and a TCanvasDrawingFunnel funnel.

Member Function: TCanvasView::DrawFeedback

virtual void DrawFeedback (TGrafPort &) const

Interface Category:

API.

Purpose:

Draws any feedback graphic that has been adopted via AdoptFeedbackGraphic on top of all else.

Calling Context:

Called as the last step in TCanvasView::DrawContents.

Parameters:

TGrafPort & -The port to draw into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::Hit

virtual TCanvasGraphicID Hit (const TGPoint &) const

Interface Category:

API.

Purpose:

Identifies a graphic that is hit by the specified point.

Calling Context:

View or interactor implementations.

Parameters:

const TGPoint & -The point.

Return Value:

The hit graphic's ID, or TCanvasGraphicID::kInvalidID if no graphic is hit.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::ConnectNotification

virtual void ConnectNotification (TRequestBasedMemberFunctionConnectionTo < TCanvasView > &)

Interface Category:

API.

Purpose:

Gives derived classes an opportunity to connect notification.

Calling Context:

Called by the Graphics Editing framework.

Parameters:

TRequestBasedMemberFunctionConnectionTo < TCanvasView > & -The connection.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Typically not called or derived by developers. Derived classes should also call the base class implementation.

Member Function: TCanvasView::RegisterNotificationInterest

virtual void RegisterNotificationInterest (TRequestBasedMemberFunctionConnectionTo < TCanvasView > &)

Interface Category:

API.

Purpose:

Gives derived classes an opportunity to register for notification.

Calling Context:

Called by the Graphics Editing framework.

Parameters:

TRequestBasedMemberFunctionConnectionTo < TCanvasView > & -The connection for notification.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes should also call the base class implementation.

Member Function: TCanvasView::DisconnectNotification

virtual void DisconnectNotification (TRequestBasedMemberFunctionConnectionTo < TCanvasView > &)

Interface Category:

API.

Purpose:

Gives derived classes an opportunity to disconnect notification.

Calling Context:

Called by the Graphics Editing framework.

Parameters:

TRequestBasedMemberFunctionConnectionTo < TCanvasView > & -The connection for notification.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Typically not called or derived by developers. Derived classes should also call the base class implementation.

Member Function: TCanvasView::HandleUnknownNotification

virtual void HandleUnknownNotification (const TNotification &)

Interface Category:

API.

Purpose:

Handles notification that is received by the canvas view and not handled by another function.

Calling Context:

Called by the Notification framework.

Parameters:

const TNotification & -The notification to handle.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes should also call the base class implementation.

Member Function: TCanvasView::CreateEmptySelection

virtual MCanvasSelection * CreateEmptySelection () const

Interface Category:

API.

Purpose:

Creates an empty MCanvasSelection of the appropriate type.

Calling Context:

Called by other view functions or by objects that reference the view, such as interactors.

Parameters:

Takes no parameters.

Return Value:

MCanvasSelection * -A new canvas selection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Pure virtual function; must be implemented in derived classes.

Member Function: TCanvasView::CopyCurrentSelection

virtual MCanvasSelection * CopyCurrentSelection () const

Interface Category:

API.

Purpose:

Copies the current selection. The current selection is the selection that is represented by selection feedback in the user interface and that is the target of most menu commands.

Calling Context:

Called by other view functions or by objects that reference the view, such as interactors.

Parameters:

Takes no parameters.

Return Value:

MCanvasSelection * -A copy of the current selection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::SetCurrentSelection

virtual void SetCurrentSelection (const MCanvasSelection &)

Interface Category:

API.

Purpose:

Sets the current selection. The current selection is the selection that is represented by selection feedback in the user interface and that is the target of most menu commands.

Calling Context:

Called by other view functions or by objects that reference the view, such as interactors.

Parameters:

const MCanvasSelection & -A constant reference to the selection to be copied as the new current selection.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::AdoptCurrentSelection

virtual void AdoptCurrentSelection (MCanvasSelection *)

Interface Category:

API.

Purpose:

Sets the current selection. The current selection is the selection that is represented by selection feedback in the user interface and that is the target of most menu commands.

Calling Context:

Called by other view functions or by objects that reference the view, such as interactors.

Parameters:

MCanvasSelection * -A pointer to the selection to be adopted as the new current selection.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::GetEditableTextView

virtual TCanvasEditableTextView * GetEditableTextView ()

Interface Category:

API.

Purpose:

Provides the static view used for editable text by the TCanvasTextTool (see Mars for an example of this).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the editable text view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::SetBackgroundColor

virtual void SetBackgroundColor (const TColor &)

Interface Category:

API.

Purpose:

Sets the background color for the view.

Calling Context:

Call this function directly.

Parameters:

const TColor & -The color to be used for the background.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::DispatchEvent

virtual bool DispatchEvent (TEvent &)

Interface Category:

API.

Purpose:

Dispatches the specified event.

Calling Context:

Call this function directly.

Parameters:

TEvent & -The event to be dispatched.

Return Value:

Returns true if the event is successfully dispatched.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::HandleBeforeDisconnectionFromViewRoot

virtual void HandleBeforeDisconnectionFromViewRoot ()

Interface Category:

API.

Purpose:

Canvas view function overload for the routine that is used to maintain root hierarchy integrity whenever an orphaning operation is performed.

Calling Context:

Call this function directly before an orphaning operation.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasView::HandleAfterConnectionToViewRoot

virtual void HandleAfterConnectionToViewRoot ()

Interface Category:

API.

Purpose:

Canvas view function overload for the routine that is used to maintain root hierarchy integrity whenever an adoption operation is performed.

Calling Context:

Call this function directly after an adoption.

Parameters:

Takes no parameters.

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.