#include <GDI.H>
Link against: gdi.lib

Class `CPicture`

class CPicture : public CBase;

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 CPicture::Draw(CGraphicsContext &,const TPoint &,const TRect &,MGraphicsDeviceMap *)const, which draws the picture onto the graphics context at a particular point. It also has two important pure virtual functions: CPicture::ExternalizeL(RWriteStream &)const and CPicture::GetOriginalSizeInTwips(TSize &)const.

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 CPicture::Draw(CGraphicsContext &,const TPoint &,const TRect &,MGraphicsDeviceMap *)const 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.

Derivation

CBase - Base class for all classes to be instantiated on the heap.

CPicture - Abstract base class for: drawing a picture to a graphics context, storing and re...

Members

Defined in CPicture:

AddCropInPixels(MGraphicsDeviceMap *,const TMargins &)Adds pixel cropping margins to the picture.
CPicture()
Capability()constGets the picture's capabilities.
DetachFromStoreL(TDetach)
Draw(CGraphicsContext &,const TPoint &,const TRect &,MGraphicsDeviceMap *)constDraws a picture.
EDetachDrawInternalise enough information to draw the picture (and no more); null any refer...
EDetachFullInternalise all data that is required to fully store the picture later; null any...
ExternalizeL(RWriteStream &)constExternalises the picture to a stream.
GetCropInTwips(TMargins &)constGets the cropping margins of a picture in twips.
GetOriginalSizeInTwips(TSize &)constGets the pictur's original size, in twips.
GetSizeInPixels(MGraphicsDeviceMap *,TSize &)constGets the picture's size in pixels.
GetSizeInTwips(TSize &)constGets the picture's size, in twips.
LineBreakPossible(TUint,TBool,TBool)constStates whether a line break is possible, either before or after a picture.
NativePixelSize(TSize &)Derived classes might be implemented as bitmaps, in that case it might be intere...
ResetToOriginal()Resets the picture's scaling and cropping attributes to their original values.
ScaleFactorHeight()constGets the pictures height scale factor.
ScaleFactorWidth()constGets the picture's width scale factor.
SetCropInTwips(const TMargins &)Sets the cropping margins of a picture in twips.
SetScaleFactor(TInt,TInt)Sets the picture's scale factors.
SetSizeInPixels(MGraphicsDeviceMap *,const TSize &)Sets the picture's size in pixels.
SetSizeInTwips(const TSize &)Sets the picture's size, in twips
StoreL(CStreamStore &)constStores the picture to the specified store.
TDetachOptions for detaching pictures from stores. Used by CPicture::DetachFromStoreL(T...
~CPicture()Frees all resources owned by the object prior to its destruction.

Inherited from CBase:

Delete(CBase *)Deletes the specified object.
Extension_(TUint,TAny *&,TAny *)Extension function
operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TAny *)Initialises the object to binary zeroes.
operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

Construction and destruction

`~CPicture()`

IMPORT_C virtual ~CPicture();

Description

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

`CPicture()`

protected: IMPORT_C CPicture();

Description

Member functions

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

virtual void Draw(CGraphicsContext &aGc, const TPoint &aTopLeft, const TRect &aClipRect, MGraphicsDeviceMap *aMap) const=0;

Description

Draws a picture.

Parameters

`CGraphicsContext &aGc`	The graphics context.
`const TPoint &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.
`const TRect &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.
`MGraphicsDeviceMap *aMap`	The device map for the graphics device. The implementation should use this to find the scaling to apply to the picture.

`StoreL(CStreamStore &)const`

IMPORT_C virtual TStreamId StoreL(CStreamStore &aStore) const;

Description

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


                                 						CStreamStore &aStore

The store.

Return value

TStreamId

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

`DetachFromStoreL(TDetach)`

inline virtual void DetachFromStoreL(TDetach=EDetachFull);

Description

Parameters


                                 						CPicture::TDetach

`ExternalizeL(RWriteStream &)const`

virtual void ExternalizeL(RWriteStream &aStream) const=0;

Description

Externalises the picture to a stream.

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

A derived class must supply an implementation of this function.

Parameters


                                 						RWriteStream &aStream

The write stream.

`GetOriginalSizeInTwips(TSize &)const`

virtual void GetOriginalSizeInTwips(TSize &aSize) const=0;

Description

Gets the pictur's original size, in twips.

Parameters


                                 						TSize &aSize

The size of the picture, in twips

`SetScaleFactor(TInt,TInt)`

IMPORT_C virtual void SetScaleFactor(TInt aScaleFactorWidth, TInt aScaleFactorHeight);

Description

Sets the picture's scale factors.

Parameters

`TInt aScaleFactorWidth`	The width scale factor, in percent.
`TInt aScaleFactorHeight`	The height scale factor, in percent.

`SetCropInTwips(const TMargins &)`

IMPORT_C virtual void SetCropInTwips(const TMargins &aMargins);

Description

Sets the cropping margins of a picture in twips.

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

Parameters

const TMargins &aMargins

The cropping margins of the picture, in twips.

`Capability()const`

