Class: TCanvasGraphicDeque

Declaration: GrafEditUtilities.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible, MCanvasRepresentation

Inherited By:

None.

Purpose:

Storage for a collection of canvas graphics that are drawn in a canvas view. Maintains semantic order from front (drawn on top) to back (drawn below). Provides members to adopt and orphan graphics and to manipulate graphic order. Contained graphics are referenced by their unique IDs and IDs can be cross-referenced to the actual pointers.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Intended to be used as is but can also be derived.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TCanvasGraphicDeque::TCanvasGraphicDeque

TCanvasGraphicDeque ()
TCanvasGraphicDeque (const TCanvasGraphicDeque &)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators and to create a new object.
Called to copy an object.

Parameters:

Takes no parameters.
const TCanvasGraphicDeque & -Another canvas graphic deque.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::~TCanvasGraphicDeque

virtual ~ TCanvasGraphicDeque ()

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: TCanvasGraphicDeque::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:

Always returns zero.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Currently, TCanvasGraphicDeque does not support comparisons via Hash or IsEqual. Classes can be derived to add such support.

Member Function: TCanvasGraphicDeque::operator=

TCanvasGraphicDeque & operator =(const TCanvasGraphicDeque &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TCanvasGraphicDeque & -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: TCanvasGraphicDeque::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: TCanvasGraphicDeque::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 a TStandardException(kStreamBadVersion,0) when streaming in a version other than kOriginalVersion. Passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::AdoptAtFront

virtual void AdoptAtFront (MCanvasGraphic *)

Interface Category:

API.

Purpose:

Adopts the graphic at the front.

Calling Context:

Call this function directly.

Parameters:

MCanvasGraphic * -The graphic to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::AdoptAtBack

virtual void AdoptAtBack (MCanvasGraphic *)

Interface Category:

API.

Purpose:

Adopts the graphic at the back.

Calling Context:

Call this function directly.

Parameters:

MCanvasGraphic * -The graphic to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::AdoptAfter

virtual void AdoptAfter (const TCanvasGraphicID & existing, MCanvasGraphic * toBeAdded)

Interface Category:

API.

Purpose:

Adopts the graphic after an identified graphic.

Calling Context:

Call this function directly.

Parameters:

const TCanvasGraphicID & existing -The ID of the graphic to adopt after.
MCanvasGraphic * toBeAdded -The graphic to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::AdoptBefore

virtual void AdoptBefore (const TCanvasGraphicID & existing, MCanvasGraphic * toBeAdded)

Interface Category:

API.

Purpose:

Adopts the graphic before an identified graphic.

Calling Context:

Call this function directly.

Parameters:

const TCanvasGraphicID & existing -The ID of the graphic to adopt before.
MCanvasGraphic * toBeAdded -The graphic to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::MoveToFront

virtual void MoveToFront (const TCanvasGraphicID &)

Interface Category:

API.

Purpose:

Moves the identified graphic to the front.

Calling Context:

Call this function directly.

Parameters:

const TCanvasGraphicID & -The ID of the graphic to move.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::MoveToBack

virtual void MoveToBack (const TCanvasGraphicID &)

Interface Category:

API.

Purpose:

Moves the identified graphic to the back.

Calling Context:

Call this function directly.

Parameters:

const TCanvasGraphicID & -The ID of the graphic to move.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::MoveForward

virtual bool MoveForward (const TCanvasGraphicID &)

Interface Category:

API.

Purpose:

Moves the identified graphic closer to the front by one position.

Calling Context:

Call this function directly.

Parameters:

const TCanvasGraphicID & -The ID of the graphic to move forward.

Return Value:

Returns true if the graphic is moved.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::MoveBackward

virtual bool MoveBackward (const TCanvasGraphicID &)

Interface Category:

API.

Purpose:

Moves the identified graphic closer to the back by one position.

Calling Context:

Call this function directly.

Parameters:

const TCanvasGraphicID & -The ID of the graphic to move backwards.

Return Value:

Returns true if the graphic is moved.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::Orphan

virtual MCanvasGraphic * Orphan (const TCanvasGraphicID &)

Interface Category:

API.

Purpose:

Removes a graphic and returns it, passing the ownership responsibility for it to the caller.

Calling Context:

Call this function directly.

Parameters:

const TCanvasGraphicID & -The ID of the graphic to orphan.

Return Value:

MCanvasGraphic * -The orphaned graphic.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::Swap

virtual MCanvasGraphic * Swap (const TCanvasGraphicID &, MCanvasGraphic * adopt)

Interface Category:

API.

Purpose:

Adopts a graphic in place of the identified other graphic. First, it swaps the IDs of the graphics so that the new graphic assumes the identity of the replaced graphic. Then, it returns the replaced graphic, passing the ownership responsibility to the caller.

Calling Context:

Typically called in the context of undoing or redoing a command.

Parameters:

const TCanvasGraphicID & -The ID of the existing graphic to replace.
MCanvasGraphic * adopt -The new graphic to adopt.

Return Value:

MCanvasGraphic * -The replaced graphic.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::Delete

virtual void Delete (const TCanvasGraphicID &)

Interface Category:

API.

Purpose:

Removes the identified graphic and destructs it.

Calling Context:

Call this function directly.

Parameters:

const TCanvasGraphicID & -The ID of the graphic to delete.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::DeleteAll

virtual void DeleteAll ()

Interface Category:

API.

Purpose:

Removes all graphics and destructs them.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::Member

virtual bool Member (const TCanvasGraphicID &) const

Interface Category:

API.

Purpose:

Determines if the identified graphic is a member.

Calling Context:

Call this function directly.

Parameters:

const TCanvasGraphicID & -The graphic.

Return Value:

Returns true if the identified graphic is a member.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::FrontMost

virtual TCanvasGraphicID FrontMost () const

Interface Category:

API.

Purpose:

Identifies the frontmost graphic.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

TCanvasGraphicID -The ID of the frontmost graphic.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::BackMost

virtual TCanvasGraphicID BackMost () const

Interface Category:

API.

Purpose:

Identifies the backmost graphic.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

TCanvasGraphicID -The ID of the backmost graphic.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::After

virtual TCanvasGraphicID After (const TCanvasGraphicID &) const

Interface Category:

API.

Purpose:

Identifies the graphic that is immediately after another graphic.

Calling Context:

Call this function directly.

Parameters:

const TCanvasGraphicID & -The ID of the other graphic.

Return Value:

TCanvasGraphicID -The ID of the graphic after the other one.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::Before

virtual TCanvasGraphicID Before (const TCanvasGraphicID &) const

Interface Category:

API.

Purpose:

Identifies the graphic that is immediately before another graphic.

Calling Context:

Call this function directly.

Parameters:

const TCanvasGraphicID & -The ID of the graphic before the other one.

Return Value:

TCanvasGraphicID -The ID of the graphic before the other one.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::Count

virtual long Count () const

Interface Category:

API.

Purpose:

Returns the number of graphics stored.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

long -The number of graphics.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::Lookup

virtual const MCanvasGraphic * Lookup (const TCanvasGraphicID &) const
virtual MCanvasGraphic * Lookup (const TCanvasGraphicID &)

Interface Category:

API.

Purpose:

Returns a const pointer to the identified graphic.
Returns a non-const pointer to the identified graphic.

Calling Context:

Called to cross-reference a graphic from its ID.
Called to cross-reference a graphic from its ID.

Parameters:

const TCanvasGraphicID & -The ID of the graphic to look up.
const TCanvasGraphicID & -The ID of the graphic to look up.

Return Value:

const MCanvasGraphic * -A const pointer to the graphic.
MCanvasGraphic * -A non-const pointer to the graphic.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::CreateReadIterator

virtual TCanvasGraphicReadIterator * CreateReadIterator () const

Interface Category:

API.

Purpose:

Creates a read iterator over this representation.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

TCanvasGraphicReadIterator * -The iterator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCanvasGraphicDeque::CreateWriteIterator

virtual TCanvasGraphicWriteIterator * CreateWriteIterator ()

Interface Category:

API.

Purpose:

Creates a write iterator over this representation.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

TCanvasGraphicWriteIterator * -The iterator.

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.