CGraphicsContext Class Reference

#include <gdi.h>

Link against: gdi.lib

class CGraphicsContext : public CBase

Inherits from

Public Member Enumerations
enumTBrushStyle { ENullBrush, ESolidBrush, EPatternedBrush, EVerticalHatchBrush, ..., EDiamondCrossHatchBrush }
enumTDrawMode { EDrawModeAND, EDrawModeNOTAND, EDrawModePEN, EDrawModeANDNOT, ..., EDrawModeWriteAlpha }
enumTDrawModeComponents { EInvertScreen, EXor, EOr, EAnd, ..., EWriteAlpha }
enumTFillRule { EAlternate, EWinding }
enumTPenStyle { ENullPen, ESolidPen, EDottedPen, EDashedPen, ..., EDotDotDashPen }
enumTTextAlign { ELeft, ECenter, ERight }
Public Member Functions
pure virtual voidCancelClippingRect()
pure virtual voidCancelClippingRegion()
pure virtual CGraphicsDevice *Device()
pure virtual voidDiscardBrushPattern()
pure virtual voidDiscardFont()
pure virtual voidDrawArc(const TRect &, const TPoint &, const TPoint &)
pure virtual voidDrawBitmap(const TPoint &, const CFbsBitmap *)
pure virtual voidDrawBitmap(const TRect &, const CFbsBitmap *)
pure virtual voidDrawBitmap(const TRect &, const CFbsBitmap *, const TRect &)
pure virtual voidDrawBitmapMasked(const TRect &, const CFbsBitmap *, const TRect &, const CFbsBitmap *, TBool)
pure virtual voidDrawBitmapMasked(const TRect &, const CWsBitmap *, const TRect &, const CWsBitmap *, TBool)
pure virtual voidDrawEllipse(const TRect &)
pure virtual voidDrawLine(const TPoint &, const TPoint &)
pure virtual voidDrawLineBy(const TPoint &)
pure virtual voidDrawLineTo(const TPoint &)
pure virtual voidDrawPie(const TRect &, const TPoint &, const TPoint &)
pure virtual voidDrawPolyLine(const CArrayFix< TPoint > *)
pure virtual voidDrawPolyLine(const TPoint *, TInt)
pure virtual TInt DrawPolygon(const CArrayFix< TPoint > *, TFillRule)
pure virtual TInt DrawPolygon(const TPoint *, TInt, TFillRule)
pure virtual voidDrawRect(const TRect &)
pure virtual voidDrawRoundRect(const TRect &, const TSize &)
pure virtual voidDrawText(const TDesC &, const TPoint &)
pure virtual voidDrawText(const TDesC &, const TRect &, TInt, TTextAlign, TInt)
virtual IMPORT_C voidDrawText(const TDesC &, const TPoint &, const TDrawTextParam &)
IMPORT_C voidDrawText(const TDesC &, const TTextParameters *, const TPoint &)
IMPORT_C voidDrawText(const TDesC &, const TTextParameters *, const TRect &, TInt, TTextAlign, TInt)
IMPORT_C voidDrawText(const TDesC &, const TTextParameters *, const TPoint &, const TDrawTextParam &)
IMPORT_C TIntDrawTextExtended(const TDesC &, const TPoint &, const TDrawTextExtendedParam &)
IMPORT_C TIntDrawTextExtended(const TDesC &, const TTextParameters *, const TPoint &, const TDrawTextExtendedParam &)
pure virtual voidDrawTextVertical(const TDesC &, const TPoint &, TBool)
pure virtual voidDrawTextVertical(const TDesC &, const TRect &, TInt, TBool, TTextAlign, TInt)
IMPORT_C voidDrawTextVertical(const TDesC &, const TTextParameters *, const TPoint &, TBool)
IMPORT_C voidDrawTextVertical(const TDesC &, const TTextParameters *, const TRect &, TInt, TBool, TTextAlign, TInt)
IMPORT_C TIntGetShadowColor(TRgb &)
IMPORT_C TIntGetUnderlineMetrics(TInt &, TInt &)
IMPORT_C TBoolIsFbsBitGc()
IMPORT_C TIntJustificationInPixels(TInt, TInt, TInt, TInt)
IMPORT_C TIntJustificationInPixels(TInt &, TInt &)
pure virtual voidMapColors(const TRect &, const TRgb *, TInt, TBool)
pure virtual voidMoveBy(const TPoint &)
pure virtual voidMoveTo(const TPoint &)
pure virtual voidPlot(const TPoint &)
virtual IMPORT_C voidReserved()
pure virtual voidReset()
pure virtual voidSetBrushColor(const TRgb &)
pure virtual voidSetBrushOrigin(const TPoint &)
pure virtual voidSetBrushStyle(TBrushStyle)
pure virtual voidSetCharJustification(TInt, TInt)
pure virtual voidSetClippingRect(const TRect &)
pure virtual TInt SetClippingRegion(const TRegion &)
pure virtual voidSetDrawMode(TDrawMode)
pure virtual voidSetOrigin(const TPoint &)
pure virtual voidSetPenColor(const TRgb &)
pure virtual voidSetPenSize(const TSize &)
pure virtual voidSetPenStyle(TPenStyle)
IMPORT_C TIntSetShadowColor(const TRgb &)
pure virtual voidSetStrikethroughStyle(TFontStrikethrough)
pure virtual voidSetUnderlineStyle(TFontUnderline)
pure virtual voidSetWordJustification(TInt, TInt)
pure virtual voidUseBrushPattern(const CFbsBitmap *)
pure virtual voidUseFont(const CFont *)
Protected Member Functions
virtual IMPORT_C TIntAPIExtension(TUid, TAny *&, TAny *)
virtual IMPORT_C voidReserved_CGraphicsContext_2()
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 all graphics contexts.

Created by a CGraphicsDevice.

Provides the 'context' in which you are drawing to an associated device, in the sense that it holds the settings for drawing, such as the pen and brush settings (e.g. color, line styles) and the font settings (e.g. bold, underline, italic). These settings are device-independent.

Also provides the clipping region (the visible drawing area).

The settings and clipping area can be updated while drawing.

This class also contains the main drawing functions, and all drawing is done through a CGraphicsContext.

The graphics context deals with pixels of device-dependent size and uses fonts with device-dependent size and representation. The sizes and fonts to be passed to the class functions therefore need to be converted from size-independent units to size-dependent units first. This is done by an MGraphicsDeviceMap derived class. This may be a TZoomFactor or the CGraphicsDevice.

See CGraphicsContext::Reset() for the default graphics context settings immediately after construction.

See also: CBitmapContext

Member Enumeration Documentation

Enum TBrushStyle

Brush styles.

EnumeratorValueDescription
ENullBrush

The brush fill has no effect (default).

ESolidBrush

The brush fills with a solid single colour, determined by SetBrushColor() and the drawing mode.

EPatternedBrush

The brush fills with a selected bitmap pattern, set by UseBrushPattern().

EVerticalHatchBrush

The brush fills with vertical hatching lines going from top to bottom.

EForwardDiagonalHatchBrush

The brush fills with diagonal hatching lines going from bottom left to top right.