IMPORT_C virtual TPictureCapability Capability() const;

Description

Gets the picture's capabilities.

These include whether it is scalable and croppable.

Return value

TPictureCapability

The capabilities of the picture.

`GetCropInTwips(TMargins &)const`

IMPORT_C virtual void GetCropInTwips(TMargins &aMargins) const;

Description

Gets the cropping margins of a picture in twips.

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

Parameters


                                 						TMargins &aMargins

The cropping margins of the picture, in twips

`ScaleFactorWidth()const`

IMPORT_C virtual TInt ScaleFactorWidth() const;

Description

Gets the picture's width scale factor.

Return value

TInt

The width scale factor, in percent.

`ScaleFactorHeight()const`

IMPORT_C virtual TInt ScaleFactorHeight() const;

Description

Gets the pictures height scale factor.

Return value

TInt

The height scale factor, in percent.

`LineBreakPossible(TUint,TBool,TBool)const`

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

Description

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

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

Return value

TBool

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

`NativePixelSize(TSize &)`

IMPORT_C virtual TBool NativePixelSize(TSize &aPixelSize);

Description

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

Parameters


                                 						TSize &aPixelSize

Return value

TBool

`GetSizeInPixels(MGraphicsDeviceMap *,TSize &)const`

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

Description

Gets the picture's size in pixels.

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

Parameters

`MGraphicsDeviceMap *aMap`	The pixels to twips mapping interface of the graphics device
`TSize &aSize`	The size of the picture, in pixels.

`SetSizeInPixels(MGraphicsDeviceMap *,const TSize &)`

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

Description

Sets the picture's size in pixels.

Parameters

`MGraphicsDeviceMap *aMap`	The pixels to twips mapping interface of the graphics device.
`const TSize &aSize`	The size of the picture, in pixels.

`AddCropInPixels(MGraphicsDeviceMap *,const TMargins &)`

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

Description

Adds pixel cropping margins to the picture.

Parameters

`MGraphicsDeviceMap *aMap`	The pixels to twips mapping interface of the graphics device
`const TMargins &aMargins`	The additional pixel cropping margins for the picture, in pixels.

`GetSizeInTwips(TSize &)const`

IMPORT_C void GetSizeInTwips(TSize &aSize) const;

Description

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


                                 						TSize &aSize

The size of the picture, in twips.

`SetSizeInTwips(const TSize &)`

IMPORT_C void SetSizeInTwips(const TSize &aSize);

Description

Sets the picture's size, in twips

Parameters

const TSize &aSize

The size of the picture, in twips.

`ResetToOriginal()`

IMPORT_C void ResetToOriginal();

Description

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

Member enumerations

Enum `TDetach`

TDetach

Description

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

`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.

Class CPicture

Description

Derivation

Members

Construction and destruction

~CPicture()

Description

CPicture()

Description

Member functions

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

Description

Parameters

StoreL(CStreamStore &)const

Description

Parameters

Return value

DetachFromStoreL(TDetach)

Description

Parameters

ExternalizeL(RWriteStream &)const

Description

Parameters

GetOriginalSizeInTwips(TSize &)const

Description

Parameters

SetScaleFactor(TInt,TInt)

Description

Parameters

SetCropInTwips(const TMargins &)

Description

Parameters

Capability()const

Description

Return value

GetCropInTwips(TMargins &)const

Description

Parameters

ScaleFactorWidth()const

Description

Return value

ScaleFactorHeight()const

Description

Return value

LineBreakPossible(TUint,TBool,TBool)const

Description

Parameters

Return value

NativePixelSize(TSize &)

Description

Parameters

Return value

GetSizeInPixels(MGraphicsDeviceMap *,TSize &)const

Description

Parameters

SetSizeInPixels(MGraphicsDeviceMap *,const TSize &)

Description

Parameters

AddCropInPixels(MGraphicsDeviceMap *,const TMargins &)

Description

Parameters

GetSizeInTwips(TSize &)const

Description

Parameters

SetSizeInTwips(const TSize &)

Description

Parameters

ResetToOriginal()

Description

Member enumerations

Enum TDetach

Description

Class `CPicture`

`~CPicture()`

`CPicture()`

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

`StoreL(CStreamStore &)const`

`DetachFromStoreL(TDetach)`

`ExternalizeL(RWriteStream &)const`

`GetOriginalSizeInTwips(TSize &)const`

`SetScaleFactor(TInt,TInt)`

`SetCropInTwips(const TMargins &)`

`Capability()const`

`GetCropInTwips(TMargins &)const`

`ScaleFactorWidth()const`

`ScaleFactorHeight()const`

`LineBreakPossible(TUint,TBool,TBool)const`

`NativePixelSize(TSize &)`

`GetSizeInPixels(MGraphicsDeviceMap *,TSize &)const`

`SetSizeInPixels(MGraphicsDeviceMap *,const TSize &)`

`AddCropInPixels(MGraphicsDeviceMap *,const TMargins &)`

`GetSizeInTwips(TSize &)const`

`SetSizeInTwips(const TSize &)`

`ResetToOriginal()`

Enum `TDetach`