1.1 --- a/epoc32/include/gdi.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/gdi.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,4152 @@
1.4 -gdi.h
1.5 +// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +#ifndef __GDI_H__
1.21 +#define __GDI_H__
1.22 +
1.23 +#include <e32base.h>
1.24 +#include <f32file.h>
1.25 +#include <s32std.h>
1.26 +/**
1.27 +The default screen number.
1.28 +@internalComponent
1.29 +*/
1.30 +const TInt KDefaultScreenNo = 0;
1.31 +
1.32 +class TOpenFontCharMetrics;
1.33 +class RShapeInfo;
1.34 +
1.35 +/**
1.36 +Number of twips per inch.
1.37 +@publishedAll
1.38 +@released
1.39 +*/
1.40 +const TInt KTwipsPerInch=1440;
1.41 +
1.42 +/**
1.43 +Number of twips per point.
1.44 +@publishedAll
1.45 +@released
1.46 +*/
1.47 +const TInt KTwipsPerPoint=20;
1.48 +
1.49 +/**
1.50 +Number of points per inch.
1.51 +@publishedAll
1.52 +@released
1.53 +*/
1.54 +const TInt KPointsPerInch=72;
1.55 +
1.56 +/**
1.57 +Number of twips per cm.
1.58 +@publishedAll
1.59 +@released
1.60 +*/
1.61 +const TInt KTwipsPerCm=567;
1.62 +#if defined(__NO_CLASS_CONSTS__)
1.63 +/**
1.64 +A4 paper size in twips.
1.65 +@publishedAll
1.66 +@released
1.67 +*/
1.68 +#define KA4PaperSizeInTwips TSize(11906,16838)
1.69 +
1.70 +/** Legal paper size in twips.
1.71 +@publishedAll
1.72 +@released
1.73 +*/
1.74 +#define KLegalPaperSizeInTwips TSize(12240,20160)
1.75 +
1.76 +/**
1.77 +Executive paper size in twips.
1.78 +@publishedAll
1.79 +@released
1.80 +*/
1.81 +#define KExecutivePaperSizeInTwips TSize(10440,15120)
1.82 +/**
1.83 +Letter paper size in twips.
1.84 +@publishedAll
1.85 +@released
1.86 +*/
1.87 +#define KLetterPaperSizeInTwips TSize(12240,15840)
1.88 +
1.89 +/**
1.90 +Com-10 paper size in twips.
1.91 +@publishedAll
1.92 +@released
1.93 +*/
1.94 +#define KCom_10PaperSizeInTwips TSize(5940,13680)
1.95 +
1.96 +/**
1.97 +Monarch paper size in twips.
1.98 +@publishedAll
1.99 +@released
1.100 +*/
1.101 +#define KMonarchPaperSizeInTwips TSize(5580,10800)
1.102 +
1.103 +/**
1.104 +DL paper size in twips.
1.105 +@publishedAll
1.106 +@released
1.107 +*/
1.108 +#define KDLPaperSizeInTwips TSize(6236,12472)
1.109 +
1.110 +/**
1.111 +C5 paper size in twips.
1.112 +@publishedAll
1.113 +@released
1.114 +*/
1.115 +#define KC5PaperSizeInTwips TSize(9184,12983)
1.116 +#else
1.117 +/**
1.118 +@publishedAll
1.119 +@released
1.120 +*/
1.121 +const TSize KA4PaperSizeInTwips(11906,16838);
1.122 +const TSize KLegalPaperSizeInTwips(12240,20160);
1.123 +const TSize KExecutivePaperSizeInTwips(10440,15120);
1.124 +const TSize KLetterPaperSizeInTwips(12240,15840);
1.125 +const TSize KCom_10PaperSizeInTwips(5940,13680);
1.126 +const TSize KMonarchPaperSizeInTwips(5580,10800);
1.127 +const TSize KDLPaperSizeInTwips(6236,12472);
1.128 +const TSize KC5PaperSizeInTwips(9184,12983);
1.129 +#endif
1.130 +
1.131 +/**
1.132 +Declaration of constant TUids for APIExtension to use as identifiers.
1.133 +@internalComponent
1.134 +@released
1.135 +*/
1.136 +const TUid KGetUnderlineMetrics = {0x102827FB};
1.137 +const TUid KSetFastBlendDisabled = {0x10285A30};
1.138 +const TUid KSetShadowColor = {0x10282DA1};
1.139 +const TUid KGetShadowColor = {0x10282DA2};
1.140 +const TUid KUidIsFbsBitmapGc = {0x10285BBE};
1.141 +
1.142 +/**
1.143 +This enumeration holds the possible panic codes that may be raised
1.144 +by the GDI API on detecting an unrecoverable error. */
1.145 +enum TGdiPanic
1.146 + {
1.147 + /** Not used */
1.148 + EGdiPanic_Unknown = 0,
1.149 + /** One or more of the input parameters to the interface were invalid */
1.150 + EGdiPanic_InvalidInputParam = 1,
1.151 + /** Insufficient text for successful completion of the method */
1.152 + EGdiPanic_OutOfText = 2,
1.153 + /** Internal failure. */
1.154 + EGdiPanic_Invariant = 3
1.155 + };
1.156 +
1.157 +/** 24-bit RGB colour value with 8 bits each for red, green and blue.
1.158 +
1.159 +All Graphics drawing functions are specified in terms of a 32-bit TRgb colour
1.160 +containing the three colour values plus 8 bits for alpha channel. For hardware which
1.161 +does not support 24-bit colour, a mapping from TRgb to display colours is
1.162 +performed.
1.163 +
1.164 +Generally, the convention for the alpha blending fact is 0 = transparent,
1.165 +255 = opaque, unless otherwise stated. The exception to this are the TRgb constructor
1.166 +taking a single value, where the top byte of the passed in parameter is used for
1.167 +alpha information and the function Value(), which returns alpha information in the top byte.
1.168 +In both these cases, 0 means opaque, 255 means transparent.
1.169 +
1.170 +The supported display modes are enumerated in the TDisplayMode type. In each
1.171 +display mode a unique index can represent each physical colours supported,
1.172 +and which can be mapped onto a full RGB value. The mappings are as follows:
1.173 +
1.174 +16-colour displays use the EGA colour set: black, white, and then both light
1.175 +and dark versions of grey, red, green, blue, cyan, magenta and yellow
1.176 +
1.177 +256-colour displays support 216 colours made up of 6x6x6 RGB values, each
1.178 +containing all possible multiples of 51 for R,G,B values. Additionally, all
1.179 +remaining 10 shades of pure red, green, blue and grey are represented, by
1.180 +adding all remaining multiples of 17. This use of 256 colours is sometimes
1.181 +known as the Netscape colour cube.
1.182 +
1.183 +4096-colour displays effectively support RGB values with 4 bits per primary
1.184 +colour
1.185 +
1.186 +64k-colour displays effectively support RGB values with 5 bits allocated to
1.187 +red, 6 to green and 5 to blue
1.188 +
1.189 +16 million-colour displays support true colour with 8 bits allocated to each
1.190 +primary colour
1.191 +
1.192 +@publishedAll
1.193 +@released
1.194 +@see TDisplayMode
1.195 +@see DynamicPalette */
1.196 +class TRgb
1.197 + {
1.198 +public:
1.199 + inline TRgb();
1.200 + inline TRgb(TUint32 aValue);
1.201 + inline TRgb(TUint32 aInternalValue, TInt aAlpha);
1.202 + inline TRgb(TInt aRed,TInt aGreen,TInt aBlue);
1.203 + inline TRgb(TInt aRed, TInt aGreen, TInt aBlue, TInt aAlpha);
1.204 + inline TInt Red() const;
1.205 + inline TInt Green() const;
1.206 + inline TInt Blue() const;
1.207 + inline TInt Alpha() const;
1.208 + IMPORT_C void SetRed(TInt aRed);
1.209 + IMPORT_C void SetGreen(TInt aGreen);
1.210 + IMPORT_C void SetBlue(TInt aBlue);
1.211 + IMPORT_C void SetAlpha(TInt aAlpha);
1.212 + IMPORT_C static TRgb Gray2(TInt aGray2);
1.213 + IMPORT_C static TRgb Gray4(TInt aGray4);
1.214 + IMPORT_C static TRgb Gray16(TInt aGray16);
1.215 + IMPORT_C static TRgb Gray256(TInt aGray256);
1.216 + IMPORT_C static TRgb Color16(TInt aColor16);
1.217 + IMPORT_C static TRgb Color256(TInt aColor256);
1.218 + IMPORT_C static TRgb Color4K(TInt aColor4K);
1.219 + IMPORT_C static TRgb Color64K(TInt aColor64K);
1.220 + IMPORT_C static TRgb Color16M(TInt aColor16M);
1.221 + IMPORT_C TInt Gray2() const;
1.222 + IMPORT_C TInt Gray4() const;
1.223 + IMPORT_C TInt Gray16() const;
1.224 + IMPORT_C TInt Gray256() const;
1.225 + IMPORT_C TInt Color16() const;
1.226 + IMPORT_C TInt Color256() const;
1.227 + IMPORT_C TInt Color4K() const;
1.228 + IMPORT_C TInt Color64K() const;
1.229 + IMPORT_C TInt Color16M() const;
1.230 + inline TBool operator==(const TRgb& aColor) const;
1.231 + inline TBool operator!=(const TRgb& aColor) const;
1.232 + inline TRgb operator~() const;
1.233 + inline TRgb operator&(const TRgb& aColor);
1.234 + inline TRgb operator|(const TRgb& aColor);
1.235 + inline TRgb operator^(const TRgb& aColor);
1.236 + inline TRgb& operator&=(const TRgb& aColor);
1.237 + inline TRgb& operator|=(const TRgb& aColor);
1.238 + inline TRgb& operator^=(const TRgb& aColor);
1.239 + inline TUint32 Value() const;
1.240 + inline TUint32 Internal() const;
1.241 + inline void SetInternal(TUint32 aInternal);
1.242 + IMPORT_C TInt Difference(const TRgb& aColor) const;
1.243 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.244 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.245 + IMPORT_C static TRgb Color16MU(TInt a0RGB);
1.246 + IMPORT_C TInt Color16MU() const;
1.247 + IMPORT_C static TRgb Color16MA(TUint aARGB);
1.248 + IMPORT_C TUint Color16MA() const;
1.249 + IMPORT_C static TRgb Color16MAP(TUint aARGB);
1.250 + IMPORT_C TUint Color16MAP() const;
1.251 + IMPORT_C TUint _Color16MAP() const;
1.252 + IMPORT_C static TRgb _Color16MAP(TUint aARGB);
1.253 + inline TInt _Gray2() const;
1.254 + inline TInt _Gray4() const;
1.255 + inline TInt _Gray16() const;
1.256 + inline TInt _Gray256() const;
1.257 + inline TInt _Color4K() const;
1.258 + inline TInt _Color64K() const;
1.259 + inline TInt _Color16M() const;
1.260 + inline TInt _Color16MU() const;
1.261 + inline TUint _Color16MA() const;
1.262 + inline static TRgb _Gray2(TInt aGray2);
1.263 + inline static TRgb _Gray4(TInt aGray4);
1.264 + inline static TRgb _Gray16(TInt aGray16);
1.265 + inline static TRgb _Gray256(TInt aGray256);
1.266 + inline static TRgb _Color4K(TInt aColor4K);
1.267 + inline static TRgb _Color64K(TInt aColor64K);
1.268 + inline static TRgb _Color16M(TInt aColor16M);
1.269 + inline static TRgb _Color16MU(TInt a0RGB);
1.270 + inline static TRgb _Color16MA(TUint aARGB);
1.271 +private:
1.272 + TUint32 iValue;
1.273 + };
1.274 +
1.275 +/**
1.276 +@publishedAll
1.277 +@released
1.278 +*/
1.279 +#define KRgbBlack TRgb(0x000000)
1.280 +#define KRgbDarkGray TRgb(0x555555)
1.281 +#define KRgbDarkRed TRgb(0x000080)
1.282 +#define KRgbDarkGreen TRgb(0x008000)
1.283 +#define KRgbDarkYellow TRgb(0x008080)
1.284 +#define KRgbDarkBlue TRgb(0x800000)
1.285 +#define KRgbDarkMagenta TRgb(0x800080)
1.286 +#define KRgbDarkCyan TRgb(0x808000)
1.287 +#define KRgbRed TRgb(0x0000ff)
1.288 +#define KRgbGreen TRgb(0x00ff00)
1.289 +#define KRgbYellow TRgb(0x00ffff)
1.290 +#define KRgbBlue TRgb(0xff0000)
1.291 +#define KRgbMagenta TRgb(0xff00ff)
1.292 +#define KRgbCyan TRgb(0xffff00)
1.293 +#define KRgbGray TRgb(0xaaaaaa)
1.294 +#define KRgbWhite TRgb(0xffffff)
1.295 +
1.296 +
1.297 +/** Display modes.
1.298 +@publishedAll
1.299 +@released
1.300 +*/
1.301 +enum TDisplayMode
1.302 + {
1.303 + /** No display mode */
1.304 + ENone,
1.305 + /** Monochrome display mode (1 bpp) */
1.306 + EGray2,
1.307 + /** Four grayscales display mode (2 bpp) */
1.308 + EGray4,
1.309 + /** 16 grayscales display mode (4 bpp) */
1.310 + EGray16,
1.311 + /** 256 grayscales display mode (8 bpp) */
1.312 + EGray256,
1.313 + /** Low colour EGA 16 colour display mode (4 bpp) */
1.314 + EColor16,
1.315 + /** 256 colour display mode (8 bpp) */
1.316 + EColor256,
1.317 + /** 64,000 colour display mode (16 bpp) */
1.318 + EColor64K,
1.319 + /** True colour display mode (24 bpp) */
1.320 + EColor16M,
1.321 + /** (Not an actual display mode used for moving buffers containing bitmaps) */
1.322 + ERgb,
1.323 + /** 4096 colour display (12 bpp). */
1.324 + EColor4K,
1.325 + /** True colour display mode (32 bpp, but top byte is unused and unspecified) */
1.326 + EColor16MU,
1.327 + /** Display mode with alpha (24bpp colour plus 8bpp alpha) */
1.328 + EColor16MA,
1.329 + /** Pre-multiplied Alpha display mode (24bpp color multiplied with the alpha channel value, plus 8bpp alpha) */
1.330 + EColor16MAP,
1.331 + //Any new display mode should be insterted here!
1.332 + //There might be up to 255 display modes, so value of the last
1.333 + //inserted EColorXXX enum item should be less than 256 -
1.334 + //BC reasons!
1.335 + EColorLast
1.336 + };
1.337 +
1.338 +
1.339 +
1.340 +/** A set of static utility functions to get information about a display mode.
1.341 +@publishedAll
1.342 +@released
1.343 +*/
1.344 +class TDisplayModeUtils
1.345 + {
1.346 +public:
1.347 + IMPORT_C static TBool IsDisplayModeColor(TDisplayMode aDispMode);
1.348 + IMPORT_C static TBool IsDisplayModeValid(TDisplayMode aDispMode);
1.349 + IMPORT_C static TInt NumDisplayModeColors(TDisplayMode aDispMode);
1.350 + IMPORT_C static TInt NumDisplayModeBitsPerPixel(TDisplayMode aDispMode);
1.351 + };
1.352 +
1.353 +/** Utility function to check if a display mode has Alpha channel information
1.354 +@param aDisplayMode - the display mode being queried
1.355 +@return ETrue if display mode contains Alpha information.
1.356 +@internalTechnology
1.357 +@released
1.358 +*/
1.359 +inline TBool IsAlphaChannel(TDisplayMode aDisplayMode);
1.360 +/** Provides user-definable palette support to the GDI.
1.361 +
1.362 +A palette is a user-defined set of colours, which is a subset of the full
1.363 +range of 24-bit colours. This allows users the advantages of having a low
1.364 +bpp colour mode whilst being able to specify the colours available in that
1.365 +mode. To give an example, the EColor16 mode provides a palette of 16 colours
1.366 +as it provides a mapping between an integer index and a TRgb colour (see the
1.367 +table EGA Low-colour constants). Only a palette of 16 colour enables you to
1.368 +change the palette. Palettes are also used to allow 24-bit bitmaps to be stored
1.369 +in a more compressed form by finding the actual number of different colours
1.370 +used in the bitmap, creating a palette to allow the mapping of these colours
1.371 +to a smaller index space, and encoding the bitmaps pixels using indexes
1.372 +to this new index space.
1.373 +
1.374 +A palette has a size which is set at its creation and cannot be altered
1.375 +the number of entries in the palette. Each entry in a palette is a mapping
1.376 +between that entrys index and a TRgb value. Palette entries can be got
1.377 +and set at any time between the palettes creation and destruction. The
1.378 +GDIs palette support also provides functions to find the nearest palette
1.379 +colour to a requested TRgb colour.
1.380 +@publishedAll
1.381 +@released
1.382 +*/
1.383 +class CPalette : public CBase
1.384 + {
1.385 +public:
1.386 + IMPORT_C static CPalette* NewL(TInt aNumberOfEntries);
1.387 + IMPORT_C static CPalette* NewDefaultL(TDisplayMode aDispMode);
1.388 + IMPORT_C ~CPalette();
1.389 + IMPORT_C void Clear();
1.390 + inline TInt Entries() const;
1.391 + IMPORT_C TRgb GetEntry(TInt aPaletteIndex) const;
1.392 + IMPORT_C TRgb NearestEntry(const TRgb& aColor) const;
1.393 + IMPORT_C TInt NearestIndex(const TRgb& aColor) const;
1.394 + IMPORT_C void SetEntry(TInt aPaletteIndex,const TRgb& aPaletteEntry);
1.395 + IMPORT_C void GetDataPtr(TInt aFirstColor,TInt aNumColors,TPtr8& aPtr);
1.396 +protected:
1.397 + IMPORT_C CPalette();
1.398 + void ConstructL(TInt aNumberOfEntries);
1.399 +protected:
1.400 + TRgb* iArray;
1.401 + TInt iNumEntries;
1.402 + };
1.403 +
1.404 +
1.405 +/** Enables conversion, in both directions, between a TRgb object and an index
1.406 +into an arbitrary 256 colour palette.
1.407 +@publishedAll
1.408 +@released
1.409 +*/
1.410 +class TColor256Util
1.411 + {
1.412 +public:
1.413 + IMPORT_C void Construct(const CPalette& aPalette);
1.414 + IMPORT_C TInt Color256(TRgb aRgb) const;
1.415 + IMPORT_C void Color256(TUint8* aDestination,const TRgb* aSource,TInt aNumPixels) const;
1.416 + inline TRgb Color256(TInt aColor256) const;
1.417 + IMPORT_C static const TColor256Util* Default();
1.418 +public:
1.419 + /** 256 colour lookup table.
1.420 +
1.421 + Each entry is a 32 bit value which corresponds to a TRgb value in the
1.422 + palette passed to Construct(). If there are more than 256 colours in the
1.423 + palette, the first 256 colours are used in this table. If there are fewer
1.424 + than 256 entries, the remaining entries in the table are set to zero. */
1.425 + TUint32 iColorTable[256];
1.426 +
1.427 + /** Inverse colour lookup table.
1.428 +
1.429 + It has 4096 entries. Each entry is the index of a colour in the palette
1.430 + that the object was created with (see Construct()) that most closely
1.431 + matches the 4096 degrees of intensity of red, green and blue on a uniform
1.432 + 16x16x16 colour cube.
1.433 +
1.434 + It is called "inverse" because iColorTable maps indices (0..255) to TRgb
1.435 + values, but this table maps TRgb values to palette indices. */
1.436 + TUint8 iInverseColorTable[0x1000];
1.437 + };
1.438 +
1.439 +
1.440 +/** Linear digital differential analyser.
1.441 +
1.442 +This is used to calculate the pixels which most closely approximate a specified
1.443 +straight line, or when scaling a bitmap. Note that a line is infinitely thin,
1.444 +and can only be approximated by pixels with real width and height.
1.445 +
1.446 +Functions are provided for: pixel line traversing; jumping to a rectangle or
1.447 +co-ordinate
1.448 +@publishedAll
1.449 +@released
1.450 +*/
1.451 +class TLinearDDA
1.452 + {
1.453 +public:
1.454 + /** LDDA Line mode. */
1.455 + enum TLineMode
1.456 + {
1.457 + /** Centres scan-lines in the pixel line */
1.458 + ECenter,
1.459 + /** Starts at the beginning of a complete scan line. Used for bitmap
1.460 + scaling. */
1.461 + ELeft
1.462 + };
1.463 +public:
1.464 + IMPORT_C TLinearDDA();
1.465 + IMPORT_C TLinearDDA(const TLinearDDA& aLine);
1.466 + IMPORT_C void Construct(const TPoint& aStart,const TPoint& aFinish,TLineMode aMode=ECenter);
1.467 + IMPORT_C TBool SingleStep(TPoint& aPosition);
1.468 + IMPORT_C TBool SingleScanline(TPoint& aStartPosition,TPoint& aEndPosition);
1.469 + IMPORT_C TBool NextStep(TPoint& aPosition);
1.470 + IMPORT_C void JumpToRect(const TRect& aRect);
1.471 + IMPORT_C void JumpToXCoord(const TInt aXCoord,TInt& aYCoord);
1.472 + IMPORT_C void JumpToYCoord(TInt& aXCoord,const TInt aYCoord);
1.473 + IMPORT_C void JumpToXCoord2(TInt aXCoord,TInt& aYCoord);
1.474 + IMPORT_C void JumpToYCoord2(TInt& aXCoord,TInt aYCoord);
1.475 +private:
1.476 + void UpdatePosition();
1.477 +private:
1.478 + enum TLineStatus
1.479 + {
1.480 + EInitialised,
1.481 + ECurrent,
1.482 + EComplete
1.483 + };
1.484 +private:
1.485 + TInt iCount;
1.486 + TSize iDifference;
1.487 + TPoint iFinish;
1.488 + TInt iGradient;
1.489 + TPoint iInc;
1.490 + TPoint iPos;
1.491 + TPoint iStart;
1.492 + TRect iBoundingRect;
1.493 + TBool iBoundingRectSet;
1.494 + TBool iInside;
1.495 + TLineStatus iStatus;
1.496 + };
1.497 +
1.498 +
1.499 +/**
1.500 +Font posture flags.
1.501 +Fonts can be either upright or italic.
1.502 +@publishedAll
1.503 +@released
1.504 +*/
1.505 +enum TFontPosture
1.506 + {
1.507 + /** Font posture is normal (upright). */
1.508 + EPostureUpright,
1.509 + /** Font posture is italic. */
1.510 + EPostureItalic
1.511 + };
1.512 +
1.513 +/**
1.514 +Font stroke weight flags.
1.515 +@publishedAll
1.516 +@released
1.517 +*/
1.518 +enum TFontStrokeWeight
1.519 + {
1.520 + /** Font stroke weight is normal. */
1.521 + EStrokeWeightNormal,
1.522 + /** Font stroke weight is bold. */
1.523 + EStrokeWeightBold
1.524 + };
1.525 +
1.526 +/**
1.527 +Font print position flags.
1.528 +Fonts can be normal, superscript or subscript.
1.529 +@publishedAll
1.530 +@released
1.531 +*/
1.532 +enum TFontPrintPosition
1.533 + {
1.534 + /** Font is normal. */
1.535 + EPrintPosNormal,
1.536 + /** Font is superscript. */
1.537 + EPrintPosSuperscript,
1.538 + /** Font is subscript. */
1.539 + EPrintPosSubscript
1.540 + };
1.541 +
1.542 +/**
1.543 +Font underline flags.
1.544 +@publishedAll
1.545 +@released
1.546 +*/
1.547 +enum TFontUnderline
1.548 + {
1.549 + /** Font is not underlined. */
1.550 + EUnderlineOff,
1.551 + /** Font is underlined. */
1.552 + EUnderlineOn
1.553 + };
1.554 +
1.555 +/**
1.556 +Font strike-through flags.
1.557 +@publishedAll
1.558 +@released
1.559 +*/
1.560 +enum TFontStrikethrough
1.561 + {
1.562 + /** Font is not struck-through. */
1.563 + EStrikethroughOff,
1.564 + /** Font is struck-through. */
1.565 + EStrikethroughOn
1.566 + };
1.567 +
1.568 +/**
1.569 +The maximum length of a typeface name (in characters).
1.570 +@publishedAll
1.571 +@released
1.572 +*/
1.573 +const TInt KMaxTypefaceNameLength=0x18;
1.574 +
1.575 +
1.576 +/** Typeface name and attributes.
1.577 +
1.578 +This class identifies a typeface by name, and contains the combination of
1.579 +attributes of the typeface. These attributes define whether it is a symbol
1.580 +typeface, whether the typeface is proportional, and whether it is serif or
1.581 +sans-serif.
1.582 +
1.583 +The combination of attributes for a typeface are stored in a bitmask, with
1.584 +the various bits indicating different attributes. The bitmask is calculated
1.585 +for any particular attribute combination by ORing the enumerated value for
1.586 +each individual attribute.
1.587 +@publishedAll
1.588 +@released
1.589 +*/
1.590 +class TTypeface
1.591 + {
1.592 +public:
1.593 + enum
1.594 + {
1.595 + /** Typeface is a proportional typeface (e.g. Swiss)
1.596 + */
1.597 + EProportional = 1,
1.598 + /** Typeface is a serif typeface (e.g. Times)
1.599 + */
1.600 + ESerif = 2,
1.601 + /** Typeface is a symbol typeface (e.g. Symbol)
1.602 + */
1.603 + ESymbol = 4,
1.604 + };
1.605 +public:
1.606 + IMPORT_C TTypeface();
1.607 + IMPORT_C TBool operator==(const TTypeface& aTypeface) const;
1.608 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.609 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.610 + IMPORT_C void SetAttributes(TInt aAttributes);
1.611 + IMPORT_C void SetIsProportional(TBool aIsProportional);
1.612 + IMPORT_C void SetIsSerif(TBool aIsSerif);
1.613 + IMPORT_C void SetIsSymbol(TBool aIsSymbol);
1.614 + IMPORT_C TInt Attributes() const;
1.615 + IMPORT_C TBool IsProportional() const;
1.616 + IMPORT_C TBool IsSerif() const;
1.617 + IMPORT_C TBool IsSymbol() const;
1.618 + IMPORT_C void SetScriptTypeForMetrics(TLanguage aLanguage);
1.619 + IMPORT_C void SetScriptTypeForMetrics(TInt aScript);
1.620 + IMPORT_C TInt ScriptTypeForMetrics() const;
1.621 +private:
1.622 + void ResetAttributes();
1.623 + void ResetScriptType();
1.624 +public:
1.625 + /** The typeface name. */
1.626 + TBufC<KMaxTypefaceNameLength> iName;
1.627 +private:
1.628 + TUint32 iFlags;
1.629 + };
1.630 +
1.631 +
1.632 +/**
1.633 +An enumerated type for the format of a glyph bitmap. This type is currently
1.634 +used to indicate whether glyph bitmaps for scalable fonts are drawn anti-aliased.
1.635 +Additional values may be defined in the future.
1.636 +
1.637 +@see TFontStyle::SetBitmapType()
1.638 +@see CFbsTypefaceStore::SetDefaultBitmapType()
1.639 +@publishedAll
1.640 +@released
1.641 +*/
1.642 +enum TGlyphBitmapType
1.643 + {
1.644 + /** The font store's default glyph bitmap format is used. */
1.645 + EDefaultGlyphBitmap = 0,
1.646 + /** The standard monochrome format: no anti-aliasing, 1 bit per pixel,
1.647 + run-length encoded. */
1.648 + EMonochromeGlyphBitmap,
1.649 + /** Standard 8-bits-per-pixel with anti-aliasing. */
1.650 + EAntiAliasedGlyphBitmap,
1.651 + /** The format used when sub-pixel font rendering is used. */
1.652 + ESubPixelGlyphBitmap,
1.653 + /** The format used when outline and shadow font rendering is used.
1.654 +
1.655 + If the raterizer supports the outline and shadow fonts, it will set the bitmaptype as
1.656 + EFourColourBlendGlyphBitmap but only when glyph bitmap type is set as EAntiAliasedGlyphBitmap and
1.657 + when any of the EDropShadow or EOutline effect is on. Only rasterizer providers can use this enum.
1.658 +
1.659 + @publishedPartner
1.660 + */
1.661 + EFourColourBlendGlyphBitmap,
1.662 + };
1.663 +
1.664 +
1.665 +/**
1.666 +Defines a set of font effects flags.
1.667 +
1.668 +@publishedPartner For use by system/UI software.
1.669 +@released
1.670 +*/
1.671 +NONSHARABLE_CLASS(FontEffect)
1.672 + {
1.673 +public:
1.674 + enum TEffect
1.675 + {
1.676 + ENone = 0x0, // No effects.
1.677 + EAlgorithmicBold= 0x10, // Font is algorithmic bold (a.k.a pseudo bold.)
1.678 + EDropShadow = 0x20, // Font has a drop shadow.
1.679 + EOutline = 0x40, // Font is an outline font.
1.680 + EEmbossed = 0x80, // Font is embossed.
1.681 + EEngraved = 0x100, // Font is engraved.
1.682 + ESoftEdge = 0x200, // Font is soft edged.
1.683 + EReserved1 = 0x400, // Reserved for Symbian use.
1.684 + EReserved2 = 0x800, // Reserved for Symbian use.
1.685 + EReserved3 = 0x1000, // Reserved for Symbian use.
1.686 + EReserved4 = 0x2000, // Reserved for Symbian use.
1.687 + EReserved5 = 0x4000, // Reserved for Symbian use.
1.688 + EReserved6 = 0x8000, // Reserved for Symbian use.
1.689 + };
1.690 +public:
1.691 + IMPORT_C static TBool IsEffectOn(TEffect aEffect, TUint32 aFontEffect);
1.692 + IMPORT_C static void SetEffect(TEffect aEffect, TBool aOn, TUint32& aFontEffect);
1.693 + };
1.694 +
1.695 +
1.696 +/** Encapsulates a font style.
1.697 +
1.698 +The font style information is comprised of:
1.699 +
1.700 +the posture of the font upright or italic
1.701 +
1.702 +the stroke weight of the font normal or bold
1.703 +
1.704 +the print position of the font normal, subscript or superscript
1.705 +
1.706 +Note that the underline and strike-through attributes are not included in
1.707 +this class, but are set in the graphics context.
1.708 +
1.709 +@see CGraphicsContext::SetUnderlineStyle()
1.710 +@see CGraphicsContext::SetStrikethroughStyle()
1.711 +@publishedAll
1.712 +@released
1.713 +*/
1.714 +class TFontStyle
1.715 + {
1.716 +public:
1.717 + IMPORT_C TFontStyle();
1.718 + IMPORT_C TFontStyle(TFontPosture aPost,TFontStrokeWeight aStrWgt,TFontPrintPosition aPrintPos);
1.719 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.720 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.721 + IMPORT_C TFontPosture Posture() const;
1.722 + IMPORT_C TFontStrokeWeight StrokeWeight() const;
1.723 + IMPORT_C TFontPrintPosition PrintPosition() const;
1.724 + IMPORT_C void SetPosture(TFontPosture aPosture);
1.725 + IMPORT_C void SetStrokeWeight(TFontStrokeWeight aStrokeWeight);
1.726 + IMPORT_C void SetPrintPosition(TFontPrintPosition aPrintPosition);
1.727 + inline TGlyphBitmapType BitmapType() const;
1.728 + inline void SetBitmapType(TGlyphBitmapType aBitmapType);
1.729 + IMPORT_C TBool operator==(const TFontStyle& aFontStyle) const;
1.730 + IMPORT_C TUint32 Effects() const;
1.731 + IMPORT_C TBool IsEffectOn(FontEffect::TEffect aEffect) const;
1.732 + IMPORT_C void SetEffects(TUint32 aEffects);
1.733 + IMPORT_C void SetEffects(FontEffect::TEffect aEffect, TBool aOn);
1.734 +private:
1.735 + enum
1.736 + {
1.737 + EItalic=0x1,
1.738 + EBold=0x2,
1.739 + ESuper=0x4,
1.740 + ESub=0x8
1.741 + };
1.742 +private:
1.743 + TUint32 iFlags; // bitmap type - 16 bits (high), font effects - 12 bits (middle), style - 4 bits (low)
1.744 + TAny* iReserved1;
1.745 + TAny* iReserved2;
1.746 + };
1.747 +
1.748 +
1.749 +
1.750 +/**
1.751 +Specifies the font specification in device independent terms.
1.752 +@publishedAll
1.753 +@released
1.754 +*/
1.755 +class TFontSpec
1.756 + {
1.757 +public:
1.758 + IMPORT_C TFontSpec();
1.759 + IMPORT_C TFontSpec(const TDesC& aTypefaceName,TInt aHeight);
1.760 + IMPORT_C TBool operator==(const TFontSpec& aFontSpec) const;
1.761 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.762 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.763 + IMPORT_C void SetScriptTypeForMetrics(TLanguage aLanguage);
1.764 + IMPORT_C TInt ScriptTypeForMetrics() const;
1.765 +public:
1.766 + /** The typeface. */
1.767 + TTypeface iTypeface;
1.768 + /** The height of the typeface (in twips). */
1.769 + TInt iHeight;
1.770 + /** The font style of the typeface. */
1.771 + TFontStyle iFontStyle;
1.772 + };
1.773 +
1.774 +
1.775 +
1.776 +/** Typeface family support information.
1.777 +
1.778 +This data-only class includes the name and attributes of a typeface, how many
1.779 +font heights are available, its minimum and maximum heights, and whether or
1.780 +not it is scaleable a typeface is scaleable if it supports heights at
1.781 +fixed intervals between the minimum and maximum heights.
1.782 +@publishedAll
1.783 +@released
1.784 +*/
1.785 +class TTypefaceSupport
1.786 + {
1.787 +public:
1.788 + /** The name and attributes of the typeface. */
1.789 + TTypeface iTypeface;
1.790 + /** The number of distinct font heights available in the typeface. */
1.791 + TInt iNumHeights;
1.792 + /** The typeface's minimum font height, in twips. */
1.793 + TInt iMinHeightInTwips;
1.794 + /** The typeface's maximum font height, in twips. */
1.795 + TInt iMaxHeightInTwips;
1.796 + /** Whether the typeface is scaleable. ETrue if it is scaleable, otherwise
1.797 + EFalse. */
1.798 + TBool iIsScalable; // supports heights from min to max at fixed interval
1.799 + };
1.800 +
1.801 +/**
1.802 +The percentage used to multiply a normal font height when calculating its
1.803 +superscript or subscript height.
1.804 +@publishedAll
1.805 +@released
1.806 +*/
1.807 +const TInt KSuperSubScalingPercentage=67;
1.808 +
1.809 +/**
1.810 +The percentage of a font height used to calculate its baseline offset for a
1.811 +superscript print position.
1.812 +@publishedAll
1.813 +@released
1.814 +*/
1.815 +const TInt KSuperscriptOffsetPercentage=-28;
1.816 +
1.817 +/**
1.818 +The percentage of a font height used to calculate its baseline offset for a
1.819 +subscript print position.
1.820 +@publishedAll
1.821 +@released
1.822 +*/
1.823 +const TInt KSubscriptOffsetPercentage=14;
1.824 +
1.825 +class CFont;
1.826 +
1.827 +
1.828 +
1.829 +/** Typeface store abstract base interface.
1.830 +
1.831 +This class provides the interface to a store for typefaces.
1.832 +
1.833 +See also CFontStore.
1.834 +@publishedAll
1.835 +@released
1.836 +*/
1.837 +class CTypefaceStore : public CBase
1.838 + {
1.839 +public:
1.840 + IMPORT_C ~CTypefaceStore();
1.841 +
1.842 + /**
1.843 + Gets the font which is the nearest to the given font specification.
1.844 +
1.845 + When the font is no longer needed, call @c ReleaseFont().
1.846 +
1.847 + Note that this deprecated function is replaced by the new @c GetNearestFontToDesignHeightInTwips()
1.848 + yielding (virtually) the same result. However clients are strongly encouraged to use the new
1.849 + @c GetNearestFontToMaxHeightInTwips() function instead. This will guarantee that every
1.850 + character within any given text string will fit within the given amount of twips, whereas the design
1.851 + height is an aesthetic unit decided by the font designer without strict physical meaning, which
1.852 + may result in cropped characters.
1.853 +
1.854 + @param aFont On return, contains a pointer to the nearest font.
1.855 + @param aFontSpec The specification of the font to be matched.
1.856 + @return KErrNone if successful; a system-wide error code otherwise.
1.857 + @publishedAll
1.858 + @deprecated Use GetNearestFontToDesignHeightInTwips
1.859 + */
1.860 + virtual TInt GetNearestFontInTwips(CFont*& aFont, const TFontSpec& aFontSpec) = 0;
1.861 +
1.862 + /**
1.863 + Gets the font which is the nearest to the given font specification.
1.864 +
1.865 + When the font is no longer needed, call @c ReleaseFont().
1.866 +
1.867 + This new function replaces the deprecated @c GetNearestFontInTwips() yielding (virtually) the
1.868 + same result. However clients are strongly encouraged to use the new
1.869 + @c GetNearestFontToMaxHeightInTwips() function instead. This will guarantee that every
1.870 + character within any given text string will fit within the given amount of twips, whereas the design
1.871 + height is an aesthetic unit decided by the font designer without strict physical meaning, which
1.872 + may result in cropped characters.
1.873 +
1.874 + @param aFont On return, contains a pointer to the nearest font.
1.875 + @param aFontSpec The specification of the font to be matched.
1.876 + @return KErrNone if successful; a system-wide error code otherwise.
1.877 + @publishedAll
1.878 + @released
1.879 + */
1.880 + virtual TInt GetNearestFontToDesignHeightInTwips(CFont*& aFont, const TFontSpec& aFontSpec) = 0;
1.881 +
1.882 + /**
1.883 + Gets the font which is the nearest to the given font specification.
1.884 +
1.885 + When the font is no longer needed, call @c ReleaseFont().
1.886 +
1.887 + The font and bitmap server returns a pointer to the nearest matching font
1.888 + from those available. Matches to max height of font - this does its best
1.889 + to return a font that will fit within the maximum height specified (but
1.890 + note that variations due to hinting algorithms may rarely result in this
1.891 + height being exceeded by up to one pixel). Problems can also be
1.892 + encountered with bitmap fonts where the typeface exists but doesn't have
1.893 + a font small enough.
1.894 +
1.895 + @param aFont On return, contains a pointer to the nearest font.
1.896 + @param aFontSpec The specification of the font to be matched.
1.897 + @param aMaxHeight The maximum height within which the font must fit.
1.898 + @return KErrNone if successful; a system-wide error code otherwise.
1.899 + @publishedAll
1.900 + @released
1.901 + */
1.902 + virtual TInt GetNearestFontToMaxHeightInTwips(CFont*& aFont, const TFontSpec& aFontSpec, TInt aMaxHeight) = 0;
1.903 +
1.904 + /** Gets the number of typefaces supported by the typeface store.
1.905 +
1.906 + @return The number of supported typefaces. */
1.907 + virtual TInt NumTypefaces() const=0;
1.908 +
1.909 + /** Gets typeface information for a specified typeface index.
1.910 +
1.911 + This information is returned in aTypefaceSupport, and
1.912 + includes the typeface name and typeface attributes, the number of font
1.913 + heights, the maximum and minimum font heights, and whether it is a
1.914 + scaleable typeface.
1.915 +
1.916 + @param aTypefaceSupport On return, if the function executed successfully,
1.917 + this object contains the typeface information.
1.918 + @param aTypefaceIndex A typeface index number, in the range: zero to
1.919 + (NumTypefaces() - 1). */
1.920 + virtual void TypefaceSupport(TTypefaceSupport& aTypefaceSupport,TInt aTypefaceIndex) const=0;
1.921 +
1.922 + /** Gets the height of the font with specified height and typeface indices,
1.923 + in twips.
1.924 +
1.925 + The value returned is rounded up or down to the nearest font height in twips.
1.926 +
1.927 + @param aTypefaceIndex A typeface index number, in the range: 0 to
1.928 + (NumTypefaces() - 1).
1.929 + @param aHeightIndex A font height index number.
1.930 + @return The height of the font, in twips. */
1.931 + virtual TInt FontHeightInTwips(TInt aTypefaceIndex,TInt aHeightIndex) const=0;
1.932 + IMPORT_C void ReleaseFont(CFont* aFont);
1.933 + IMPORT_C static TInt BaselineOffset(TInt aHeight,TFontPrintPosition aPos);
1.934 + IMPORT_C static TInt SuperSubHeight(TInt aHeight,TFontPrintPosition aPos);
1.935 +protected:
1.936 + IMPORT_C CTypefaceStore();
1.937 + IMPORT_C void ConstructL();
1.938 + IMPORT_C void AddFontL(CFont* aFont);
1.939 + IMPORT_C TBool IncrementFontCount(const CFont* aFont);
1.940 +private:
1.941 + TBool FindFont(const CFont* aFont, TInt& aIdx) const;
1.942 +
1.943 + NONSHARABLE_CLASS(TFontAccess)
1.944 + /**
1.945 + Pairs a font with a count of how many clients of the typeface store
1.946 + are accessing that font.
1.947 + @internalTechnology
1.948 + */
1.949 + {
1.950 + public:
1.951 + /** A device specific font. */
1.952 + CFont* iFont;
1.953 + /** The number of clients accessing the font. */
1.954 + TInt iAccessCount;
1.955 + };
1.956 +protected:
1.957 + /** A list of fonts accessed by clients of the typeface store, which pairs
1.958 + a font with a count of the number of clients accessing the font.
1.959 +
1.960 + Implemented as an array of TFontAccess objects.
1.961 +
1.962 + An object is added to this array for every font accessed. If the font is
1.963 + released by all clients, and the access count drops to zero, the font is
1.964 + removed from the list. */
1.965 + CArrayFixFlat<TFontAccess>* iFontAccess;
1.966 + };
1.967 +
1.968 +/** The maximum number of entries in the font cache.
1.969 +
1.970 +@see CFontCache */
1.971 +const TInt KMaxFontCacheEntries=32;
1.972 +
1.973 +/** Font cache.
1.974 +
1.975 +When a CFont* needs to be found for a particular TFontSpec, the cache can
1.976 +be searched to see if the TFontSpec is already in the cache. If the TFontSpec
1.977 +is in the cache, its corresponding CFont* can be returned. Otherwise
1.978 +GetNearestFontInTwips() must be used to search all of the available fonts for
1.979 +the nearest CFont- a procedure which takes much longer than a simple cache
1.980 +search.
1.981 +
1.982 +The current font cache should be destroyed and a new cache created whenever
1.983 +the zoom factor or device map changes, as these changes break the relation
1.984 +between CFont and TFontSpec.
1.985 +@publishedAll
1.986 +@released
1.987 +*/
1.988 +class CFontCache : public CBase
1.989 + {
1.990 +public:
1.991 + IMPORT_C CFontCache();
1.992 + IMPORT_C CFontCache(TInt aMaxEntries);
1.993 + IMPORT_C ~CFontCache();
1.994 + IMPORT_C CFont* Search(const TFontSpec& aFontSpec);
1.995 + IMPORT_C CFont* AddEntryL(CFont* aFont,const TFontSpec& aFontSpec);
1.996 + IMPORT_C CFont* RemoveFirstEntry();
1.997 +public:
1.998 + /** The number of cache hits since the font cache was created i.e.
1.999 + successful results from CFontCache::Search(). */
1.1000 + TInt iNumHits;
1.1001 + /** The number of cache misses since the font cache was created i.e.
1.1002 + unsuccessful results from CFontCache::Search(). */
1.1003 + TInt iNumMisses;
1.1004 +private:
1.1005 + class CFontCacheEntry : public CBase
1.1006 + {
1.1007 + public:
1.1008 + CFontCacheEntry(CFont* aFont,const TFontSpec& aFontSpec,CFontCacheEntry* aNext);
1.1009 + public:
1.1010 + CFont* iFont;
1.1011 + TFontSpec iSpec;
1.1012 + CFontCacheEntry* iNext;
1.1013 + };
1.1014 +private:
1.1015 + TInt iNumEntries;
1.1016 + TInt iMaxEntries;
1.1017 + CFontCacheEntry* iFirst;
1.1018 + };
1.1019 +
1.1020 +/** Interface class for mapping between twips and device-specific units (pixels).
1.1021 +
1.1022 +TZoomFactor is derived from MGraphicsDeviceMap.
1.1023 +
1.1024 +@see CGraphicsDevice
1.1025 +@see TZoomFactor
1.1026 +@publishedAll
1.1027 +@released
1.1028 +*/
1.1029 +class MGraphicsDeviceMap
1.1030 + {
1.1031 +public:
1.1032 + IMPORT_C MGraphicsDeviceMap();
1.1033 + IMPORT_C virtual ~MGraphicsDeviceMap();
1.1034 + IMPORT_C TPoint TwipsToPixels(const TPoint& aTwipPoint) const;
1.1035 + IMPORT_C TRect TwipsToPixels(const TRect& aTwipRect) const;
1.1036 + IMPORT_C TPoint PixelsToTwips(const TPoint& aPixelPoint) const;
1.1037 + IMPORT_C TRect PixelsToTwips(const TRect& aPixelRect) const;
1.1038 +
1.1039 + /** Converts a horizontal dimension from twips to pixels.
1.1040 +
1.1041 + An implementation is supplied by a derived class.
1.1042 +
1.1043 + @param aTwips A horizontal dimension of a device in twips.
1.1044 + @return A horizontal dimension of a device in pixels. */
1.1045 + virtual TInt HorizontalTwipsToPixels(TInt aTwips) const=0;
1.1046 +
1.1047 + /** Converts a vertical dimension from twips to pixels.
1.1048 +
1.1049 + An implementation is supplied by a derived class.
1.1050 +
1.1051 + @param aTwips A vertical dimension of a device in twips.
1.1052 + @return A vertical dimension of a device in pixels. */
1.1053 + virtual TInt VerticalTwipsToPixels(TInt aTwips) const=0;
1.1054 +
1.1055 + /** Converts a horizontal dimension from pixels to twips.
1.1056 +
1.1057 + An implementation is supplied by a derived class.
1.1058 +
1.1059 + @param aPixels A horizontal dimension of a device in pixels.
1.1060 + @return A horizontal dimension of a device in twips. */
1.1061 + virtual TInt HorizontalPixelsToTwips(TInt aPixels) const=0;
1.1062 +
1.1063 + /** Converts a vertical dimension from pixels to twips.
1.1064 +
1.1065 + An implementation is supplied by a derived class.
1.1066 +
1.1067 + @param aPixels A vertical dimension of a device in pixels.
1.1068 + @return A vertical dimension of a device in twips. */
1.1069 + virtual TInt VerticalPixelsToTwips(TInt aPixels) const=0;
1.1070 +
1.1071 + /**
1.1072 + Gets the font which is the nearest to the given font specification.
1.1073 +
1.1074 + When the font is no longer needed, call @c ReleaseFont().
1.1075 +
1.1076 + Note that this deprecated function is replaced by the new @c GetNearestFontToDesignHeightInTwips()
1.1077 + yielding (virtually) the same result. However clients are strongly encouraged to use the new
1.1078 + @c GetNearestFontToMaxHeightInTwips() function instead. This will guarantee that every
1.1079 + character within any given text string will fit within the given amount of twips, whereas the design
1.1080 + height is an aesthetic unit decided by the font designer without strict physical meaning, which
1.1081 + may result in cropped characters.
1.1082 +
1.1083 + @param aFont On return, contains a pointer to the nearest font.
1.1084 + @param aFontSpec The specification of the font to be matched.
1.1085 + @return KErrNone if successful; a system-wide error code otherwise.
1.1086 + @publishedAll
1.1087 + @deprecated Use GetNearestFontToDesignHeightInTwips
1.1088 + */
1.1089 + virtual TInt GetNearestFontInTwips(CFont*& aFont,const TFontSpec& aFontSpec)=0;
1.1090 +
1.1091 + /**
1.1092 + Gets the font which is the nearest to the given font specification.
1.1093 +
1.1094 + When the font is no longer needed, call @c ReleaseFont().
1.1095 +
1.1096 + This new function replaces the deprecated @c GetNearestFontInTwips() yielding (virtually) the
1.1097 + same result. However clients are strongly encouraged to use the new
1.1098 + @c GetNearestFontToMaxHeightInTwips() function instead. This will guarantee that every
1.1099 + character within any given text string will fit within the given amount of twips, whereas the design
1.1100 + height is an aesthetic unit decided by the font designer without strict physical meaning, which
1.1101 + may result in cropped characters.
1.1102 +
1.1103 + @param aFont On return, contains a pointer to the nearest font.
1.1104 + @param aFontSpec The specification of the font to be matched.
1.1105 + @return KErrNone if successful; a system-wide error code otherwise.
1.1106 + @publishedAll
1.1107 + @released
1.1108 + */
1.1109 + virtual TInt GetNearestFontToDesignHeightInTwips(
1.1110 + CFont*& /*aFont*/, const TFontSpec& /*aFontSpec*/) { return KErrNotSupported; }
1.1111 +
1.1112 + /**
1.1113 + Gets the font which is the nearest to the given font specification.
1.1114 +
1.1115 + When the font is no longer needed, call @c ReleaseFont().
1.1116 +
1.1117 + The font and bitmap server returns a pointer to the nearest matching font
1.1118 + from those available. Matches to max height of font - this does its best
1.1119 + to return a font that will fit within the maximum height specified (but
1.1120 + note that variations due to hinting algorithms may rarely result in this
1.1121 + height being exceeded by up to one pixel). Problems can also be
1.1122 + encountered with bitmap fonts where the typeface exists but doesn't have
1.1123 + a font small enough.
1.1124 +
1.1125 + @param aFont On return, contains a pointer to the nearest font.
1.1126 + @param aFontSpec The specification of the font to be matched.
1.1127 + @param aMaxHeight The maximum height within which the font must fit.
1.1128 + This overrides the height specified in aFontSpec.
1.1129 + @return KErrNone if successful; a system-wide error code otherwise.
1.1130 + @publishedAll
1.1131 + @released
1.1132 + */
1.1133 + virtual TInt GetNearestFontToMaxHeightInTwips(
1.1134 + CFont*& /*aFont*/, const TFontSpec& /*aFontSpec*/, TInt /*aMaxHeight*/) { return KErrNotSupported; }
1.1135 +
1.1136 + /** Releases the specified font.
1.1137 +
1.1138 + It is used to indicate that the specified font is no longer needed for use
1.1139 + by the device map. As fonts can be shared between applications, this
1.1140 + function does not delete the copy of the font from RAM unless the font was
1.1141 + only being used by this particular device map.
1.1142 +
1.1143 + An implementation is supplied by a derived class.
1.1144 +
1.1145 + @param aFont A pointer to the font to be released. */
1.1146 + virtual void ReleaseFont(CFont* aFont)=0;
1.1147 + };
1.1148 +
1.1149 +class CGraphicsContext;
1.1150 +
1.1151 +/** Specifies the interface for concrete device classes.
1.1152 +
1.1153 +It holds information on the capabilities and attributes of a graphics device.
1.1154 +The CBitmapDevice and CPrinterDevice classes are derived from CGraphicsDevice.
1.1155 +
1.1156 +@see CGraphicsDevice
1.1157 +@see CPrinterDevice
1.1158 +@publishedAll
1.1159 +@released
1.1160 +*/
1.1161 +class CGraphicsDevice : public CBase , public MGraphicsDeviceMap
1.1162 + {
1.1163 +public:
1.1164 + /** Gets the display mode of the device.
1.1165 +
1.1166 + @return The display mode of the device. */
1.1167 + virtual TDisplayMode DisplayMode() const=0;
1.1168 +
1.1169 + /** Gets the size of the device area in pixels.
1.1170 +
1.1171 + @return The width and height of the device area, in pixels */
1.1172 + virtual TSize SizeInPixels() const=0;
1.1173 +
1.1174 + /** Gets the size of the device area in twips.
1.1175 +
1.1176 + @return The width and height of the device area, in twips */
1.1177 + virtual TSize SizeInTwips() const=0;
1.1178 +
1.1179 + /** Creates a graphics context for the device.
1.1180 +
1.1181 + @param aGC On return, contains a pointer to the created graphics context.
1.1182 + @return KErrNone, if successful; otherwise, another of the system-wide error
1.1183 + codes. */
1.1184 + virtual TInt CreateContext(CGraphicsContext*& aGC)=0;
1.1185 +
1.1186 + /** Gets the number of typefaces supported by the graphics device.
1.1187 +
1.1188 + @return The number of typefaces supported. */
1.1189 + virtual TInt NumTypefaces() const=0;
1.1190 +
1.1191 + /** Gets typeface information for a specified typeface.
1.1192 +
1.1193 + This information is returned in aTypefaceSupport, and includes:
1.1194 +
1.1195 + the typeface name and typeface attributes
1.1196 +
1.1197 + the number of font heights
1.1198 +
1.1199 + the maximum and minimum font heights
1.1200 +
1.1201 + whether it is a scalable typeface
1.1202 +
1.1203 + @param aTypefaceSupport On return, contains the typeface information.
1.1204 + @param aTypefaceIndex A typeface index number, in the range: zero to
1.1205 + (NumTypefaces() - 1).
1.1206 + @see NumTypefaces() */
1.1207 + virtual void TypefaceSupport(TTypefaceSupport& aTypefaceSupport,TInt aTypefaceIndex) const=0;
1.1208 +
1.1209 + /** Get the height of a font in twips.
1.1210 +
1.1211 + The font is identified by typeface and height.
1.1212 +
1.1213 + The value returned is rounded up or down to the nearest font height in twips.
1.1214 +
1.1215 + @param aTypefaceIndex An index identifying the typeface, in the range: 0
1.1216 + to (NumTypefaces() - 1).
1.1217 + @param aHeightIndex An index identifying the font height, in the range: 0
1.1218 + to (iNumHeights - 1). Note that iNumHeights is in the TTypefaceSupport
1.1219 + object returned by TypefaceSupport().
1.1220 + @return The height of the font, in twips. */
1.1221 + virtual TInt FontHeightInTwips(TInt aTypefaceIndex,TInt aHeightIndex) const=0;
1.1222 +
1.1223 + /** Gets the palette attributes of the device.
1.1224 +
1.1225 + @param aModifiable On return, holds information on whether or not the device's
1.1226 + palette is modifiable (ETrue) or fixed (EFalse).
1.1227 + @param aNumEntries On return, holds the number of entries in the device's
1.1228 + palette. */
1.1229 + virtual void PaletteAttributes(TBool& aModifiable,TInt& aNumEntries) const=0;
1.1230 +
1.1231 + /** Sets the device's palette.
1.1232 +
1.1233 + @param aPalette The new palette for the device. */
1.1234 + virtual void SetPalette(CPalette* aPalette)=0;
1.1235 +
1.1236 + /** Gets the device's current palette.
1.1237 +
1.1238 + @param aPalette On return, holds the device's current palette.
1.1239 + @return KErrNone, if successful; otherwise, another of the system-wide error
1.1240 + codes. */
1.1241 + virtual TInt GetPalette(CPalette*& aPalette) const=0;
1.1242 + };
1.1243 +
1.1244 +
1.1245 +/**
1.1246 +Code section range information.
1.1247 +
1.1248 +A code section defines the bitmaps for characters in a specified range -
1.1249 +the range is stored in objects of this type.
1.1250 +@publishedAll
1.1251 +@deprecated This is not used anywhere in version 6.0.
1.1252 +*/
1.1253 +class TCodeSection
1.1254 + {
1.1255 +public:
1.1256 + /** The beginning of the range. */
1.1257 + TInt iStart;
1.1258 + /** The end of the range. */
1.1259 + TInt iEnd;
1.1260 + };
1.1261 +
1.1262 +/**
1.1263 +UIDs corresponding to the CFont API extension functions
1.1264 +@internalTechnology
1.1265 +@released
1.1266 +*/
1.1267 +const TUid KFontCapitalAscent = {0x1020498E};
1.1268 +const TUid KFontMaxAscent = {0x10204B10};
1.1269 +const TUid KFontStandardDescent = {0x10204B11};
1.1270 +const TUid KFontMaxDescent = {0x10205AFC};
1.1271 +const TUid KFontLineGap = {0x10204B12};
1.1272 +
1.1273 +
1.1274 +
1.1275 +/** Abstract font interface.
1.1276 +
1.1277 +The CFont class provides a device-independent interface to a device-dependent
1.1278 +font usually obtained from a call to GetNearestFont...() on a graphics device.
1.1279 +It is used as a handle in CGraphicsContext::UseFont() and to obtain
1.1280 +device-dependent information about the font - notably the pixel width of a text
1.1281 +string.
1.1282 +
1.1283 +@see CFbsFont
1.1284 +@see CGraphicsContext::UseFont()
1.1285 +@publishedAll
1.1286 +@released
1.1287 +*/
1.1288 +class CFont : public CBase
1.1289 + {
1.1290 + friend class CTypefaceStore;
1.1291 +public:
1.1292 +
1.1293 + /** Text direction flags.
1.1294 +
1.1295 + This enum is used in TMeasureTextInput and determines whether the text is
1.1296 + drawn horizontally or vertically. Note: text is drawn vertically in some
1.1297 + styles of Japanese, etc.
1.1298 +
1.1299 + @see TMeasureTextInput */
1.1300 + enum TTextDirection
1.1301 + {
1.1302 + /** Text is drawn horizontally. */
1.1303 + /** Text is drawn horizontally. */
1.1304 + EHorizontal,
1.1305 + /** Text is drawn vertically. */
1.1306 + EVertical
1.1307 + };
1.1308 +
1.1309 + /** Complicated parameter block used for contextual glyph selection,
1.1310 + ligature creation and diacritic placement when drawing text in complex
1.1311 + scripts
1.1312 +
1.1313 + This class declares a constructor, another scoped class, and several other
1.1314 + enums. However this class is unlikely to be useful to third party developers.
1.1315 +
1.1316 + @see CFont::GetCharacterPosition()
1.1317 + @see CFont::GetCharacterPosition2()
1.1318 + @publishedAll
1.1319 + @released
1.1320 + */
1.1321 + class TPositionParam
1.1322 + {
1.1323 + public:
1.1324 + /** Standard constructor. */
1.1325 + TPositionParam():
1.1326 + iDirection(EHorizontal),
1.1327 + iFlags(0),
1.1328 + iPosInText(0),
1.1329 + iOutputGlyphs(0)
1.1330 + {
1.1331 + }
1.1332 +
1.1333 + enum
1.1334 + {
1.1335 + EMaxInputChars = 18, // ligatures cannot be made from more than 18 components
1.1336 + EMaxOutputGlyphs = 8 // output can consist of up to 8 characters (one base and 7 combining characters)
1.1337 + };
1.1338 +
1.1339 + /**Flags for TPositionParam::iFlags. */
1.1340 + enum TFlags
1.1341 + {
1.1342 + /** Input text is logically ordered not visually ordered. */
1.1343 + EFLogicalOrder = 1
1.1344 + };
1.1345 +
1.1346 + /** Input: Orientation (EHorizontal or EVertical) in which to draw
1.1347 + the text. */
1.1348 + TInt16 iDirection;
1.1349 + /** Input: Flags from TFlags. */
1.1350 + TUint16 iFlags;
1.1351 + /** Input: Text containing the characters to be positioned. */
1.1352 + TPtrC iText;
1.1353 +
1.1354 + /** Input and output: Position within iText to shape. On exit
1.1355 + it will index the first character not positioned */
1.1356 + TInt iPosInText;
1.1357 + /** Input and output: Pen position. */
1.1358 + TPoint iPen;
1.1359 +
1.1360 + /** Output of GetCharacterPosition and GetCharacterPosition2.
1.1361 + @see CFont::GetCharacterPosition
1.1362 + @see CFont::GetCharacterPosition2
1.1363 + @publishedAll
1.1364 + @released */
1.1365 + class TOutput
1.1366 + {
1.1367 + public:
1.1368 + /** Standard constructor. */
1.1369 + TOutput() : iBitmapSize(TSize::EUninitialized),
1.1370 + iBounds(TRect::EUninitialized) {}
1.1371 + /** Character or glyph code. */
1.1372 + TUint iCode;
1.1373 + /** Bitmap data for the glyph, if available */
1.1374 + const TUint8* iBitmap;
1.1375 + /** Size of the bitmap before algorithmic bolding, size
1.1376 + multiplication, etc. */
1.1377 + TSize iBitmapSize;
1.1378 + /** Bitmap bounds relative to the original pen position. */
1.1379 + TRect iBounds;
1.1380 + };
1.1381 +
1.1382 + /** Information about the glyphs that were output. */
1.1383 + TOutput iOutput[EMaxOutputGlyphs];
1.1384 + /** Number of glyphs actually output. */
1.1385 + TInt iOutputGlyphs;
1.1386 + };
1.1387 +
1.1388 +
1.1389 + /** Input parameter block.
1.1390 +
1.1391 + This is optionally used by CFont::MeasureText(), which is the powerful text
1.1392 + measurement function underlying all the other text measurement functions.
1.1393 +
1.1394 + @see CFont::MeasureText()
1.1395 + @publishedAll
1.1396 + @released
1.1397 + */
1.1398 + class TMeasureTextInput
1.1399 + {
1.1400 + public:
1.1401 + TMeasureTextInput():
1.1402 + iStartInputChar(0),
1.1403 + iEndInputChar(KMaxTInt),
1.1404 + iDirection(EHorizontal),
1.1405 + iFlags(0),
1.1406 + iMaxAdvance(KMaxTInt),
1.1407 + iMaxBounds(KMaxTInt),
1.1408 + iCharJustNum(0),
1.1409 + iCharJustExcess(0),
1.1410 + iWordJustNum(0),
1.1411 + iWordJustExcess(0)
1.1412 + {
1.1413 + }
1.1414 +
1.1415 + /**Flags for TMeasureTextInput::iFlags. */
1.1416 + enum TFlags
1.1417 + {
1.1418 + /** Input text is visually ordered left-to-right. */
1.1419 + EFVisualOrder = 1,
1.1420 + /** Input text is visually ordered right-to-left.
1.1421 + Overrides EFVisualOrder. */
1.1422 + EFVisualOrderRightToLeft = 2,
1.1423 + /** Flag to consider side bearings when checking bounds for line-break */
1.1424 + EFIncludePenPositionInBoundsCheck = 4
1.1425 + };
1.1426 +
1.1427 + /** Starting index specifying first input character in iText.
1.1428 +
1.1429 + Together with iEndInputChar, this allows some context before and
1.1430 + after the measured text to be supplied so that shaping can work
1.1431 + properly. */
1.1432 + TInt iStartInputChar;
1.1433 +
1.1434 + /** Index specifying the final input character.
1.1435 +
1.1436 + Together with iStartInputChar, this allows some context before and
1.1437 + after the measured text to be supplied so that shaping can work
1.1438 + properly. */
1.1439 + TInt iEndInputChar;
1.1440 +
1.1441 + /** The direction in which to draw the text. */
1.1442 + TUint16 iDirection;
1.1443 +
1.1444 + /** Flags from TFlags. */
1.1445 + TUint16 iFlags;
1.1446 +
1.1447 + /** The maximum advance. */
1.1448 + TInt iMaxAdvance;
1.1449 +
1.1450 + /** The maximum width (or height if drawing vertically) of bounds. */
1.1451 + TInt iMaxBounds;
1.1452 +
1.1453 + /** The number of glyph groups to be letter-spaced. */
1.1454 + TInt iCharJustNum;
1.1455 +
1.1456 + /** The amount of space to be used for letter spacing. */
1.1457 + TInt iCharJustExcess;
1.1458 +
1.1459 + /** The number of spaces to be used for word spacing. */
1.1460 + TInt iWordJustNum;
1.1461 +
1.1462 + /** The amount of space to be used for word spacing. */
1.1463 + TInt iWordJustExcess;
1.1464 + };
1.1465 +
1.1466 + /** Output parameter block.
1.1467 +
1.1468 + This is optionally used by CFont::MeasureText(), which is the powerful text
1.1469 + measurement function underlying all the other text measurement functions.
1.1470 +
1.1471 + @see CFont::MeasureText()
1.1472 + @publishedAll
1.1473 + @released
1.1474 + */
1.1475 + class TMeasureTextOutput
1.1476 + {
1.1477 + public:
1.1478 + /** The number of input characters that would be drawn.
1.1479 +
1.1480 + This may be less than the length of the text if a maximum advance or bounding
1.1481 + box size is specified. */
1.1482 + TInt iChars;
1.1483 + /** The number of glyphs that would be drawn. */
1.1484 + TInt iGlyphs;
1.1485 + /** The number of groups that would be drawn.
1.1486 +
1.1487 + A group is a base glyph plus one or more combining characters. */
1.1488 + TInt iGroups;
1.1489 + /** The number of word spaces (U+0020) that would be drawn. */
1.1490 + TInt iSpaces;
1.1491 + /** The bounding box of all the glyphs that would be drawn. */
1.1492 + TRect iBounds;
1.1493 + /** The maximum width and height of any glyph. */
1.1494 + TSize iMaxGlyphSize;
1.1495 + };
1.1496 +
1.1497 + /**
1.1498 + Data availability flags.
1.1499 +
1.1500 + Some fonts like printer fonts may only have width information and can return
1.1501 + ECharacterWidthOnly to show this: the text drawing routines in CFont synthesize
1.1502 + the rest of the data if necessary.
1.1503 +
1.1504 + @see GetCharacterData()
1.1505 + @publishedAll
1.1506 + @released
1.1507 + */
1.1508 + enum TCharacterDataAvailability
1.1509 + {
1.1510 + /** No font information available. */
1.1511 + ENoCharacterData,
1.1512 + /** Width information only is available. */
1.1513 + ECharacterWidthOnly,
1.1514 + /** All character data is available. */
1.1515 + EAllCharacterData
1.1516 + };
1.1517 +
1.1518 +private:
1.1519 + // virtual functions have been made protected and public non-virtual ones
1.1520 + // added to convert CFont to a handle-body pattern. SC is kept throught the
1.1521 + // new functions and BC is kept by keeping the protected functions in the
1.1522 + // same place in the class, and therefore in the same place in the vtable
1.1523 +
1.1524 + /**
1.1525 + This member is internal and not intended for use. Please see derived class for implementation
1.1526 + @internalTechnology
1.1527 + */
1.1528 + virtual TUid DoTypeUid() const=0;
1.1529 + /**
1.1530 + This member is internal and not intended for use. Please see derived class for implementation
1.1531 + @internalTechnology
1.1532 + */
1.1533 + virtual TInt DoHeightInPixels() const=0;
1.1534 + /**
1.1535 + This member is internal and not intended for use. Please see derived class for implementation
1.1536 + @internalTechnology
1.1537 + */
1.1538 + virtual TInt DoAscentInPixels() const=0;
1.1539 + IMPORT_C virtual TInt DoDescentInPixels() const;
1.1540 + /**
1.1541 + This member is internal and not intended for use. Please see derived class for implementation
1.1542 + @internalTechnology
1.1543 + */
1.1544 + virtual TInt DoCharWidthInPixels(TChar aChar) const=0;
1.1545 + /**
1.1546 + This member is internal and not intended for use. Please see derived class for implementation
1.1547 + @internalTechnology
1.1548 + */
1.1549 + virtual TInt DoTextWidthInPixels(const TDesC& aText) const=0;
1.1550 + /**
1.1551 + This member is internal and not intended for use. Please see derived class for implementation
1.1552 + @internalTechnology
1.1553 + */
1.1554 + virtual TInt DoBaselineOffsetInPixels() const=0;
1.1555 + /**
1.1556 + This member is internal and not intended for use. Please see derived class for implementation
1.1557 + @internalTechnology
1.1558 + */
1.1559 + virtual TInt DoTextCount(const TDesC& aText,TInt aWidthInPixels) const=0;
1.1560 + /**
1.1561 + This member is internal and not intended for use. Please see derived class for implementation
1.1562 + @internalTechnology
1.1563 + */
1.1564 + virtual TInt DoTextCount(const TDesC& aText,TInt aWidthInPixels,TInt& aExcessWidthInPixels) const=0;
1.1565 + /**
1.1566 + This member is internal and not intended for use. Please see derived class for implementation
1.1567 + @internalTechnology
1.1568 + */
1.1569 + virtual TInt DoMaxCharWidthInPixels() const=0;
1.1570 + /**
1.1571 + This member is internal and not intended for use. Please see derived class for implementation
1.1572 + @internalTechnology
1.1573 + */
1.1574 + virtual TInt DoMaxNormalCharWidthInPixels() const=0;
1.1575 + /**
1.1576 + This member is internal and not intended for use. Please see derived class for implementation
1.1577 + @internalTechnology
1.1578 + */
1.1579 + virtual TFontSpec DoFontSpecInTwips() const=0;
1.1580 +
1.1581 +protected:
1.1582 + IMPORT_C virtual TCharacterDataAvailability DoGetCharacterData(TUint aCode, TOpenFontCharMetrics& aMetrics,const TUint8*& aBitmap,TSize& aBitmapSize) const;
1.1583 + IMPORT_C virtual TBool DoGetCharacterPosition(TPositionParam& aParam) const;
1.1584 + IMPORT_C virtual TInt DoExtendedFunction(TUid aFunctionId, TAny* aParam = NULL) const;
1.1585 +
1.1586 +protected:
1.1587 + IMPORT_C virtual ~CFont();
1.1588 +
1.1589 +public:
1.1590 + inline TInt FontCapitalAscent() const;
1.1591 + inline TInt FontMaxAscent() const;
1.1592 + inline TInt FontStandardDescent() const;
1.1593 + inline TInt FontMaxDescent() const;
1.1594 + inline TInt FontLineGap() const;
1.1595 + inline TInt FontMaxHeight() const;
1.1596 +
1.1597 +public:
1.1598 + /** Gets run-time identity of the actual font type. This enables safe casting to
1.1599 + a derived type.
1.1600 +
1.1601 + For example, if the derived type is a CFbsFont, the return value is KCFbsFontUid.
1.1602 + You would need to cast to a CFbsFont to get a character bounding box. Similarly,
1.1603 + a CBitmapFont returns KCBitmapFontUidVal.
1.1604 +
1.1605 + @return The font-type identifier. */
1.1606 + IMPORT_C TUid TypeUid() const;
1.1607 +
1.1608 + /** Gets the font height in pixels.
1.1609 + Note that this deprecated function is replaced by the new @c FontMaxHeight().
1.1610 +
1.1611 + @return The font height in pixels.
1.1612 + @see FontMaxHeight()
1.1613 + @deprecated */
1.1614 + IMPORT_C TInt HeightInPixels() const;
1.1615 +
1.1616 + /** Gets the font ascent in pixels.
1.1617 + Note that this deprecated function is replaced by the new @c FontMaxAscent()
1.1618 + or in some cases @c FontCapitalAscent().
1.1619 +
1.1620 + @return The font ascent in pixels.
1.1621 + @see FontCapitalAscent()
1.1622 + @see FontMaxAscent()
1.1623 + @deprecated */
1.1624 + IMPORT_C TInt AscentInPixels() const;
1.1625 +
1.1626 + /** Gets the font descent in pixels.
1.1627 + Note that this deprecated function is replaced by the new @c FontMaxDescent()
1.1628 + or in some cases @c FontStandardDescent().
1.1629 +
1.1630 + @return The font descent in pixels.
1.1631 + @see FontStandardDescent()
1.1632 + @see FontMaxDescent()
1.1633 + @deprecated */
1.1634 + IMPORT_C TInt DescentInPixels() const;
1.1635 +
1.1636 + /** Gets the width in pixels in this font of the specified character.
1.1637 +
1.1638 + Note: For OpenType fonts this function returns the horizontal advance of
1.1639 + the character, which may be different from the actual width.
1.1640 +
1.1641 + @param aChar The character whose width should be determined.
1.1642 + @return The width in pixels of the specified character in this font. */
1.1643 + IMPORT_C TInt CharWidthInPixels(TChar aChar) const;
1.1644 +
1.1645 + /** Gets the width in pixels of the specified descriptor when displayed in this
1.1646 + font.
1.1647 +
1.1648 + @param aText The descriptor whose width should be determined.
1.1649 + @return The width of the specified descriptor when displayed in this font,
1.1650 + in pixels. */
1.1651 + IMPORT_C TInt TextWidthInPixels(const TDesC& aText) const;
1.1652 +
1.1653 + /** Gets the baseline offset in pixels.
1.1654 +
1.1655 + The baseline offset is how far a font is raised or lowered from its normal
1.1656 + baseline.
1.1657 +
1.1658 + @return Offset from normal baseline, in pixels. */
1.1659 + IMPORT_C TInt BaselineOffsetInPixels() const;
1.1660 +
1.1661 + /** Gets how much of the specified descriptor can be displayed in this font without
1.1662 + exceeding the specified width.
1.1663 +
1.1664 + Note:
1.1665 +
1.1666 + This function does not display any of the descriptor itself - it is used
1.1667 + before display, to test whether the whole descriptor can be displayed.
1.1668 +
1.1669 + @param aText The descriptor.
1.1670 + @param aWidthInPixels The available width for character display.
1.1671 + @return The number of characters which will be able to be displayed without
1.1672 + exceeding the specified width. The count starts from the beginning of the
1.1673 + descriptor. */
1.1674 + IMPORT_C TInt TextCount(const TDesC& aText,TInt aWidthInPixels) const;
1.1675 +
1.1676 + /** Gets how much of the specified descriptor can be displayed in this font without
1.1677 + exceeding the specified width.
1.1678 +
1.1679 + It also returns the excess width - defined as the specified available width
1.1680 + minus the width of the portion of the descriptor which can be displayed without
1.1681 + exceeding the available width.
1.1682 +
1.1683 + @param aText The descriptor.
1.1684 + @param aWidthInPixels The available width for character display.
1.1685 + @param aExcessWidthInPixels The excess width after displaying the portion of
1.1686 + the descriptor, in pixels.
1.1687 + @return The number of characters which will be able to be displayed without
1.1688 + exceeding the specified width. The count starts from the beginning of the
1.1689 + descriptor. */
1.1690 + IMPORT_C TInt TextCount(const TDesC& aText,TInt aWidthInPixels,TInt& aExcessWidthInPixels) const;
1.1691 +
1.1692 + /** Gets the width in pixels of the widest character in this font.
1.1693 +
1.1694 + @return The width of the maximum width character, in pixels. */
1.1695 + IMPORT_C TInt MaxCharWidthInPixels() const;
1.1696 +
1.1697 + /** Gets the width in pixels of the widest normal character in this font.
1.1698 +
1.1699 + Normal characters include all character in a character set except non-alphabetic
1.1700 + characters (e.g. the copyright symbol, or a block graphics symbol, for example).
1.1701 +
1.1702 + @return The width of the maximum width normal character, in pixels. */
1.1703 + IMPORT_C TInt MaxNormalCharWidthInPixels() const;
1.1704 +
1.1705 + /** Gets the font specification of this font in twips.
1.1706 +
1.1707 + @return The font specification of this font (in twips). */
1.1708 + IMPORT_C TFontSpec FontSpecInTwips() const;
1.1709 + IMPORT_C TCharacterDataAvailability GetCharacterData(TUint aCode, TOpenFontCharMetrics& aMetrics,const TUint8*& aBitmap,TSize& aBitmapSize) const;
1.1710 + IMPORT_C TBool GetCharacterPosition(TPositionParam& aParam) const;
1.1711 + IMPORT_C TInt WidthZeroInPixels() const;
1.1712 + IMPORT_C TInt MeasureText(const TDesC& aText, const TMeasureTextInput* aInput = NULL, TMeasureTextOutput* aOutput = NULL) const;
1.1713 + IMPORT_C static TBool CharactersJoin(TInt aLeftCharacter, TInt aRightCharacter);
1.1714 + IMPORT_C TInt ExtendedFunction(TUid aFunctionId, TAny* aParam = NULL) const;
1.1715 + IMPORT_C TBool GetCharacterPosition2(TPositionParam& aParam, RShapeInfo& aShapeInfo) const;
1.1716 + };
1.1717 +
1.1718 +class CFbsBitmap;
1.1719 +class CWsBitmap;
1.1720 +/** Abstract base class for all graphics contexts.
1.1721 +
1.1722 +Created by a CGraphicsDevice.
1.1723 +
1.1724 +Provides the 'context' in which you are drawing to an associated device, in
1.1725 +the sense that it holds the settings for drawing, such as the pen and brush
1.1726 +settings (e.g. color, line styles) and the font settings (e.g. bold, underline,
1.1727 +italic). These settings are device-independent.
1.1728 +
1.1729 +Also provides the clipping region (the visible drawing area).
1.1730 +
1.1731 +The settings and clipping area can be updated while drawing.
1.1732 +
1.1733 +This class also contains the main drawing functions, and all drawing is done
1.1734 +through a CGraphicsContext.
1.1735 +
1.1736 +The graphics context deals with pixels of device-dependent size and uses fonts
1.1737 +with device-dependent size and representation. The sizes and fonts to be passed
1.1738 +to the class functions therefore need to be converted from size-independent
1.1739 +units to size-dependent units first. This is done by an MGraphicsDeviceMap
1.1740 +derived class. This may be a TZoomFactor or the CGraphicsDevice.
1.1741 +
1.1742 +See CGraphicsContext::Reset() for the default graphics context settings immediately
1.1743 +after construction.
1.1744 +
1.1745 +@see CBitmapContext
1.1746 +@publishedAll
1.1747 +@released
1.1748 +*/
1.1749 +class CGraphicsContext : public CBase
1.1750 + {
1.1751 +public:
1.1752 +
1.1753 +
1.1754 + /** Text alignment.
1.1755 + @publishedAll
1.1756 + @released
1.1757 + */
1.1758 + enum TTextAlign
1.1759 + {
1.1760 + /** Text is left-aligned. */
1.1761 + ELeft,
1.1762 + /** Text is centred. */
1.1763 + ECenter,
1.1764 + /** Text is right-aligned. */
1.1765 + ERight
1.1766 + };
1.1767 +
1.1768 + /**
1.1769 + Drawing mode components.
1.1770 + This enum is not intended to be used directly, but provides components for
1.1771 + the easy specification of drawing modes in the TDrawMode enum.
1.1772 + @publishedAll
1.1773 + @released
1.1774 + */
1.1775 + enum TDrawModeComponents
1.1776 + {
1.1777 + /** 1 */
1.1778 + EInvertScreen=1,
1.1779 + /** 2 */
1.1780 + EXor=2,
1.1781 + /** 4 */
1.1782 + EOr=4,
1.1783 + /** 8 */
1.1784 + EAnd=8,
1.1785 + /** 14 */
1.1786 + ELogicalOp=14,
1.1787 + /** 16 */
1.1788 + EInvertPen=16,
1.1789 + /** 32 */
1.1790 + EPenmode=32,
1.1791 + /** 64 */
1.1792 + EWriteAlpha=64,
1.1793 + };
1.1794 +
1.1795 +
1.1796 + /**
1.1797 + Drawing modes.
1.1798 +
1.1799 + This enum builds on the drawing mode components in the TDrawModeComponents
1.1800 + enum.
1.1801 +
1.1802 + If the pen colour is p, brush colour is b and screen colour is s, the effect
1.1803 + of TDrawMode::EDrawModeAND is P=p&s and B=b&s. In other words, the effective
1.1804 + colour of the pen on the screen, P, is that produced by the bitwise ANDing
1.1805 + of the current screen colour and the current pen colour. The effect is similar
1.1806 + for the effective brush colour, B.
1.1807 +
1.1808 + The effective pen and brush colour are given in the table using the key
1.1809 + Inputs: pen colour is p, brush colour is b and screen colour is s
1.1810 + Outputs: effective brush colour is B, effective pen colour is P.
1.1811 +
1.1812 + Some notes on using EDrawModeWriteAlpha:-
1.1813 +
1.1814 + - It is rare for client code to need to use this draw mode: see the documentation
1.1815 + of SetDrawMode() for more information.
1.1816 + - EDrawModeWriteAlpha should only be used with DrawRect(), Clear(), BitBlt(), and BitBltMasked()
1.1817 + with EGray2 mask (and DrawBitmap() and DrawBitmapMasked()). For other draw operations, it is not
1.1818 + supported, and may have unintended effects.
1.1819 + - EDrawModeWriteAlpha has the same effect as EDrawModePEN, unless the brush colour has transparency
1.1820 + (DrawRect(), Clear()), or the source bitmap is EColor16MA (and has transparency) (BitBlt(), BitBltMasked())
1.1821 + - EDrawModeWriteAlpha has the same effect as EDrawModePEN if the draw mode of the destination does not
1.1822 + support alpha blending. (Blending is only supported in 24bpp and 32bpp colour i.e. EColor16M, EColor16MU, EColor16MA)
1.1823 + - In these cases, EDrawModePEN does alpha blending, whereas EDrawModeWriteAlpha means don't do alpha blending.
1.1824 +
1.1825 + @see SetDrawMode()
1.1826 + @publishedAll
1.1827 + @released
1.1828 + */
1.1829 + enum TDrawMode
1.1830 + {
1.1831 + /** Bitwise ANDs the pen and brush colours with the screen colour.
1.1832 + P=p&s, B=b&s */
1.1833 + EDrawModeAND=EAnd,
1.1834 + /** Inverts the pen and brush colours before ANDing. P=(~p)&s,
1.1835 + B=(~b)&s */
1.1836 + EDrawModeNOTAND=EInvertScreen|EAnd,
1.1837 + /** Uses both pen and brush colour as they are. P=p, B=b */
1.1838 + EDrawModePEN=EPenmode,
1.1839 + /** Inverts the screen colour before ANDing. P=p&(~s), B=b&(~s) */
1.1840 + EDrawModeANDNOT=EAnd|EInvertPen,
1.1841 + /** Bitwise XORs the pen and brush colours with the screen colour.
1.1842 + P=p^s, B=b^s */
1.1843 + EDrawModeXOR=EXor,
1.1844 + /** Bitwise ORs the pen and brush colours with the screen colour.
1.1845 + P=p|s, B=b|s */
1.1846 + EDrawModeOR=EOr,
1.1847 + /** Inverts the screen and pen and brush colours before ANDing.
1.1848 + P=(~p)&(~s), B=(~b)&(~s) */
1.1849 + EDrawModeNOTANDNOT=EInvertScreen|EAnd|EInvertPen,
1.1850 + /** Inverts the pen and brush colours before XORing. P=(~p)^s,
1.1851 + B=(~b)^s */
1.1852 + EDrawModeNOTXOR=EInvertScreen|EXor,
1.1853 + /** Inverts the colour of each pixel that is drawn over, (pen and
1.1854 + brush attributes are ignored). P=~s, B=~s */
1.1855 + EDrawModeNOTSCREEN=EInvertScreen,
1.1856 + /** Inverts the pen and brush colours before ORing. P=(~p)|s,
1.1857 + B=(~b)|s */
1.1858 + EDrawModeNOTOR=EInvertScreen|EOr,
1.1859 + /** Inverts the pen and brush colours. P=~p, B=~b */
1.1860 + EDrawModeNOTPEN=EInvertPen|EPenmode,
1.1861 + /** Inverts the screen, pen and brush colours before ORing. P=p|(~s),
1.1862 + B=b|(~s) */
1.1863 + EDrawModeORNOT=EOr|EInvertPen,
1.1864 + /** NOT OR NOT mode. P=(~p)|(~s), B=(~b)|(~s) */
1.1865 + EDrawModeNOTORNOT=EInvertScreen|EOr|EInvertPen,
1.1866 + /** Writes alpha information in the source directly into the destination, rather than blending. */
1.1867 + EDrawModeWriteAlpha=EWriteAlpha,
1.1868 + };
1.1869 +
1.1870 + /**
1.1871 + Pen styles. The screen pattern unit in each definition below describes the
1.1872 + pattern drawn by the line 1 represents a pixel drawn, 0 represents a
1.1873 + pixel that is not affected.
1.1874 + @publishedAll
1.1875 + @released
1.1876 + */
1.1877 + enum TPenStyle
1.1878 + {
1.1879 + /** The pen does not draw. Screen pattern unit = 00... */
1.1880 + ENullPen,
1.1881 + /** A solid line (default). Screen pattern unit = 11... */
1.1882 + ESolidPen,
1.1883 + /** A dotted line. Screen pattern unit = 1000... */
1.1884 + EDottedPen,
1.1885 + /** A dashed line. Screen pattern unit = 111000... */
1.1886 + EDashedPen,
1.1887 + /** A line of alternating dashes and dots. Screen pattern unit =
1.1888 + 1111001100... */
1.1889 + EDotDashPen,
1.1890 + /** A line of alternating single dashes and pairs of dots. Screen
1.1891 + pattern unit = 11110011001100... */
1.1892 + EDotDotDashPen
1.1893 + };
1.1894 +
1.1895 + /**
1.1896 + Brush styles.
1.1897 + @publishedAll
1.1898 + @released
1.1899 + */
1.1900 + enum TBrushStyle
1.1901 + {
1.1902 + /** The brush fill has no effect (default). */
1.1903 + ENullBrush,
1.1904 + /** The brush fills with a solid single colour, determined by
1.1905 + SetBrushColor() and the drawing mode. */
1.1906 + ESolidBrush,
1.1907 + /** The brush fills with a selected bitmap pattern, set by
1.1908 + UseBrushPattern(). */
1.1909 + EPatternedBrush,
1.1910 + /** The brush fills with vertical hatching lines going from top to
1.1911 + bottom. */
1.1912 + EVerticalHatchBrush,
1.1913 + /** The brush fills with diagonal hatching lines going from bottom
1.1914 + left to top right. */
1.1915 + EForwardDiagonalHatchBrush,
1.1916 + /** The brush fills with horizontal hatching lines going from left
1.1917 + to right. */
1.1918 + EHorizontalHatchBrush,
1.1919 + /** The brush fills with rearward diagonal hatching lines going from top
1.1920 + left to bottom right. */
1.1921 + ERearwardDiagonalHatchBrush,
1.1922 + /** The brush fills with horizontal and vertical hatching lines going
1.1923 + from left to right plus lines going from top to bottom giving the
1.1924 + effect of a grid of small squares */
1.1925 + ESquareCrossHatchBrush,
1.1926 + /** The brush fills with forward diagonal and rearward diagonal hatching
1.1927 + lines going from bottom left to top right plus lines going from top left
1.1928 + to bottom right giving the effect of a grid of small diamonds. */
1.1929 + EDiamondCrossHatchBrush
1.1930 + };
1.1931 +
1.1932 + /**
1.1933 + Rules used to fill self crossing polygons.
1.1934 +
1.1935 + The filling of a polygon proceeds as follows: for a given point in the
1.1936 + polygon, then
1.1937 +
1.1938 + if the rule is TFillRule::EAlternate (default) and it has an odd winding
1.1939 + number, then fill the surrounding area.
1.1940 +
1.1941 + if the rule is TFillRule::EWinding and it has a winding number greater than
1.1942 + zero, then fill the surrounding area.
1.1943 + @publishedAll
1.1944 + @released
1.1945 + */
1.1946 + enum TFillRule
1.1947 + {
1.1948 + /** Only fill areas with odd winding numbers. */
1.1949 + EAlternate,
1.1950 + /** Fill areas with winding numbers greater than zero. */
1.1951 + EWinding
1.1952 + };
1.1953 +
1.1954 + /** Parameters to control the drawing of text. */
1.1955 + struct TDrawTextParam
1.1956 + {
1.1957 + public:
1.1958 + TDrawTextParam():
1.1959 + iDirection(CFont::EHorizontal),
1.1960 + iCharJustNum(0),
1.1961 + iCharJustExcess(0),
1.1962 + iWordJustNum(0),
1.1963 + iWordJustExcess(0)
1.1964 + /** Reserved for future use. */
1.1965 + {}
1.1966 + public:
1.1967 + /** the direction in which to draw the text. */
1.1968 + CFont::TTextDirection iDirection;
1.1969 + /** number of glyph groups to be letterspaced */
1.1970 + TInt iCharJustNum;
1.1971 + /** amount of space to be used for letterspacing */
1.1972 + TInt iCharJustExcess;
1.1973 + /** number of spaces to be used for wordspacing*/
1.1974 + TInt iWordJustNum;
1.1975 + /** amount of space to be used for wordspacing*/
1.1976 + TInt iWordJustExcess;
1.1977 + };
1.1978 +
1.1979 +
1.1980 + /** Parameters for extended text drawing and measuring. It is used by
1.1981 + CGraphicsContext::DrawTextExtended() to indicate whether text should be
1.1982 + drawn from right-to-left or left-to-right. */
1.1983 + struct TDrawTextExtendedParam : public TDrawTextParam
1.1984 + {
1.1985 + public:
1.1986 + /** Constructor. Initialises iParRightToLeft to EFalse. */
1.1987 + TDrawTextExtendedParam():
1.1988 + iParRightToLeft(EFalse)
1.1989 + {}
1.1990 + public:
1.1991 + /** ETrue if the text direction is right-to-left (for scripts like
1.1992 + Arabic and Hebrew). EFalse if left-to-right. */
1.1993 + TBool iParRightToLeft;
1.1994 + };
1.1995 +public:
1.1996 + /** Gets a pointer to the graphics context's graphics device.
1.1997 +
1.1998 + @return A pointer to the graphics device. */
1.1999 + virtual CGraphicsDevice* Device() const=0;
1.2000 +
1.2001 + /** Sets the position of the co-ordinate origin.
1.2002 +
1.2003 + All subsequent drawing operations are done relative to this origin.
1.2004 +
1.2005 + @param aPos The origin. The default origin is TPoint(0,0) the top left
1.2006 + corner of the screen. */
1.2007 + virtual void SetOrigin(const TPoint& aPos=TPoint(0,0))=0;
1.2008 +
1.2009 + /** Sets the drawing mode.
1.2010 +
1.2011 + The way that the pen and brush draw depends on the drawing mode. The drawing
1.2012 + mode affects the colour that is actually drawn, because it defines the way
1.2013 + that the current screen colour logically combines with the current pen colour
1.2014 + and brush colour. There are many drawing modes, each giving different logical
1.2015 + combinations of pen, brush and screen colours. Each mode is produced by ORing
1.2016 + together different combinations of seven drawing mode components.
1.2017 +
1.2018 + The three most important modes are TDrawMode::EDrawModePEN, TDrawMode::EDrawModeNOTSCREEN
1.2019 + and TDrawMode::EDrawModeXOR. The default drawing mode is TDrawMode::EDrawModePEN.
1.2020 +
1.2021 + The drawing mode is over-ridden for line and shape drawing functions when
1.2022 + a wide pen line has been selected. It is forced to TDrawMode::EDrawModePEN.
1.2023 + This is to prevent undesired effects at line joins (vertexes).
1.2024 +
1.2025 + Notes:
1.2026 +
1.2027 + TDrawMode::EDrawModeAND gives a "colour filter" effect. For example:
1.2028 +
1.2029 + - ANDing with white gives the original colour
1.2030 + - ANDing with black gives black
1.2031 +
1.2032 + TDrawMode::EDrawModeOR gives a "colour boost" effect. For example:
1.2033 +
1.2034 + - ORing with black gives the original colour
1.2035 + - ORing with white gives white
1.2036 +
1.2037 + TDrawMode::EDrawModeXOR gives an "Exclusive OR" effect. For example:
1.2038 +
1.2039 + - white XOR black gives white
1.2040 + - white XOR white gives black
1.2041 + - black XOR black gives black
1.2042 +
1.2043 + TDrawMode::EDrawModeWriteAlpha should not normally need to be used by client code.
1.2044 + The following are exceptions:-
1.2045 +
1.2046 + - When a client side EColor16MA bitmap needs to have a transparent background
1.2047 + (because you are intending to blend it onto something else), then you need to set
1.2048 + EDrawModeWriteAlpha to Clear() it.
1.2049 + - When you want to BitBlt() with an EColor16MA source bitmap that is opaque everywhere,
1.2050 + then using EDrawModeWriteAlpha is more efficient than EDrawModePEN, because the bitmap
1.2051 + does not need to be blended.
1.2052 +
1.2053 + Note that if you have a transparent brush or source bitmap and you are drawing to a window,
1.2054 + then it is a defect to use EDrawModeWriteAlpha.
1.2055 +
1.2056 + @param aDrawingMode The drawing mode.
1.2057 + @see CGraphicsContext::TDrawMode
1.2058 + @see CGraphicsContext::TDrawModeComponents */
1.2059 + virtual void SetDrawMode(TDrawMode aDrawingMode)=0;
1.2060 +
1.2061 + /** Sets the clipping rectangle.
1.2062 +
1.2063 + The area of visible drawing depends on the clipping region. The default
1.2064 + clipping rectangle is the full device area.
1.2065 +
1.2066 + @param aRect The clipping rectangle. */
1.2067 + virtual void SetClippingRect(const TRect& aRect)=0;
1.2068 +
1.2069 + /** Cancels any clipping rectangle.
1.2070 +
1.2071 + Clipping thus reverts to the full device area, the default.
1.2072 +
1.2073 + @see SetClippingRect() */
1.2074 + virtual void CancelClippingRect()=0;
1.2075 +
1.2076 + /** Resets the graphics context to its default settings:
1.2077 +
1.2078 + the drawing mode is TDrawMode::EDrawModePen (pen and brush colours used as
1.2079 + they are)
1.2080 +
1.2081 + there is no clipping rectangle
1.2082 +
1.2083 + the pen settings are: black, solid, single pixel size
1.2084 +
1.2085 + the brush style is null
1.2086 +
1.2087 + no text font is selected */
1.2088 + virtual void Reset()=0;
1.2089 +
1.2090 + /** Sets the device font to be used for text drawing.
1.2091 +
1.2092 + If the font is already in memory, then that copy is shared.
1.2093 +
1.2094 + Notes:
1.2095 +
1.2096 + The CFont* argument must have been previously initialised by calling
1.2097 + MGraphicsDeviceMap::GetNearestFontInTwips() with the required
1.2098 + font-specification. If the CFont* has not been initialised
1.2099 + correctly, and therefore does not point to an available font-bitmap,
1.2100 + then a panic is raised.
1.2101 +
1.2102 + When the font is no longer required, use DiscardFont() to free up the
1.2103 + memory used. If UseFont() is used again without using DiscardFont() then
1.2104 + the previous font is discarded automatically.
1.2105 +
1.2106 + If no font has been selected, and an attempt is made to draw text with
1.2107 + DrawText(), then a panic is raised.
1.2108 +
1.2109 + @param aFont A device font
1.2110 + @see MGraphicsDeviceMap::GetNearestFontInTwips() */
1.2111 + virtual void UseFont(const CFont* aFont)=0;
1.2112 +
1.2113 + /** Discards a font.
1.2114 +
1.2115 + This frees up the memory used, if the font is not being shared.
1.2116 +
1.2117 + The function can be called when no font is in use. */
1.2118 + virtual void DiscardFont()=0;
1.2119 +
1.2120 + /** Sets the underline style.
1.2121 +
1.2122 + This is applied to all subsequently drawn text.
1.2123 +
1.2124 + @param aUnderlineStyle The underline style on or off. */
1.2125 + virtual void SetUnderlineStyle(TFontUnderline aUnderlineStyle)=0;
1.2126 +
1.2127 + /** Sets the strikethrough style.
1.2128 +
1.2129 + This is applied to all subsequently drawn text.
1.2130 +
1.2131 + @param aStrikethroughStyle The strikethrough style on or off. */
1.2132 + virtual void SetStrikethroughStyle(TFontStrikethrough aStrikethroughStyle)=0;
1.2133 + IMPORT_C static TInt JustificationInPixels(TInt aExcessPixels,TInt aTotalUnits,TInt aFirstUnit,TInt aNumUnits);
1.2134 + IMPORT_C static TInt JustificationInPixels(TInt& aExcessPixels,TInt& aTotalUnits);
1.2135 +
1.2136 + /** Adjusts the spaces between words to stretch or squeeze to a certain
1.2137 + width.
1.2138 +
1.2139 + The function is required by the Text Views API, and is not intended for
1.2140 + regular use by developers.
1.2141 +
1.2142 + The text line that is to be justified has a certain number of gaps (spaces)
1.2143 + between the words. It also has a distance (in pixels) between the end of
1.2144 + the last word and the actual end of the line (right hand margin, usually).
1.2145 + These excess width pixels are distributed amongst the gaps between the words
1.2146 + to achieve full justification of the text line. Spaces become fat spaces to
1.2147 + keep underlining/strikethrough consistent. Pixels are distributed to the
1.2148 + inter-word gaps starting from the left end of the string. The spacing
1.2149 + between characters in each word remains unchanged.
1.2150 +
1.2151 + After a call to SetWordJustification(), subsequent calls to either of the
1.2152 + two DrawText() functions are affected until the number of spaces specified
1.2153 + by aNumSpaces is used up.
1.2154 +
1.2155 + The easiest way to find out the excess width and number of spaces is to call
1.2156 + CFont::MeasureText(). This function can also perform counting, which is
1.2157 + finding how much of some text will fit into a given width.
1.2158 +
1.2159 + Use CFont::TextCount() to return the excess width.
1.2160 +
1.2161 + For example, in the string "To be, or not to be", there are five inter-word
1.2162 + gaps. If there are six excess pixels they will be distributed in the
1.2163 + proportion 2, 1, 1, 1, 1 between the words. If there are nine excess pixels
1.2164 + they will be distributed in the proportion 2, 2, 2, 2, 1 between the words.
1.2165 +
1.2166 + Notes:
1.2167 +
1.2168 + If the excess width is zero, then calling SetWordJustification() has no
1.2169 + effect.
1.2170 +
1.2171 + At first sight it may appear that SetWordJustification() is not required
1.2172 + because you can simply call DrawText() for each word. However, underlined
1.2173 + justified text does not work using this strategy you get a non-underlined
1.2174 + gap between the space and the beginning of the next word.
1.2175 +
1.2176 + @param aExcessWidth The width (in pixels) to be distributed between the
1.2177 + specified number of spaces. It may be positive, in which case the text is
1.2178 + stretched, or negative, in which case it is shrunk.
1.2179 + @param aNumGaps The number of word spaces (characters with the code U+0020)
1.2180 + over which the change in width is distributed. */
1.2181 + virtual void SetWordJustification(TInt aExcessWidth,TInt aNumGaps)=0;
1.2182 +
1.2183 + /** Sets character justification.
1.2184 +
1.2185 + This function is required by the Text Views API, and is not intended for
1.2186 + regular use by developers.
1.2187 +
1.2188 + It affects the strings of text used in the calls to DrawText() that follow,
1.2189 + until the number of characters drawn equals aNumChars.
1.2190 +
1.2191 + The text line that is to be justified has a certain number of characters
1.2192 + this includes the spaces between the words. It also has a distance (in
1.2193 + pixels) between the end of the last word and the actual end of the line
1.2194 + (right hand margin, usually). These excess width pixels are distributed
1.2195 + amongst all the characters, increasing the gaps between them, to achieve
1.2196 + full justification of the text line.
1.2197 +
1.2198 + Use CFont::TextCount() to return the excess width.
1.2199 +
1.2200 + Notes:
1.2201 +
1.2202 + This function is provided to allow simulation of printer fonts on screen.
1.2203 + Due to the fact that fully-scalable fonts are not used before v5, large
1.2204 + printer fonts can be simulated by using the nearest smaller font and
1.2205 + widening it slightly.
1.2206 +
1.2207 + If the excess width is zero, then calling SetCharJustification() has no
1.2208 + effect.
1.2209 +
1.2210 + SetCharJustification() is required for WYSIWYG where the layout uses
1.2211 + printer font metrics but screen fonts have to be drawn on the screen.
1.2212 + Because continuously scalable typefaces (c.f. TrueType) are not used
1.2213 + before v5 and because screen fonts are coarser and less numerous in
1.2214 + their variety than the printer fonts, the best matching smaller screen
1.2215 + font must be used with character justification to simulate the printer
1.2216 + font on the screen.
1.2217 +
1.2218 + There is also a situation where the gaps between characters on screen have
1.2219 + to be reduced with character clipping. The screen font that best matches
1.2220 + the printer font may have the required height, but has characters that are
1.2221 + too wide. A line of text that works on the printer will then be too long
1.2222 + on the screen, unless it is squashed horizontally. The number of pixels
1.2223 + that overlap the end of the screen line must now be removed from the gaps
1.2224 + between the characters, i.e. there is a negative excess width. This
1.2225 + situation is especially important where adding a TAB on screen gives
1.2226 + perfectly acceptable printout, but would push the last character of the
1.2227 + line off the right hand side of the screen.
1.2228 +
1.2229 + In practice what you do in printer layout mode is:
1.2230 +
1.2231 + Calculate where the line breaks will come on the printer. To do this you
1.2232 + use a printer font (which in practice means a table of character widths
1.2233 + of the font that the printer will use).
1.2234 +
1.2235 + Now change to use a screen font that is the closest font which is no taller
1.2236 + that the printer font. In practice it will often be fatter maybe only for
1.2237 + certain characters such as 'i'.
1.2238 +
1.2239 + You have to recalculate the width of the characters using the screen fonts.
1.2240 + You can do this using CFont::TextWidth() as you have already determined how
1.2241 + many characters will fit on the line.
1.2242 +
1.2243 + If, in the screen font, the characters are not as wide as the line then you
1.2244 + can just use word justification to expand the line. You would only do this
1.2245 + if the text is to be justified.
1.2246 +
1.2247 + If, however, the characters are wider than the line then you would use
1.2248 + character justification to clip each character. You would need to do this
1.2249 + even if the line is not justified.
1.2250 +
1.2251 + Thus, in practice, character justification will only very rarely be used to
1.2252 + expand a line of characters.
1.2253 +
1.2254 + @param aExcessWidth The excess width (in pixels) to be distributed between
1.2255 + the specified number of characters.
1.2256 + @param aNumChars The number of characters involved. */
1.2257 + virtual void SetCharJustification(TInt aExcessWidth,TInt aNumChars)=0;
1.2258 +
1.2259 + /** Sets the pen colour.
1.2260 +
1.2261 + The effective pen colour depends on the drawing mode. The default pen colour
1.2262 + is black.
1.2263 +
1.2264 + Note:
1.2265 +
1.2266 + The pen is used to draw lines, the outlines of filled shapes, and text. The
1.2267 + class provides member functions to set the colour of the pen, the style of
1.2268 + line and the line size drawn.
1.2269 +
1.2270 + @param aColor An RGB colour for the pen.
1.2271 + @see CGraphicsContext::SetDrawMode() */
1.2272 + virtual void SetPenColor(const TRgb& aColor)=0;
1.2273 +
1.2274 + /** Sets the line drawing style for the pen.
1.2275 +
1.2276 + There are 6 pen styles. If no pen style is set, then the default is
1.2277 + TPenStyle::ESolidPen. To use a pen style, its full context must be given,
1.2278 + e.g. for a null pen:
1.2279 +
1.2280 + CGraphicsContext::TPenStyle::ENullPen
1.2281 + Notes:
1.2282 +
1.2283 + The pen is used to draw lines, the outlines of filled shapes, and text.
1.2284 + CGraphicsContext member functions are provided to set the colour of the
1.2285 + pen, the style of line and the line size drawn.
1.2286 +
1.2287 + The TPenStyle::ENullPen style should be used if a border is not required
1.2288 + around a filled shape.
1.2289 +
1.2290 + Dotted and dashed pen styles have a device dependant implementation, always
1.2291 + give single-pixel size lines on the screen whatever the pen size set
1.2292 + by SetPenSize() and can only be used for straight lines, polylines,
1.2293 + non-rounded rectangles and polygons.
1.2294 +
1.2295 + The dotted/dashed pattern is continued, without re-starting, for all
1.2296 + consecutively drawn straight lines, i.e.
1.2297 +
1.2298 + the outlines of rectangles the pattern starts in the top left corner.
1.2299 + It is reset at the end of the function call.
1.2300 +
1.2301 + the outlines of polygons the pattern starts at the first point. It is
1.2302 + reset at the end of the function call.
1.2303 +
1.2304 + polylines and straight lines the pattern starts at the first point
1.2305 + initially. Consecutive calls to DrawLine() and/or DrawPolyLine(), whether
1.2306 + the lines are concatenated or not, continue the pattern. It can be reset
1.2307 + by a further call to SetPenStyle() using the same dotted/dashed style
1.2308 + parameter.
1.2309 +
1.2310 + @param aPenStyle A pen style.
1.2311 + @see CGraphicsContext::TPenStyle */
1.2312 + virtual void SetPenStyle(TPenStyle aPenStyle)=0;
1.2313 +
1.2314 + /** Sets the line drawing size for the pen.
1.2315 +
1.2316 + Lines of size greater than one pixel:
1.2317 +
1.2318 + are drawn with rounded ends that extend beyond the end points, (as if the
1.2319 + line is drawn using a circular pen tip of the specified size).
1.2320 +
1.2321 + are always drawn in TDrawMode::EDrawModePEN mode, overriding whatever mode
1.2322 + has been set using SetDrawMode().
1.2323 +
1.2324 + Notes:
1.2325 +
1.2326 + The pen is used to draw lines, the outlines of filled shapes, and text. The
1.2327 + class provides member functions to set the colour of the pen, the style of
1.2328 + line and the line size drawn.
1.2329 +
1.2330 + Wide straight lines and arcs have rounded ends so that concatenated wide
1.2331 + lines have smoothly rounded corners at the vertexes.
1.2332 +
1.2333 + When lines are made wide, the extra strips of pixels are added equally to
1.2334 + both sides of the line. This works precisely for lines of odd pixel size
1.2335 + (3, 5, 7, etc.). Wide lines of even pixel size, (2, 4, 6, etc.),
1.2336 + have the extra strip of pixels added to the right and/or below the line.
1.2337 +
1.2338 + Wide outlines of ellipses and wide line arcs are drawn with the pixels
1.2339 + distributed either side of a thin (single pixel wide) true ellipse
1.2340 + constructed in the normal manner. Wide ellipses and arcs of even pixel
1.2341 + size have the extra strip of pixels added to the right and/or below the
1.2342 + curved line. This gives a slight asymmetry to ellipses.
1.2343 +
1.2344 + If the pen style is dotted or dashed, the size specification is ignored: a
1.2345 + single-pixel wide primitive is drawn, (this is device dependant).
1.2346 +
1.2347 + A line size of zero is handled as if the pen style had been set to
1.2348 + TPenStyle::ENullPen.
1.2349 +
1.2350 + @param aSize A line size. The default is 1 pixel. */
1.2351 + virtual void SetPenSize(const TSize& aSize)=0;
1.2352 +
1.2353 + /** Sets the brush colour.
1.2354 +
1.2355 + The effective brush colour depends on the drawing mode.
1.2356 +
1.2357 + Notes:
1.2358 +
1.2359 + The brush is used for filling shapes and the background of text boxes. The
1.2360 + brush has colour, style, pattern and pattern origin parameters.
1.2361 +
1.2362 + If no brush colour has been set, it defaults to white. However the default
1.2363 + brush style is null, so when drawing to a window the default appears to be
1.2364 + the window's background colour.
1.2365 +
1.2366 + @param aColor An RGB colour for the brush.
1.2367 + @see SetDrawMode() */
1.2368 + virtual void SetBrushColor(const TRgb& aColor)=0;
1.2369 +
1.2370 + /** Sets the brush style.
1.2371 +
1.2372 + Ten brush styles are provided, including six built-in hatching patterns.
1.2373 + Note: The brush is used for filling shapes and the background of text boxes.
1.2374 + The brush has colour, style, pattern and pattern origin parameters.
1.2375 + Note: Use TBrushStyle::ENullBrush to draw the outline of a fillable
1.2376 + shape on its own, without filling.
1.2377 + Note: If the TBrushStyle::EPatternedBrush style is set, but no bitmap
1.2378 + pattern has been selected using UseBrushPattern(), then the function panics.
1.2379 + Note: Hatching lines are done in the current pen colour, set using SetPenColor().
1.2380 + The hatching pattern starts at the brush origin, set using SetBrushOrigin().
1.2381 + @see TBrushStyle::ENullBrush
1.2382 + @see TBrushStyle::EPatternedBrush
1.2383 + @see UseBrushPattern()
1.2384 + @see SetPenColor()
1.2385 + @see SetBrushOrigin()
1.2386 + @publishedAll
1.2387 + @released
1.2388 + @param aBrushStyle A brush style. */
1.2389 + virtual void SetBrushStyle(TBrushStyle aBrushStyle)=0;
1.2390 +
1.2391 + /** Sets the brush pattern origin.
1.2392 +
1.2393 + This specifies the top left-hand corner position for the pattern tile around
1.2394 + which copies of the pattern are tiled.
1.2395 +
1.2396 + The brush pattern may be a built-in style, or a bitmap. To use a bitmap, the
1.2397 + brush must have a pattern set and the brush style must be set to
1.2398 + TBrushStyle::EPatternedBrush.
1.2399 +
1.2400 + Notes
1.2401 +
1.2402 + The brush is used for filling shapes and the background of text boxes. The
1.2403 + brush has colour, style, pattern and pattern origin parameters.
1.2404 +
1.2405 + If SetBrushOrigin() is not used, then the origin defaults to (0,0).
1.2406 +
1.2407 + This brush origin remains in effect for all fillable shapes drawn
1.2408 + subsequently, until a new brush origin is set. Shapes can thus be
1.2409 + considered as windows onto a continuous pattern field (covering the whole
1.2410 + clipping region of a screen device, or the whole device area of a printer).
1.2411 +
1.2412 + @param aOrigin An origin point for the brush. The coordinates are relative
1.2413 + to the rectangle to fill, i.e. specify 0,0 to align the pattern flush with
1.2414 + the top and left hand sides of the rectangle.
1.2415 + @see SetBrushStyle()
1.2416 + @see UseBrushPattern() */
1.2417 + virtual void SetBrushOrigin(const TPoint& aOrigin)=0;
1.2418 +
1.2419 + /** Sets the brush pattern to the specified bitmap.
1.2420 +
1.2421 + For the brush to actually use the bitmap, TBrushStyle::EPatternedBrush must
1.2422 + be used to set the brush style.
1.2423 +
1.2424 + When the brush pattern is no longer required, use DiscardBrushPattern() to
1.2425 + free up the memory used, if the bitmap is not being shared.
1.2426 + If UseBrushPattern() is used again without using DiscardBrushPattern()
1.2427 + then the previous pattern is discarded automatically.
1.2428 +
1.2429 + Notes:
1.2430 +
1.2431 + The brush is used for filling shapes and the background of text boxes. The
1.2432 + brush has colour, style, pattern and pattern origin parameters.
1.2433 +
1.2434 + When loading a bitmap, the bitmap is checked to see if it is already in
1.2435 + memory. If the bitmap is already there, then that copy is shared.
1.2436 +
1.2437 + The brush does not need to have a pattern set at all. There are several
1.2438 + built-in hatching patterns which can be selected using SetBrushStyle().
1.2439 +
1.2440 + @param aBitmap A bitmap pattern for the brush.
1.2441 + @see SetBrushStyle() */
1.2442 + virtual void UseBrushPattern(const CFbsBitmap* aBitmap)=0;
1.2443 +
1.2444 + /** Discards a non-built-in brush pattern.
1.2445 +
1.2446 + This frees up the memory used by the bitmap, if it is not being shared by
1.2447 + another process.
1.2448 +
1.2449 + Notes:
1.2450 +
1.2451 + The brush is used for filling shapes and the background of text boxes. The
1.2452 + brush has colour, style, pattern and pattern origin parameters.
1.2453 +
1.2454 + If DiscardBrushPattern() is used, with no brush pattern set, then there is
1.2455 + no effect. */
1.2456 + virtual void DiscardBrushPattern()=0;
1.2457 +
1.2458 +
1.2459 + /** Sets the drawing point relative to the co-ordinate origin.
1.2460 +
1.2461 + A subsequent call to DrawLineTo() or DrawLineBy() uses the new drawing
1.2462 + point as the start point for the line drawn.
1.2463 +
1.2464 + Notes
1.2465 +
1.2466 + The operations DrawLine(), DrawLineTo(), DrawLineBy() and DrawPolyline()
1.2467 + also change the internal drawing position to the last point of the drawn
1.2468 + line(s).
1.2469 +
1.2470 + The internal drawing position is set to the co-ordinate origin if no drawing
1.2471 + or moving operations have yet taken place.
1.2472 +
1.2473 + @param aPoint The new internal drawing position. */
1.2474 + virtual void MoveTo(const TPoint& aPoint)=0;
1.2475 +
1.2476 + /** Sets the drawing point relative to the current co-ordinates.
1.2477 +
1.2478 + A subsequent call to DrawLineTo() or DrawLineBy() uses the new drawing point
1.2479 + as the start point for the line drawn.
1.2480 +
1.2481 + Notes
1.2482 +
1.2483 + The operations DrawLine(), DrawLineTo(), DrawLineBy() and DrawPolyline()
1.2484 + also change the internal drawing position to the last point of the drawn
1.2485 + line(s).
1.2486 +
1.2487 + The internal drawing position is set to the co-ordinate origin if no drawing
1.2488 + or moving operations have yet taken place.
1.2489 +
1.2490 + @param aVector The amount by which the internal drawing position is to move. */
1.2491 + virtual void MoveBy(const TPoint& aVector)=0;
1.2492 +
1.2493 + /** Draws a single point. The point is drawn with the current pen settings
1.2494 + using the current drawing mode.
1.2495 +
1.2496 + Note:
1.2497 +
1.2498 + If the pen size is greater than one pixel, a filled circle of the current
1.2499 + pen colour is drawn, with the pen size as the diameter and the plotted point
1.2500 + as the centre. If the pen size is an even number of pixels, the extra pixels
1.2501 + are drawn below and to the right of the centre.
1.2502 +
1.2503 + @param aPoint The point to be drawn.
1.2504 + @see SetPenSize() */
1.2505 + virtual void Plot(const TPoint& aPoint)=0;
1.2506 +
1.2507 + /** Draws an arc.
1.2508 +
1.2509 + The arc is considered a portion of an ellipse. The ellipse is defined by the
1.2510 + TRect argument.
1.2511 +
1.2512 + The pixels at both the start point and the end point are drawn.
1.2513 +
1.2514 + The arc itself is the segment of the ellipse drawn in an anti-clockwise
1.2515 + direction from the start point to the end point.
1.2516 +
1.2517 + Notes:
1.2518 +
1.2519 + A rectangle is used in the construction of the ellipse of which the arc is
1.2520 + a segment. This rectangle is passed as an argument of type TRect.
1.2521 +
1.2522 + A wide line arc is drawn with the pixels distributed either side of a true
1.2523 + ellipse, in such a way that the outer edge of the line would touch the edge
1.2524 + of the construction rectangle. In other words, the ellipse used to
1.2525 + construct it is slightly smaller than that for a single pixel line size.
1.2526 +
1.2527 + If the specified start or end point is at the centre of the ellipse, then
1.2528 + the line that defines the start or end of the arc defaults to one extending
1.2529 + vertically above the centre point.
1.2530 +
1.2531 + If the start and end point are the same point or are points on the same line
1.2532 + through the ellipse centre then a complete unfilled ellipse is drawn.
1.2533 +
1.2534 + @param aRect A rectangle in which to draw the ellipse, of which the arc is
1.2535 + a segment.
1.2536 + @param aStart The point defining the start of the arc. It defines one end of
1.2537 + a line from the geometric centre of the ellipse. The point of intersection
1.2538 + between this line and the ellipse defines the start point of the arc.
1.2539 + @param aEnd The point defining the end of the arc. It defines one end of a
1.2540 + second line from the geometric centre of the ellipse. The point of
1.2541 + intersection between this line and the ellipse defines the end point of the
1.2542 + arc.
1.2543 + @see DrawEllipse() */
1.2544 + virtual void DrawArc(const TRect& aRect,const TPoint& aStart,const TPoint& aEnd)=0;
1.2545 +
1.2546 + /** Draws a straight line between two points.
1.2547 +
1.2548 + @param aPoint1 The point at the start of the line.
1.2549 + @param aPoint2 The point at the end of the line. */
1.2550 + virtual void DrawLine(const TPoint& aPoint1,const TPoint& aPoint2)=0;
1.2551 +
1.2552 + /** Draws a straight line from the current drawing point to a specified
1.2553 + point.
1.2554 +
1.2555 + @param aPoint The point at the end of the line.
1.2556 + @see MoveTo()
1.2557 + @see MoveBy() */
1.2558 + virtual void DrawLineTo(const TPoint& aPoint)=0;
1.2559 +
1.2560 + /** Draws a straight line relative to the current drawing point, using a
1.2561 + vector.
1.2562 +
1.2563 + The start point of the line is the current drawing point. The specified
1.2564 + vector
1.2565 + is added to the drawing point to give the end point of the line
1.2566 +
1.2567 + @param aVector The vector to add to the current internal drawing position,
1.2568 + giving the end point of the line.
1.2569 + @see MoveTo()
1.2570 + @see MoveBy() */
1.2571 + virtual void DrawLineBy(const TPoint& aVector)=0;
1.2572 +
1.2573 + /** Draws a polyline from a set of points in an array.
1.2574 +
1.2575 + A polyline is a series of concatenated straight lines joining a set of
1.2576 + points.
1.2577 +
1.2578 + @param aPointList An array containing the points on the polyline. */
1.2579 + virtual void DrawPolyLine(const CArrayFix<TPoint>* aPointList)=0;
1.2580 +
1.2581 + /** Draws a polyline from a set of points in a list.
1.2582 +
1.2583 + A polyline is a series of concatenated straight lines joining a set of
1.2584 + points.
1.2585 +
1.2586 + @param aPointList Pointer to a set of points on the polyline.
1.2587 + @param aNumPoints Number of points in the list. */
1.2588 + virtual void DrawPolyLine(const TPoint* aPointList,TInt aNumPoints)=0;
1.2589 +
1.2590 + /** Draws and fills a pie slice.
1.2591 +
1.2592 + The pie slice is an area bounded by:
1.2593 +
1.2594 + the arc of an ellipse drawn in an anticlockwise direction from the start
1.2595 + point to the end point
1.2596 +
1.2597 + the straight line drawn to the start point from the geometric centre of the
1.2598 + ellipse.
1.2599 +
1.2600 + the straight line to the end point from the geometric centre of the ellipse.
1.2601 +
1.2602 + Notes:
1.2603 +
1.2604 + A rectangle is used in the construction of the pie slice. This rectangle is
1.2605 + passed as an argument of type TRect. The curved edge of the pie slice is an
1.2606 + arc of an ellipse constructed within the rectangle.
1.2607 +
1.2608 + The line drawn by the pen goes inside the specified rectangle.
1.2609 +
1.2610 + The pixels at the end point of the arc are not drawn.
1.2611 +
1.2612 + A wide line edged pie slice has the arc drawn with the pixels distributed
1.2613 + either side of a true ellipse. This is done in such a way that the outer
1.2614 + edge of the line touches the edge of the construction rectangle. In other
1.2615 + words, the ellipse used to construct it is slightly smaller than that for
1.2616 + a single pixel line size.
1.2617 +
1.2618 + If the specified start or end point is at the centre of the ellipse, then
1.2619 + the line that defines the start or end of the arc defaults to one extending
1.2620 + vertically above the centre point.
1.2621 +
1.2622 + If the start and end point are the same point or are points on the same line
1.2623 + through the ellipse centre then a complete filled ellipse is drawn. A line
1.2624 + is also drawn from the edge to the ellipse centre.
1.2625 +
1.2626 + @param aRect A rectangle in which to draw the ellipse bounding the pie slice.
1.2627 + @param aStart A point defining the start of the arc bounding the pie slice.
1.2628 + It defines one end of a line from the geometrical centre of the ellipse. The
1.2629 + point of intersection between this line and the ellipse defines the start
1.2630 + point of the arc.
1.2631 + @param aEnd A point to define the end of the arc bounding the pie slice. It
1.2632 + defines one end of a second line from the geometrical centre of the ellipse.
1.2633 + The point of intersection between this line and the ellipse defines the end
1.2634 + point of the arc. */
1.2635 + virtual void DrawPie(const TRect& aRect,const TPoint& aStart,const TPoint& aEnd)=0;
1.2636 +
1.2637 + /** Draws and fills an ellipse.
1.2638 +
1.2639 + The ellipse is drawn inside the rectangle defined by the TRect argument. Any
1.2640 + rectangle that has odd pixel dimensions, has the bottom right corner trimmed
1.2641 + to give even pixel dimensions before the ellipse is constructed.
1.2642 +
1.2643 + Note:
1.2644 +
1.2645 + A wide outline ellipse is drawn with the pixels distributed either side of
1.2646 + a true ellipse, in such a way that the outer edge of the line touches the
1.2647 + edge of the construction rectangle. In other words, the ellipse used to
1.2648 + construct it is smaller than that for a single pixel line size.
1.2649 +
1.2650 + @param aRect The rectangle in which the ellipse is drawn. */
1.2651 + virtual void DrawEllipse(const TRect& aRect)=0;
1.2652 +
1.2653 + /** Draws and fills a rectangle.
1.2654 +
1.2655 + @param aRect The rectangle to be drawn. */
1.2656 + virtual void DrawRect(const TRect& aRect)=0;
1.2657 +
1.2658 + /** Draws and fills a rectangle with rounded corners.
1.2659 +
1.2660 + The rounded corners are each constructed as an arc of an ellipse.
1.2661 +
1.2662 + The line drawn by the pen, if any, goes inside the specified rectangle.
1.2663 +
1.2664 + Notes:
1.2665 +
1.2666 + Dotted and dashed pen styles cannot be used for the outline of a rounded
1.2667 + rectangle.
1.2668 +
1.2669 + If either corner size dimension is greater than half the corresponding
1.2670 + rectangle length, the corner size dimension is reduced to half the
1.2671 + rectangle size.
1.2672 +
1.2673 + @param aRect The rectangle to be drawn.
1.2674 + @param aCornerSize The dimensions of each corner.
1.2675 + @see DrawArc() */
1.2676 + virtual void DrawRoundRect(const TRect& aRect,const TSize& aCornerSize)=0;
1.2677 +
1.2678 + /** Draws and fills a polygon defined using an array of points.
1.2679 +
1.2680 + The first point in the array defines the start of the first side of the
1.2681 + polygon. The second point defines the second vertex (the end point of the
1.2682 + first side and the start point of the second side).
1.2683 +
1.2684 + The final side of the polygon is drawn using the last point from the array,
1.2685 + and the line is drawn to the start point of the first side.
1.2686 +
1.2687 + Self-crossing polygons are filled according to the specified fill rule.
1.2688 +
1.2689 + @param aPointList An array of points, specifying the vertices of the polygon.
1.2690 + @param aFillRule The fill rule. By default, this is TFillRule::EAlternate.
1.2691 + @return KErrNone, if successful; otherwise, another of the system-wide error
1.2692 + codes. */
1.2693 + virtual TInt DrawPolygon(const CArrayFix<TPoint>* aPointList,TFillRule aFillRule=EAlternate)=0;
1.2694 +
1.2695 + /** Draws and fills a polygon defined using a list of points.
1.2696 +
1.2697 + The first point in the list defines the start of the first side of the
1.2698 + polygon. The second point defines the second vertex (the end point of the
1.2699 + first side and the start point of the second side).
1.2700 +
1.2701 + The final side of the polygon is drawn using the last point from the list,
1.2702 + and the line is drawn to the start point of the first side.
1.2703 +
1.2704 + Self-crossing polygons are filled according to the specified fill rule.
1.2705 +
1.2706 + @param aPointList Pointer to list of points, specifying the vertices of the
1.2707 + polygon.
1.2708 + @param aNumPoints The number of points in the list.
1.2709 + @param aFillRule The fill rule. By default this is TFillRule::EAlternate.
1.2710 + @return KErrNone, if successful; otherwise, another of the system-wide error
1.2711 + codes. */
1.2712 + virtual TInt DrawPolygon(const TPoint* aPointList,TInt aNumPoints,TFillRule aFillRule=EAlternate)=0;
1.2713 +
1.2714 + /** Draws a bitmap at the specified point.
1.2715 +
1.2716 + The point specifies the top left hand corner of the bitmap. The bitmap is
1.2717 + compressed or stretched based on its internally stored size in twips.
1.2718 +
1.2719 + Notes:
1.2720 +
1.2721 + This member function uses the bitmap's size in twips and does a
1.2722 + stretch/compress blit using a linear DDA.
1.2723 +
1.2724 + As this function scales the bitmap, it is unavoidably slow. Therefore, where
1.2725 + possible, use CBitmapContext::BitBlt() instead. If the bitmap has to be
1.2726 + scaled, consider creating another bitmap along with an CFbsBitmapDevice etc,
1.2727 + doing DrawBitmap() once and using BitBlt() subsequently.
1.2728 +
1.2729 + Note that all bitmaps are clipped to the device boundaries.
1.2730 +
1.2731 + @param aTopLeft The point where the top left pixel of the bitmap is to be
1.2732 + drawn
1.2733 + @param aSource A source bitmap
1.2734 + @see TLinearDDA */
1.2735 + virtual void DrawBitmap(const TPoint& aTopLeft,const CFbsBitmap* aSource)=0;
1.2736 +
1.2737 + /** Draws a bitmap to fit a given rectangle.
1.2738 +
1.2739 + The bitmap is compressed or stretched based on its internally stored size
1.2740 + in pixels.
1.2741 +
1.2742 + Notes:
1.2743 +
1.2744 + This member function uses the bitmap's size in pixels and does a
1.2745 + stretch/compress blit using a linear DDA.
1.2746 +
1.2747 + As this function scales the bitmap, it is unavoidably slow. Therefore,
1.2748 + where possible, use CBitmapContext::BitBlt() instead. If the bitmap has
1.2749 + to be scaled, consider creating another bitmap along with an
1.2750 + CFbsBitmapDevice etc., doing DrawBitmap() once and using BitBlt()
1.2751 + subsequently.
1.2752 +
1.2753 + Note that all bitmaps are clipped to the device boundaries.
1.2754 +
1.2755 + @param aDestRect The rectangle within which the bitmap is to be drawn.
1.2756 + @param aSource A source bitmap.
1.2757 + @see TLinearDDA */
1.2758 + virtual void DrawBitmap(const TRect& aDestRect,const CFbsBitmap* aSource)=0;
1.2759 +
1.2760 + /** Draws a specified rectangle of a source bitmap to fit into a given
1.2761 + destination rectangle.
1.2762 +
1.2763 + Notes:
1.2764 +
1.2765 + This member function uses rectangle sizes in pixels and does a
1.2766 + stretch/compress blit using a linear DDA.
1.2767 +
1.2768 + As this function scales the bitmap, it is unavoidably slow. Therefore,
1.2769 + where possible, use CBitmapContext::BitBlt() instead. If the bitmap has
1.2770 + to be scaled, consider creating another bitmap along with an
1.2771 + CFbsBitmapDevice etc., doing DrawBitmap() once and using BitBlt()
1.2772 + subsequently.
1.2773 +
1.2774 + Note that all bitmaps are clipped to the device boundaries.
1.2775 +
1.2776 + @param aDestRect The rectangle within which the bitmap is to be drawn.
1.2777 + @param aSource A source bitmap.
1.2778 + @param aSourceRect The rectangle in the source bitmap that is copied to the
1.2779 + destination rectangle.
1.2780 + @see TLinearDDA */
1.2781 + virtual void DrawBitmap(const TRect& aDestRect,const CFbsBitmap* aSource,const TRect& aSourceRect)=0;
1.2782 +
1.2783 + /** Draws a specified rectangle of a source bitmap to fit into a given rectangle using a given mask.
1.2784 +
1.2785 + Notes:
1.2786 +
1.2787 + This member function uses rectangle sizes in pixels and does a
1.2788 + stretch/compress blit using a linear DDA.
1.2789 +
1.2790 +
1.2791 + @param aDestRect The rectangle within which the bitmap is to be drawn.
1.2792 + @param aBitmap The source bitmap
1.2793 + @param aSourceRect The rectangle in the source bitmap that is to be drawn
1.2794 + @param aMaskBitmap The mask to be applied to the source bitmap while drawing
1.2795 + @param aInvertMask Flag to indicate if the mask should be inverted.
1.2796 + */
1.2797 + virtual void DrawBitmapMasked(const TRect& aDestRect,const CFbsBitmap* aBitmap,const TRect& aSourceRect,const CFbsBitmap* aMaskBitmap,TBool aInvertMask)=0;
1.2798 +
1.2799 + /** Draws a specified rectangle from a wserv bitmap and its mask into
1.2800 + another rectangle.
1.2801 +
1.2802 + The function compresses/stretches the specified rectangle from the bitmap
1.2803 + to fit the destination rectangle.
1.2804 + The mask bitmap can be used as either a positive or negative mask. Masked
1.2805 + pixels are not mapped to the destination rectangle.
1.2806 +
1.2807 + A black and white (binary) mask bitmap is used. With aInvertMask=EFalse, black
1.2808 + pixels in the mask bitmap stop corresponding pixels in the source bitmap from
1.2809 + being transferred to the destination rectangle. With aInvertMask=ETrue, white
1.2810 + pixels in the mask bitmap stop corresponding pixels in the source bitmap from
1.2811 + being transferred to the destination rectangle.
1.2812 +
1.2813 + Note: this member function uses rectangle sizes in pixels and does a stretch/compress
1.2814 + blit using a linear DDA.
1.2815 +
1.2816 + @param aDestRect The rectangle within which the masked bitmap is to be drawn.
1.2817 + @param aBitmap A source wserv bitmap.
1.2818 + @param aSourceRect The rectangle in the source bitmap that is copied to the
1.2819 + destination rectangle.
1.2820 + @param aMaskBitmap A mask wserv bitmap.
1.2821 + @param aInvertMask If false, a source pixel that is masked by a black pixel
1.2822 + is not transferred to the destination rectangle. If true, then a source pixel
1.2823 + that is masked by a white pixel is not transferred to the destination rectangle. */
1.2824 + virtual void DrawBitmapMasked(const TRect& aDestRect,const CWsBitmap* aBitmap,const TRect& aSourceRect,const CWsBitmap* aMaskBitmap,TBool aInvertMask)=0;
1.2825 +
1.2826 + /** Draws text without a surrounding box.
1.2827 +
1.2828 + The text baseline is aligned with the y co-ordinate of the specified point,
1.2829 + and the left end of the text is aligned with the x co-ordinate of the
1.2830 + specified point.
1.2831 +
1.2832 + Note:
1.2833 +
1.2834 + Text drawing is done with the pen, and is subject to the pen colour. The
1.2835 + effective text colour also depends on the drawing mode. The size and style
1.2836 + of the text depends on the font used. The layout of the text depends on the
1.2837 + justification mode set.
1.2838 +
1.2839 + @param aText The text string to be drawn.
1.2840 + @param aPosition A point specifying the position of the left end of the text. */
1.2841 + virtual void DrawText(const TDesC& aText,const TPoint& aPosition) = 0;
1.2842 +
1.2843 + /** Draws text inside a box.
1.2844 +
1.2845 + The surrounding box is filled with the current brush colour (not a pattern)
1.2846 + and is drawn without any outline. The effective box colour depends on the
1.2847 + drawing mode - if a brush colour has not been set then the brush defaults
1.2848 + to white. The brush may be set to TBrushStyle::ENullBrush if text
1.2849 + positioning relative to a box is required, but the box should not be filled.
1.2850 +
1.2851 + The font used is that set by UseFont(). If no font is in use then a panic
1.2852 + occurs.
1.2853 +
1.2854 + The alignment of the text within the box can be specified.
1.2855 +
1.2856 + Text drawn within a box is also clipped to that box. Unless you intend to
1.2857 + clip the top off the text, aBaselineOffset should be greater than or equal
1.2858 + to the ascent of the current font.
1.2859 +
1.2860 + Offsets:
1.2861 +
1.2862 + If the offset is negative, zero, or less than font height this is handled
1.2863 + as would be expected, i.e. no text will be seen in the box in the first two
1.2864 + instances, and the top of the text will be clipped in the latter case.
1.2865 +
1.2866 + Margins:
1.2867 +
1.2868 + For the drawing of right-aligned text, aLeftMargin indicates the margin from
1.2869 + the right of aBox - where a positive value results in a leftwards offset.
1.2870 +
1.2871 + Negative margins can be used to display portions of the text string clipped
1.2872 + by the box. A negative margin for left aligned text would clip the start of
1.2873 + the text string. Similarly, a negative margin for right aligned text would
1.2874 + clip the end of the text string.
1.2875 +
1.2876 + If the margin is greater than the width of the box then no text will be
1.2877 + visible.
1.2878 +
1.2879 + The margin is still honoured for centred text - centred text will not be
1.2880 + centred in the box, unless the margin is zero.
1.2881 +
1.2882 + Note:
1.2883 +
1.2884 + Text drawing is done with the pen, and is thus subject to the pen colour.
1.2885 + The effective text colour also depends on the drawing mode. The size and
1.2886 + style of the text depends on the used font. The layout of the text depends
1.2887 + on the justification mode set.
1.2888 +
1.2889 + @param aText The text string to be drawn.
1.2890 + @param aBox The box to draw the text in.
1.2891 + @param aBaselineOffset An offset from the top of the box to the text
1.2892 + baseline.
1.2893 + @param aAlignment The text alignment mode default is left aligned.
1.2894 + @param aLeftMargin The left margin for left-aligned text, or the right
1.2895 + margin
1.2896 + for right-aligned text default is zero. */
1.2897 + virtual void DrawText(const TDesC& aText,const TRect& aBox,TInt aBaselineOffset,TTextAlign aAlignment = ELeft,
1.2898 + TInt aLeftMargin = 0) = 0;
1.2899 + IMPORT_C virtual void DrawText(const TDesC& aText,const TPoint& aPosition,const TDrawTextParam& aParam);
1.2900 + IMPORT_C virtual void Reserved();
1.2901 + IMPORT_C TInt DrawTextExtended(const TDesC& aText,const TPoint& aPosition,const TDrawTextExtendedParam& aParam);
1.2902 +
1.2903 + /** Maps pixels in the specified rectangle.
1.2904 + The function tries to match the colour of a pixel with one of the RGB values
1.2905 + in an array of RGB pairs. If there is a match, the colour is changed to the
1.2906 + value specified in the other RGB in the RGB pair.
1.2907 + @param aRect The rectangle in which pixels are to be mapped.
1.2908 + @param aColors A pointer to a set of RGB pairs.
1.2909 + @param aNumPairs The number of pairs
1.2910 + @param aMapForwards ETrue, mapping is done from the first RGB to the second
1.2911 + RGB in the pair; EFalse, mapping is done from the second RGB to the first
1.2912 + RGB in the pair. */
1.2913 + virtual void MapColors(const TRect &aRect,const TRgb *aColors,TInt aNumPairs,TBool aMapForwards) = 0;
1.2914 +
1.2915 + /** Sets the clipping region.
1.2916 + @param aClippingRegion The new clipping region.
1.2917 + @return KErrNone if successful; KErrArgument if the TRegion is not valid; KErrNoMemory if there is insufficient memory.
1.2918 + @see CGraphicsContext::CancelClippingRegion()*/
1.2919 + virtual TInt SetClippingRegion(const TRegion &aRegion) = 0;
1.2920 +
1.2921 + /** Cancels the current clipping region.
1.2922 + @see CGraphicsContext::SetClippingRegion()*/
1.2923 + virtual void CancelClippingRegion() = 0;
1.2924 +
1.2925 + /** Draws vertical text in the specified direction.
1.2926 + @param aText The text to be drawn.
1.2927 + @param aPos Point of origin of the text baseline.
1.2928 + @param aUp Direction. ETrue for up, EFalse for down. */
1.2929 + virtual void DrawTextVertical(const TDesC& aText,const TPoint& aPos,TBool aUp) = 0;
1.2930 +
1.2931 + /** Draws text vertically in the specified direction, within a box of the specified size.
1.2932 + @param aText The text to be drawn.
1.2933 + @param aBox The bounding box within which the text should be drawn, and which it is clipped to.
1.2934 + @param aBaselineOffset The height of the top of the characters from their text baseline.
1.2935 + @param aUp The direction. ETrue for up, EFalse for down.
1.2936 + @param aVert The text alignment.
1.2937 + @param aMargin The margin. */
1.2938 + virtual void DrawTextVertical(const TDesC& aText,const TRect& aBox,TInt aBaselineOffset,TBool aUp,TTextAlign aVert=ELeft,TInt aMargin=0) = 0;
1.2939 +
1.2940 + IMPORT_C TInt GetUnderlineMetrics(TInt& aTop,TInt& aBottom);
1.2941 +
1.2942 + /** Set the font's shadow colour
1.2943 + @param aShadowColor Shadow colour to be set.
1.2944 + @return KErrNone, if successful; otherwise, another of the system-wide errors. */
1.2945 + IMPORT_C TInt SetShadowColor(const TRgb& aShadowColor);
1.2946 +
1.2947 + /** Get the font's shadow colour
1.2948 + @param aShadowColor Shadow colour of the font returned by the funtion.
1.2949 + @return KErrNone, if successful; otherwise, another of the system-wide errors. */
1.2950 + IMPORT_C TInt GetShadowColor(TRgb& aShadowColor);
1.2951 +
1.2952 + /** Determine if the Gc is a CFbsBitGc
1.2953 + @return ETrue, if the Gc is a CFbsBitGc, EFalse otherwise
1.2954 + @internalComponent
1.2955 + */
1.2956 + IMPORT_C TBool IsFbsBitGc() const;
1.2957 +
1.2958 +protected:
1.2959 +
1.2960 + /**
1.2961 + An APIExtension method to allow the addition of new APIs to retain compatibility
1.2962 + with previous versions of gdi.dll
1.2963 + @param aOutput is for output
1.2964 + @param aInput is for input
1.2965 + @see CGraphicsContext
1.2966 + @internalComponent
1.2967 + */
1.2968 + IMPORT_C virtual TInt APIExtension(TUid aUid, TAny*& aOutput, TAny* aInput);
1.2969 +
1.2970 + /**
1.2971 + A reserved virtual function for future use.
1.2972 + */
1.2973 + IMPORT_C virtual void Reserved_CGraphicsContext_2();
1.2974 + };
1.2975 +
1.2976 +
1.2977 +/** An abstract, device-independent, interface to bitmapped graphics contexts.
1.2978 +
1.2979 +This holds the setting used to draw to a CBitmapDevice.
1.2980 +
1.2981 +The default settings of a CBitmapContext object immediately after construction
1.2982 +are:
1.2983 +
1.2984 +drawing mode is EDrawModePen (pen and brush colours used as they are)
1.2985 +
1.2986 +no clipping rectangle
1.2987 +
1.2988 +pen settings are: black, solid, single pixel width
1.2989 +
1.2990 +brush style is null
1.2991 +
1.2992 +no text font selected
1.2993 +
1.2994 +The classes CFbsBitGc and CWindowGc are derived from this class.
1.2995 +
1.2996 +@see CFbsBitGc
1.2997 +@publishedAll
1.2998 +@released
1.2999 +*/
1.3000 +class CBitmapContext : public CGraphicsContext
1.3001 + {
1.3002 +public:
1.3003 + /** Clears the whole bitmap.
1.3004 +
1.3005 + The cleared area is filled with the current brush colour.
1.3006 +
1.3007 + This pure virtual function is implemented in derived classes. */
1.3008 + virtual void Clear()=0;
1.3009 +
1.3010 + /** Clears a rectangular area of a bitmap.
1.3011 +
1.3012 + The cleared area is filled with the current brush colour.
1.3013 +
1.3014 + This pure virtual function is implemented in derived classes.
1.3015 +
1.3016 + @param aRect The rectangle to clear. */
1.3017 + virtual void Clear(const TRect& aRect)=0;
1.3018 +
1.3019 + /** Copies a rectangle.
1.3020 +
1.3021 + This pure virtual function is implemented in derived classes.
1.3022 +
1.3023 + @param aOffset The offset from the top left corner of the rectangle to be
1.3024 + copied to the top left corner of the copy.
1.3025 + @param aRect The rectangular area to be copied. */
1.3026 + virtual void CopyRect(const TPoint& aOffset,const TRect& aRect)=0;
1.3027 +
1.3028 + /** Performs a bitmap block transfer.
1.3029 +
1.3030 + This pure virtual function is implemented in derived classes.
1.3031 +
1.3032 + @param aPoint The destination for the top left corner of the transferred bitmap.
1.3033 + It is relative to the top left corner of the destination bitmap, which may be the screen.
1.3034 + @param aBitmap A memory-resident bitmap. */
1.3035 + virtual void BitBlt(const TPoint& aPoint,const CFbsBitmap* aBitmap)=0;
1.3036 +
1.3037 + /** Performs a bitmap block transfer of a rectangular piece of a bitmap.
1.3038 +
1.3039 + If the specified rectangle is larger than the bitmap then the bitmap is
1.3040 + padded with white.
1.3041 +
1.3042 + This pure virtual function is implemented in derived classes.
1.3043 +
1.3044 + @param aPoint The destination for the top left corner of the transferred bitmap.
1.3045 + It is relative to the top left corner of the destination bitmap, which may be the screen.
1.3046 +
1.3047 + @param aBitmap A memory-resident bitmap
1.3048 + @param aRect A rectangle defining the portion of the bitmap to transfer.
1.3049 + Its coordinates are relative to the top left corner of the source bitmap. */
1.3050 + virtual void BitBlt(const TPoint& aPoint,const CFbsBitmap* aBitmap,const TRect& aRect)=0;
1.3051 +
1.3052 + /** Performs a masked bitmap block transfer.
1.3053 +
1.3054 + The mask bitmap can be used as either a positive or negative mask. Masked
1.3055 + pixels are not mapped to the destination rectangle.
1.3056 +
1.3057 + This function uses either a black and white (binary) mask bitmap, or if
1.3058 + aMaskBitmap's display mode is EGray256, alpha blending is used. Use of
1.3059 + any other mode may result in unpredictable results
1.3060 +
1.3061 + With aInvertMask=EFalse, black pixels in the mask bitmap stop corresponding
1.3062 + pixels in the source bitmap from being transferred to the destination rectangle.
1.3063 + With aInvertMask=ETrue, white pixels in the mask bitmap stop corresponding
1.3064 + pixels in the source bitmap from being transferred to the destination
1.3065 + rectangle.
1.3066 +
1.3067 + Note that if the mask bitmap is smaller than the source bitmap, then it is
1.3068 + tiled across the bitmap. Note that the mask is applied before the piece of
1.3069 + the bitmap is defined - the mask is tiled relative to the top left of the
1.3070 + original source bitmap rather than the top left of the bitmap piece.
1.3071 +
1.3072 + This pure virtual function is implemented in derived classes.
1.3073 +
1.3074 + @param aPoint The destination for the top left corner of the transferred bitmap.
1.3075 + It is relative to the top left corner of the destination bitmap, which may be the screen.
1.3076 + @param aBitmap A memory-resident source bitmap.
1.3077 + @param aSourceRect A rectangle defining the piece of the bitmap to be drawn,
1.3078 + with co-ordinates relative to the top left corner of the bitmap.
1.3079 + @param aMaskBitmap A mask bitmap
1.3080 + @param aInvertMask If EFalse, a source pixel that is masked by a black pixel
1.3081 + is not transferred to the destination rectangle. If ETrue, then a source
1.3082 + pixel that is masked by a white pixel is not transferred to the destination
1.3083 + rectangle. */
1.3084 + virtual void BitBltMasked(const TPoint& aPoint,const CFbsBitmap* aBitmap,const TRect& aSourceRect,const CFbsBitmap* aMaskBitmap,TBool aInvertMask)=0;
1.3085 +
1.3086 + /** Sets whether the graphics context is faded.
1.3087 +
1.3088 + @param aFaded ETrue to fade the GC; EFalse to unfade it. */
1.3089 + virtual void SetFaded(TBool aFaded)=0;
1.3090 +
1.3091 + /** Sets the fading parameters.
1.3092 +
1.3093 + This function allows you to override the map used when drawing with a faded
1.3094 + graphics context (GC). However if you draw to a faded window with a faded
1.3095 + GC, then fading on the GC is ignored and the fading of the window is used.
1.3096 +
1.3097 + Fading is used to change the colour of a window to make other windows stand
1.3098 + out. Fading can either make a faded window closer to white or closer to
1.3099 + black.
1.3100 +
1.3101 + Fading re-maps colours in the faded GC to fall between the specified black
1.3102 + and white map values. If aBlackMap=0 and aWhiteMap=255 then the colours are
1.3103 + mapped unchanged. As the values converge the colours are mapped to a smaller
1.3104 + range - so the differences between colours in the faded GC decrease. If
1.3105 + the values are reversed then the colours are inverted (i.e. where the GC
1.3106 + would be black, it is now white).
1.3107 +
1.3108 + @param aBlackMap Black map fading parameter. Unfaded this is 0.
1.3109 + @param aWhiteMap White map fading parameter. Unfaded this is 255. */
1.3110 + virtual void SetFadingParameters(TUint8 aBlackMap,TUint8 aWhiteMap)=0;
1.3111 +
1.3112 + /**
1.3113 + Performs an alpha blending of the source data, aSrcBmp, with the CBitmapContext, using
1.3114 + the data from aAlphaBmp as an alpha blending factor.
1.3115 + The formula used is:
1.3116 + (S * A + W * (255 - A)) / 255, where:
1.3117 + - S - a pixel from aSrcBmp;
1.3118 + - W - a pixel from the window;
1.3119 + - A - a pixel from aAlphaBmp;
1.3120 + The contents of source and alpha bitmap are preserved.
1.3121 + The calculated alpha blended pixels are written to the destination CBitmapContext.
1.3122 + @param aDestPt Position in the target the result should be drawn to.
1.3123 + @param aSrcBmp A pointer to the source bitmap.
1.3124 + @param aSrcRect The part of the source bitmap that should be used.
1.3125 + @param aAlphaBmp A pointer to the bitmap used as an alpha blending factor.
1.3126 + @param aAlphaPt Position of the first pixel in the alpha bitmap that should be used as a source
1.3127 + for the alpha blending. The size of the area is the same as the
1.3128 + source bitmap area - aSrcRect parameter.
1.3129 + @return KErrNone, if successful; otherwise, another of the system-wide error codes.*/
1.3130 +
1.3131 + virtual TInt AlphaBlendBitmaps(const TPoint& aDestPt, const CFbsBitmap* aSrcBmp, const TRect& aSrcRect, const CFbsBitmap* aAlphaBmp, const TPoint& aAlphaPt) = 0;
1.3132 +
1.3133 + /**
1.3134 + The method performs an alpha blending of the source data, aSrcBmp, with the CBitmapContext, using
1.3135 + the data from aAlphaBmp as an alpha blending factor.
1.3136 + For information on how this function works, see the other overload.
1.3137 + @param aDestPt Position in the target the result should be drawn to.
1.3138 + @param aSrcBmp A pointer to the source bitmap.
1.3139 + @param aSrcRect The part of the source bitmap that should be used.
1.3140 + @param aAlphaBmp A pointer to the bitmap used as an alpha blending factor.
1.3141 + @param aAlphaPt Position of the first pixel in the alpha bitmap that should be used as a source
1.3142 + for the alpha blending. The size of the area is the same as the
1.3143 + source bitmap area - aSrcRect parameter.
1.3144 + @return KErrNone, if successful; otherwise, another of the system-wide error codes.*/
1.3145 + virtual TInt AlphaBlendBitmaps(const TPoint& aDestPt, const CWsBitmap* aSrcBmp, const TRect& aSrcRect, const CWsBitmap* aAlphaBmp, const TPoint& aAlphaPt) = 0;
1.3146 +
1.3147 +protected:
1.3148 +
1.3149 + /*
1.3150 + Implementations from CGraphicsContext
1.3151 + @see CGraphicsContext::APIExtension(TUid, TAny*&, TAny*)
1.3152 + */
1.3153 + IMPORT_C TInt APIExtension(TUid aUid, TAny*& aOutput, TAny* aInput);
1.3154 + /*
1.3155 + Implementations from CGraphicsContext
1.3156 + @see CGraphicsContext::Reserved_CGraphicsContext_2()
1.3157 + */
1.3158 + IMPORT_C void Reserved_CGraphicsContext_2();
1.3159 +
1.3160 + IMPORT_C virtual void Reserved_CBitmapContext_1();
1.3161 + IMPORT_C virtual void Reserved_CBitmapContext_2();
1.3162 + IMPORT_C virtual void Reserved_CBitmapContext_3();
1.3163 + };
1.3164 +
1.3165 +/** Defines an abstract interface for the capabilities and attributes of a
1.3166 +bitmapped graphics device.
1.3167 +
1.3168 +The class specialises the graphics device interface CGraphicsDevice for bitmaps
1.3169 +graphics. The Window Server Client-Side API provides one implementation of
1.3170 +the interface, CWsScreenDevice, for screen drawing. Another implementation,
1.3171 +CFbsBitmapDevice, is used for drawing to in-memory bitmaps. A third,
1.3172 +CFbsScreenDevice, is used (rarely) to access the screen directly, without the
1.3173 +mediation of the window server.
1.3174 +@publishedAll
1.3175 +@released
1.3176 +*/
1.3177 +class CBitmapDevice : public CGraphicsDevice
1.3178 + {
1.3179 +public:
1.3180 + /** Gets the RGB colour of an individual pixel on a bitmapped graphics
1.3181 + device.
1.3182 +
1.3183 + This pure virtual function is implemented in derived classes.
1.3184 +
1.3185 + @param aColor On return, should contain the RGB colour of the pixel.
1.3186 + @param aPixel The (x,y) co-ordinates of the pixel. The top left pixel is
1.3187 + (0,0). */
1.3188 + virtual void GetPixel(TRgb& aColor,const TPoint& aPixel) const=0;
1.3189 +
1.3190 + /** Copies a scanline into a buffer.
1.3191 +
1.3192 + The pixels are converted from the display mode format on the bitmapped
1.3193 + graphics device to the format of the specified device display mode.
1.3194 +
1.3195 + By specifying the start pixel and the number of pixels, either the whole or
1.3196 + a portion of a bitmapped graphics device pixel row may be copied.
1.3197 +
1.3198 + This pure virtual function is implemented in derived classes.
1.3199 +
1.3200 + @param aBuf An 8 bit modifiable descriptor buffer into which pixels are
1.3201 + copied; it must be sufficiently large to store all the scanline pixels.
1.3202 + @param aStartPixel The (x,y) co-ordinates of the first pixel of the bitmap
1.3203 + scanline to be put into the buffer.
1.3204 + @param aLength The number of pixels to put into the buffer.
1.3205 + @param aDispMode The display mode into which to convert the pixels. */
1.3206 + virtual void GetScanLine(TDes8& aBuf,const TPoint& aStartPixel,TInt aLength,TDisplayMode aDispMode) const=0;
1.3207 +
1.3208 + /** Adds a font file to the device's typeface store. The specified font
1.3209 + file must be accessible to any process, i.e. not located inside an
1.3210 + application's private directory.
1.3211 +
1.3212 + This pure virtual function is implemented in derived classes.
1.3213 +
1.3214 + @param aName The name of the font file.
1.3215 + @param aId On return, contains an ID for the font file.
1.3216 + @return KErrNone, if successful; otherwise, another of the system-wide error
1.3217 + codes. */
1.3218 + virtual TInt AddFile(const TDesC& aName,TInt& aId)=0;
1.3219 +
1.3220 + /** Removes a font file from the font store.
1.3221 +
1.3222 + This pure virtual function is implemented in derived classes.
1.3223 +
1.3224 + @param aId The ID of the font file to be removed. The default is 0. */
1.3225 + virtual void RemoveFile(TInt aId=0)=0;
1.3226 +
1.3227 + /**
1.3228 + Gets the font which is the nearest to the given font specification.
1.3229 +
1.3230 + When the font is no longer needed, call @c ReleaseFont().
1.3231 +
1.3232 + Note that this deprecated function is replaced by the new @c GetNearestFontToDesignHeightInPixels()
1.3233 + yielding (virtually) the same result. However clients are strongly encouraged to use the new
1.3234 + @c GetNearestFontToMaxHeightInPixels() function instead. This will guarantee that every
1.3235 + character within any given text string will fit within the given amount of pixels, whereas the design
1.3236 + height is an aesthetic unit decided by the font designer without strict physical meaning, which
1.3237 + may result in cropped characters.
1.3238 +
1.3239 + @param aFont On return, contains a pointer to the nearest font.
1.3240 + @param aFontSpec The specification of the font to be matched.
1.3241 + @return KErrNone if successful; a system-wide error code otherwise.
1.3242 + @publishedAll
1.3243 + @deprecated Use GetNearestFontToDesignHeightInPixels
1.3244 + */
1.3245 + virtual TInt GetNearestFontInPixels(CFont*& aFont, const TFontSpec& aFontSpec) = 0;
1.3246 +
1.3247 + /**
1.3248 + Gets the font which is the nearest to the given font specification.
1.3249 +
1.3250 + When the font is no longer needed, call @c ReleaseFont().
1.3251 +
1.3252 + This new function replaces the deprecated @c GetNearestFontInPixels() yielding (virtually) the
1.3253 + same result. However clients are strongly encouraged to use the new
1.3254 + @c GetNearestFontToMaxHeightInPixels() function instead. This will guarantee that every
1.3255 + character within any given text string will fit within the given amount of pixels, whereas the design
1.3256 + height is an aesthetic unit decided by the font designer without strict physical meaning, which
1.3257 + may result in cropped characters.
1.3258 +
1.3259 + @param aFont On return, contains a pointer to the nearest font.
1.3260 + @param aFontSpec The specification of the font to be matched.
1.3261 + @return KErrNone if successful; a system-wide error code otherwise.
1.3262 + @publishedAll
1.3263 + @released
1.3264 + */
1.3265 + virtual TInt GetNearestFontToDesignHeightInPixels(
1.3266 + CFont*& /*aFont*/, const TFontSpec& /*aFontSpec*/) { return KErrNotSupported; }
1.3267 +
1.3268 + /**
1.3269 + Gets the font which is the nearest to the given font specification.
1.3270 +
1.3271 + When the font is no longer needed, call @c ReleaseFont().
1.3272 +
1.3273 + The font and bitmap server returns a pointer to the nearest matching font
1.3274 + from those available. Matches to max height of font - this does its best
1.3275 + to return a font that will fit within the maximum height specified (but
1.3276 + note that variations due to hinting algorithms may rarely result in this
1.3277 + height being exceeded by up to one pixel). Problems can also be
1.3278 + encountered with bitmap fonts where the typeface exists but doesn't have
1.3279 + a font small enough.
1.3280 +
1.3281 + @param aFont On return, contains a pointer to the nearest font.
1.3282 + @param aFontSpec The specification of the font to be matched.
1.3283 + @param aMaxHeight The maximum height within which the font must fit.
1.3284 + This overrides the height specified in aFontSpec.
1.3285 + @return KErrNone if successful; a system-wide error code otherwise.
1.3286 + @publishedAll
1.3287 + @released
1.3288 + */
1.3289 + virtual TInt GetNearestFontToMaxHeightInPixels(
1.3290 + CFont*& /*aFont*/, const TFontSpec& /*aFontSpec*/, TInt /*aMaxHeight*/) { return KErrNotSupported; }
1.3291 +
1.3292 + /** Gets the height, in pixels, of the specified typeface at one of its
1.3293 + defined heights.
1.3294 +
1.3295 + The typeface is identified by by an index. For a given typeface, there are
1.3296 + a discrete number of heights; the specific height is also identified by an
1.3297 + index.
1.3298 +
1.3299 + The value returned is rounded up or down to the nearest font height in
1.3300 + pixels.
1.3301 +
1.3302 + This pure virtual function is implemented in derived classes.
1.3303 +
1.3304 + @param aTypefaceIndex A typeface index number, in the range: 0 to
1.3305 + (NumTypefaces() - 1).
1.3306 + @param aHeightIndex A font height index number, in the range: 0 to
1.3307 + (iNumHeights - 1) where iNumHeights is a public data member of the
1.3308 + TTypefaceSupport object returned by TypefaceSupport().
1.3309 + @return The height of the font, in pixels.
1.3310 + @see TTypefaceSupport
1.3311 + @see CGraphicsDevice::NumTypefaces()
1.3312 + @see CGraphicsDevice::TypefaceSupport() */
1.3313 + virtual TInt FontHeightInPixels(TInt aTypefaceIndex,TInt aHeightIndex) const=0;
1.3314 + inline TInt CreateBitmapContext(CBitmapContext*& aGC);
1.3315 + };
1.3316 +
1.3317 +/** A set of margins used for cropping a picture.
1.3318 +
1.3319 +Margins are specified in twips or pixels.
1.3320 +@publishedAll
1.3321 +@released
1.3322 +*/
1.3323 +class TMargins
1.3324 + {
1.3325 +public:
1.3326 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.3327 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.3328 + IMPORT_C TBool operator==(const TMargins& aMargins) const;
1.3329 + IMPORT_C TBool operator!=(const TMargins& aMargins) const;
1.3330 +public:
1.3331 + /** Left margin, (in twips or pixels). */
1.3332 + TInt iLeft;
1.3333 + /** Right margin, (in twips or pixels). */
1.3334 + TInt iRight;
1.3335 + /** Top margin, (in twips or pixels). */
1.3336 + TInt iTop;
1.3337 + /** Bottom margin, (in twips or pixels). */
1.3338 + TInt iBottom;
1.3339 + };
1.3340 +
1.3341 +/** Picture capabilities.
1.3342 +
1.3343 +These include the types of scaling that can be applied to a picture, and whether
1.3344 +or not it is croppable.
1.3345 +@publishedAll
1.3346 +@released
1.3347 +*/
1.3348 +class TPictureCapability
1.3349 + {
1.3350 +public:
1.3351 + /** Scaling types. */
1.3352 + enum TScalingType
1.3353 + {
1.3354 + /** The picture is not scalable. */
1.3355 + ENotScaleable,
1.3356 + /** The picture is fully scalable. */
1.3357 + EFullyScaleable,
1.3358 + /** The picture is scalable to any size, as long as its aspect ratio
1.3359 + (the ratio of its height to its width) remains constant. */
1.3360 + EScaleableMaintainingAspectRatio
1.3361 + };
1.3362 +public:
1.3363 + inline TPictureCapability(TScalingType aScalingType,TBool aCroppable);
1.3364 +public:
1.3365 + /** Whether or not the picture is croppable. */
1.3366 + TScalingType iScalingType;
1.3367 + /** Scaling type. */
1.3368 + TBool iIsCroppable;
1.3369 + };
1.3370 +
1.3371 +/** Abstract base class for: drawing a picture to a graphics context, storing
1.3372 +and restoring the picture.
1.3373 +
1.3374 +The class defines the protocol for a number of concrete picture classes. Its
1.3375 +main role is to support glass doors used in object embedding.
1.3376 +
1.3377 +The class provides a protocol for the provision of scaling and cropping
1.3378 +functions by derived classes, together with default implementations.
1.3379 +
1.3380 +Its main function is Draw(), which draws the picture onto the graphics context
1.3381 +at a particular point. It also has two important pure virtual functions:
1.3382 +ExternalizeL() and GetOriginalSizeInTwips().
1.3383 +
1.3384 +A picture has both an original representation and an on-screen representation.
1.3385 +The original representation has a size in twips, and can somehow be drawn.
1.3386 +The on-screen representation is assumed to be drawn under the control of an
1.3387 +application which may wish to re-size or scale the original in some way, to
1.3388 +crop it at the edges, and/or to ensure it fits within a particular defined
1.3389 +area on the screen.
1.3390 +
1.3391 +The class provides several functions that allow an application to set scaling
1.3392 +and cropping before invoking the Draw() function to draw the picture on-screen.
1.3393 +It is up to the internal workings of the function to determine the order of
1.3394 +application cropping and scaling.
1.3395 +@publishedAll
1.3396 +@released
1.3397 +*/
1.3398 +class CPicture : public CBase
1.3399 + {
1.3400 +public:
1.3401 + /** Options for detaching pictures from stores. Used by DetachFromStoreL(). */
1.3402 + enum TDetach
1.3403 + {
1.3404 + /** Internalise all data that is required to fully store the picture
1.3405 + later; null any references to containing stores. */
1.3406 + EDetachFull,
1.3407 + /** Internalise enough information to draw the picture (and no more);
1.3408 + null any references to containing stores. */
1.3409 + EDetachDraw
1.3410 + };
1.3411 +public:
1.3412 + IMPORT_C virtual ~CPicture();
1.3413 + /** Draws a picture.
1.3414 +
1.3415 + @param aGc The graphics context.
1.3416 + @param aTopLeft The co-ordinates where the top left corner pixel of the
1.3417 + picture should be placed. Note that whether this is actually drawn depends
1.3418 + on the clipping area defined.
1.3419 + @param aClipRect A clipping rectangle that defines the area to which the
1.3420 + function should draw. An implementation should never draw outside this
1.3421 + rectangle. Note that the graphics context may also have a clipping rectangle
1.3422 + set on it.
1.3423 + @param aMap The device map for the graphics device. The implementation
1.3424 + should use this to find the scaling to apply to the picture. */
1.3425 + virtual void Draw(CGraphicsContext& aGc,const TPoint& aTopLeft,const TRect& aClipRect,MGraphicsDeviceMap* aMap) const=0;
1.3426 + IMPORT_C virtual TStreamId StoreL(CStreamStore& aStore) const; // assumes no sub streams
1.3427 + virtual void DetachFromStoreL(TDetach /*aDegree*/=EDetachFull) {}
1.3428 +
1.3429 + /** Externalises the picture to a stream.
1.3430 +
1.3431 + The presence of this function means that the standard templated stream
1.3432 + operator<<() is available to externalise objects of this class.
1.3433 +
1.3434 + A derived class must supply an implementation of this function.
1.3435 +
1.3436 + @param aStream The write stream. */
1.3437 + virtual void ExternalizeL(RWriteStream& aStream) const =0;
1.3438 +
1.3439 + /** Gets the pictur's original size, in twips.
1.3440 +
1.3441 + @param aSize The size of the picture, in twips */
1.3442 + virtual void GetOriginalSizeInTwips(TSize& aSize) const =0;
1.3443 + IMPORT_C virtual void SetScaleFactor(TInt aScaleFactorWidth,TInt aScaleFactorHeight); // does nothing
1.3444 + IMPORT_C virtual void SetCropInTwips(const TMargins& aMargins); // does nothing
1.3445 + IMPORT_C virtual TPictureCapability Capability() const; // no scale, no crop
1.3446 + IMPORT_C virtual void GetCropInTwips(TMargins& aMargins) const; // returns no crop
1.3447 + IMPORT_C virtual TInt ScaleFactorWidth() const; // returns no scaling
1.3448 + IMPORT_C virtual TInt ScaleFactorHeight() const; // returns no scaling
1.3449 + IMPORT_C virtual TBool LineBreakPossible(TUint aClass,TBool aBeforePicture,TBool aHaveSpaces) const;
1.3450 + IMPORT_C virtual TBool NativePixelSize(TSize& aPixelSize);
1.3451 +
1.3452 + IMPORT_C void GetSizeInPixels(MGraphicsDeviceMap* aMap, TSize& aSize) const;
1.3453 + IMPORT_C void SetSizeInPixels(MGraphicsDeviceMap* aMap, const TSize& aSize);
1.3454 + IMPORT_C void AddCropInPixels(MGraphicsDeviceMap* aMap, const TMargins& aMargins);
1.3455 + IMPORT_C void GetSizeInTwips(TSize& aSize) const;
1.3456 + IMPORT_C void SetSizeInTwips(const TSize& aSize);
1.3457 + IMPORT_C void ResetToOriginal();
1.3458 +protected:
1.3459 + IMPORT_C CPicture();
1.3460 + };
1.3461 +
1.3462 +
1.3463 +/** Picture header providing an interface to a stored picture. The header holds:
1.3464 +
1.3465 +the picture's type, encoded as a UID, which ensures that it will be restored
1.3466 +to the correct picture type
1.3467 +
1.3468 +the picture's size, which facilitates deferred loading
1.3469 +
1.3470 +the stream ID of the picture body, which is replaced by a pointer to the picture
1.3471 +object when it has been restored.
1.3472 +@publishedAll
1.3473 +@released
1.3474 +*/
1.3475 +class TPictureHeader
1.3476 + {
1.3477 +public:
1.3478 + IMPORT_C TPictureHeader();
1.3479 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.3480 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.3481 + IMPORT_C void DeletePicture();
1.3482 +public:
1.3483 + /** A swizzle storing either the ID of the stream in which the picture is
1.3484 + stored, or a pointer to the internalised picture. */
1.3485 + TSwizzle<CPicture> iPicture;
1.3486 + /** A UID specifying the type of the picture. */
1.3487 + TUid iPictureType;
1.3488 + /** The original size of the picture. */
1.3489 + TSize iSize;
1.3490 + };
1.3491 +
1.3492 +
1.3493 +/** Abstract interface for instantiating and restoring new CPicture derived
1.3494 +objects.
1.3495 +
1.3496 +A concrete derived class creates pictures of one or more specific types. The
1.3497 +class has no member data and just one function, NewPictureL, that needs to
1.3498 +be provided by derived classes.
1.3499 +@publishedAll
1.3500 +@released
1.3501 +*/
1.3502 +class MPictureFactory
1.3503 + {
1.3504 +public:
1.3505 + /** Interface to the picture restoration process that ensures that a
1.3506 + picture of the correct type is restored.
1.3507 +
1.3508 + The class of the object to be restored is determined by the UID of the
1.3509 + stored picture, contained in the specified picture header.
1.3510 +
1.3511 + The function can allow the restoration of:
1.3512 +
1.3513 + just one CPicture-derived class, returning an error if the UID indicates
1.3514 + that the stored picture is not of the required type
1.3515 +
1.3516 + many different CPicture-derived classes, using the UID to choose which of
1.3517 + the possible CPicture-derived classes should be instantiated
1.3518 +
1.3519 + @param aHeader The picture header that should be restored.
1.3520 + @param aDeferredPictureStore The store in which both the header and picture
1.3521 + reside. */
1.3522 + virtual void NewPictureL(TPictureHeader& aHeader,const CStreamStore& aDeferredPictureStore)const=0;
1.3523 + };
1.3524 +
1.3525 +// printing classes
1.3526 +
1.3527 +/**
1.3528 +The maximum length of a printer model name.
1.3529 +@see TPrinterModelName
1.3530 +@publishedAll
1.3531 +@released
1.3532 +*/
1.3533 +const TInt KMaxPrinterModelNameLength=0x20;
1.3534 +
1.3535 +/**
1.3536 +Defines a modifiable buffer descriptor that can contain the name of a
1.3537 +printer model. The maximum length of the buffer is 32.
1.3538 +@since 5.0
1.3539 +@publishedAll
1.3540 +@released
1.3541 +*/
1.3542 +typedef TBuf<KMaxPrinterModelNameLength> TPrinterModelName;
1.3543 +
1.3544 +/** Page specification for a print operation.
1.3545 +
1.3546 + The page specification consists of the page orientation and the page
1.3547 +size in twips or pixels. By default, the page orientation is portrait.
1.3548 +When using landscape orientation, the left hand side of the page
1.3549 +becomes the top.
1.3550 +"gdi.lib"
1.3551 +@since 5.0
1.3552 +@publishedAll
1.3553 +@released
1.3554 +*/
1.3555 +class TPageSpec
1.3556 + {
1.3557 +public:
1.3558 + /**The available page orientations. */
1.3559 + enum TPageOrientation
1.3560 + {
1.3561 + /** Portrait page orientation */
1.3562 + EPortrait,
1.3563 + /** Landscape page orientation */
1.3564 + ELandscape
1.3565 + };
1.3566 +public:
1.3567 + IMPORT_C TPageSpec();
1.3568 + IMPORT_C TPageSpec(TPageOrientation aOrientation,const TSize& aSize);
1.3569 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.3570 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.3571 + IMPORT_C TSize OrientedPageSize() const;
1.3572 + IMPORT_C TBool operator==(const TPageSpec& aPageSpec) const;
1.3573 + IMPORT_C TBool operator!=(const TPageSpec& aPageSpec) const;
1.3574 +public:
1.3575 + /** The width and height of the page in portrait orientation in twips or
1.3576 + pixels.
1.3577 +
1.3578 + Note that OrientedPageSize() returns the width and height in reverse order
1.3579 + for a landscape portrait. */
1.3580 + TSize iPortraitPageSize;
1.3581 + /** The page orientation. */
1.3582 + TPageOrientation iOrientation;
1.3583 + };
1.3584 +
1.3585 +
1.3586 +/** Controls the attributes of the band to be printed.
1.3587 +
1.3588 +An object of this type is passed as a parameter to functions.
1.3589 +MPageRegionPrinter::PrintBandL() and CPrinterControl::QueueGetBand().
1.3590 +@see MPageRegionPrinter::PrintBandL()
1.3591 +@see CPrinterControl::QueueGetBand()
1.3592 +@since 5.0
1.3593 +@publishedAll
1.3594 +@released
1.3595 +*/
1.3596 +class TBandAttributes
1.3597 + {
1.3598 +public:
1.3599 + /** The width and height of the band in twips or pixels. */
1.3600 + TRect iRect;
1.3601 + /** ETrue to draw no text to the band; EFalse to draw text. */
1.3602 + TBool iTextIsIgnored; // any text drawing to this band is ignored
1.3603 + /** ETrue to draw no graphics to the band; EFalse to draw graphics. */
1.3604 + TBool iGraphicsIsIgnored; // any graphics drawing to this band is ignored
1.3605 + /** ETrue if band is the first band on the page; EFalse if not. */
1.3606 + TBool iFirstBandOnPage;
1.3607 + };
1.3608 +
1.3609 +/** Printer port interface.
1.3610 +
1.3611 +This interface is used as the base class for the various types of
1.3612 +printer port. New printer port classes should be derived from this
1.3613 +class.After allocation and construction, a pointer to a concrete
1.3614 +printer port should be passed to
1.3615 +CPrintSetup::StartPrintL().
1.3616 +@see CPrintSetup::StartPrintL()
1.3617 +@since 5.0
1.3618 +@publishedAll
1.3619 +@released
1.3620 +*/
1.3621 +class CPrinterPort : public CBase
1.3622 + {
1.3623 +public:
1.3624 + /** Writes data asynchronously to the printer port.
1.3625 +
1.3626 + @param aBuf Data to be written to the port
1.3627 + @param aRequestStatus A reference to the request status object. If the
1.3628 + request is cancelled, this should be set to KErrCancel; if the request
1.3629 + completes normally, this should be set to KErrNone. */
1.3630 + virtual void WriteRequest(const TDesC8& aBuf,TRequestStatus& aRequestStatus)=0;
1.3631 +
1.3632 + /** Cancels an outstanding WriteRequest() operation. */
1.3633 + virtual void Cancel()=0;
1.3634 + };
1.3635 +
1.3636 +
1.3637 +/** Detailed information about a printer model.
1.3638 +"gdi.lib"
1.3639 +@since 5.0
1.3640 +@publishedAll
1.3641 +@released
1.3642 +*/
1.3643 +class TPrinterModelEntry
1.3644 + {
1.3645 +public:
1.3646 + /** The name of the printer model. */
1.3647 + TPrinterModelName iModelName;
1.3648 + /** If ETrue, then a printer port is required. */
1.3649 + TBool iRequiresPrinterPort;
1.3650 + /** The UID associated with this printer model. */
1.3651 + TUid iUid;
1.3652 +public:
1.3653 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.3654 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.3655 + };
1.3656 +
1.3657 +
1.3658 +/** Information about a printer model.
1.3659 +
1.3660 +An instance of this class consists of a TPrinterModelEntry and a stream ID,
1.3661 +and is passed to CPrinterDevice::SetModel().
1.3662 +
1.3663 +@see CPrinterDevice
1.3664 +@publishedAll
1.3665 +@released
1.3666 +*/
1.3667 +class TPrinterModelHeader
1.3668 + {
1.3669 +public:
1.3670 + /** The printer model. */
1.3671 + TPrinterModelEntry iEntry;
1.3672 + /** The stream ID for model data. */
1.3673 + TStreamId iModelDataStreamId;
1.3674 +public:
1.3675 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.3676 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.3677 + };
1.3678 +
1.3679 +
1.3680 +/** Printer control interface.
1.3681 +
1.3682 +This abstract base class acts as the interface between a CPrinterDevice object
1.3683 +and the printer. It creates the context for, and controls the progress and
1.3684 +termination of the print job.
1.3685 +
1.3686 +Only those who need to add new printer drivers should write derived classes.
1.3687 +After instantiation of such a class, using CPrinterDevice::CreateControlL(),
1.3688 +the object can be accessed via the iControl member of CPrinterDevice.
1.3689 +
1.3690 +@see CPrinterDevice
1.3691 +@publishedAll
1.3692 +@released
1.3693 +*/
1.3694 +class CPrinterControl : public CBase
1.3695 + {
1.3696 +public:
1.3697 + /** Flags indicating whether there is more on the page to print. */
1.3698 + enum TMoreOnPage
1.3699 + {
1.3700 + /** Indicates there is more to print on the current page. */
1.3701 + EMoreOnPage,
1.3702 + /** Indicates there is no more to print on the current page. */
1.3703 + ENoMoreOnPage
1.3704 + };
1.3705 +public:
1.3706 + IMPORT_C ~CPrinterControl();
1.3707 +
1.3708 + /** Gets the number of bands per page.
1.3709 +
1.3710 + @return The number of bands on each page. */
1.3711 + virtual TInt BandsPerPage()=0;
1.3712 +
1.3713 + /** Prints the next band on the page.
1.3714 +
1.3715 + This is an asynchronous function.
1.3716 + @param aStatus Request status object. On successful completion
1.3717 + contains KErrNone, otherwise another of the system-wide
1.3718 + error codes.
1.3719 + @param aBand On return, indicates the attributes of the band, including
1.3720 + its height and width and whether or not the device will ignore one or
1.3721 + other of graphics or text output. This information may be used by
1.3722 + applications to draw more efficiently, or may be ignored
1.3723 + @return EMoreOnPage, if any unprinted bands remain on the
1.3724 + current page. ENoMoreOnPage, if the current band is last on
1.3725 + page. */
1.3726 + virtual TMoreOnPage QueueGetBand(TRequestStatus& aStatus, TBandAttributes& aBand)=0; // returns affirmative if more to print on current page
1.3727 +
1.3728 + /** Terminates the print process.
1.3729 +
1.3730 + This is an asynchronous function and is called when no more bands in
1.3731 + the document remain to be printed.Note that all bands have been
1.3732 + printed when no more pages or copies remain to be printed, and
1.3733 + QueueGetBand() returns ENoMoreToPrint.
1.3734 +
1.3735 + @param aStatus Request status object. On successful completion contains
1.3736 + KErrNone, otherwise another of the system-wide error codes. */
1.3737 + virtual void QueueEndPrint(TRequestStatus& aStatus)=0;
1.3738 +
1.3739 + /** Aborts the print process before it has completed.
1.3740 +
1.3741 + This function should be called if QueueGetBand() reports an error. */
1.3742 + virtual void AbortPrint()=0; // tidy up synchronously in a short time, return success code
1.3743 +protected:
1.3744 + IMPORT_C CPrinterControl(CPrinterPort* aPrinterPort);
1.3745 +protected:
1.3746 + /** State flags. */
1.3747 + enum TState
1.3748 + {
1.3749 + /** Not printing. */
1.3750 + ENotPrinting,
1.3751 + /** Printing. */
1.3752 + EPrinting
1.3753 + };
1.3754 + /** Printing state. */
1.3755 + TState iState;
1.3756 + /** Printer port. */
1.3757 + CPrinterPort* iPrinterPort;
1.3758 + };
1.3759 +
1.3760 +class CDictionaryStore;
1.3761 +class RFs;
1.3762 +
1.3763 +/** Printer graphics device interface.
1.3764 +
1.3765 +This abstract class represents a physical graphics device that is used for
1.3766 +printing.
1.3767 +
1.3768 +This class is used to:
1.3769 +
1.3770 +set and get the page specification
1.3771 +
1.3772 +map between the co-ordinates of the printed page (in twips) and the co-ordinates
1.3773 +of the image device (in pixels)
1.3774 +
1.3775 +get and set the printer model entry
1.3776 +
1.3777 +create and delete a printer control.
1.3778 +
1.3779 +A printer driver is defined in terms of a printer device and a printer control.
1.3780 +A printer device can own either a single or no printer control. The control
1.3781 +determines the progress and termination of the print job and is responsible
1.3782 +for producing output.
1.3783 +
1.3784 +@see CPrinterControl
1.3785 +@publishedAll
1.3786 +@released
1.3787 +*/
1.3788 +class CPrinterDevice : public CGraphicsDevice
1.3789 + {
1.3790 +public:
1.3791 + IMPORT_C ~CPrinterDevice();
1.3792 +
1.3793 + /** Gets the current page specification in twips.
1.3794 +
1.3795 + @return The current page specification, in twips. */
1.3796 + inline TPageSpec CurrentPageSpecInTwips() const {return(iCurrentPageSpecInTwips);}
1.3797 +
1.3798 + /** Sets the page specification in twips.
1.3799 +
1.3800 + @param aPageSpec The page specification in twips. */
1.3801 + IMPORT_C virtual void SelectPageSpecInTwips(const TPageSpec& aPageSpec);
1.3802 + IMPORT_C virtual TRect PrintablePageInPixels() const;
1.3803 +
1.3804 + /** Gets the printer model entry.
1.3805 +
1.3806 + @return The printer model entry. */
1.3807 + virtual TPrinterModelEntry Model()const =0;
1.3808 +
1.3809 + /** Sets the printer model header and the store.
1.3810 +
1.3811 + @param aModel The printer model header.
1.3812 + @param aStore The store.
1.3813 + @return KErrNone if successful; otherwise, another of the system-wide
1.3814 + error codes.*/
1.3815 + virtual TInt SetModel(const TPrinterModelHeader& aModel,CStreamStore& aStore)=0;
1.3816 +
1.3817 + /** Creates a printer control.
1.3818 +
1.3819 + The printer control is an instance of a CPrinterControl derived class; it
1.3820 + is assigned to this printer device's iControl member.
1.3821 +
1.3822 + Note that this function is called by CPrintSetup::StartPrintL().
1.3823 +
1.3824 + @param aPrinterPort Pointer to an instance of a printer port. */
1.3825 + virtual void CreateControlL(CPrinterPort* aPrinterPort)=0;
1.3826 + IMPORT_C virtual void DeleteControl();
1.3827 +
1.3828 + /** Externalizes printer properties to the store.
1.3829 +
1.3830 + The default implementation is empty.
1.3831 +
1.3832 + @param aStream The read stream. */
1.3833 + virtual void InternalizePropertiesL(RReadStream& /*aStream*/) {}
1.3834 +
1.3835 + /** Externalizes printer properties to the store.
1.3836 +
1.3837 + The default implementation is empty.
1.3838 +
1.3839 + @param aStream The write stream. */
1.3840 + virtual void ExternalizePropertiesL(RWriteStream& /*aStream*/) const {}
1.3841 + IMPORT_C void RestorePropertiesL();
1.3842 + IMPORT_C void StorePropertiesL() const;
1.3843 +protected:
1.3844 + IMPORT_C CPrinterDevice();
1.3845 +public:
1.3846 + /** The printer control.
1.3847 +
1.3848 + This may be NULL. If implemented, it provides control over the print
1.3849 + operation. */
1.3850 + CPrinterControl* iControl;
1.3851 +protected:
1.3852 + /** Current page specification in twips. */
1.3853 + TPageSpec iCurrentPageSpecInTwips;
1.3854 + };
1.3855 +
1.3856 +
1.3857 +/** Printer model list interface.
1.3858 +
1.3859 +Functions provided by this abstract base class can be used to extract printer
1.3860 +model information from the list of printer models. This class would typically
1.3861 +be used to implement printer selection in a dialog box.
1.3862 +
1.3863 +@see CPdrModelList
1.3864 +@publishedAll
1.3865 +@released
1.3866 +*/
1.3867 +class CPrinterModelList : public CBase
1.3868 + {
1.3869 +public:
1.3870 + /** Gets the number of printer models in the printer model list.
1.3871 +
1.3872 + @return The number of printer models. */
1.3873 + virtual TInt ModelCount() const=0;
1.3874 +
1.3875 + /**Gets printer model name.
1.3876 +
1.3877 + This is the name of the printer model at the specified index within
1.3878 + the list of printer models.
1.3879 +
1.3880 + @param anIndex The index of the printer model within the array of
1.3881 + printer models. Note that this number must be between zero and
1.3882 + ModelCount().
1.3883 + @return Name of printer model, up to 32 characters long */
1.3884 + virtual const TPrinterModelEntry operator[](TInt anIndex)=0;
1.3885 +
1.3886 + /** Gets a printer models index within the model list from its UID.
1.3887 +
1.3888 + @param aModelUid The UID of the printer model.
1.3889 + @return The index of the printer model within the array of printer models.*/
1.3890 + virtual TInt UidToNum(TUid aModelUid) const=0;
1.3891 + };
1.3892 +
1.3893 +
1.3894 +/** Interface for printing in bands.
1.3895 +
1.3896 +This class provides a single PrintBandL() function that prints
1.3897 +the body of each page band by band. Classes derived from this interface must
1.3898 +provide an implementation of the PrintBandL() function.
1.3899 +@since 5.0
1.3900 +@publishedAll
1.3901 +@released
1.3902 +*/
1.3903 +class MPageRegionPrinter
1.3904 + {
1.3905 +public:
1.3906 + /** Prints a band.
1.3907 +
1.3908 + Implementations should set up a graphics context to which all drawing should
1.3909 + take place using CGraphicsDevice::CreateContext(). All co-ordinate
1.3910 + calculations should be done in twips, and converted into pixels before
1.3911 + starting the print job.
1.3912 +
1.3913 + @param aDevice Pointer to the graphics device representing the printer.
1.3914 + @param aPageNo The number of the page containing the band to be printed.
1.3915 + @param aBandInPixels Attributes of the band to be printed. */
1.3916 + virtual void PrintBandL(CGraphicsDevice* aDevice,TInt aPageNo,const TBandAttributes& aBandInPixels)=0;
1.3917 + };
1.3918 +
1.3919 +/**
1.3920 +The UID value of a printer specification data store.
1.3921 +@publishedAll
1.3922 +@released
1.3923 +*/
1.3924 +const TInt KPdrStoreFileUidVal=268435514;
1.3925 +
1.3926 +const TInt KPdlUidVal=268450588;
1.3927 +const TInt KUdlUidVal=268450589;
1.3928 +
1.3929 +
1.3930 +/** Printer specific user interface.
1.3931 +
1.3932 +The class is used to implement a printer specific setup dialog. A concrete
1.3933 +implementation of the class is supplied in a UDL (i.e. a UI DLL).
1.3934 +
1.3935 +CPrinterDriver::CreatePrinterDriverUIL() is used to construct a CPrinterDriverUI
1.3936 +object for a specific printer. (This function calls the ordinal 1 exported
1.3937 +function of the UDL that performs the construction of the CPrinterDriverUI
1.3938 +object).
1.3939 +
1.3940 +@see CPrinterDriver::CreatePrinterDriverUIL()
1.3941 +@publishedAll
1.3942 +@released
1.3943 +*/
1.3944 +class CPrinterDriverUI : public CBase
1.3945 + {
1.3946 +protected:
1.3947 + IMPORT_C CPrinterDriverUI();
1.3948 +public:
1.3949 + IMPORT_C virtual TBool BeforePrintL();
1.3950 + IMPORT_C virtual void AfterPrintL();
1.3951 + IMPORT_C virtual void SetPropertiesL();
1.3952 + IMPORT_C virtual TBool CanSetProperties();
1.3953 +
1.3954 + /** Sets the printer device.
1.3955 +
1.3956 + @param aPrinterDevice The printer device. */
1.3957 + virtual TInt SetPrinterDevice(CPrinterDevice* aPrinterDevice)=0;
1.3958 + };
1.3959 +
1.3960 +class CFileStore;
1.3961 +
1.3962 +
1.3963 +/** Provides access to a store containing printer specification data.
1.3964 +
1.3965 +Printer specification data is held as a direct file store, and usually has
1.3966 +a .pdr file type.
1.3967 +
1.3968 +A printer driver is implemented as two files: a PDR file containing the printer
1.3969 +specification data and a PDL file containing the code to link the printer
1.3970 +with the graphics printing system.
1.3971 +
1.3972 +The printer specification data is generated by compiling a text file (a .pd
1.3973 +file type) using the pdrtran tool. Printer specification data defines:
1.3974 +
1.3975 +the name of the associated PDL
1.3976 +
1.3977 +a list of one or more models supported by this driver, identified by name
1.3978 +and UID
1.3979 +
1.3980 +device information such as the size of the device, typeface information for
1.3981 +each model, including which typefaces are supported, the heights available
1.3982 +in each typeface and the width of each character in a font.
1.3983 +
1.3984 +@see CPrinterDriverUI
1.3985 +@publishedAll
1.3986 +@released
1.3987 +*/
1.3988 +class CPrinterDriver : public CBase
1.3989 + {
1.3990 +public:
1.3991 + IMPORT_C static CPrinterDriver* NewL();
1.3992 + IMPORT_C ~CPrinterDriver();
1.3993 + IMPORT_C void OpenPdrL(const TDesC &aName);
1.3994 + IMPORT_C void Close();
1.3995 + IMPORT_C TInt NumModels() const;
1.3996 + IMPORT_C TPrinterModelEntry Model(TInt aNum) const;
1.3997 +
1.3998 + /** Gets the associated graphics printer device.
1.3999 +
1.4000 + @return The physical graphics device used for printing. */
1.4001 + inline CPrinterDevice* PrinterDevice() {return iPrinterDevice;}
1.4002 + IMPORT_C CPrinterDevice* CreatePrinterDeviceL(TUid aModelUid);
1.4003 + IMPORT_C CPrinterDriverUI* CreatePrinterDriverUIL();
1.4004 +private:
1.4005 + CPrinterDriver();
1.4006 + void DeletePrinterDevice();
1.4007 + void DoOpenPdrL(const TDesC &aName);
1.4008 + void DoCreatePrinterDeviceL(TUid aModelUid);
1.4009 + void LoadLibraryL(RLibrary& aLibrary,const TDesC& aExt,TUid aUid2);
1.4010 +private:
1.4011 + RFs iFs;
1.4012 + CFileStore *iPdrStore;
1.4013 + TInt iNumModels;
1.4014 + TPrinterModelHeader* iModelList;
1.4015 + TFileName iPdlName;
1.4016 + TUid iPdlUid;
1.4017 + RLibrary iPdlLibrary;
1.4018 + CPrinterDevice* iPrinterDevice;
1.4019 + RLibrary iUdlLibrary;
1.4020 + };
1.4021 +
1.4022 +class RResourceFile;
1.4023 +
1.4024 +
1.4025 +/** Implements a printer model list interface for a collection of PDR files.
1.4026 +@publishedAll
1.4027 +@released
1.4028 +*/
1.4029 +class CPdrModelList : public CPrinterModelList
1.4030 + {
1.4031 +public:
1.4032 + IMPORT_C static CPdrModelList* NewL();
1.4033 + IMPORT_C virtual ~CPdrModelList();
1.4034 + IMPORT_C TInt ModelCount() const;
1.4035 + IMPORT_C const TPrinterModelEntry operator [] (TInt anIndex);
1.4036 + IMPORT_C TInt UidToNum(TUid aModelUid) const; // returns KErrNotFound the model uid is not matched
1.4037 + IMPORT_C void AddDirectoryL(const TDesC& aDir);
1.4038 + IMPORT_C CPrinterModelList* ScanForModelsL();
1.4039 + IMPORT_C CPrinterDriver* CreatePrinterDriverL(TInt anIndex);
1.4040 +private:
1.4041 + CPdrModelList();
1.4042 + void ConstructL();
1.4043 +private:
1.4044 + class TFileEntry
1.4045 + {
1.4046 + public:
1.4047 + TFileName iFileName;
1.4048 + TDesC* iDirectory;
1.4049 + };
1.4050 + class TModelEntry
1.4051 + {
1.4052 + public:
1.4053 + TPrinterModelEntry iEntry;
1.4054 + TFileEntry* iFile;
1.4055 + };
1.4056 +private:
1.4057 + void ScanDirectoryL(TInt aDirIndex);
1.4058 + void ListModelsL(TInt aFileIndex, TParse& aParser, TFileName& aNameOfLoadedResourceFile, TFileName& aTempFileName, RResourceFile& aResourceFile, HBufC8*& aResource);
1.4059 + HBufC* NewPathBufL(const TFileEntry& aFileEntry);
1.4060 +private:
1.4061 + CArrayFixSeg<TModelEntry>* iModelArray;
1.4062 + CArrayFixFlat<TFileEntry>* iFileArray;
1.4063 + CArrayFixFlat<HBufC*>* iDirectoryArray;
1.4064 + RFs iFileServer;
1.4065 + };
1.4066 +
1.4067 +
1.4068 +/** The interface for mapping between twips and device-specific units enriched
1.4069 +with facilities to allow zooming.
1.4070 +
1.4071 +The class is recursive, because a TZoomFactor object can have a
1.4072 +MGraphicsDeviceMap (which could itself be a TZoomFactor) in its member data.
1.4073 +This allows a zoom factor object to contain another zoom factor object, and
1.4074 +is used to allow objects with different zoom factors to be embedded in each
1.4075 +other to an arbitrary depth by the application architecture.
1.4076 +@publishedAll
1.4077 +@released
1.4078 +*/
1.4079 +class TZoomFactor : public MGraphicsDeviceMap
1.4080 + {
1.4081 +public:
1.4082 + IMPORT_C TZoomFactor();
1.4083 + IMPORT_C ~TZoomFactor();
1.4084 + inline TZoomFactor(const MGraphicsDeviceMap* aDevice);
1.4085 + inline TZoomFactor(const TZoomFactor* aDevice);
1.4086 + IMPORT_C TInt ZoomFactor() const;
1.4087 + IMPORT_C void SetZoomFactor(TInt aZoomFactor);
1.4088 + inline void SetGraphicsDeviceMap(const MGraphicsDeviceMap* aDevice);
1.4089 + inline const MGraphicsDeviceMap* GraphicsDeviceMap() const;
1.4090 + IMPORT_C void SetTwipToPixelMapping(const TSize& aSizeInPixels,const TSize& aSizeInTwips);
1.4091 + IMPORT_C TInt HorizontalTwipsToPixels(TInt aTwipWidth) const;
1.4092 + IMPORT_C TInt VerticalTwipsToPixels(TInt aTwipHeight) const;
1.4093 + IMPORT_C TInt HorizontalPixelsToTwips(TInt aPixelWidth) const;
1.4094 + IMPORT_C TInt VerticalPixelsToTwips(TInt aPixelHeight) const;
1.4095 + IMPORT_C TInt GetNearestFontInTwips(CFont*& aFont, const TFontSpec& aFontSpec);
1.4096 + IMPORT_C TInt GetNearestFontToDesignHeightInTwips(CFont*& aFont, const TFontSpec& aFontSpec);
1.4097 + IMPORT_C TInt GetNearestFontToMaxHeightInTwips(CFont*& aFont, const TFontSpec& aFontSpec, TInt aMaxHeight);
1.4098 + IMPORT_C void ReleaseFont(CFont* aFont);
1.4099 +public:
1.4100 +
1.4101 + /** One to one zoom factor. */
1.4102 + enum {EZoomOneToOne=1000};
1.4103 +private:
1.4104 + TInt iZoomFactor;
1.4105 + const MGraphicsDeviceMap* iDevice;
1.4106 + };
1.4107 +
1.4108 +/**
1.4109 +Provides methods to map a TLanguage type to some pre-defined glyph samples.
1.4110 +Samples are defined per writing script, e.g. specifying ELangFrench or
1.4111 +ELangGerman will return the same set of samples.
1.4112 +These samples are typically the tallest and 'deep'est characters w.r.t
1.4113 +various scripts, useful for font rasterizers when calculating metrics.
1.4114 +@internalTechnology
1.4115 +*/
1.4116 +NONSHARABLE_CLASS(GlyphSample)
1.4117 + {
1.4118 +public:
1.4119 + /**
1.4120 + Writing scripts defined according to Unicode.
1.4121 + */
1.4122 + enum TScript
1.4123 + {
1.4124 + EScriptDefault = 0x0, // No script, can't be bothered
1.4125 + EScriptNone = 0x1, // No script, really
1.4126 + EScriptOther = 0x2, // Unsupported scripts
1.4127 + EScriptLatin = 0x3, // European
1.4128 + EScriptGreek = 0x4, // European
1.4129 + EScriptCyrillic = 0x5, // European
1.4130 + EScriptHebrew = 0x6, // Middle Eastern
1.4131 + EScriptArabic = 0x7, // Middle Eastern
1.4132 + EScriptDevanagari = 0x8, // Indic
1.4133 + EScriptThai = 0x9, // SE Asian
1.4134 + EScriptHanIdeographs = 0xA, // E Asian
1.4135 + };
1.4136 +public:
1.4137 + IMPORT_C static TInt TLanguage2TScript(TLanguage aLanguage);
1.4138 + IMPORT_C static const TPtrC TScript2GlyphSample(TInt aScript);
1.4139 +private:
1.4140 + static const TInt KTLanguage2TScript[];
1.4141 + static const TText* const KTScript2GlyphSample[];
1.4142 + };
1.4143 +
1.4144 +/*
1.4145 +Structure used as a package for GetUnderlineMetrics to pass to the relevant
1.4146 +section of APIExtension.
1.4147 +@internalTechnology
1.4148 +*/
1.4149 +struct TTwoTInt
1.4150 +{
1.4151 + TInt iTop;
1.4152 + TInt iBottom;
1.4153 +};
1.4154 +
1.4155 +#include <gdi.inl>
1.4156 +#endif // __GDI_H__