EHorizontalHatchBrush

The brush fills with horizontal hatching lines going from left to right.

ERearwardDiagonalHatchBrush

The brush fills with rearward diagonal hatching lines going from top left to bottom right.

ESquareCrossHatchBrush

The brush fills with horizontal and vertical hatching lines going from left to right plus lines going from top to bottom giving the effect of a grid of small squares

EDiamondCrossHatchBrush

The brush fills with forward diagonal and rearward diagonal hatching lines going from bottom left to top right plus lines going from top left to bottom right giving the effect of a grid of small diamonds.

Enum TDrawMode

Drawing modes.

This enum builds on the drawing mode components in the TDrawModeComponents enum.

If the pen colour is p, brush colour is b and screen colour is s, the effect of TDrawMode::EDrawModeAND is P=p&s and B=b&s. In other words, the effective colour of the pen on the screen, P, is that produced by the bitwise ANDing of the current screen colour and the current pen colour. The effect is similar for the effective brush colour, B.

The effective pen and brush colour are given in the table using the key Inputs: pen colour is p, brush colour is b and screen colour is s Outputs: effective brush colour is B, effective pen colour is P.

Some notes on using EDrawModeWriteAlpha:-

  • It is rare for client code to need to use this draw mode: see the documentation of SetDrawMode() for more information.

  • EDrawModeWriteAlpha should only be used with DrawRect(), Clear(), BitBlt(), and BitBltMasked() with EGray2 mask (and DrawBitmap() and DrawBitmapMasked()). For other draw operations, it is not supported, and may have unintended effects.

  • EDrawModeWriteAlpha has the same effect as EDrawModePEN, unless the brush colour has transparency (DrawRect(), Clear()), or the source bitmap is EColor16MA (and has transparency) (BitBlt(), BitBltMasked())

  • EDrawModeWriteAlpha has the same effect as EDrawModePEN if the draw mode of the destination does not support alpha blending. (Blending is only supported in 24bpp and 32bpp colour i.e. EColor16M, EColor16MU, EColor16MA)

  • In these cases, EDrawModePEN does alpha blending, whereas EDrawModeWriteAlpha means don't do alpha blending.

See also: SetDrawMode()

EnumeratorValueDescription
EDrawModeANDEAnd

Bitwise ANDs the pen and brush colours with the screen colour. P=p&s, B=b&s

EDrawModeNOTANDEInvertScreen|EAnd

Inverts the pen and brush colours before ANDing. P=(~p)&s, B=(~b)&s

EDrawModePENEPenmode

Uses both pen and brush colour as they are. P=p, B=b

EDrawModeANDNOTEAnd|EInvertPen

Inverts the screen colour before ANDing. P=p&(~s), B=b&(~s)

EDrawModeXOREXor

Bitwise XORs the pen and brush colours with the screen colour. P=p^s, B=b^s

EDrawModeOREOr

Bitwise ORs the pen and brush colours with the screen colour. P=p|s, B=b|s

EDrawModeNOTANDNOTEInvertScreen|EAnd|EInvertPen

Inverts the screen and pen and brush colours before ANDing. P=(~p)&(~s), B=(~b)&(~s)

EDrawModeNOTXOREInvertScreen|EXor

Inverts the pen and brush colours before XORing. P=(~p)^s, B=(~b)^s

EDrawModeNOTSCREENEInvertScreen

Inverts the colour of each pixel that is drawn over, (pen and brush attributes are ignored). P=~s, B=~s

EDrawModeNOTOREInvertScreen|EOr

Inverts the screen colour before ORing. P=p|(~s), B=b|(~s)

EDrawModeNOTPENEInvertPen|EPenmode

Inverts the pen and brush colours. P=~p, B=~b

EDrawModeORNOTEOr|EInvertPen

Inverts the pen and brush colours before ORing. P=(~p)|s, B=(~b)|s

EDrawModeNOTORNOTEInvertScreen|EOr|EInvertPen

Inverts the screen and pen and brush colours before ORing. P=(~p)|(~s), B=(~b)|(~s)

EDrawModeWriteAlphaEWriteAlpha

Writes alpha information in the source directly into the destination, rather than blending.

Enum TDrawModeComponents

Drawing mode components. This enum is not intended to be used directly, but provides components for the easy specification of drawing modes in the TDrawMode enum.

EnumeratorValueDescription
EInvertScreen1

1

EXor2

2

EOr4

4

EAnd8

8

ELogicalOp14

14

EInvertPen16

16

EPenmode32

32

EWriteAlpha64

64

Enum TFillRule

Rules used to fill self crossing polygons.

The filling of a polygon proceeds as follows: for a given point in the polygon, then

if the rule is TFillRule::EAlternate (default) and it has an odd winding number, then fill the surrounding area.

if the rule is TFillRule::EWinding and it has a winding number greater than zero, then fill the surrounding area.

EnumeratorValueDescription
EAlternate

Only fill areas with odd winding numbers.

EWinding

Fill areas with winding numbers greater than zero.

Enum TPenStyle

Pen styles. The screen pattern unit in each definition below describes the pattern drawn by the line 1 represents a pixel drawn, 0 represents a pixel that is not affected.

EnumeratorValueDescription
ENullPen

The pen does not draw. Screen pattern unit = 00...

ESolidPen

A solid line (default). Screen pattern unit = 11...

EDottedPen

A dotted line. Screen pattern unit = 1000...

EDashedPen

A dashed line. Screen pattern unit = 111000...

EDotDashPen

A line of alternating dashes and dots. Screen pattern unit = 1111001100...

EDotDotDashPen

A line of alternating single dashes and pairs of dots. Screen pattern unit = 11110011001100...

Enum TTextAlign

Text alignment.

EnumeratorValueDescription
ELeft

Text is left-aligned.

ECenter

Text is centred.

ERight

Text is right-aligned.

Member Function Documentation

APIExtension ( TUid, TAny *&, TAny * )

IMPORT_C TIntAPIExtension(TUidaUid,
TAny *&aOutput,
TAny *aInput
)[protected, virtual]

An APIExtension method to allow the addition of new APIs to retain compatibility with previous versions of gdi.dll

See also: CGraphicsContext WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases.

An API extension for CGraphics context replacing a reserved virtual method. Effectively allows multiple methods to use just one ordinal number.

Parameters
aOutputis for output
aInputis for input
Return Value
KErrNone If a successful derived function is found, if the default is used then KErrNotSupported is returned.

CancelClippingRect ( )

voidCancelClippingRect()[pure virtual]

Cancels any clipping rectangle.

Clipping thus reverts to the full device area, the default.

See also: SetClippingRect()

CancelClippingRegion ( )

voidCancelClippingRegion()[pure virtual]

Cancels the current clipping region.

See also: CGraphicsContext::SetClippingRegion()

Device ( )

CGraphicsDevice *Device()const [pure virtual]

Gets a pointer to the graphics context's graphics device.

Return Value
A pointer to the graphics device.

DiscardBrushPattern ( )

voidDiscardBrushPattern()[pure virtual]

Discards a non-built-in brush pattern.

This frees up the memory used by the bitmap, if it is not being shared by another process.

