Class CPicture

CPicture

Support

Supported from 5.0

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.

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 restoring the picture

Defined in CPicture:
AddCropInPixels(), Capability(), DetachFromStoreL(), Draw(), EDetachDraw, EDetachFull, ExternalizeL(), GetCropInTwips(), GetOriginalSizeInTwips(), GetSizeInPixels(), GetSizeInTwips(), LineBreakPossible(), ResetToOriginal(), ScaleFactorHeight(), ScaleFactorWidth(), SetCropInTwips(), SetScaleFactor(), SetSizeInPixels(), SetSizeInTwips(), StoreL(), TDetach, ~CPicture()

Inherited from CBase:
operator new()

virtual ~CPicture();

Description

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

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.

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<<() is available to externalise objects of this class.

A derived class must supply an implementation of this function.

Parameters

RWriteStream& aStream The write stream.

virtual void DetachFromStoreL(TDetach /*aDegree*/=EDetachFull);

Description

Detaches a picture from its store, restoring any unrestored elements of the picture, if necessary.

The function would be used, for example, prior to storing the picture to another store or when pasting from a clipboard.

The default implementation is empty on the assumption that the picture factory restores everything.

Parameters

TDetach aDegree=EDetachFull Degree to which picture is detached.

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.

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.

virtual TInt ScaleFactorWidth() const;

Description

Gets the picture’s width scale factor.

Return value

TInt The width scale factor, in percent.

virtual TInt ScaleFactorHeight() const;

Description

Gets the picture’s height scale factor.

Return value

TInt The height scale factor, in percent.

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.

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.

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

Description

Gets the picture’s original size, in twips.

Parameters

TSize& aSize The size of the picture, in twips

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.

void SetSizeInTwips(const TSize& aSize);

Description

Sets the picture’s size, in twips

Parameters

const TSize& aSize The size of the picture, in twips.

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

Support

Supported from 6.0

Description

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

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

This may be overriden 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 True, if a line break is possible; false, otherwise.

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

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.

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.

void ResetToOriginal();

Description

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

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.

TDetach

Description

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

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.