CPicture Class Reference

#include <gdi.h>

Link against: gdi.lib

class CPicture : public CBase

Inherits from

CPicture
- CBase

Public Member Enumerations
enum	TDetach { EDetachFull, EDetachDraw }

Public Member Functions
virtual	~CPicture()
IMPORT_C void	AddCropInPixels(MGraphicsDeviceMap *, const TMargins &)
virtual IMPORT_C TPictureCapability	Capability()
virtual void	DetachFromStoreL(TDetach)
pure virtual void	Draw(CGraphicsContext &, const TPoint &, const TRect &, MGraphicsDeviceMap *)
pure virtual void	ExternalizeL(RWriteStream &)
virtual IMPORT_C void	GetCropInTwips(TMargins &)
pure virtual void	GetOriginalSizeInTwips(TSize &)
IMPORT_C void	GetSizeInPixels(MGraphicsDeviceMap *, TSize &)
IMPORT_C void	GetSizeInTwips(TSize &)
virtual IMPORT_C TBool	LineBreakPossible(TUint, TBool, TBool)
virtual IMPORT_C TBool	NativePixelSize(TSize &)
IMPORT_C void	ResetToOriginal()
virtual IMPORT_C TInt	ScaleFactorHeight()
virtual IMPORT_C TInt	ScaleFactorWidth()
virtual IMPORT_C void	SetCropInTwips(const TMargins &)
virtual IMPORT_C void	SetScaleFactor(TInt, TInt)
IMPORT_C void	SetSizeInPixels(MGraphicsDeviceMap *, const TSize &)
IMPORT_C void	SetSizeInTwips(const TSize &)
virtual IMPORT_C TStreamId	StoreL(CStreamStore &)

Protected Member Functions
	CPicture()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Detailed Description

Abstract base class for: drawing a picture to a graphics context, storing and restoring the picture.

The class defines the protocol for a number of concrete picture classes. Its main role is to support glass doors used in object embedding.

The class provides a protocol for the provision of scaling and cropping functions by derived classes, together with default implementations.

Its main function is Draw(), which draws the picture onto the graphics context at a particular point. It also has two important pure virtual functions: ExternalizeL() and GetOriginalSizeInTwips().

A picture has both an original representation and an on-screen representation. The original representation has a size in twips, and can somehow be drawn. The on-screen representation is assumed to be drawn under the control of an application which may wish to re-size or scale the original in some way, to crop it at the edges, and/or to ensure it fits within a particular defined area on the screen.

The class provides several functions that allow an application to set scaling and cropping before invoking the Draw() function to draw the picture on-screen. It is up to the internal workings of the function to determine the order of application cropping and scaling.

Member Enumeration Documentation

Enum TDetach

Options for detaching pictures from stores. Used by DetachFromStoreL().

Enumerator	Value	Description
EDetachFull		Internalise all data that is required to fully store the picture later; null any references to containing stores.
EDetachDraw		Internalise enough information to draw the picture (and no more); null any references to containing stores.

Constructor & Destructor Documentation

CPicture ( )

IMPORT_C

CPicture

(

)

[protected]

~CPicture ( )

IMPORT_C

~CPicture

(

)

[virtual]

Frees all resources owned by the object prior to its destruction.

Member Function Documentation

AddCropInPixels ( MGraphicsDeviceMap *, const TMargins & )

IMPORT_C void	AddCropInPixels	(	MGraphicsDeviceMap *	aMap,
			const TMargins &	aMargins
		)

Adds pixel cropping margins to the picture.

Parameters
aMap	The pixels to twips mapping interface of the graphics device
aMargins	The additional pixel cropping margins for the picture, in pixels.

Capability ( )

IMPORT_C TPictureCapability

Capability

(

)

const [virtual]

Gets the picture's capabilities.

These include whether it is scalable and croppable.

Return Value: The capabilities of the picture.

DetachFromStoreL ( TDetach )

void

DetachFromStoreL

(

TDetach

= EDetachFull

)

[inline, virtual]

Draw ( CGraphicsContext &, const TPoint &, const TRect &, MGraphicsDeviceMap * )

void	Draw	(	CGraphicsContext &	aGc,
			const TPoint &	aTopLeft,
			const TRect &	aClipRect,
			MGraphicsDeviceMap *	aMap
		)	const [pure virtual]

Draws a picture.

Parameters
aGc	The graphics context.
aTopLeft	The co-ordinates where the top left corner pixel of the picture should be placed. Note that whether this is actually drawn depends on the clipping area defined.
aClipRect	A clipping rectangle that defines the area to which the function should draw. An implementation should never draw outside this rectangle. Note that the graphics context may also have a clipping rectangle set on it.
aMap	The device map for the graphics device. The implementation should use this to find the scaling to apply to the picture.

ExternalizeL ( RWriteStream & )