Notes:

The brush is used for filling shapes and the background of text boxes. The brush has colour, style, pattern and pattern origin parameters.

If DiscardBrushPattern() is used, with no brush pattern set, then there is no effect.

DiscardFont ( )

voidDiscardFont()[pure virtual]

Discards a font.

This frees up the memory used, if the font is not being shared.

The function can be called when no font is in use.

DrawArc ( const TRect &, const TPoint &, const TPoint & )

voidDrawArc(const TRect &aRect,
const TPoint &aStart,
const TPoint &aEnd
)[pure virtual]

Draws an arc.

The arc is considered a portion of an ellipse. The ellipse is defined by the TRect argument.

The pixels at both the start point and the end point are drawn.

The arc itself is the segment of the ellipse drawn in an anti-clockwise direction from the start point to the end point.

Notes:

A rectangle is used in the construction of the ellipse of which the arc is a segment. This rectangle is passed as an argument of type TRect.

A wide line arc is drawn with the pixels distributed either side of a true ellipse, in such a way that the outer edge of the line would touch the edge of the construction rectangle. In other words, the ellipse used to construct it is slightly smaller than that for a single pixel line size.

If the specified start or end point is at the centre of the ellipse, then the line that defines the start or end of the arc defaults to one extending vertically above the centre point.

If the start and end point are the same point or are points on the same line through the ellipse centre then a complete unfilled ellipse is drawn.

See also: DrawEllipse()

Parameters
aRectA rectangle in which to draw the ellipse, of which the arc is a segment.
aStartThe point defining the start of the arc. It defines one end of a line from the geometric centre of the ellipse. The point of intersection between this line and the ellipse defines the start point of the arc.
aEndThe point defining the end of the arc. It defines one end of a second line from the geometric centre of the ellipse. The point of intersection between this line and the ellipse defines the end point of the arc.

DrawBitmap ( const TPoint &, const CFbsBitmap * )

voidDrawBitmap(const TPoint &aTopLeft,
const CFbsBitmap *aSource
)[pure virtual]

Draws a bitmap at the specified point.

The point specifies the top left hand corner of the bitmap. The bitmap is compressed or stretched based on its internally stored size in twips.

Notes:

This member function uses the bitmap's size in twips and does a stretch/compress blit using a linear DDA.

As this function scales the bitmap, it is unavoidably slow. Therefore, where possible, use CBitmapContext::BitBlt() instead. If the bitmap has to be scaled, consider creating another bitmap along with an CFbsBitmapDevice etc, doing DrawBitmap() once and using BitBlt() subsequently.

Note that all bitmaps are clipped to the device boundaries.

See also: TLinearDDA

Parameters
aTopLeftThe point where the top left pixel of the bitmap is to be drawn
aSourceA source bitmap

DrawBitmap ( const TRect &, const CFbsBitmap * )

voidDrawBitmap(const TRect &aDestRect,
const CFbsBitmap *aSource
)[pure virtual]

Draws a bitmap to fit a given rectangle.

The bitmap is compressed or stretched based on its internally stored size in pixels.

Notes:

This member function uses the bitmap's size in pixels and does a stretch/compress blit using a linear DDA.

As this function scales the bitmap, it is unavoidably slow. Therefore, where possible, use CBitmapContext::BitBlt() instead. If the bitmap has to be scaled, consider creating another bitmap along with an CFbsBitmapDevice etc., doing DrawBitmap() once and using BitBlt() subsequently.

Note that all bitmaps are clipped to the device boundaries.

See also: TLinearDDA

Parameters
aDestRectThe rectangle within which the bitmap is to be drawn.
aSourceA source bitmap.

DrawBitmap ( const TRect &, const CFbsBitmap *, const TRect & )

voidDrawBitmap(const TRect &aDestRect,
const CFbsBitmap *aSource,
const TRect &aSourceRect
)[pure virtual]

Draws a specified rectangle of a source bitmap to fit into a given destination rectangle.

Notes:

This member function uses rectangle sizes in pixels and does a stretch/compress blit using a linear DDA.

As this function scales the bitmap, it is unavoidably slow. Therefore, where possible, use CBitmapContext::BitBlt() instead. If the bitmap has to be scaled, consider creating another bitmap along with an CFbsBitmapDevice etc., doing DrawBitmap() once and using BitBlt() subsequently.

Note that all bitmaps are clipped to the device boundaries.

See also: TLinearDDA

Parameters
aDestRectThe rectangle within which the bitmap is to be drawn.
aSourceA source bitmap.
aSourceRectThe rectangle in the source bitmap that is copied to the destination rectangle.

DrawBitmapMasked ( const TRect &, const CFbsBitmap *, const TRect &, const CFbsBitmap *, TBool )

voidDrawBitmapMasked(const TRect &aDestRect,
const CFbsBitmap *aBitmap,
const TRect &aSourceRect,
const CFbsBitmap *aMaskBitmap,
TBoolaInvertMask
)[pure virtual]

Draws a specified rectangle of a source bitmap to fit into a given rectangle using a given mask.

Notes:

This member function uses rectangle sizes in pixels and does a stretch/compress blit using a linear DDA.

Parameters
aDestRectThe rectangle within which the bitmap is to be drawn.
aBitmapThe source bitmap
aSourceRectThe rectangle in the source bitmap that is to be drawn
aMaskBitmapThe mask to be applied to the source bitmap while drawing
aInvertMaskFlag to indicate if the mask should be inverted.

DrawBitmapMasked ( const TRect &, const CWsBitmap *, const TRect &, const CWsBitmap *, TBool )

voidDrawBitmapMasked(const TRect &aDestRect,
const CWsBitmap *aBitmap,
const TRect &aSourceRect,
const CWsBitmap *aMaskBitmap,
TBoolaInvertMask
)[pure virtual]

Draws a specified rectangle from a wserv bitmap and its mask into another rectangle.

The function compresses/stretches the specified rectangle from the bitmap to fit the destination rectangle. The mask bitmap can be used as either a positive or negative mask. Masked pixels are not mapped to the destination rectangle.

A black and white (binary) mask bitmap is used. With aInvertMask=EFalse, black pixels in the mask bitmap stop corresponding pixels in the source bitmap from being transferred to the destination rectangle. With aInvertMask=ETrue, white pixels in the mask bitmap stop corresponding pixels in the source bitmap from being transferred to the destination rectangle.

Note: this member function uses rectangle sizes in pixels and does a stretch/compress blit using a linear DDA.

Parameters
aDestRectThe rectangle within which the masked bitmap is to be drawn.
aBitmapA source wserv bitmap.
aSourceRectThe rectangle in the source bitmap that is copied to the destination rectangle.
aMaskBitmapA mask wserv bitmap.
aInvertMaskIf false, a source pixel that is masked by a black pixel is not transferred to the destination rectangle. If true, then a source pixel that is masked by a white pixel is not transferred to the destination rectangle.

DrawEllipse ( const TRect & )

voidDrawEllipse(const TRect &aRect)[pure virtual]

Draws and fills an ellipse.

