Class: TPicture

Declaration: Picture.h

Taxonomy Categories:

Member Functions:

TPicture
~TPicture
Draw
GetGeometricBounds
GetLooseFitBounds
TransformBy
operator==
operator!=
operator>>=
operator<<=
operator=
GetGrafPort

Interface Category:

API.

Inherits From:

MGraphic

Inherited By:

None.

Purpose:

TPicture derives from MGraphic and represents a picture of both 2-D and 3-D geometries and images composited together. The picture, once created, can be edited only by adding more geometries and images to it. It cannot be edited in any other respect, such as removing old geometries or modifying the geometries which are already part of this picture. Users wanting to edit the picture must destroy one TPicture and create another. TPicture is similar to TImage: both classes represent a scene made of primitive geometries. However, TImage renders the primitives onto a device-dependent pixel buffer and does not retain the geometries from which it is constructed. TPicture keeps a pure state of each geometry and its attributes as rendered onto the TGrafPort. TPicture renders its geometries in the same order (first come, first drawn) that they were originally rendered to the TGrafPort, concatenating the geometry's state with that of the picture. Because 3-D geometries can also be rendered, a SceneBundle is needed in the constructor of TPicture so that the 3-D objects can be projected onto the picture's 2-D plane. Once projected, the projection plane is not modified when the images are rendered. TPicture is a 2-D representation of 3-D and 2-D objects.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPicture::TPicture

TPicture ()
TPicture (const TSceneBundle &, TGrafBundle * =NIL)
TPicture (const TPicture &)

Interface Category:

API.

Purpose:

Creates a TPicture without a scene bundle (for users who want only 2-D objects).
Creates a TPicture and initializes its scene bundle and attribute bundle to the ones provided as parameters.
Copy constructor.

Calling Context:

Call this function directly.
Call this function directly.
Called to copy an object.

Parameters:

Takes no parameters.
const TSceneBundle & -The scene bundle for the new picture.
TGrafBundle * =NIL -The attribute bundle of the new picture. The default value is NIL.
const TPicture & -The picture to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPicture::~TPicture

virtual ~ TPicture ()

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: TPicture::Draw

virtual void Draw (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws the picture to the specified TGrafPort. TPicture renders its geometries in the same order (first come, first drawn) that they were originally rendered to the grafport, concatenating the geometry's state with that of the picture.

Calling Context:

Call this function directly.

Parameters:

TGrafPort & port -The grafport into which to draw the picture.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPicture::GetGeometricBounds

virtual TGRect GetGeometricBounds () const

Interface Category:

API.

Purpose:

Returns the bounding rectangle of the geometry, without considering any area determined by the bundle information.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the rectangle that encloses the picture, in world space coordinates.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPicture::GetLooseFitBounds

virtual TGRect GetLooseFitBounds (const TGrafPort * port =NIL) const

Interface Category:

API.

Purpose:

Returns the entire graphic's bounding rectangle, including the area determined by the bundle information.

Calling Context:

Call this function directly.

Parameters:

const TGrafPort * port =NIL -The graphics port used for accessing hierarchical bundles.

Return Value:

Returns the rectangle that encloses the picture, in world space coordinates.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPicture::TransformBy

virtual void TransformBy (const TGrafMatrix &)

Interface Category:

API.

Purpose:

Transforms the graphic's shape and position by applying the specified transformation matrix. Transformation is achieved through concatenation.

Calling Context:

Call this function directly.

Parameters:

const TGrafMatrix & -The matrix by which the picture is to be transformed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPicture::operator==

bool operator ==(const TPicture & source) const

Interface Category:

API.

Purpose:

Tests whether two objects are equal.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TPicture & source -The object to be compared with this object.

Return Value:

Returns true if the objects are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPicture::operator!=

bool operator != (const TPicture & source) const

Interface Category:

API.

Purpose:

Tests whether two objects are equal.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TPicture & source -The object to be compared with this object.

Return Value:

Returns true if the objects are not equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPicture::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream to which the object streams itself out.

Return Value:

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

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The stream from which the object streams itself in.

Return Value:

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

TPicture & operator =(const TPicture & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement.

Parameters:

const TPicture & source -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: TPicture::GetGrafPort

virtual TGrafPort * GetGrafPort () const

Interface Category:

API.

Purpose:

Returns the TGrafPort associated with the picture. The port is created in the constructor. This function does not return a const pointer because the port is modified when the picture is drawn into it.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The grafport currently associated with the picture.

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.