void

ExternalizeL

(

RWriteStream &

aStream

)

const [pure virtual]

Externalises the picture to a stream.

The presence of this function means that the standard templated stream operator<<() is available to externalise objects of this class.

A derived class must supply an implementation of this function.

Parameters
aStream	The write stream.

GetCropInTwips ( TMargins & )

IMPORT_C void

GetCropInTwips

(

TMargins &

aMargins

)

const [virtual]

Gets the cropping margins of a picture in twips.

These margins are relative to the original unscaled size of the picture.

Parameters
aMargins	The cropping margins of the picture, in twips

GetOriginalSizeInTwips ( TSize & )

void

GetOriginalSizeInTwips

(

TSize &

aSize

)

const [pure virtual]

Gets the pictur's original size, in twips.

Parameters
aSize	The size of the picture, in twips

GetSizeInPixels ( MGraphicsDeviceMap *, TSize & )

IMPORT_C void	GetSizeInPixels	(	MGraphicsDeviceMap *	aMap,
			TSize &	aSize
		)	const

Gets the picture's size in pixels.

This is calculated from the original size of the picture, taking cropping and scaling into account.

Parameters
aMap	The pixels to twips mapping interface of the graphics device
aSize	The size of the picture, in pixels.

GetSizeInTwips ( TSize & )

IMPORT_C void

GetSizeInTwips

(

TSize &

aSize

)

const

Gets the picture's size, in twips.

This size is calculated from the original size of the picture, taking cropping and scaling into account.

Parameters
aSize	The size of the picture, in twips.

LineBreakPossible ( TUint, TBool, TBool )

IMPORT_C TBool	LineBreakPossible	(	TUint	aClass,
			TBool	aBeforePicture,
			TBool	aHaveSpaces
		)	const [virtual]

States whether a line break is possible, either before or after a picture.

The default implementation returns ETrue, implying that there is a break opportunity both before and after the picture, whether or not a space is present.

This may be overridden for special types of pictures.

Parameters
aClass	The line breaking class of the adjacent character. Line breaking classes are defined in the header file, tagma.h
aBeforePicture	ETrue, if the adjacent character is before the picture; EFalse, if the adjacent character is afterwards.
aHaveSpaces	ETrue, if spaces occur between the adjacent character and the picture; EFalse, otherwise.

Return Value: ETrue, if a line break is possible; EFalse, otherwise.

NativePixelSize ( TSize & )

IMPORT_C TBool

NativePixelSize

(

TSize &

aPixelSize

)

[virtual]

Derived classes might be implemented as bitmaps, in that case it might be interesting to now the native pixel size of the bitmap.

ResetToOriginal ( )

IMPORT_C void

ResetToOriginal

(

)

Resets the picture's scaling and cropping attributes to their original values.

ScaleFactorHeight ( )

IMPORT_C TInt

ScaleFactorHeight

(

)

const [virtual]

Gets the pictures height scale factor.

Return Value: The height scale factor, in percent.

ScaleFactorWidth ( )

IMPORT_C TInt

ScaleFactorWidth

(

)

const [virtual]

Gets the picture's width scale factor.

Return Value: The width scale factor, in percent.

SetCropInTwips ( const TMargins & )

IMPORT_C void

SetCropInTwips

(

const TMargins &

aMargins

)

[virtual]

Sets the cropping margins of a picture in twips.

These are relative to the original unscaled size of the picture.

Parameters
aMargins	The cropping margins of the picture, in twips.

SetScaleFactor ( TInt, TInt )

IMPORT_C void	SetScaleFactor	(	TInt	aScaleFactorWidth,
			TInt	aScaleFactorHeight
		)	[virtual]

Sets the picture's scale factors.

Parameters
aScaleFactorWidth	The width scale factor, in percent.
aScaleFactorHeight	The height scale factor, in percent.

SetSizeInPixels ( MGraphicsDeviceMap *, const TSize & )

IMPORT_C void	SetSizeInPixels	(	MGraphicsDeviceMap *	aMap,
			const TSize &	aSize
		)

Sets the picture's size in pixels.

Parameters
aMap	The pixels to twips mapping interface of the graphics device.
aSize	The size of the picture, in pixels.

SetSizeInTwips ( const TSize & )

IMPORT_C void

SetSizeInTwips

(

const TSize &

aSize

)

Sets the picture's size, in twips

Parameters
aSize	The size of the picture, in twips.

StoreL ( CStreamStore & )

IMPORT_C TStreamId

StoreL

(

CStreamStore &

aStore

)

const [virtual]

Stores the picture to the specified store.

The default implementation assumes that the content of the picture is externalized to a single stream. The implementation may need to be changed for those derived classes that have components.

Parameters
aStore	The store.

Return Value: The ID of the (head) stream used to store the picture.