The ellipse is drawn inside the rectangle defined by the TRect argument. Any rectangle that has odd pixel dimensions, has the bottom right corner trimmed to give even pixel dimensions before the ellipse is constructed.

Note:

A wide outline ellipse is drawn with the pixels distributed either side of a true ellipse, in such a way that the outer edge of the line touches the edge of the construction rectangle. In other words, the ellipse used to construct it is smaller than that for a single pixel line size.

Parameters
aRectThe rectangle in which the ellipse is drawn.

DrawLine ( const TPoint &, const TPoint & )

voidDrawLine(const TPoint &aPoint1,
const TPoint &aPoint2
)[pure virtual]

Draws a straight line between two points.

Parameters
aPoint1The point at the start of the line.
aPoint2The point at the end of the line.

DrawLineBy ( const TPoint & )

voidDrawLineBy(const TPoint &aVector)[pure virtual]

Draws a straight line relative to the current drawing point, using a vector.

The start point of the line is the current drawing point. The specified vector is added to the drawing point to give the end point of the line

See also: MoveTo() MoveBy()

Parameters
aVectorThe vector to add to the current internal drawing position, giving the end point of the line.

DrawLineTo ( const TPoint & )

voidDrawLineTo(const TPoint &aPoint)[pure virtual]

Draws a straight line from the current drawing point to a specified point.

See also: MoveTo() MoveBy()

Parameters
aPointThe point at the end of the line.

DrawPie ( const TRect &, const TPoint &, const TPoint & )

voidDrawPie(const TRect &aRect,
const TPoint &aStart,
const TPoint &aEnd
)[pure virtual]

Draws and fills a pie slice.

The pie slice is an area bounded by:

the arc of an ellipse drawn in an anticlockwise direction from the start point to the end point

the straight line drawn to the start point from the geometric centre of the ellipse.

the straight line to the end point from the geometric centre of the ellipse.

Notes:

A rectangle is used in the construction of the pie slice. This rectangle is passed as an argument of type TRect. The curved edge of the pie slice is an arc of an ellipse constructed within the rectangle.

The line drawn by the pen goes inside the specified rectangle.

The pixels at the end point of the arc are not drawn.

A wide line edged pie slice has the arc drawn with the pixels distributed either side of a true ellipse. This is done in such a way that the outer edge of the line touches the edge of the construction rectangle. In other words, the ellipse used to construct it is slightly smaller than that for a single pixel line size.

If the specified start or end point is at the centre of the ellipse, then the line that defines the start or end of the arc defaults to one extending vertically above the centre point.

If the start and end point are the same point or are points on the same line through the ellipse centre then a complete filled ellipse is drawn. A line is also drawn from the edge to the ellipse centre.

Parameters
aRectA rectangle in which to draw the ellipse bounding the pie slice.
aStartA point defining the start of the arc bounding the pie slice. It defines one end of a line from the geometrical centre of the ellipse. The point of intersection between this line and the ellipse defines the start point of the arc.
aEndA point to define the end of the arc bounding the pie slice. It defines one end of a second line from the geometrical centre of the ellipse. The point of intersection between this line and the ellipse defines the end point of the arc.

DrawPolyLine ( const CArrayFix< TPoint > * )

voidDrawPolyLine(const CArrayFix< TPoint > *aPointList)[pure virtual]

Draws a polyline from a set of points in an array.

A polyline is a series of concatenated straight lines joining a set of points.

Parameters
aPointListAn array containing the points on the polyline.

DrawPolyLine ( const TPoint *, TInt )

voidDrawPolyLine(const TPoint *aPointList,
TIntaNumPoints
)[pure virtual]

Draws a polyline from a set of points in a list.

A polyline is a series of concatenated straight lines joining a set of points.

Parameters
aPointListPointer to a set of points on the polyline.
aNumPointsNumber of points in the list.

DrawPolygon ( const CArrayFix< TPoint > *, TFillRule )

TInt DrawPolygon(const CArrayFix< TPoint > *aPointList,
TFillRuleaFillRule = EAlternate
)[pure virtual]

Draws and fills a polygon defined using an array of points.

The first point in the array defines the start of the first side of the polygon. The second point defines the second vertex (the end point of the first side and the start point of the second side).

The final side of the polygon is drawn using the last point from the array, and the line is drawn to the start point of the first side.

Self-crossing polygons are filled according to the specified fill rule.

Parameters
aPointListAn array of points, specifying the vertices of the polygon.
aFillRuleThe fill rule. By default, this is TFillRule::EAlternate.
Return Value
KErrNone, if successful; otherwise, another of the system-wide error codes.

DrawPolygon ( const TPoint *, TInt, TFillRule )

TInt DrawPolygon(const TPoint *aPointList,
TIntaNumPoints,
TFillRuleaFillRule = EAlternate
)[pure virtual]

Draws and fills a polygon defined using a list of points.

The first point in the list defines the start of the first side of the polygon. The second point defines the second vertex (the end point of the first side and the start point of the second side).

The final side of the polygon is drawn using the last point from the list, and the line is drawn to the start point of the first side.

Self-crossing polygons are filled according to the specified fill rule.

Parameters
aPointListPointer to list of points, specifying the vertices of the polygon.
aNumPointsThe number of points in the list.
aFillRuleThe fill rule. By default this is TFillRule::EAlternate.
Return Value
KErrNone, if successful; otherwise, another of the system-wide error codes.

DrawRect ( const TRect & )

voidDrawRect(const TRect &aRect)[pure virtual]

Draws and fills a rectangle.

Parameters
aRectThe rectangle to be drawn.

DrawRoundRect ( const TRect &, const TSize & )

voidDrawRoundRect(const TRect &aRect,
const TSize &aCornerSize
)[pure virtual]

Draws and fills a rectangle with rounded corners.

The rounded corners are each constructed as an arc of an ellipse.

The line drawn by the pen, if any, goes inside the specified rectangle.

Notes:

Dotted and dashed pen styles cannot be used for the outline of a rounded rectangle.

If either corner size dimension is greater than half the corresponding rectangle length, the corner size dimension is reduced to half the rectangle size.

See also: DrawArc()

Parameters
aRectThe rectangle to be drawn.
aCornerSizeThe dimensions of each corner.

DrawText ( const TDesC &, const TPoint & )

voidDrawText(const TDesC &aText,
const TPoint &aPosition
)[pure virtual]

Draws text without a surrounding box.

The text baseline is aligned with the y co-ordinate of the specified point, and the left end of the text is aligned with the x co-ordinate of the specified point.

Note:

Text drawing is done with the pen, and is subject to the pen colour. The effective text colour also depends on the drawing mode. The size and style of the text depends on the font used. The layout of the text depends on the justification mode set.

Parameters
aTextThe text string to be drawn.
aPositionA point specifying the position of the left end of the text.

DrawText ( const TDesC &, const TRect &, TInt, TTextAlign, TInt )

voidDrawText(const TDesC &aText,
const TRect &aBox,
TIntaBaselineOffset,
TTextAlignaAlignment = ELeft,
TIntaLeftMargin = 0
)[pure virtual]

Draws text inside a box.

The surrounding box is filled with the current brush colour (not a pattern) and is drawn without any outline. The effective box colour depends on the drawing mode - if a brush colour has not been set then the brush defaults to white. The brush may be set to TBrushStyle::ENullBrush if text positioning relative to a box is required, but the box should not be filled.

The font used is that set by UseFont(). If no font is in use then a panic occurs.

The alignment of the text within the box can be specified.

Text drawn within a box is also clipped to that box. Unless you intend to clip the top off the text, aBaselineOffset should be greater than or equal to the ascent of the current font.

Offsets:

If the offset is negative, zero, or less than font height this is handled as would be expected, i.e. no text will be seen in the box in the first two instances, and the top of the text will be clipped in the latter case.

Margins:

For the drawing of right-aligned text, aLeftMargin indicates the margin from the right of aBox - where a positive value results in a leftwards offset.

Negative margins can be used to display portions of the text string clipped by the box. A negative margin for left aligned text would clip the start of the text string. Similarly, a negative margin for right aligned text would clip the end of the text string.

If the margin is greater than the width of the box then no text will be visible.

The margin is still honoured for centred text - centred text will not be centred in the box, unless the margin is zero.

Note:

Text drawing is done with the pen, and is thus subject to the pen colour. The effective text colour also depends on the drawing mode. The size and style of the text depends on the used font. The layout of the text depends on the justification mode set.

Parameters
aTextThe text string to be drawn.
aBoxThe box to draw the text in.
aBaselineOffsetAn offset from the top of the box to the text baseline.
aAlignmentThe text alignment mode default is left aligned.
aLeftMarginThe left margin for left-aligned text, or the right margin for right-aligned text default is zero.

DrawText ( const TDesC &, const TPoint &, const TDrawTextParam & )

IMPORT_C voidDrawText(const TDesC &aText,
const TPoint &aPosition,
const TDrawTextParam &aParam
)[virtual]

Draws the specified text at the given position using the parameters supplied.

Parameters
aTextThe text to be drawn.
aPositionThe position to draw the text at.
aParamParameters to use for text drawing.

DrawText ( const TDesC &, const TTextParameters *, const TPoint & )

IMPORT_C voidDrawText(const TDesC &aText,
const TTextParameters *iParam,
const TPoint &aPosition
)

DrawText ( const TDesC &, const TTextParameters *, const TRect &, TInt, TTextAlign, TInt )

IMPORT_C voidDrawText(const TDesC &aText,
const TTextParameters *iParam,
const TRect &aBox,
TIntaBaselineOffset,
TTextAlignaHrz = ELeft,
TIntaMargin = 0
)

DrawText ( const TDesC &, const TTextParameters *, const TPoint &, const TDrawTextParam & )

IMPORT_C voidDrawText(const TDesC &aText,
const TTextParameters *iParam,
const TPoint &aPosition,
const TDrawTextParam &aParam
)

DrawTextExtended ( const TDesC &, const TPoint &, const TDrawTextExtendedParam & )

IMPORT_C TIntDrawTextExtended(const TDesC &aText,
const TPoint &aPosition,
const TDrawTextExtendedParam &aParam
)

Draws text, optionally changing its direction (right-to-left / left-to-right).

Apart from reordering the text, the function is the same as the two parameter variant of DrawText(), described above.

Parameters
aTextThe text string to be drawn, optionally changing its direction (right-to-left / left-to-right).
aPositionA point specifying the position of the left end of the text.
aParamIndicates whether the text should be drawn from right-to-left (for scripts like Arabic and Hebrew) or left-to-right.
Return Value
KErrNoMemory indicates there was an OOM error when reordering the text; KErrNone if the reordering was successful.

DrawTextExtended ( const TDesC &, const TTextParameters *, const TPoint &, const TDrawTextExtendedParam & )

IMPORT_C TIntDrawTextExtended(const TDesC &aText,
const TTextParameters *iParam,
const TPoint &aPosition,
const TDrawTextExtendedParam &aParam
)

Draws text, optionally changing its direction (right-to-left / left-to-right).

Apart from reordering the text, the function is the same as the two parameter variant of DrawText(), described above.

Parameters
aTextThe text string to be drawn, optionally changing its direction (right-to-left / left-to-right).
aPositionA point specifying the position of the left end of the text.
aParamIndicates whether the text should be drawn from right-to-left (for scripts like Arabic and Hebrew) or left-to-right.
Return Value
KErrNoMemory indicates there was an OOM error when reordering the text; KErrNone if the reordering was successful.

DrawTextVertical ( const TDesC &, const TPoint &, TBool )

voidDrawTextVertical(const TDesC &aText,
const TPoint &aPos,
TBoolaUp
)[pure virtual]

Draws vertical text in the specified direction.

Parameters
aTextThe text to be drawn.
aPosPoint of origin of the text baseline.
aUpDirection. ETrue for up, EFalse for down.

DrawTextVertical ( const TDesC &, const TRect &, TInt, TBool, TTextAlign, TInt )

voidDrawTextVertical(const TDesC &aText,
const TRect &aBox,
TIntaBaselineOffset,
TBoolaUp,
TTextAlignaVert = ELeft,
TIntaMargin = 0
)[pure virtual]

Draws text vertically in the specified direction, within a box of the specified size.

Parameters
aTextThe text to be drawn.
aBoxThe bounding box within which the text should be drawn, and which it is clipped to.
aBaselineOffsetThe height of the top of the characters from their text baseline.
aUpThe direction. ETrue for up, EFalse for down.
aVertThe text alignment.
aMarginThe margin.

DrawTextVertical ( const TDesC &, const TTextParameters *, const TPoint &, TBool )

IMPORT_C voidDrawTextVertical(const TDesC &aText,
const TTextParameters *iParam,
const TPoint &aPos,
TBoolaUp
)

DrawTextVertical ( const TDesC &, const TTextParameters *, const TRect &, TInt, TBool, TTextAlign, TInt )

IMPORT_C voidDrawTextVertical(const TDesC &aText,
const TTextParameters *iParam,
const TRect &aBox,
TIntaBaselineOffset,
TBoolaUp,
TTextAlignaVert = ELeft,
TIntaMargin = 0
)

GetShadowColor ( TRgb & )

IMPORT_C TIntGetShadowColor(TRgb &aShadowColor)

Get the font's shadow colour

Parameters
aShadowColorShadow colour of the font returned by the funtion.
Return Value
KErrNone, if successful; otherwise, another of the system-wide errors.

GetUnderlineMetrics ( TInt &, TInt & )

IMPORT_C TIntGetUnderlineMetrics(TInt &aTop,
TInt &aBottom
)

IsFbsBitGc ( )

IMPORT_C TBoolIsFbsBitGc()const

Determine if the Gc is a CFbsBitGc

Return Value
ETrue, if the Gc is a CFbsBitGc, EFalse otherwise WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases.

JustificationInPixels ( TInt, TInt, TInt, TInt )

IMPORT_C TIntJustificationInPixels(TIntaExcessPixels,
TIntaTotalUnits,
TIntaFirstUnit,
TIntaNumUnits
)[static]

Gets the amount of space in pixels by which to adjust letter or word spacing, given the total number of words and spaces, a start space, and the number of units to be adjusted.

The first two arguments are the number of pixels (character groups) and the number of units (word spaces) over which justification is to occur. The third argument specifies the current character group or word space, while the final argument specifies the number of units that are to be adjusted.

A panic occurs if aExcessPixels is 0, aTotalUnits is not greater than 0, or aFirstUnit is not less than aTotalUnits.

See also: SetWordJustification() SetCharJustification()

Parameters
aExcessPixelsThe number of pixels by which the width of the text is to be changed. It may be positive, in which case the text is stretched, or negative, in which case it is shrunk.
aTotalUnitsThe number of word spaces over which the change in width is to be distributed.
aFirstUnitThe current unit the character group or word space we are 'on'.
aNumUnitsThe number of units that are to be adjusted starting at aFirstUnit.
Return Value
The number of pixels to be added to the width of the current unit.

JustificationInPixels ( TInt &, TInt & )

IMPORT_C TIntJustificationInPixels(TInt &aExcessPixels,
TInt &aTotalUnits
)[static]

Gets the amount of space in pixels by which to adjust the current letter or word spacing, and also retrieves the number of excess pixels and word spaces remaining after the adjustment is performed.

The arguments are the number of remaining pixels (character groups) and units (word spaces) over which justification is to occur. The function can be called repetitively until the number of units is zero, and hence justification is complete. A panic occurs if the number of units is less than one or the amount of pixels is zero.

See also: SetWordJustification() SetCharJustification()

Parameters
aExcessPixelsThe number of pixels by which the width of the text is to be changed. It may be positive, in which case the text is stretched, or negative, in which case it is shrunk. On return, this is equal to its old value minus the return value.
aTotalUnitsThe number of word spaces over which the change in width is to be distributed. On return, this is reduced by one.
Return Value
The number of pixels to be added to the width of the current unit.

MapColors ( const TRect &, const TRgb *, TInt, TBool )

voidMapColors(const TRect &aRect,
const TRgb *aColors,
TIntaNumPairs,
TBoolaMapForwards
)[pure virtual]

Maps pixels in the specified rectangle. The function tries to match the colour of a pixel with one of the RGB values in an array of RGB pairs. If there is a match, the colour is changed to the value specified in the other RGB in the RGB pair.

Parameters
aRectThe rectangle in which pixels are to be mapped.
aColorsA pointer to a set of RGB pairs.
aNumPairsThe number of pairs
aMapForwardsETrue, mapping is done from the first RGB to the second RGB in the pair; EFalse, mapping is done from the second RGB to the first RGB in the pair.

MoveBy ( const TPoint & )

voidMoveBy(const TPoint &aVector)[pure virtual]

Sets the drawing point relative to the current co-ordinates.

A subsequent call to DrawLineTo() or DrawLineBy() uses the new drawing point as the start point for the line drawn.

Notes

The operations DrawLine(), DrawLineTo(), DrawLineBy() and DrawPolyline() also change the internal drawing position to the last point of the drawn line(s).

The internal drawing position is set to the co-ordinate origin if no drawing or moving operations have yet taken place.

Parameters
aVectorThe amount by which the internal drawing position is to move.

MoveTo ( const TPoint & )

voidMoveTo(const TPoint &aPoint)[pure virtual]

Sets the drawing point relative to the co-ordinate origin.

A subsequent call to DrawLineTo() or DrawLineBy() uses the new drawing point as the start point for the line drawn.

Notes

The operations DrawLine(), DrawLineTo(), DrawLineBy() and DrawPolyline() also change the internal drawing position to the last point of the drawn line(s).

The internal drawing position is set to the co-ordinate origin if no drawing or moving operations have yet taken place.

Parameters
aPointThe new internal drawing position.

Plot ( const TPoint & )

voidPlot(const TPoint &aPoint)[pure virtual]

Draws a single point. The point is drawn with the current pen settings using the current drawing mode.

Note:

If the pen size is greater than one pixel, a filled circle of the current pen colour is drawn, with the pen size as the diameter and the plotted point as the centre. If the pen size is an even number of pixels, the extra pixels are drawn below and to the right of the centre.

See also: SetPenSize()

Parameters
aPointThe point to be drawn.

Reserved ( )

IMPORT_C voidReserved()[virtual]

Reserved function for future use.

Reserved_CGraphicsContext_2 ( )

IMPORT_C voidReserved_CGraphicsContext_2()[protected, virtual]

A reserved virtual function for future use.

Reset ( )

voidReset()[pure virtual]

Resets the graphics context to its default settings:

the drawing mode is TDrawMode::EDrawModePen (pen and brush colours used as they are)

there is no clipping rectangle

the pen settings are: black, solid, single pixel size

the brush style is null

no text font is selected

SetBrushColor ( const TRgb & )

voidSetBrushColor(const TRgb &aColor)[pure virtual]

Sets the brush colour.

The effective brush colour depends on the drawing mode.

Notes:

The brush is used for filling shapes and the background of text boxes. In case of outlined text, the brush is used for filling the font. The brush has colour, style, pattern and pattern origin parameters.

If no brush colour has been set, it defaults to white. However the default brush style is null, so when drawing to a window the default appears to be the window's background colour.

See also: SetDrawMode()

Parameters
aColorAn RGB colour for the brush.

SetBrushOrigin ( const TPoint & )

voidSetBrushOrigin(const TPoint &aOrigin)[pure virtual]

Sets the brush pattern origin.

This specifies the top left-hand corner position for the pattern tile around which copies of the pattern are tiled.

The brush pattern may be a built-in style, or a bitmap. To use a bitmap, the brush must have a pattern set and the brush style must be set to TBrushStyle::EPatternedBrush.

Notes

The brush is used for filling shapes and the background of text boxes. The brush has colour, style, pattern and pattern origin parameters.

If SetBrushOrigin() is not used, then the origin defaults to (0,0).

This brush origin remains in effect for all fillable shapes drawn subsequently, until a new brush origin is set. Shapes can thus be considered as windows onto a continuous pattern field (covering the whole clipping region of a screen device, or the whole device area of a printer).

See also: SetBrushStyle() UseBrushPattern()

Parameters
aOriginAn origin point for the brush. The coordinates are relative to the rectangle to fill, i.e. specify 0,0 to align the pattern flush with the top and left hand sides of the rectangle.

SetBrushStyle ( TBrushStyle )

voidSetBrushStyle(TBrushStyleaBrushStyle)[pure virtual]

Sets the brush style.

Ten brush styles are provided, including six built-in hatching patterns. Note: The brush is used for filling shapes and the background of text boxes. The brush has colour, style, pattern and pattern origin parameters. Note: Use TBrushStyle::ENullBrush to draw the outline of a fillable shape on its own, without filling. Note: If the TBrushStyle::EPatternedBrush style is set, but no bitmap pattern has been selected using UseBrushPattern(), then the function panics. Note: Hatching lines are done in the current pen colour, set using SetPenColor(). The hatching pattern starts at the brush origin, set using SetBrushOrigin().

See also: TBrushStyle::ENullBrush TBrushStyle::EPatternedBrush UseBrushPattern() SetPenColor() SetBrushOrigin()

Parameters
aBrushStyleA brush style.

SetCharJustification ( TInt, TInt )

voidSetCharJustification(TIntaExcessWidth,
TIntaNumChars
)[pure virtual]

Sets character justification.

This function is required by the Text Views API, and is not intended for regular use by developers.

It affects the strings of text used in the calls to DrawText() that follow, until the number of characters drawn equals aNumChars.

The text line that is to be justified has a certain number of characters this includes the spaces between the words. It also has a distance (in pixels) between the end of the last word and the actual end of the line (right hand margin, usually). These excess width pixels are distributed amongst all the characters, increasing the gaps between them, to achieve full justification of the text line.

Use CFont::TextCount() to return the excess width.

Notes:

This function is provided to allow simulation of printer fonts on screen. Due to the fact that fully-scalable fonts are not used before v5, large printer fonts can be simulated by using the nearest smaller font and widening it slightly.

If the excess width is zero, then calling SetCharJustification() has no effect.

SetCharJustification() is required for WYSIWYG where the layout uses printer font metrics but screen fonts have to be drawn on the screen. Because continuously scalable typefaces (c.f. TrueType) are not used before v5 and because screen fonts are coarser and less numerous in their variety than the printer fonts, the best matching smaller screen font must be used with character justification to simulate the printer font on the screen.

There is also a situation where the gaps between characters on screen have to be reduced with character clipping. The screen font that best matches the printer font may have the required height, but has characters that are too wide. A line of text that works on the printer will then be too long on the screen, unless it is squashed horizontally. The number of pixels that overlap the end of the screen line must now be removed from the gaps between the characters, i.e. there is a negative excess width. This situation is especially important where adding a TAB on screen gives perfectly acceptable printout, but would push the last character of the line off the right hand side of the screen.

In practice what you do in printer layout mode is:

Calculate where the line breaks will come on the printer. To do this you use a printer font (which in practice means a table of character widths of the font that the printer will use).

Now change to use a screen font that is the closest font which is no taller that the printer font. In practice it will often be fatter maybe only for certain characters such as 'i'.

You have to recalculate the width of the characters using the screen fonts. You can do this using CFont::TextWidth() as you have already determined how many characters will fit on the line.

If, in the screen font, the characters are not as wide as the line then you can just use word justification to expand the line. You would only do this if the text is to be justified.

If, however, the characters are wider than the line then you would use character justification to clip each character. You would need to do this even if the line is not justified.

Thus, in practice, character justification will only very rarely be used to expand a line of characters.

Parameters
aExcessWidthThe excess width (in pixels) to be distributed between the specified number of characters. It may be positive, in which case the text is stretched, or negative, in which case it is shrunk.
aNumCharsThe number of characters involved.

SetClippingRect ( const TRect & )

voidSetClippingRect(const TRect &aRect)[pure virtual]

Sets the clipping rectangle.

The area of visible drawing depends on the clipping rectangle, any items that fall outside the extent of the clipping rectangle will not be drawn. The default clipping rectangle is the full device area.

Note that clipping is additive. If a clipping region has been set using SetClippingRegion() then clipping will be to the intersection of that region and this rectangle.

See also: CGraphicsContext::SetClippingRegion() CGraphicsContext::SetOrigin()

Parameters
aRectThe rectangle to be used as the clipping rectangle. Note that this rectangle is tranformed by the current co-ordinate origin before it is used. The co-ordinate origin is set using SetOrigin().

SetClippingRegion ( const TRegion & )

TInt SetClippingRegion(const TRegion &aRegion)[pure virtual]

Sets the clipping region, any items that fall outside the extent of the clipping region will not be drawn.

Note that clipping is additive. If a clipping rectangle has been set using SetClippingRect() then clipping will be to the intersection of that rectangle and this region.

See also: CGraphicsContext::CancelClippingRegion() CGraphicsContext::SetClippingRect()

Parameters
aRegionThe new clipping region. Note that clipping region co-ordinates are used as absolute co-ordinates, they are not transformed by the current co-ordinate origin before use (as occurs in SetClippingRect()).
Return Value
KErrNone if successful; KErrArgument if the TRegion is not valid; KErrNoMemory if there is insufficient memory.

SetDrawMode ( TDrawMode )

voidSetDrawMode(TDrawModeaDrawingMode)[pure virtual]

Sets the drawing mode.

The way that the pen and brush draw depends on the drawing mode. The drawing mode affects the colour that is actually drawn, because it defines the way that the current screen colour logically combines with the current pen colour and brush colour. There are many drawing modes, each giving different logical combinations of pen, brush and screen colours. Each mode is produced by ORing together different combinations of seven drawing mode components.

The three most important modes are TDrawMode::EDrawModePEN, TDrawMode::EDrawModeNOTSCREEN and TDrawMode::EDrawModeXOR. The default drawing mode is TDrawMode::EDrawModePEN.

The drawing mode is over-ridden for line and shape drawing functions when a wide pen line has been selected. It is forced to TDrawMode::EDrawModePEN. This is to prevent undesired effects at line joins (vertexes).

Notes:

TDrawMode::EDrawModeAND gives a "colour filter" effect. For example:

  • ANDing with white gives the original colour

  • ANDing with black gives black

TDrawMode::EDrawModeOR gives a "colour boost" effect. For example:

  • ORing with black gives the original colour

  • ORing with white gives white

TDrawMode::EDrawModeXOR gives an "Exclusive OR" effect. For example:

  • white XOR black gives white

  • white XOR white gives black

  • black XOR black gives black

TDrawMode::EDrawModeWriteAlpha should not normally need to be used by client code. The following are exceptions:-

  • When a client side EColor16MA bitmap needs to have a transparent background (because you are intending to blend it onto something else), then you need to set EDrawModeWriteAlpha to Clear() it.

  • When you want to BitBlt() with an EColor16MA source bitmap that is opaque everywhere, then using EDrawModeWriteAlpha is more efficient than EDrawModePEN, because the bitmap does not need to be blended.

Note that if you have a transparent brush or source bitmap and you are drawing to a window, then it is a defect to use EDrawModeWriteAlpha.

See also: CGraphicsContext::TDrawMode CGraphicsContext::TDrawModeComponents

Parameters
aDrawingModeThe drawing mode.

SetOrigin ( const TPoint & )

voidSetOrigin(const TPoint &aPos =  TPoint(0, 0))[pure virtual]

Sets the position of the co-ordinate origin.

All subsequent drawing operations are done relative to this origin.

Parameters
aPosThe origin. The default origin is TPoint(0,0) the top left corner of the screen.

SetPenColor ( const TRgb & )

voidSetPenColor(const TRgb &aColor)[pure virtual]

Sets the pen colour.

The effective pen colour depends on the drawing mode. The default pen colour is black.

Note:

The pen is used to draw lines, the outlines of filled shapes, and text. In case of outlined text, the pen is used to draw the outline of the font.

The class provides member functions to set the colour of the pen, the style of line and the line size drawn.

See also: CGraphicsContext::SetDrawMode()

Parameters
aColorAn RGB colour for the pen.

SetPenSize ( const TSize & )

voidSetPenSize(const TSize &aSize)[pure virtual]

Sets the line drawing size for the pen.

Lines of size greater than one pixel:

are drawn with rounded ends that extend beyond the end points, (as if the line is drawn using a circular pen tip of the specified size).

are always drawn in TDrawMode::EDrawModePEN mode, overriding whatever mode has been set using SetDrawMode().

Notes:

The pen is used to draw lines, the outlines of filled shapes, and text. The class provides member functions to set the colour of the pen, the style of line and the line size drawn.

Wide straight lines and arcs have rounded ends so that concatenated wide lines have smoothly rounded corners at the vertexes.

When lines are made wide, the extra strips of pixels are added equally to both sides of the line. This works precisely for lines of odd pixel size (3, 5, 7, etc.). Wide lines of even pixel size, (2, 4, 6, etc.), have the extra strip of pixels added to the right and/or below the line.

Wide outlines of ellipses and wide line arcs are drawn with the pixels distributed either side of a thin (single pixel wide) true ellipse constructed in the normal manner. Wide ellipses and arcs of even pixel size have the extra strip of pixels added to the right and/or below the curved line. This gives a slight asymmetry to ellipses.

If the pen style is dotted or dashed, the size specification is ignored: a single-pixel wide primitive is drawn, (this is device dependant).

A line size of zero is handled as if the pen style had been set to TPenStyle::ENullPen.

Parameters
aSizeA line size. The default is 1 pixel.

SetPenStyle ( TPenStyle )

voidSetPenStyle(TPenStyleaPenStyle)[pure virtual]

Sets the line drawing style for the pen.

There are 6 pen styles. If no pen style is set, then the default is TPenStyle::ESolidPen. To use a pen style, its full context must be given, e.g. for a null pen:

CGraphicsContext::TPenStyle::ENullPen Notes:

The pen is used to draw lines, the outlines of filled shapes, and text. CGraphicsContext member functions are provided to set the colour of the pen, the style of line and the line size drawn.

The TPenStyle::ENullPen style should be used if a border is not required around a filled shape.

Dotted and dashed pen styles have a device dependant implementation, always give single-pixel size lines on the screen whatever the pen size set by SetPenSize() and can only be used for straight lines, polylines, non-rounded rectangles and polygons.

The dotted/dashed pattern is continued, without re-starting, for all consecutively drawn straight lines, i.e.

the outlines of rectangles the pattern starts in the top left corner. It is reset at the end of the function call.

the outlines of polygons the pattern starts at the first point. It is reset at the end of the function call.

polylines and straight lines the pattern starts at the first point initially. Consecutive calls to DrawLine() and/or DrawPolyLine(), whether the lines are concatenated or not, continue the pattern. It can be reset by a further call to SetPenStyle() using the same dotted/dashed style parameter.

See also: CGraphicsContext::TPenStyle

Parameters
aPenStyleA pen style.

SetShadowColor ( const TRgb & )

IMPORT_C TIntSetShadowColor(const TRgb &aShadowColor)

Set the font's shadow colour

Parameters
aShadowColorShadow colour to be set.
Return Value
KErrNone, if successful; otherwise, another of the system-wide errors.

SetStrikethroughStyle ( TFontStrikethrough )

voidSetStrikethroughStyle(TFontStrikethroughaStrikethroughStyle)[pure virtual]

Sets the strikethrough style.

This is applied to all subsequently drawn text.

Parameters
aStrikethroughStyleThe strikethrough style on or off.

SetUnderlineStyle ( TFontUnderline )

voidSetUnderlineStyle(TFontUnderlineaUnderlineStyle)[pure virtual]

Sets the underline style.

This is applied to all subsequently drawn text.

Parameters
aUnderlineStyleThe underline style on or off.

SetWordJustification ( TInt, TInt )

voidSetWordJustification(TIntaExcessWidth,
TIntaNumGaps
)[pure virtual]

Adjusts the spaces between words to stretch or squeeze to a certain width.

The function is required by the Text Views API, and is not intended for regular use by developers.

The text line that is to be justified has a certain number of gaps (spaces) between the words. It also has a distance (in pixels) between the end of the last word and the actual end of the line (right hand margin, usually). These excess width pixels are distributed amongst the gaps between the words to achieve full justification of the text line. Spaces become fat spaces to keep underlining/strikethrough consistent. Pixels are distributed to the inter-word gaps starting from the left end of the string. The spacing between characters in each word remains unchanged.

After a call to SetWordJustification(), subsequent calls to either of the two DrawText() functions are affected until the number of spaces specified by aNumSpaces is used up.

The easiest way to find out the excess width and number of spaces is to call CFont::MeasureText(). This function can also perform counting, which is finding how much of some text will fit into a given width.

Use CFont::TextCount() to return the excess width.

For example, in the string "To be, or not to be", there are five inter-word gaps. If there are six excess pixels they will be distributed in the proportion 2, 1, 1, 1, 1 between the words. If there are nine excess pixels they will be distributed in the proportion 2, 2, 2, 2, 1 between the words.

Notes:

If the excess width is zero, then calling SetWordJustification() has no effect.

At first sight it may appear that SetWordJustification() is not required because you can simply call DrawText() for each word. However, underlined justified text does not work using this strategy you get a non-underlined gap between the space and the beginning of the next word.

Parameters
aExcessWidthThe width (in pixels) to be distributed between the specified number of spaces.
aNumGapsThe number of word spaces (characters with the code U+0020) over which the change in width is distributed.

UseBrushPattern ( const CFbsBitmap * )

voidUseBrushPattern(const CFbsBitmap *aBitmap)[pure virtual]

Sets the brush pattern to the specified bitmap.

For the brush to actually use the bitmap, TBrushStyle::EPatternedBrush must be used to set the brush style.

When the brush pattern is no longer required, use DiscardBrushPattern() to free up the memory used, if the bitmap is not being shared. If UseBrushPattern() is used again without using DiscardBrushPattern() then the previous pattern is discarded automatically.

Notes:

The brush is used for filling shapes and the background of text boxes. The brush has colour, style, pattern and pattern origin parameters.

When loading a bitmap, the bitmap is checked to see if it is already in memory. If the bitmap is already there, then that copy is shared.

The brush does not need to have a pattern set at all. There are several built-in hatching patterns which can be selected using SetBrushStyle().

See also: SetBrushStyle()

Parameters
aBitmapA bitmap pattern for the brush.

UseFont ( const CFont * )

voidUseFont(const CFont *aFont)[pure virtual]

Sets the device font to be used for text drawing.

If the font is already in memory, then that copy is shared.

Notes:

The CFont* argument must have been previously initialised by calling MGraphicsDeviceMap::GetNearestFontInTwips() with the required font-specification. If the CFont* has not been initialised correctly, and therefore does not point to an available font-bitmap, then a panic is raised.

When the font is no longer required, use DiscardFont() to free up the memory used. If UseFont() is used again without using DiscardFont() then the previous font is discarded automatically.

If no font has been selected, and an attempt is made to draw text with DrawText(), then a panic is raised.

See also: MGraphicsDeviceMap::GetNearestFontInTwips()

Parameters
aFontA device font