williamr@2: // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@2: // All rights reserved. williamr@2: // This component and the accompanying materials are made available williamr@4: // under the terms of "Eclipse Public License v1.0" williamr@2: // which accompanies this distribution, and is available williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@2: // williamr@2: // Initial Contributors: williamr@2: // Nokia Corporation - initial contribution. williamr@2: // williamr@2: // Contributors: williamr@2: // williamr@2: // Description: williamr@2: // williamr@2: williamr@2: #ifndef __GDI_H__ williamr@2: #define __GDI_H__ williamr@2: williamr@2: #include williamr@2: #include williamr@2: #include williamr@4: #include williamr@4: williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS williamr@4: #include williamr@4: #include williamr@4: #endif //SYMBIAN_ENABLE_SPLIT_HEADERS williamr@2: williamr@2: class TOpenFontCharMetrics; williamr@2: class RShapeInfo; williamr@4: class CGraphicsContext; williamr@4: class TTextParameters; williamr@2: williamr@2: /** williamr@2: Number of twips per inch. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: const TInt KTwipsPerInch=1440; williamr@2: williamr@2: /** williamr@2: Number of twips per point. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: const TInt KTwipsPerPoint=20; williamr@2: williamr@2: /** williamr@2: Number of points per inch. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: const TInt KPointsPerInch=72; williamr@2: williamr@2: /** williamr@2: Number of twips per cm. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: const TInt KTwipsPerCm=567; williamr@2: #if defined(__NO_CLASS_CONSTS__) williamr@2: /** williamr@2: A4 paper size in twips. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: #define KA4PaperSizeInTwips TSize(11906,16838) williamr@2: williamr@2: /** Legal paper size in twips. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: #define KLegalPaperSizeInTwips TSize(12240,20160) williamr@2: williamr@2: /** williamr@2: Executive paper size in twips. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: #define KExecutivePaperSizeInTwips TSize(10440,15120) williamr@2: /** williamr@2: Letter paper size in twips. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: #define KLetterPaperSizeInTwips TSize(12240,15840) williamr@2: williamr@2: /** williamr@2: Com-10 paper size in twips. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: #define KCom_10PaperSizeInTwips TSize(5940,13680) williamr@2: williamr@2: /** williamr@2: Monarch paper size in twips. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: #define KMonarchPaperSizeInTwips TSize(5580,10800) williamr@2: williamr@2: /** williamr@2: DL paper size in twips. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: #define KDLPaperSizeInTwips TSize(6236,12472) williamr@2: williamr@2: /** williamr@2: C5 paper size in twips. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: #define KC5PaperSizeInTwips TSize(9184,12983) williamr@2: #else williamr@2: /** williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: const TSize KA4PaperSizeInTwips(11906,16838); williamr@2: const TSize KLegalPaperSizeInTwips(12240,20160); williamr@2: const TSize KExecutivePaperSizeInTwips(10440,15120); williamr@2: const TSize KLetterPaperSizeInTwips(12240,15840); williamr@2: const TSize KCom_10PaperSizeInTwips(5940,13680); williamr@2: const TSize KMonarchPaperSizeInTwips(5580,10800); williamr@2: const TSize KDLPaperSizeInTwips(6236,12472); williamr@2: const TSize KC5PaperSizeInTwips(9184,12983); williamr@2: #endif williamr@4: williamr@2: williamr@2: /** williamr@2: This enumeration holds the possible panic codes that may be raised williamr@2: by the GDI API on detecting an unrecoverable error. */ williamr@2: enum TGdiPanic williamr@2: { williamr@2: /** Not used */ williamr@2: EGdiPanic_Unknown = 0, williamr@2: /** One or more of the input parameters to the interface were invalid */ williamr@2: EGdiPanic_InvalidInputParam = 1, williamr@2: /** Insufficient text for successful completion of the method */ williamr@2: EGdiPanic_OutOfText = 2, williamr@2: /** Internal failure. */ williamr@2: EGdiPanic_Invariant = 3 williamr@2: }; williamr@2: williamr@4: williamr@2: /** 24-bit RGB colour value with 8 bits each for red, green and blue. williamr@2: williamr@2: All Graphics drawing functions are specified in terms of a 32-bit TRgb colour williamr@2: containing the three colour values plus 8 bits for alpha channel. For hardware which williamr@2: does not support 24-bit colour, a mapping from TRgb to display colours is williamr@2: performed. williamr@2: williamr@2: Generally, the convention for the alpha blending fact is 0 = transparent, williamr@2: 255 = opaque, unless otherwise stated. The exception to this are the TRgb constructor williamr@2: taking a single value, where the top byte of the passed in parameter is used for williamr@2: alpha information and the function Value(), which returns alpha information in the top byte. williamr@2: In both these cases, 0 means opaque, 255 means transparent. williamr@2: williamr@2: The supported display modes are enumerated in the TDisplayMode type. In each williamr@2: display mode a unique index can represent each physical colours supported, williamr@2: and which can be mapped onto a full RGB value. The mappings are as follows: williamr@2: williamr@2: 16-colour displays use the EGA colour set: black, white, and then both light williamr@2: and dark versions of grey, red, green, blue, cyan, magenta and yellow williamr@2: williamr@2: 256-colour displays support 216 colours made up of 6x6x6 RGB values, each williamr@2: containing all possible multiples of 51 for R,G,B values. Additionally, all williamr@2: remaining 10 shades of pure red, green, blue and grey are represented, by williamr@2: adding all remaining multiples of 17. This use of 256 colours is sometimes williamr@2: known as the Netscape colour cube. williamr@2: williamr@2: 4096-colour displays effectively support RGB values with 4 bits per primary williamr@2: colour williamr@2: williamr@2: 64k-colour displays effectively support RGB values with 5 bits allocated to williamr@2: red, 6 to green and 5 to blue williamr@2: williamr@2: 16 million-colour displays support true colour with 8 bits allocated to each williamr@2: primary colour williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: @see TDisplayMode williamr@2: @see DynamicPalette */ williamr@2: class TRgb williamr@2: { williamr@2: public: williamr@2: inline TRgb(); williamr@2: inline TRgb(TUint32 aValue); williamr@2: inline TRgb(TUint32 aInternalValue, TInt aAlpha); williamr@2: inline TRgb(TInt aRed,TInt aGreen,TInt aBlue); williamr@2: inline TRgb(TInt aRed, TInt aGreen, TInt aBlue, TInt aAlpha); williamr@2: inline TInt Red() const; williamr@2: inline TInt Green() const; williamr@2: inline TInt Blue() const; williamr@2: inline TInt Alpha() const; williamr@2: IMPORT_C void SetRed(TInt aRed); williamr@2: IMPORT_C void SetGreen(TInt aGreen); williamr@2: IMPORT_C void SetBlue(TInt aBlue); williamr@2: IMPORT_C void SetAlpha(TInt aAlpha); williamr@2: IMPORT_C static TRgb Gray2(TInt aGray2); williamr@2: IMPORT_C static TRgb Gray4(TInt aGray4); williamr@2: IMPORT_C static TRgb Gray16(TInt aGray16); williamr@2: IMPORT_C static TRgb Gray256(TInt aGray256); williamr@2: IMPORT_C static TRgb Color16(TInt aColor16); williamr@2: IMPORT_C static TRgb Color256(TInt aColor256); williamr@2: IMPORT_C static TRgb Color4K(TInt aColor4K); williamr@2: IMPORT_C static TRgb Color64K(TInt aColor64K); williamr@2: IMPORT_C static TRgb Color16M(TInt aColor16M); williamr@2: IMPORT_C TInt Gray2() const; williamr@2: IMPORT_C TInt Gray4() const; williamr@2: IMPORT_C TInt Gray16() const; williamr@2: IMPORT_C TInt Gray256() const; williamr@2: IMPORT_C TInt Color16() const; williamr@2: IMPORT_C TInt Color256() const; williamr@2: IMPORT_C TInt Color4K() const; williamr@2: IMPORT_C TInt Color64K() const; williamr@2: IMPORT_C TInt Color16M() const; williamr@2: inline TBool operator==(const TRgb& aColor) const; williamr@2: inline TBool operator!=(const TRgb& aColor) const; williamr@2: inline TRgb operator~() const; williamr@2: inline TRgb operator&(const TRgb& aColor); williamr@2: inline TRgb operator|(const TRgb& aColor); williamr@2: inline TRgb operator^(const TRgb& aColor); williamr@2: inline TRgb& operator&=(const TRgb& aColor); williamr@2: inline TRgb& operator|=(const TRgb& aColor); williamr@2: inline TRgb& operator^=(const TRgb& aColor); williamr@2: inline TUint32 Value() const; williamr@2: inline TUint32 Internal() const; williamr@2: inline void SetInternal(TUint32 aInternal); williamr@2: IMPORT_C TInt Difference(const TRgb& aColor) const; williamr@2: IMPORT_C void InternalizeL(RReadStream& aStream); williamr@2: IMPORT_C void ExternalizeL(RWriteStream& aStream) const; williamr@2: IMPORT_C static TRgb Color16MU(TInt a0RGB); williamr@2: IMPORT_C TInt Color16MU() const; williamr@2: IMPORT_C static TRgb Color16MA(TUint aARGB); williamr@2: IMPORT_C TUint Color16MA() const; williamr@2: IMPORT_C static TRgb Color16MAP(TUint aARGB); williamr@2: IMPORT_C TUint Color16MAP() const; williamr@2: IMPORT_C TUint _Color16MAP() const; williamr@2: IMPORT_C static TRgb _Color16MAP(TUint aARGB); williamr@2: inline TInt _Gray2() const; williamr@2: inline TInt _Gray4() const; williamr@2: inline TInt _Gray16() const; williamr@2: inline TInt _Gray256() const; williamr@2: inline TInt _Color4K() const; williamr@2: inline TInt _Color64K() const; williamr@2: inline TInt _Color16M() const; williamr@2: inline TInt _Color16MU() const; williamr@2: inline TUint _Color16MA() const; williamr@2: inline static TRgb _Gray2(TInt aGray2); williamr@2: inline static TRgb _Gray4(TInt aGray4); williamr@2: inline static TRgb _Gray16(TInt aGray16); williamr@2: inline static TRgb _Gray256(TInt aGray256); williamr@2: inline static TRgb _Color4K(TInt aColor4K); williamr@2: inline static TRgb _Color64K(TInt aColor64K); williamr@2: inline static TRgb _Color16M(TInt aColor16M); williamr@2: inline static TRgb _Color16MU(TInt a0RGB); williamr@2: inline static TRgb _Color16MA(TUint aARGB); williamr@2: private: williamr@2: TUint32 iValue; williamr@2: }; williamr@2: williamr@4: williamr@2: /** williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: #define KRgbBlack TRgb(0x000000) williamr@2: #define KRgbDarkGray TRgb(0x555555) williamr@2: #define KRgbDarkRed TRgb(0x000080) williamr@2: #define KRgbDarkGreen TRgb(0x008000) williamr@2: #define KRgbDarkYellow TRgb(0x008080) williamr@2: #define KRgbDarkBlue TRgb(0x800000) williamr@2: #define KRgbDarkMagenta TRgb(0x800080) williamr@2: #define KRgbDarkCyan TRgb(0x808000) williamr@2: #define KRgbRed TRgb(0x0000ff) williamr@2: #define KRgbGreen TRgb(0x00ff00) williamr@2: #define KRgbYellow TRgb(0x00ffff) williamr@2: #define KRgbBlue TRgb(0xff0000) williamr@2: #define KRgbMagenta TRgb(0xff00ff) williamr@2: #define KRgbCyan TRgb(0xffff00) williamr@2: #define KRgbGray TRgb(0xaaaaaa) williamr@2: #define KRgbWhite TRgb(0xffffff) williamr@4: #define KRgbTransparent TRgb(0x000000,0x00) williamr@2: williamr@2: /** A set of static utility functions to get information about a display mode. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TDisplayModeUtils williamr@2: { williamr@2: public: williamr@2: IMPORT_C static TBool IsDisplayModeColor(TDisplayMode aDispMode); williamr@2: IMPORT_C static TBool IsDisplayModeValid(TDisplayMode aDispMode); williamr@2: IMPORT_C static TInt NumDisplayModeColors(TDisplayMode aDispMode); williamr@2: IMPORT_C static TInt NumDisplayModeBitsPerPixel(TDisplayMode aDispMode); williamr@2: }; williamr@2: williamr@2: /** Provides user-definable palette support to the GDI. williamr@2: williamr@2: A palette is a user-defined set of colours, which is a subset of the full williamr@2: range of 24-bit colours. This allows users the advantages of having a low williamr@2: bpp colour mode whilst being able to specify the colours available in that williamr@2: mode. To give an example, the EColor16 mode provides a palette of 16 colours williamr@2: as it provides a mapping between an integer index and a TRgb colour (see the williamr@2: table EGA Low-colour constants). Only a palette of 16 colour enables you to williamr@2: change the palette. Palettes are also used to allow 24-bit bitmaps to be stored williamr@2: in a more compressed form by finding the actual number of different colours williamr@2: used in the bitmap, creating a palette to allow the mapping of these colours williamr@2: to a smaller index space, and encoding the bitmaps pixels using indexes williamr@2: to this new index space. williamr@2: williamr@2: A palette has a size which is set at its creation and cannot be altered williamr@2: the number of entries in the palette. Each entry in a palette is a mapping williamr@2: between that entrys index and a TRgb value. Palette entries can be got williamr@2: and set at any time between the palettes creation and destruction. The williamr@2: GDIs palette support also provides functions to find the nearest palette williamr@2: colour to a requested TRgb colour. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CPalette : public CBase williamr@2: { williamr@2: public: williamr@2: IMPORT_C static CPalette* NewL(TInt aNumberOfEntries); williamr@2: IMPORT_C static CPalette* NewDefaultL(TDisplayMode aDispMode); williamr@2: IMPORT_C ~CPalette(); williamr@2: IMPORT_C void Clear(); williamr@2: inline TInt Entries() const; williamr@2: IMPORT_C TRgb GetEntry(TInt aPaletteIndex) const; williamr@2: IMPORT_C TRgb NearestEntry(const TRgb& aColor) const; williamr@2: IMPORT_C TInt NearestIndex(const TRgb& aColor) const; williamr@2: IMPORT_C void SetEntry(TInt aPaletteIndex,const TRgb& aPaletteEntry); williamr@2: IMPORT_C void GetDataPtr(TInt aFirstColor,TInt aNumColors,TPtr8& aPtr); williamr@2: protected: williamr@2: IMPORT_C CPalette(); williamr@2: void ConstructL(TInt aNumberOfEntries); williamr@2: protected: williamr@2: TRgb* iArray; williamr@2: TInt iNumEntries; williamr@2: }; williamr@2: williamr@2: williamr@2: /** Enables conversion, in both directions, between a TRgb object and an index williamr@2: into an arbitrary 256 colour palette. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TColor256Util williamr@2: { williamr@2: public: williamr@2: IMPORT_C void Construct(const CPalette& aPalette); williamr@2: IMPORT_C TInt Color256(TRgb aRgb) const; williamr@2: IMPORT_C void Color256(TUint8* aDestination,const TRgb* aSource,TInt aNumPixels) const; williamr@2: inline TRgb Color256(TInt aColor256) const; williamr@2: IMPORT_C static const TColor256Util* Default(); williamr@2: public: williamr@2: /** 256 colour lookup table. williamr@2: williamr@2: Each entry is a 32 bit value which corresponds to a TRgb value in the williamr@2: palette passed to Construct(). If there are more than 256 colours in the williamr@2: palette, the first 256 colours are used in this table. If there are fewer williamr@2: than 256 entries, the remaining entries in the table are set to zero. */ williamr@2: TUint32 iColorTable[256]; williamr@2: williamr@2: /** Inverse colour lookup table. williamr@2: williamr@2: It has 4096 entries. Each entry is the index of a colour in the palette williamr@2: that the object was created with (see Construct()) that most closely williamr@2: matches the 4096 degrees of intensity of red, green and blue on a uniform williamr@2: 16x16x16 colour cube. williamr@2: williamr@2: It is called "inverse" because iColorTable maps indices (0..255) to TRgb williamr@2: values, but this table maps TRgb values to palette indices. */ williamr@2: TUint8 iInverseColorTable[0x1000]; williamr@2: }; williamr@2: williamr@2: williamr@2: /** Linear digital differential analyser. williamr@2: williamr@2: This is used to calculate the pixels which most closely approximate a specified williamr@2: straight line, or when scaling a bitmap. Note that a line is infinitely thin, williamr@2: and can only be approximated by pixels with real width and height. williamr@2: williamr@2: Functions are provided for: pixel line traversing; jumping to a rectangle or williamr@2: co-ordinate williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TLinearDDA williamr@2: { williamr@2: public: williamr@2: /** LDDA Line mode. */ williamr@2: enum TLineMode williamr@2: { williamr@2: /** Centres scan-lines in the pixel line */ williamr@2: ECenter, williamr@2: /** Starts at the beginning of a complete scan line. Used for bitmap williamr@2: scaling. */ williamr@2: ELeft williamr@2: }; williamr@2: public: williamr@2: IMPORT_C TLinearDDA(); williamr@2: IMPORT_C TLinearDDA(const TLinearDDA& aLine); williamr@2: IMPORT_C void Construct(const TPoint& aStart,const TPoint& aFinish,TLineMode aMode=ECenter); williamr@2: IMPORT_C TBool SingleStep(TPoint& aPosition); williamr@2: IMPORT_C TBool SingleScanline(TPoint& aStartPosition,TPoint& aEndPosition); williamr@2: IMPORT_C TBool NextStep(TPoint& aPosition); williamr@2: IMPORT_C void JumpToRect(const TRect& aRect); williamr@2: IMPORT_C void JumpToXCoord(const TInt aXCoord,TInt& aYCoord); williamr@2: IMPORT_C void JumpToYCoord(TInt& aXCoord,const TInt aYCoord); williamr@2: IMPORT_C void JumpToXCoord2(TInt aXCoord,TInt& aYCoord); williamr@2: IMPORT_C void JumpToYCoord2(TInt& aXCoord,TInt aYCoord); williamr@2: private: williamr@2: void UpdatePosition(); williamr@2: private: williamr@2: enum TLineStatus williamr@2: { williamr@2: EInitialised, williamr@2: ECurrent, williamr@2: EComplete williamr@2: }; williamr@2: private: williamr@2: TInt iCount; williamr@2: TSize iDifference; williamr@2: TPoint iFinish; williamr@2: TInt iGradient; williamr@2: TPoint iInc; williamr@2: TPoint iPos; williamr@2: TPoint iStart; williamr@2: TRect iBoundingRect; williamr@2: TBool iBoundingRectSet; williamr@4: TInt16 iInsideX; // boolean, defined as TInt16 to maintain binary compatibility williamr@4: TInt16 iInsideY; // boolean, defined as TInt16 to maintain binary compatibility williamr@2: TLineStatus iStatus; williamr@2: }; williamr@2: williamr@2: williamr@2: /** williamr@2: Font posture flags. williamr@2: Fonts can be either upright or italic. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TFontPosture williamr@2: { williamr@2: /** Font posture is normal (upright). */ williamr@2: EPostureUpright, williamr@2: /** Font posture is italic. */ williamr@2: EPostureItalic williamr@2: }; williamr@2: williamr@2: /** williamr@2: Font stroke weight flags. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TFontStrokeWeight williamr@2: { williamr@2: /** Font stroke weight is normal. */ williamr@2: EStrokeWeightNormal, williamr@2: /** Font stroke weight is bold. */ williamr@2: EStrokeWeightBold williamr@2: }; williamr@2: williamr@2: /** williamr@2: Font print position flags. williamr@2: Fonts can be normal, superscript or subscript. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TFontPrintPosition williamr@2: { williamr@2: /** Font is normal. */ williamr@2: EPrintPosNormal, williamr@2: /** Font is superscript. */ williamr@2: EPrintPosSuperscript, williamr@2: /** Font is subscript. */ williamr@2: EPrintPosSubscript williamr@2: }; williamr@2: williamr@2: /** williamr@2: Font underline flags. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TFontUnderline williamr@2: { williamr@2: /** Font is not underlined. */ williamr@2: EUnderlineOff, williamr@2: /** Font is underlined. */ williamr@2: EUnderlineOn williamr@2: }; williamr@2: williamr@2: /** williamr@2: Font strike-through flags. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TFontStrikethrough williamr@2: { williamr@2: /** Font is not struck-through. */ williamr@2: EStrikethroughOff, williamr@2: /** Font is struck-through. */ williamr@2: EStrikethroughOn williamr@2: }; williamr@2: williamr@2: /** williamr@2: The maximum length of a typeface name (in characters). williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: const TInt KMaxTypefaceNameLength=0x18; williamr@2: williamr@2: williamr@2: /** Typeface name and attributes. williamr@2: williamr@2: This class identifies a typeface by name, and contains the combination of williamr@2: attributes of the typeface. These attributes define whether it is a symbol williamr@2: typeface, whether the typeface is proportional, and whether it is serif or williamr@2: sans-serif. williamr@2: williamr@2: The combination of attributes for a typeface are stored in a bitmask, with williamr@2: the various bits indicating different attributes. The bitmask is calculated williamr@2: for any particular attribute combination by ORing the enumerated value for williamr@2: each individual attribute. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TTypeface williamr@2: { williamr@2: public: williamr@2: enum williamr@2: { williamr@2: /** Typeface is a proportional typeface (e.g. Swiss) williamr@2: */ williamr@2: EProportional = 1, williamr@2: /** Typeface is a serif typeface (e.g. Times) williamr@2: */ williamr@2: ESerif = 2, williamr@2: /** Typeface is a symbol typeface (e.g. Symbol) williamr@2: */ williamr@2: ESymbol = 4, williamr@2: }; williamr@2: public: williamr@2: IMPORT_C TTypeface(); williamr@2: IMPORT_C TBool operator==(const TTypeface& aTypeface) const; williamr@2: IMPORT_C void InternalizeL(RReadStream& aStream); williamr@2: IMPORT_C void ExternalizeL(RWriteStream& aStream) const; williamr@2: IMPORT_C void SetAttributes(TInt aAttributes); williamr@2: IMPORT_C void SetIsProportional(TBool aIsProportional); williamr@2: IMPORT_C void SetIsSerif(TBool aIsSerif); williamr@2: IMPORT_C void SetIsSymbol(TBool aIsSymbol); williamr@2: IMPORT_C TInt Attributes() const; williamr@2: IMPORT_C TBool IsProportional() const; williamr@2: IMPORT_C TBool IsSerif() const; williamr@2: IMPORT_C TBool IsSymbol() const; williamr@2: IMPORT_C void SetScriptTypeForMetrics(TLanguage aLanguage); williamr@2: IMPORT_C void SetScriptTypeForMetrics(TInt aScript); williamr@2: IMPORT_C TInt ScriptTypeForMetrics() const; williamr@2: private: williamr@2: void ResetAttributes(); williamr@2: void ResetScriptType(); williamr@2: public: williamr@2: /** The typeface name. */ williamr@2: TBufC iName; williamr@2: private: williamr@2: TUint32 iFlags; williamr@2: }; williamr@2: williamr@2: williamr@2: /** williamr@2: An enumerated type for the format of a glyph bitmap. This type is currently williamr@2: used to indicate whether glyph bitmaps for scalable fonts are drawn anti-aliased. williamr@2: Additional values may be defined in the future. williamr@2: williamr@2: @see TFontStyle::SetBitmapType() williamr@2: @see CFbsTypefaceStore::SetDefaultBitmapType() williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TGlyphBitmapType williamr@2: { williamr@2: /** The font store's default glyph bitmap format is used. */ williamr@2: EDefaultGlyphBitmap = 0, williamr@2: /** The standard monochrome format: no anti-aliasing, 1 bit per pixel, williamr@2: run-length encoded. */ williamr@2: EMonochromeGlyphBitmap, williamr@2: /** Standard 8-bits-per-pixel with anti-aliasing. */ williamr@2: EAntiAliasedGlyphBitmap, williamr@2: /** The format used when sub-pixel font rendering is used. */ williamr@2: ESubPixelGlyphBitmap, williamr@2: /** The format used when outline and shadow font rendering is used. williamr@2: williamr@2: If the raterizer supports the outline and shadow fonts, it will set the bitmaptype as williamr@2: EFourColourBlendGlyphBitmap but only when glyph bitmap type is set as EAntiAliasedGlyphBitmap and williamr@2: when any of the EDropShadow or EOutline effect is on. Only rasterizer providers can use this enum. williamr@2: */ williamr@2: EFourColourBlendGlyphBitmap, williamr@4: /** williamr@4: This is used for glyphs, and not fonts, and is needed to inform the font drawing routines williamr@4: that the character should be drawn using the overall font setting. williamr@4: For Internal Use Only. williamr@4: */ williamr@4: EGlyphBitmapTypeNotDefined, williamr@4: /** williamr@4: This is used to inform the rasterizer that the best match should be williamr@4: found for the bitmap type based upon its knowledge. williamr@4: For Internal Use Only. williamr@4: */ williamr@4: EAntiAliasedOrMonochromeGlyphBitmap, williamr@2: }; williamr@2: williamr@2: /** williamr@2: Defines a set of font effects flags. williamr@2: williamr@4: @publishedAll williamr@2: @released williamr@4: WARNING: This Class is for use by system/UI software ONLY. williamr@2: */ williamr@2: NONSHARABLE_CLASS(FontEffect) williamr@2: { williamr@2: public: williamr@2: enum TEffect williamr@2: { williamr@2: ENone = 0x0, // No effects. williamr@2: EAlgorithmicBold= 0x10, // Font is algorithmic bold (a.k.a pseudo bold.) williamr@2: EDropShadow = 0x20, // Font has a drop shadow. williamr@2: EOutline = 0x40, // Font is an outline font. williamr@2: EEmbossed = 0x80, // Font is embossed. williamr@2: EEngraved = 0x100, // Font is engraved. williamr@2: ESoftEdge = 0x200, // Font is soft edged. williamr@2: EReserved1 = 0x400, // Reserved for Symbian use. williamr@2: EReserved2 = 0x800, // Reserved for Symbian use. williamr@2: EReserved3 = 0x1000, // Reserved for Symbian use. williamr@2: EReserved4 = 0x2000, // Reserved for Symbian use. williamr@2: EReserved5 = 0x4000, // Reserved for Symbian use. williamr@2: EReserved6 = 0x8000, // Reserved for Symbian use. williamr@2: }; williamr@2: public: williamr@2: IMPORT_C static TBool IsEffectOn(TEffect aEffect, TUint32 aFontEffect); williamr@2: IMPORT_C static void SetEffect(TEffect aEffect, TBool aOn, TUint32& aFontEffect); williamr@2: }; williamr@2: williamr@2: /** Encapsulates a font style. williamr@2: williamr@2: The font style information is comprised of: williamr@2: williamr@2: the posture of the font upright or italic williamr@2: williamr@2: the stroke weight of the font normal or bold williamr@2: williamr@2: the print position of the font normal, subscript or superscript williamr@2: williamr@2: Note that the underline and strike-through attributes are not included in williamr@2: this class, but are set in the graphics context. williamr@2: williamr@2: @see CGraphicsContext::SetUnderlineStyle() williamr@2: @see CGraphicsContext::SetStrikethroughStyle() williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TFontStyle williamr@2: { williamr@2: public: williamr@2: IMPORT_C TFontStyle(); williamr@2: IMPORT_C TFontStyle(TFontPosture aPost,TFontStrokeWeight aStrWgt,TFontPrintPosition aPrintPos); williamr@2: IMPORT_C void InternalizeL(RReadStream& aStream); williamr@2: IMPORT_C void ExternalizeL(RWriteStream& aStream) const; williamr@2: IMPORT_C TFontPosture Posture() const; williamr@2: IMPORT_C TFontStrokeWeight StrokeWeight() const; williamr@2: IMPORT_C TFontPrintPosition PrintPosition() const; williamr@2: IMPORT_C void SetPosture(TFontPosture aPosture); williamr@2: IMPORT_C void SetStrokeWeight(TFontStrokeWeight aStrokeWeight); williamr@2: IMPORT_C void SetPrintPosition(TFontPrintPosition aPrintPosition); williamr@2: inline TGlyphBitmapType BitmapType() const; williamr@2: inline void SetBitmapType(TGlyphBitmapType aBitmapType); williamr@2: IMPORT_C TBool operator==(const TFontStyle& aFontStyle) const; williamr@2: IMPORT_C TUint32 Effects() const; williamr@2: IMPORT_C TBool IsEffectOn(FontEffect::TEffect aEffect) const; williamr@2: IMPORT_C void SetEffects(TUint32 aEffects); williamr@2: IMPORT_C void SetEffects(FontEffect::TEffect aEffect, TBool aOn); williamr@2: private: williamr@2: enum williamr@2: { williamr@2: EItalic=0x1, williamr@2: EBold=0x2, williamr@2: ESuper=0x4, williamr@2: ESub=0x8 williamr@2: }; williamr@2: private: williamr@2: TUint32 iFlags; // bitmap type - 16 bits (high), font effects - 12 bits (middle), style - 4 bits (low) williamr@2: TAny* iReserved1; williamr@2: TAny* iReserved2; williamr@2: }; williamr@2: williamr@2: williamr@2: williamr@2: /** williamr@2: Specifies the font specification in device independent terms. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TFontSpec williamr@2: { williamr@2: public: williamr@2: IMPORT_C TFontSpec(); williamr@2: IMPORT_C TFontSpec(const TDesC& aTypefaceName,TInt aHeight); williamr@2: IMPORT_C TBool operator==(const TFontSpec& aFontSpec) const; williamr@2: IMPORT_C void InternalizeL(RReadStream& aStream); williamr@2: IMPORT_C void ExternalizeL(RWriteStream& aStream) const; williamr@2: IMPORT_C void SetScriptTypeForMetrics(TLanguage aLanguage); williamr@2: IMPORT_C TInt ScriptTypeForMetrics() const; williamr@2: public: williamr@2: /** The typeface. */ williamr@2: TTypeface iTypeface; williamr@2: /** The height of the typeface (in twips). */ williamr@2: TInt iHeight; williamr@2: /** The font style of the typeface. */ williamr@2: TFontStyle iFontStyle; williamr@2: }; williamr@2: williamr@2: williamr@2: williamr@2: /** Typeface family support information. williamr@2: williamr@2: This data-only class includes the name and attributes of a typeface, how many williamr@2: font heights are available, its minimum and maximum heights, and whether or williamr@2: not it is scaleable a typeface is scaleable if it supports heights at williamr@2: fixed intervals between the minimum and maximum heights. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TTypefaceSupport williamr@2: { williamr@2: public: williamr@2: /** The name and attributes of the typeface. */ williamr@2: TTypeface iTypeface; williamr@2: /** The number of distinct font heights available in the typeface. */ williamr@2: TInt iNumHeights; williamr@2: /** The typeface's minimum font height, in twips. */ williamr@2: TInt iMinHeightInTwips; williamr@2: /** The typeface's maximum font height, in twips. */ williamr@2: TInt iMaxHeightInTwips; williamr@2: /** Whether the typeface is scaleable. ETrue if it is scaleable, otherwise williamr@2: EFalse. */ williamr@2: TBool iIsScalable; // supports heights from min to max at fixed interval williamr@2: }; williamr@2: williamr@2: /** williamr@2: The percentage used to multiply a normal font height when calculating its williamr@2: superscript or subscript height. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: const TInt KSuperSubScalingPercentage=67; williamr@2: williamr@2: /** williamr@2: The percentage of a font height used to calculate its baseline offset for a williamr@2: superscript print position. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: const TInt KSuperscriptOffsetPercentage=-28; williamr@2: williamr@2: /** williamr@2: The percentage of a font height used to calculate its baseline offset for a williamr@2: subscript print position. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: const TInt KSubscriptOffsetPercentage=14; williamr@2: williamr@2: class CFont; williamr@2: williamr@2: /** Typeface store abstract base interface. williamr@2: williamr@2: This class provides the interface to a store for typefaces. williamr@2: williamr@2: See also CFontStore. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CTypefaceStore : public CBase williamr@2: { williamr@2: public: williamr@2: IMPORT_C ~CTypefaceStore(); williamr@2: williamr@2: /** williamr@2: Gets the font which is the nearest to the given font specification. williamr@2: williamr@2: When the font is no longer needed, call @c ReleaseFont(). williamr@2: williamr@2: Note that this deprecated function is replaced by the new @c GetNearestFontToDesignHeightInTwips() williamr@2: yielding (virtually) the same result. However clients are strongly encouraged to use the new williamr@2: @c GetNearestFontToMaxHeightInTwips() function instead. This will guarantee that every williamr@2: character within any given text string will fit within the given amount of twips, whereas the design williamr@2: height is an aesthetic unit decided by the font designer without strict physical meaning, which williamr@2: may result in cropped characters. williamr@2: williamr@2: @param aFont On return, contains a pointer to the nearest font. williamr@2: @param aFontSpec The specification of the font to be matched. williamr@2: @return KErrNone if successful; a system-wide error code otherwise. williamr@2: @publishedAll williamr@2: @deprecated Use GetNearestFontToDesignHeightInTwips williamr@2: */ williamr@2: virtual TInt GetNearestFontInTwips(CFont*& aFont, const TFontSpec& aFontSpec) = 0; williamr@2: williamr@2: /** williamr@2: Gets the font which is the nearest to the given font specification. williamr@2: williamr@2: When the font is no longer needed, call @c ReleaseFont(). williamr@2: williamr@2: This new function replaces the deprecated @c GetNearestFontInTwips() yielding (virtually) the williamr@2: same result. However clients are strongly encouraged to use the new williamr@2: @c GetNearestFontToMaxHeightInTwips() function instead. This will guarantee that every williamr@2: character within any given text string will fit within the given amount of twips, whereas the design williamr@2: height is an aesthetic unit decided by the font designer without strict physical meaning, which williamr@2: may result in cropped characters. williamr@2: williamr@2: @param aFont On return, contains a pointer to the nearest font. williamr@2: @param aFontSpec The specification of the font to be matched. williamr@2: @return KErrNone if successful; a system-wide error code otherwise. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: virtual TInt GetNearestFontToDesignHeightInTwips(CFont*& aFont, const TFontSpec& aFontSpec) = 0; williamr@2: williamr@2: /** williamr@2: Gets the font which is the nearest to the given font specification. williamr@2: williamr@2: When the font is no longer needed, call @c ReleaseFont(). williamr@2: williamr@2: The font and bitmap server returns a pointer to the nearest matching font williamr@2: from those available. Matches to max height of font - this does its best williamr@2: to return a font that will fit within the maximum height specified (but williamr@2: note that variations due to hinting algorithms may rarely result in this williamr@2: height being exceeded by up to one pixel). Problems can also be williamr@2: encountered with bitmap fonts where the typeface exists but doesn't have williamr@2: a font small enough. williamr@2: williamr@2: @param aFont On return, contains a pointer to the nearest font. williamr@2: @param aFontSpec The specification of the font to be matched. williamr@2: @param aMaxHeight The maximum height within which the font must fit. williamr@2: @return KErrNone if successful; a system-wide error code otherwise. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: virtual TInt GetNearestFontToMaxHeightInTwips(CFont*& aFont, const TFontSpec& aFontSpec, TInt aMaxHeight) = 0; williamr@2: williamr@2: /** Gets the number of typefaces supported by the typeface store. williamr@2: williamr@2: @return The number of supported typefaces. */ williamr@2: virtual TInt NumTypefaces() const=0; williamr@2: williamr@2: /** Gets typeface information for a specified typeface index. williamr@2: williamr@2: This information is returned in aTypefaceSupport, and williamr@2: includes the typeface name and typeface attributes, the number of font williamr@2: heights, the maximum and minimum font heights, and whether it is a williamr@2: scaleable typeface. williamr@2: williamr@2: @param aTypefaceSupport On return, if the function executed successfully, williamr@2: this object contains the typeface information. williamr@2: @param aTypefaceIndex A typeface index number, in the range: zero to williamr@2: (NumTypefaces() - 1). */ williamr@2: virtual void TypefaceSupport(TTypefaceSupport& aTypefaceSupport,TInt aTypefaceIndex) const=0; williamr@2: williamr@2: /** Gets the height of the font with specified height and typeface indices, williamr@2: in twips. williamr@2: williamr@2: The value returned is rounded up or down to the nearest font height in twips. williamr@2: williamr@2: @param aTypefaceIndex A typeface index number, in the range: 0 to williamr@2: (NumTypefaces() - 1). williamr@2: @param aHeightIndex A font height index number. williamr@2: @return The height of the font, in twips. */ williamr@2: virtual TInt FontHeightInTwips(TInt aTypefaceIndex,TInt aHeightIndex) const=0; williamr@2: IMPORT_C void ReleaseFont(CFont* aFont); williamr@2: IMPORT_C static TInt BaselineOffset(TInt aHeight,TFontPrintPosition aPos); williamr@2: IMPORT_C static TInt SuperSubHeight(TInt aHeight,TFontPrintPosition aPos); williamr@2: protected: williamr@2: IMPORT_C CTypefaceStore(); williamr@2: IMPORT_C void ConstructL(); williamr@2: IMPORT_C void AddFontL(CFont* aFont); williamr@2: IMPORT_C TBool IncrementFontCount(const CFont* aFont); williamr@2: private: williamr@2: TBool FindFont(const CFont* aFont, TInt& aIdx) const; williamr@2: NONSHARABLE_CLASS(TFontAccess) williamr@2: /** williamr@2: Pairs a font with a count of how many clients of the typeface store williamr@2: are accessing that font. williamr@2: */ williamr@2: { williamr@2: public: williamr@2: /** A device specific font. */ williamr@2: CFont* iFont; williamr@2: /** The number of clients accessing the font. */ williamr@2: TInt iAccessCount; williamr@2: }; williamr@2: protected: williamr@2: /** A list of fonts accessed by clients of the typeface store, which pairs williamr@2: a font with a count of the number of clients accessing the font. williamr@2: williamr@2: Implemented as an array of TFontAccess objects. williamr@2: williamr@2: An object is added to this array for every font accessed. If the font is williamr@2: released by all clients, and the access count drops to zero, the font is williamr@2: removed from the list. */ williamr@2: CArrayFixFlat* iFontAccess; williamr@2: }; williamr@2: williamr@2: /** The maximum number of entries in the font cache. williamr@2: williamr@2: @see CFontCache */ williamr@2: const TInt KMaxFontCacheEntries=32; williamr@2: williamr@2: /** Font cache. williamr@2: williamr@2: When a CFont* needs to be found for a particular TFontSpec, the cache can williamr@2: be searched to see if the TFontSpec is already in the cache. If the TFontSpec williamr@2: is in the cache, its corresponding CFont* can be returned. Otherwise williamr@2: GetNearestFontInTwips() must be used to search all of the available fonts for williamr@2: the nearest CFont- a procedure which takes much longer than a simple cache williamr@2: search. williamr@2: williamr@2: The current font cache should be destroyed and a new cache created whenever williamr@2: the zoom factor or device map changes, as these changes break the relation williamr@2: between CFont and TFontSpec. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CFontCache : public CBase williamr@2: { williamr@2: public: williamr@2: IMPORT_C CFontCache(); williamr@2: IMPORT_C CFontCache(TInt aMaxEntries); williamr@2: IMPORT_C ~CFontCache(); williamr@2: IMPORT_C CFont* Search(const TFontSpec& aFontSpec); williamr@2: IMPORT_C CFont* AddEntryL(CFont* aFont,const TFontSpec& aFontSpec); williamr@2: IMPORT_C CFont* RemoveFirstEntry(); williamr@2: public: williamr@2: /** The number of cache hits since the font cache was created i.e. williamr@2: successful results from CFontCache::Search(). */ williamr@2: TInt iNumHits; williamr@2: /** The number of cache misses since the font cache was created i.e. williamr@2: unsuccessful results from CFontCache::Search(). */ williamr@2: TInt iNumMisses; williamr@2: private: williamr@2: class CFontCacheEntry : public CBase williamr@2: { williamr@2: public: williamr@2: CFontCacheEntry(CFont* aFont,const TFontSpec& aFontSpec,CFontCacheEntry* aNext); williamr@2: public: williamr@2: CFont* iFont; williamr@2: TFontSpec iSpec; williamr@2: CFontCacheEntry* iNext; williamr@2: }; williamr@2: private: williamr@2: TInt iNumEntries; williamr@2: TInt iMaxEntries; williamr@2: CFontCacheEntry* iFirst; williamr@2: }; williamr@2: williamr@2: /** Interface class for mapping between twips and device-specific units (pixels). williamr@2: williamr@2: TZoomFactor is derived from MGraphicsDeviceMap. williamr@2: williamr@2: @see CGraphicsDevice williamr@2: @see TZoomFactor williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class MGraphicsDeviceMap williamr@2: { williamr@2: public: williamr@2: IMPORT_C MGraphicsDeviceMap(); williamr@2: IMPORT_C virtual ~MGraphicsDeviceMap(); williamr@2: IMPORT_C TPoint TwipsToPixels(const TPoint& aTwipPoint) const; williamr@2: IMPORT_C TRect TwipsToPixels(const TRect& aTwipRect) const; williamr@2: IMPORT_C TPoint PixelsToTwips(const TPoint& aPixelPoint) const; williamr@2: IMPORT_C TRect PixelsToTwips(const TRect& aPixelRect) const; williamr@2: williamr@2: /** Converts a horizontal dimension from twips to pixels. williamr@2: williamr@2: An implementation is supplied by a derived class. williamr@2: williamr@2: @param aTwips A horizontal dimension of a device in twips. williamr@2: @return A horizontal dimension of a device in pixels. */ williamr@2: virtual TInt HorizontalTwipsToPixels(TInt aTwips) const=0; williamr@2: williamr@2: /** Converts a vertical dimension from twips to pixels. williamr@2: williamr@2: An implementation is supplied by a derived class. williamr@2: williamr@2: @param aTwips A vertical dimension of a device in twips. williamr@2: @return A vertical dimension of a device in pixels. */ williamr@2: virtual TInt VerticalTwipsToPixels(TInt aTwips) const=0; williamr@2: williamr@2: /** Converts a horizontal dimension from pixels to twips. williamr@2: williamr@2: An implementation is supplied by a derived class. williamr@2: williamr@2: @param aPixels A horizontal dimension of a device in pixels. williamr@2: @return A horizontal dimension of a device in twips. */ williamr@2: virtual TInt HorizontalPixelsToTwips(TInt aPixels) const=0; williamr@2: williamr@2: /** Converts a vertical dimension from pixels to twips. williamr@2: williamr@2: An implementation is supplied by a derived class. williamr@2: williamr@2: @param aPixels A vertical dimension of a device in pixels. williamr@2: @return A vertical dimension of a device in twips. */ williamr@2: virtual TInt VerticalPixelsToTwips(TInt aPixels) const=0; williamr@2: williamr@2: /** williamr@2: Gets the font which is the nearest to the given font specification. williamr@2: williamr@2: When the font is no longer needed, call @c ReleaseFont(). williamr@2: williamr@2: Note that this deprecated function is replaced by the new @c GetNearestFontToDesignHeightInTwips() williamr@2: yielding (virtually) the same result. However clients are strongly encouraged to use the new williamr@2: @c GetNearestFontToMaxHeightInTwips() function instead. This will guarantee that every williamr@2: character within any given text string will fit within the given amount of twips, whereas the design williamr@2: height is an aesthetic unit decided by the font designer without strict physical meaning, which williamr@2: may result in cropped characters. williamr@2: williamr@2: @param aFont On return, contains a pointer to the nearest font. williamr@2: @param aFontSpec The specification of the font to be matched. williamr@2: @return KErrNone if successful; a system-wide error code otherwise. williamr@2: @publishedAll williamr@2: @deprecated Use GetNearestFontToDesignHeightInTwips williamr@2: */ williamr@2: virtual TInt GetNearestFontInTwips(CFont*& aFont,const TFontSpec& aFontSpec)=0; williamr@2: williamr@2: /** williamr@2: Gets the font which is the nearest to the given font specification. williamr@2: williamr@2: When the font is no longer needed, call @c ReleaseFont(). williamr@2: williamr@2: This new function replaces the deprecated @c GetNearestFontInTwips() yielding (virtually) the williamr@2: same result. However clients are strongly encouraged to use the new williamr@2: @c GetNearestFontToMaxHeightInTwips() function instead. This will guarantee that every williamr@2: character within any given text string will fit within the given amount of twips, whereas the design williamr@2: height is an aesthetic unit decided by the font designer without strict physical meaning, which williamr@2: may result in cropped characters. williamr@2: williamr@2: @param aFont On return, contains a pointer to the nearest font. williamr@2: @param aFontSpec The specification of the font to be matched. williamr@2: @return KErrNone if successful; a system-wide error code otherwise. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: virtual TInt GetNearestFontToDesignHeightInTwips( williamr@2: CFont*& /*aFont*/, const TFontSpec& /*aFontSpec*/) { return KErrNotSupported; } williamr@2: williamr@2: /** williamr@2: Gets the font which is the nearest to the given font specification. williamr@2: williamr@2: When the font is no longer needed, call @c ReleaseFont(). williamr@2: williamr@2: The font and bitmap server returns a pointer to the nearest matching font williamr@2: from those available. Matches to max height of font - this does its best williamr@2: to return a font that will fit within the maximum height specified (but williamr@2: note that variations due to hinting algorithms may rarely result in this williamr@2: height being exceeded by up to one pixel). Problems can also be williamr@2: encountered with bitmap fonts where the typeface exists but doesn't have williamr@2: a font small enough. williamr@2: williamr@2: @param aFont On return, contains a pointer to the nearest font. williamr@2: @param aFontSpec The specification of the font to be matched. williamr@2: @param aMaxHeight The maximum height within which the font must fit. williamr@2: This overrides the height specified in aFontSpec. williamr@2: @return KErrNone if successful; a system-wide error code otherwise. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: virtual TInt GetNearestFontToMaxHeightInTwips( williamr@2: CFont*& /*aFont*/, const TFontSpec& /*aFontSpec*/, TInt /*aMaxHeight*/) { return KErrNotSupported; } williamr@2: williamr@2: /** Releases the specified font. williamr@2: williamr@2: It is used to indicate that the specified font is no longer needed for use williamr@2: by the device map. As fonts can be shared between applications, this williamr@2: function does not delete the copy of the font from RAM unless the font was williamr@2: only being used by this particular device map. williamr@2: williamr@2: An implementation is supplied by a derived class. williamr@2: williamr@2: @param aFont A pointer to the font to be released. */ williamr@2: virtual void ReleaseFont(CFont* aFont)=0; williamr@2: }; williamr@2: williamr@2: class CGraphicsContext; williamr@2: williamr@2: /** Specifies the interface for concrete device classes. williamr@2: williamr@2: It holds information on the capabilities and attributes of a graphics device. williamr@2: The CBitmapDevice and CPrinterDevice classes are derived from CGraphicsDevice. williamr@2: williamr@2: @see CGraphicsDevice williamr@2: @see CPrinterDevice williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CGraphicsDevice : public CBase , public MGraphicsDeviceMap williamr@2: { williamr@2: public: williamr@2: /** Gets the display mode of the device. williamr@2: williamr@2: @return The display mode of the device. */ williamr@2: virtual TDisplayMode DisplayMode() const=0; williamr@2: williamr@2: /** Gets the size of the device area in pixels. williamr@2: williamr@2: @return The width and height of the device area, in pixels */ williamr@2: virtual TSize SizeInPixels() const=0; williamr@2: williamr@2: /** Gets the size of the device area in twips. williamr@2: williamr@2: @return The width and height of the device area, in twips */ williamr@2: virtual TSize SizeInTwips() const=0; williamr@2: williamr@2: /** Creates a graphics context for the device. williamr@2: williamr@2: @param aGC On return, contains a pointer to the created graphics context. williamr@2: @return KErrNone, if successful; otherwise, another of the system-wide error williamr@2: codes. */ williamr@2: virtual TInt CreateContext(CGraphicsContext*& aGC)=0; williamr@2: williamr@2: /** Gets the number of typefaces supported by the graphics device. williamr@2: williamr@2: @return The number of typefaces supported. */ williamr@2: virtual TInt NumTypefaces() const=0; williamr@2: williamr@2: /** Gets typeface information for a specified typeface. williamr@2: williamr@2: This information is returned in aTypefaceSupport, and includes: williamr@2: williamr@2: the typeface name and typeface attributes williamr@2: williamr@2: the number of font heights williamr@2: williamr@2: the maximum and minimum font heights williamr@2: williamr@2: whether it is a scalable typeface williamr@2: williamr@2: @param aTypefaceSupport On return, contains the typeface information. williamr@2: @param aTypefaceIndex A typeface index number, in the range: zero to williamr@2: (NumTypefaces() - 1). williamr@2: @see NumTypefaces() */ williamr@2: virtual void TypefaceSupport(TTypefaceSupport& aTypefaceSupport,TInt aTypefaceIndex) const=0; williamr@2: williamr@2: /** Get the height of a font in twips. williamr@2: williamr@2: The font is identified by typeface and height. williamr@2: williamr@2: The value returned is rounded up or down to the nearest font height in twips. williamr@2: williamr@2: @param aTypefaceIndex An index identifying the typeface, in the range: 0 williamr@2: to (NumTypefaces() - 1). williamr@2: @param aHeightIndex An index identifying the font height, in the range: 0 williamr@2: to (iNumHeights - 1). Note that iNumHeights is in the TTypefaceSupport williamr@2: object returned by TypefaceSupport(). williamr@2: @return The height of the font, in twips. */ williamr@2: virtual TInt FontHeightInTwips(TInt aTypefaceIndex,TInt aHeightIndex) const=0; williamr@2: williamr@2: /** Gets the palette attributes of the device. williamr@2: williamr@2: @param aModifiable On return, holds information on whether or not the device's williamr@2: palette is modifiable (ETrue) or fixed (EFalse). williamr@2: @param aNumEntries On return, holds the number of entries in the device's williamr@2: palette. */ williamr@2: virtual void PaletteAttributes(TBool& aModifiable,TInt& aNumEntries) const=0; williamr@2: williamr@2: /** Sets the device's palette. williamr@2: williamr@4: Setting the palette is only possible if the device has a modifiable palette, williamr@4: which can be determined by calling PaletteAttributes(). williamr@4: williamr@2: @param aPalette The new palette for the device. */ williamr@2: virtual void SetPalette(CPalette* aPalette)=0; williamr@2: williamr@2: /** Gets the device's current palette. williamr@2: williamr@4: This function is only supported if the device has a modifiable palette, williamr@4: which can be determined by calling PaletteAttributes(). williamr@4: williamr@2: @param aPalette On return, holds the device's current palette. williamr@2: @return KErrNone, if successful; otherwise, another of the system-wide error williamr@2: codes. */ williamr@2: virtual TInt GetPalette(CPalette*& aPalette) const=0; williamr@2: }; williamr@2: williamr@2: williamr@2: /** williamr@2: Code section range information. williamr@2: williamr@2: A code section defines the bitmaps for characters in a specified range - williamr@2: the range is stored in objects of this type. williamr@2: @publishedAll williamr@2: @deprecated This is not used anywhere in version 6.0. williamr@2: */ williamr@2: class TCodeSection williamr@2: { williamr@2: public: williamr@2: /** The beginning of the range. */ williamr@2: TInt iStart; williamr@2: /** The end of the range. */ williamr@2: TInt iEnd; williamr@2: }; williamr@2: williamr@2: /** williamr@4: WARNING: this Class is for internal use ONLY. Compatibility is not guaranteed in future releases. williamr@2: UIDs corresponding to the CFont API extension functions williamr@2: @internalTechnology williamr@2: */ williamr@2: const TUid KFontCapitalAscent = {0x1020498E}; williamr@2: const TUid KFontMaxAscent = {0x10204B10}; williamr@2: const TUid KFontStandardDescent = {0x10204B11}; williamr@2: const TUid KFontMaxDescent = {0x10205AFC}; williamr@2: const TUid KFontLineGap = {0x10204B12}; williamr@2: williamr@2: williamr@2: williamr@2: /** Abstract font interface. williamr@2: williamr@2: The CFont class provides a device-independent interface to a device-dependent williamr@2: font usually obtained from a call to GetNearestFont...() on a graphics device. williamr@2: It is used as a handle in CGraphicsContext::UseFont() and to obtain williamr@2: device-dependent information about the font - notably the pixel width of a text williamr@2: string. williamr@2: williamr@2: @see CFbsFont williamr@2: @see CGraphicsContext::UseFont() williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CFont : public CBase williamr@2: { williamr@2: friend class CTypefaceStore; williamr@2: public: williamr@2: williamr@2: /** Text direction flags. williamr@2: williamr@2: This enum is used in TMeasureTextInput and determines whether the text is williamr@2: drawn horizontally or vertically. Note: text is drawn vertically in some williamr@2: styles of Japanese, etc. williamr@2: williamr@2: @see TMeasureTextInput */ williamr@2: enum TTextDirection williamr@2: { williamr@2: /** Text is drawn horizontally. */ williamr@2: /** Text is drawn horizontally. */ williamr@2: EHorizontal, williamr@2: /** Text is drawn vertically. */ williamr@2: EVertical williamr@2: }; williamr@2: williamr@2: /** Complicated parameter block used for contextual glyph selection, williamr@2: ligature creation and diacritic placement when drawing text in complex williamr@2: scripts williamr@2: williamr@2: This class declares a constructor, another scoped class, and several other williamr@2: enums. However this class is unlikely to be useful to third party developers. williamr@2: williamr@2: @see CFont::GetCharacterPosition() williamr@2: @see CFont::GetCharacterPosition2() williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TPositionParam williamr@2: { williamr@2: public: williamr@2: /** Standard constructor. */ williamr@2: TPositionParam(): williamr@2: iDirection(EHorizontal), williamr@2: iFlags(0), williamr@2: iPosInText(0), williamr@2: iOutputGlyphs(0) williamr@2: { williamr@2: } williamr@2: williamr@2: enum williamr@2: { williamr@2: EMaxInputChars = 18, // ligatures cannot be made from more than 18 components williamr@2: EMaxOutputGlyphs = 8 // output can consist of up to 8 characters (one base and 7 combining characters) williamr@2: }; williamr@2: williamr@2: /**Flags for TPositionParam::iFlags. */ williamr@2: enum TFlags williamr@2: { williamr@2: /** Input text is logically ordered not visually ordered. */ williamr@2: EFLogicalOrder = 1 williamr@2: }; williamr@2: williamr@2: /** Input: Orientation (EHorizontal or EVertical) in which to draw williamr@2: the text. */ williamr@2: TInt16 iDirection; williamr@2: /** Input: Flags from TFlags. */ williamr@2: TUint16 iFlags; williamr@2: /** Input: Text containing the characters to be positioned. */ williamr@2: TPtrC iText; williamr@2: williamr@2: /** Input and output: Position within iText to shape. On exit williamr@2: it will index the first character not positioned */ williamr@2: TInt iPosInText; williamr@2: /** Input and output: Pen position. */ williamr@2: TPoint iPen; williamr@2: williamr@2: /** Output of GetCharacterPosition and GetCharacterPosition2. williamr@2: @see CFont::GetCharacterPosition williamr@2: @see CFont::GetCharacterPosition2 williamr@2: @publishedAll williamr@2: @released */ williamr@2: class TOutput williamr@2: { williamr@2: public: williamr@2: /** Standard constructor. */ williamr@2: TOutput() : iBitmapSize(TSize::EUninitialized), williamr@2: iBounds(TRect::EUninitialized) {} williamr@2: /** Character or glyph code. */ williamr@2: TUint iCode; williamr@2: /** Bitmap data for the glyph, if available */ williamr@2: const TUint8* iBitmap; williamr@2: /** Size of the bitmap before algorithmic bolding, size williamr@2: multiplication, etc. */ williamr@2: TSize iBitmapSize; williamr@2: /** Bitmap bounds relative to the original pen position. */ williamr@2: TRect iBounds; williamr@2: }; williamr@2: williamr@2: /** Information about the glyphs that were output. */ williamr@2: TOutput iOutput[EMaxOutputGlyphs]; williamr@2: /** Number of glyphs actually output. */ williamr@2: TInt iOutputGlyphs; williamr@2: }; williamr@2: williamr@2: williamr@2: /** Input parameter block. williamr@2: williamr@2: This is optionally used by CFont::MeasureText(), which is the powerful text williamr@2: measurement function underlying all the other text measurement functions. williamr@2: williamr@2: @see CFont::MeasureText() williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TMeasureTextInput williamr@2: { williamr@2: public: williamr@2: TMeasureTextInput(): williamr@2: iStartInputChar(0), williamr@2: iEndInputChar(KMaxTInt), williamr@2: iDirection(EHorizontal), williamr@2: iFlags(0), williamr@2: iMaxAdvance(KMaxTInt), williamr@2: iMaxBounds(KMaxTInt), williamr@2: iCharJustNum(0), williamr@2: iCharJustExcess(0), williamr@2: iWordJustNum(0), williamr@2: iWordJustExcess(0) williamr@2: { williamr@2: } williamr@2: williamr@2: /**Flags for TMeasureTextInput::iFlags. */ williamr@2: enum TFlags williamr@2: { williamr@2: /** Input text is visually ordered left-to-right. */ williamr@2: EFVisualOrder = 1, williamr@2: /** Input text is visually ordered right-to-left. williamr@2: Overrides EFVisualOrder. */ williamr@2: EFVisualOrderRightToLeft = 2, williamr@2: /** Flag to consider side bearings when checking bounds for line-break */ williamr@2: EFIncludePenPositionInBoundsCheck = 4 williamr@2: }; williamr@2: williamr@2: /** Starting index specifying first input character in iText. williamr@2: williamr@2: Together with iEndInputChar, this allows some context before and williamr@2: after the measured text to be supplied so that shaping can work williamr@2: properly. */ williamr@2: TInt iStartInputChar; williamr@2: williamr@2: /** Index specifying the final input character. williamr@2: williamr@2: Together with iStartInputChar, this allows some context before and williamr@2: after the measured text to be supplied so that shaping can work williamr@2: properly. */ williamr@2: TInt iEndInputChar; williamr@2: williamr@2: /** The direction in which to draw the text. */ williamr@2: TUint16 iDirection; williamr@2: williamr@2: /** Flags from TFlags. */ williamr@2: TUint16 iFlags; williamr@2: williamr@2: /** The maximum advance. */ williamr@2: TInt iMaxAdvance; williamr@2: williamr@2: /** The maximum width (or height if drawing vertically) of bounds. */ williamr@2: TInt iMaxBounds; williamr@2: williamr@2: /** The number of glyph groups to be letter-spaced. */ williamr@2: TInt iCharJustNum; williamr@2: williamr@2: /** The amount of space to be used for letter spacing. */ williamr@2: TInt iCharJustExcess; williamr@2: williamr@2: /** The number of spaces to be used for word spacing. */ williamr@2: TInt iWordJustNum; williamr@2: williamr@2: /** The amount of space to be used for word spacing. */ williamr@2: TInt iWordJustExcess; williamr@2: }; williamr@2: williamr@2: /** Output parameter block. williamr@2: williamr@2: This is optionally used by CFont::MeasureText(), which is the powerful text williamr@2: measurement function underlying all the other text measurement functions. williamr@2: williamr@2: @see CFont::MeasureText() williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TMeasureTextOutput williamr@2: { williamr@2: public: williamr@2: /** The number of input characters that would be drawn. williamr@2: williamr@2: This may be less than the length of the text if a maximum advance or bounding williamr@2: box size is specified. */ williamr@2: TInt iChars; williamr@2: /** The number of glyphs that would be drawn. */ williamr@2: TInt iGlyphs; williamr@2: /** The number of groups that would be drawn. williamr@2: williamr@2: A group is a base glyph plus one or more combining characters. */ williamr@2: TInt iGroups; williamr@2: /** The number of word spaces (U+0020) that would be drawn. */ williamr@2: TInt iSpaces; williamr@2: /** The bounding box of all the glyphs that would be drawn. */ williamr@2: TRect iBounds; williamr@2: /** The maximum width and height of any glyph. */ williamr@2: TSize iMaxGlyphSize; williamr@2: }; williamr@2: williamr@2: /** williamr@2: Data availability flags. williamr@2: williamr@2: Some fonts like printer fonts may only have width information and can return williamr@2: ECharacterWidthOnly to show this: the text drawing routines in CFont synthesize williamr@2: the rest of the data if necessary. williamr@2: williamr@2: @see GetCharacterData() williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TCharacterDataAvailability williamr@2: { williamr@2: /** No font information available. */ williamr@2: ENoCharacterData, williamr@2: /** Width information only is available. */ williamr@2: ECharacterWidthOnly, williamr@2: /** All character data is available. */ williamr@2: EAllCharacterData williamr@2: }; williamr@2: williamr@2: private: williamr@2: // virtual functions have been made protected and public non-virtual ones williamr@2: // added to convert CFont to a handle-body pattern. SC is kept throught the williamr@2: // new functions and BC is kept by keeping the protected functions in the williamr@2: // same place in the class, and therefore in the same place in the vtable williamr@2: /** williamr@4: @publishedAll williamr@4: WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation. williamr@2: */ williamr@2: virtual TUid DoTypeUid() const=0; williamr@2: /** williamr@4: @publishedAll williamr@4: WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation. williamr@2: */ williamr@2: virtual TInt DoHeightInPixels() const=0; williamr@2: /** williamr@4: @publishedAll williamr@4: WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation. williamr@2: */ williamr@2: virtual TInt DoAscentInPixels() const=0; williamr@2: IMPORT_C virtual TInt DoDescentInPixels() const; williamr@2: /** williamr@4: @publishedAll williamr@4: WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation. williamr@2: */ williamr@2: virtual TInt DoCharWidthInPixels(TChar aChar) const=0; williamr@2: /** williamr@4: @publishedAll williamr@4: WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation. williamr@2: */ williamr@2: virtual TInt DoTextWidthInPixels(const TDesC& aText) const=0; williamr@2: /** williamr@4: @publishedAll williamr@4: WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation. williamr@2: */ williamr@2: virtual TInt DoBaselineOffsetInPixels() const=0; williamr@2: /** williamr@4: @publishedAll williamr@4: WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation. williamr@2: */ williamr@2: virtual TInt DoTextCount(const TDesC& aText,TInt aWidthInPixels) const=0; williamr@2: /** williamr@4: @publishedAll williamr@4: WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation. williamr@2: */ williamr@2: virtual TInt DoTextCount(const TDesC& aText,TInt aWidthInPixels,TInt& aExcessWidthInPixels) const=0; williamr@2: /** williamr@4: @publishedAll williamr@4: WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation. williamr@2: */ williamr@2: virtual TInt DoMaxCharWidthInPixels() const=0; williamr@2: /** williamr@4: @publishedAll williamr@4: WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation. williamr@2: */ williamr@2: virtual TInt DoMaxNormalCharWidthInPixels() const=0; williamr@2: /** williamr@4: @publishedAll williamr@4: WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation. williamr@2: */ williamr@2: virtual TFontSpec DoFontSpecInTwips() const=0; williamr@2: williamr@2: protected: williamr@2: IMPORT_C virtual TCharacterDataAvailability DoGetCharacterData(TUint aCode, TOpenFontCharMetrics& aMetrics,const TUint8*& aBitmap,TSize& aBitmapSize) const; williamr@2: IMPORT_C virtual TBool DoGetCharacterPosition(TPositionParam& aParam) const; williamr@2: IMPORT_C virtual TInt DoExtendedFunction(TUid aFunctionId, TAny* aParam = NULL) const; williamr@2: williamr@2: protected: williamr@2: IMPORT_C virtual ~CFont(); williamr@2: williamr@2: public: williamr@2: inline TInt FontCapitalAscent() const; williamr@2: inline TInt FontMaxAscent() const; williamr@2: inline TInt FontStandardDescent() const; williamr@2: inline TInt FontMaxDescent() const; williamr@2: inline TInt FontLineGap() const; williamr@2: inline TInt FontMaxHeight() const; williamr@2: williamr@2: public: williamr@2: /** Gets run-time identity of the actual font type. This enables safe casting to williamr@2: a derived type. williamr@2: williamr@2: For example, if the derived type is a CFbsFont, the return value is KCFbsFontUid. williamr@2: You would need to cast to a CFbsFont to get a character bounding box. Similarly, williamr@2: a CBitmapFont returns KCBitmapFontUidVal. williamr@2: williamr@2: @return The font-type identifier. */ williamr@2: IMPORT_C TUid TypeUid() const; williamr@2: williamr@2: /** Gets the font height in pixels. williamr@2: Note that this deprecated function is replaced by the new @c FontMaxHeight(). williamr@2: williamr@2: @return The font height in pixels. williamr@2: @see FontMaxHeight() williamr@2: @deprecated */ williamr@2: IMPORT_C TInt HeightInPixels() const; williamr@2: williamr@2: /** Gets the font ascent in pixels. williamr@2: Note that this deprecated function is replaced by the new @c FontMaxAscent() williamr@4: or in some cases @c FontCapitalAscent(). williamr@4: williamr@2: @return The font ascent in pixels. williamr@2: @see FontCapitalAscent() williamr@2: @see FontMaxAscent() williamr@2: @deprecated */ williamr@2: IMPORT_C TInt AscentInPixels() const; williamr@2: williamr@2: /** Gets the font descent in pixels. williamr@2: Note that this deprecated function is replaced by the new @c FontMaxDescent() williamr@4: or in some cases @c FontStandardDescent(). williamr@2: williamr@2: @return The font descent in pixels. williamr@2: @see FontStandardDescent() williamr@2: @see FontMaxDescent() williamr@2: @deprecated */ williamr@2: IMPORT_C TInt DescentInPixels() const; williamr@2: williamr@2: /** Gets the width in pixels in this font of the specified character. williamr@2: williamr@2: Note: For OpenType fonts this function returns the horizontal advance of williamr@2: the character, which may be different from the actual width. williamr@2: williamr@2: @param aChar The character whose width should be determined. williamr@2: @return The width in pixels of the specified character in this font. */ williamr@2: IMPORT_C TInt CharWidthInPixels(TChar aChar) const; williamr@2: williamr@2: /** Gets the width in pixels of the specified descriptor when displayed in this williamr@2: font. williamr@2: williamr@2: @param aText The descriptor whose width should be determined. williamr@2: @return The width of the specified descriptor when displayed in this font, williamr@2: in pixels. */ williamr@2: IMPORT_C TInt TextWidthInPixels(const TDesC& aText) const; williamr@2: williamr@2: /** Gets the baseline offset in pixels. williamr@2: williamr@2: The baseline offset is how far a font is raised or lowered from its normal williamr@2: baseline. williamr@2: williamr@2: @return Offset from normal baseline, in pixels. */ williamr@2: IMPORT_C TInt BaselineOffsetInPixels() const; williamr@2: williamr@2: /** Gets how much of the specified descriptor can be displayed in this font without williamr@2: exceeding the specified width. williamr@2: williamr@2: Note: williamr@2: williamr@2: This function does not display any of the descriptor itself - it is used williamr@2: before display, to test whether the whole descriptor can be displayed. williamr@2: williamr@2: @param aText The descriptor. williamr@2: @param aWidthInPixels The available width for character display. williamr@2: @return The number of characters which will be able to be displayed without williamr@2: exceeding the specified width. The count starts from the beginning of the williamr@2: descriptor. */ williamr@2: IMPORT_C TInt TextCount(const TDesC& aText,TInt aWidthInPixels) const; williamr@2: williamr@2: /** Gets how much of the specified descriptor can be displayed in this font without williamr@2: exceeding the specified width. williamr@2: williamr@2: It also returns the excess width - defined as the specified available width williamr@2: minus the width of the portion of the descriptor which can be displayed without williamr@2: exceeding the available width. williamr@2: williamr@2: @param aText The descriptor. williamr@2: @param aWidthInPixels The available width for character display. williamr@2: @param aExcessWidthInPixels The excess width after displaying the portion of williamr@2: the descriptor, in pixels. williamr@2: @return The number of characters which will be able to be displayed without williamr@2: exceeding the specified width. The count starts from the beginning of the williamr@2: descriptor. */ williamr@2: IMPORT_C TInt TextCount(const TDesC& aText,TInt aWidthInPixels,TInt& aExcessWidthInPixels) const; williamr@2: williamr@2: /** Gets the width in pixels of the widest character in this font. williamr@2: williamr@2: @return The width of the maximum width character, in pixels. */ williamr@2: IMPORT_C TInt MaxCharWidthInPixels() const; williamr@2: williamr@2: /** Gets the width in pixels of the widest normal character in this font. williamr@2: williamr@2: Normal characters include all character in a character set except non-alphabetic williamr@2: characters (e.g. the copyright symbol, or a block graphics symbol, for example). williamr@2: williamr@2: @return The width of the maximum width normal character, in pixels. */ williamr@2: IMPORT_C TInt MaxNormalCharWidthInPixels() const; williamr@2: williamr@2: /** Gets the font specification of this font in twips. williamr@2: williamr@2: @return The font specification of this font (in twips). */ williamr@2: IMPORT_C TFontSpec FontSpecInTwips() const; williamr@2: IMPORT_C TCharacterDataAvailability GetCharacterData(TUint aCode, TOpenFontCharMetrics& aMetrics,const TUint8*& aBitmap,TSize& aBitmapSize) const; williamr@2: IMPORT_C TBool GetCharacterPosition(TPositionParam& aParam) const; williamr@2: IMPORT_C TInt WidthZeroInPixels() const; williamr@2: IMPORT_C TInt MeasureText(const TDesC& aText, const TMeasureTextInput* aInput = NULL, TMeasureTextOutput* aOutput = NULL) const; williamr@2: IMPORT_C static TBool CharactersJoin(TInt aLeftCharacter, TInt aRightCharacter); williamr@2: IMPORT_C TInt ExtendedFunction(TUid aFunctionId, TAny* aParam = NULL) const; williamr@2: IMPORT_C TBool GetCharacterPosition2(TPositionParam& aParam, RShapeInfo& aShapeInfo) const; williamr@4: williamr@4: /** Gets the width in pixels of the specified descriptor when displayed in this williamr@4: font. williamr@4: williamr@4: @param aText The descriptor whose width should be determined. williamr@4: @param aParam Parameter block that controls how much of aText is measured williamr@4: @return The width of the specified descriptor when displayed in this font, williamr@4: in pixels. */ williamr@4: IMPORT_C TInt TextWidthInPixels(const TDesC& aText,const TMeasureTextInput* aParam) const; williamr@2: }; williamr@2: williamr@2: class CFbsBitmap; williamr@2: class CWsBitmap; williamr@2: /** Abstract base class for all graphics contexts. williamr@2: williamr@2: Created by a CGraphicsDevice. williamr@2: williamr@2: Provides the 'context' in which you are drawing to an associated device, in williamr@2: the sense that it holds the settings for drawing, such as the pen and brush williamr@2: settings (e.g. color, line styles) and the font settings (e.g. bold, underline, williamr@2: italic). These settings are device-independent. williamr@2: williamr@2: Also provides the clipping region (the visible drawing area). williamr@2: williamr@2: The settings and clipping area can be updated while drawing. williamr@2: williamr@2: This class also contains the main drawing functions, and all drawing is done williamr@2: through a CGraphicsContext. williamr@2: williamr@2: The graphics context deals with pixels of device-dependent size and uses fonts williamr@2: with device-dependent size and representation. The sizes and fonts to be passed williamr@2: to the class functions therefore need to be converted from size-independent williamr@2: units to size-dependent units first. This is done by an MGraphicsDeviceMap williamr@2: derived class. This may be a TZoomFactor or the CGraphicsDevice. williamr@2: williamr@2: See CGraphicsContext::Reset() for the default graphics context settings immediately williamr@2: after construction. williamr@2: williamr@2: @see CBitmapContext williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CGraphicsContext : public CBase williamr@2: { williamr@2: public: williamr@2: williamr@2: williamr@2: /** Text alignment. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TTextAlign williamr@2: { williamr@2: /** Text is left-aligned. */ williamr@2: ELeft, williamr@2: /** Text is centred. */ williamr@2: ECenter, williamr@2: /** Text is right-aligned. */ williamr@2: ERight williamr@2: }; williamr@2: williamr@2: /** williamr@2: Drawing mode components. williamr@2: This enum is not intended to be used directly, but provides components for williamr@2: the easy specification of drawing modes in the TDrawMode enum. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TDrawModeComponents williamr@2: { williamr@2: /** 1 */ williamr@2: EInvertScreen=1, williamr@2: /** 2 */ williamr@2: EXor=2, williamr@2: /** 4 */ williamr@2: EOr=4, williamr@2: /** 8 */ williamr@2: EAnd=8, williamr@2: /** 14 */ williamr@2: ELogicalOp=14, williamr@2: /** 16 */ williamr@2: EInvertPen=16, williamr@2: /** 32 */ williamr@2: EPenmode=32, williamr@2: /** 64 */ williamr@2: EWriteAlpha=64, williamr@2: }; williamr@2: williamr@2: williamr@2: /** williamr@2: Drawing modes. williamr@2: williamr@2: This enum builds on the drawing mode components in the TDrawModeComponents williamr@2: enum. williamr@2: williamr@2: If the pen colour is p, brush colour is b and screen colour is s, the effect williamr@2: of TDrawMode::EDrawModeAND is P=p&s and B=b&s. In other words, the effective williamr@2: colour of the pen on the screen, P, is that produced by the bitwise ANDing williamr@2: of the current screen colour and the current pen colour. The effect is similar williamr@2: for the effective brush colour, B. williamr@2: williamr@2: The effective pen and brush colour are given in the table using the key williamr@2: Inputs: pen colour is p, brush colour is b and screen colour is s williamr@2: Outputs: effective brush colour is B, effective pen colour is P. williamr@2: williamr@2: Some notes on using EDrawModeWriteAlpha:- williamr@2: williamr@2: - It is rare for client code to need to use this draw mode: see the documentation williamr@2: of SetDrawMode() for more information. williamr@2: - EDrawModeWriteAlpha should only be used with DrawRect(), Clear(), BitBlt(), and BitBltMasked() williamr@2: with EGray2 mask (and DrawBitmap() and DrawBitmapMasked()). For other draw operations, it is not williamr@2: supported, and may have unintended effects. williamr@2: - EDrawModeWriteAlpha has the same effect as EDrawModePEN, unless the brush colour has transparency williamr@2: (DrawRect(), Clear()), or the source bitmap is EColor16MA (and has transparency) (BitBlt(), BitBltMasked()) williamr@2: - EDrawModeWriteAlpha has the same effect as EDrawModePEN if the draw mode of the destination does not williamr@2: support alpha blending. (Blending is only supported in 24bpp and 32bpp colour i.e. EColor16M, EColor16MU, EColor16MA) williamr@2: - In these cases, EDrawModePEN does alpha blending, whereas EDrawModeWriteAlpha means don't do alpha blending. williamr@2: williamr@2: @see SetDrawMode() williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TDrawMode williamr@2: { williamr@2: /** Bitwise ANDs the pen and brush colours with the screen colour. williamr@2: P=p&s, B=b&s */ williamr@2: EDrawModeAND=EAnd, williamr@2: /** Inverts the pen and brush colours before ANDing. P=(~p)&s, williamr@2: B=(~b)&s */ williamr@2: EDrawModeNOTAND=EInvertScreen|EAnd, williamr@2: /** Uses both pen and brush colour as they are. P=p, B=b */ williamr@2: EDrawModePEN=EPenmode, williamr@2: /** Inverts the screen colour before ANDing. P=p&(~s), B=b&(~s) */ williamr@2: EDrawModeANDNOT=EAnd|EInvertPen, williamr@2: /** Bitwise XORs the pen and brush colours with the screen colour. williamr@2: P=p^s, B=b^s */ williamr@2: EDrawModeXOR=EXor, williamr@2: /** Bitwise ORs the pen and brush colours with the screen colour. williamr@2: P=p|s, B=b|s */ williamr@2: EDrawModeOR=EOr, williamr@2: /** Inverts the screen and pen and brush colours before ANDing. williamr@2: P=(~p)&(~s), B=(~b)&(~s) */ williamr@2: EDrawModeNOTANDNOT=EInvertScreen|EAnd|EInvertPen, williamr@2: /** Inverts the pen and brush colours before XORing. P=(~p)^s, williamr@2: B=(~b)^s */ williamr@2: EDrawModeNOTXOR=EInvertScreen|EXor, williamr@2: /** Inverts the colour of each pixel that is drawn over, (pen and williamr@2: brush attributes are ignored). P=~s, B=~s */ williamr@2: EDrawModeNOTSCREEN=EInvertScreen, williamr@4: /** Inverts the screen colour before ORing. P=p|(~s), williamr@4: B=b|(~s) */ williamr@2: EDrawModeNOTOR=EInvertScreen|EOr, williamr@2: /** Inverts the pen and brush colours. P=~p, B=~b */ williamr@2: EDrawModeNOTPEN=EInvertPen|EPenmode, williamr@4: /** Inverts the pen and brush colours before ORing. P=(~p)|s, williamr@4: B=(~b)|s */ williamr@2: EDrawModeORNOT=EOr|EInvertPen, williamr@4: /** Inverts the screen and pen and brush colours before ORing. williamr@4: P=(~p)|(~s), B=(~b)|(~s) */ williamr@2: EDrawModeNOTORNOT=EInvertScreen|EOr|EInvertPen, williamr@2: /** Writes alpha information in the source directly into the destination, rather than blending. */ williamr@2: EDrawModeWriteAlpha=EWriteAlpha, williamr@2: }; williamr@2: williamr@2: /** williamr@2: Pen styles. The screen pattern unit in each definition below describes the williamr@2: pattern drawn by the line 1 represents a pixel drawn, 0 represents a williamr@2: pixel that is not affected. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TPenStyle williamr@2: { williamr@2: /** The pen does not draw. Screen pattern unit = 00... */ williamr@2: ENullPen, williamr@2: /** A solid line (default). Screen pattern unit = 11... */ williamr@2: ESolidPen, williamr@2: /** A dotted line. Screen pattern unit = 1000... */ williamr@2: EDottedPen, williamr@2: /** A dashed line. Screen pattern unit = 111000... */ williamr@2: EDashedPen, williamr@2: /** A line of alternating dashes and dots. Screen pattern unit = williamr@2: 1111001100... */ williamr@2: EDotDashPen, williamr@2: /** A line of alternating single dashes and pairs of dots. Screen williamr@2: pattern unit = 11110011001100... */ williamr@2: EDotDotDashPen williamr@2: }; williamr@2: williamr@2: /** williamr@2: Brush styles. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TBrushStyle williamr@2: { williamr@2: /** The brush fill has no effect (default). */ williamr@2: ENullBrush, williamr@2: /** The brush fills with a solid single colour, determined by williamr@2: SetBrushColor() and the drawing mode. */ williamr@2: ESolidBrush, williamr@2: /** The brush fills with a selected bitmap pattern, set by williamr@2: UseBrushPattern(). */ williamr@2: EPatternedBrush, williamr@2: /** The brush fills with vertical hatching lines going from top to williamr@2: bottom. */ williamr@2: EVerticalHatchBrush, williamr@2: /** The brush fills with diagonal hatching lines going from bottom williamr@2: left to top right. */ williamr@2: EForwardDiagonalHatchBrush, williamr@2: /** The brush fills with horizontal hatching lines going from left williamr@2: to right. */ williamr@2: EHorizontalHatchBrush, williamr@2: /** The brush fills with rearward diagonal hatching lines going from top williamr@2: left to bottom right. */ williamr@2: ERearwardDiagonalHatchBrush, williamr@2: /** The brush fills with horizontal and vertical hatching lines going williamr@2: from left to right plus lines going from top to bottom giving the williamr@2: effect of a grid of small squares */ williamr@2: ESquareCrossHatchBrush, williamr@2: /** The brush fills with forward diagonal and rearward diagonal hatching williamr@2: lines going from bottom left to top right plus lines going from top left williamr@2: to bottom right giving the effect of a grid of small diamonds. */ williamr@2: EDiamondCrossHatchBrush williamr@2: }; williamr@2: williamr@2: /** williamr@2: Rules used to fill self crossing polygons. williamr@2: williamr@2: The filling of a polygon proceeds as follows: for a given point in the williamr@2: polygon, then williamr@2: williamr@2: if the rule is TFillRule::EAlternate (default) and it has an odd winding williamr@2: number, then fill the surrounding area. williamr@2: williamr@2: if the rule is TFillRule::EWinding and it has a winding number greater than williamr@2: zero, then fill the surrounding area. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TFillRule williamr@2: { williamr@2: /** Only fill areas with odd winding numbers. */ williamr@2: EAlternate, williamr@2: /** Fill areas with winding numbers greater than zero. */ williamr@2: EWinding williamr@2: }; williamr@2: williamr@2: /** Parameters to control the drawing of text. */ williamr@2: struct TDrawTextParam williamr@2: { williamr@2: public: williamr@2: TDrawTextParam(): williamr@2: iDirection(CFont::EHorizontal), williamr@2: iCharJustNum(0), williamr@2: iCharJustExcess(0), williamr@2: iWordJustNum(0), williamr@2: iWordJustExcess(0) williamr@2: /** Reserved for future use. */ williamr@2: {} williamr@2: public: williamr@2: /** the direction in which to draw the text. */ williamr@2: CFont::TTextDirection iDirection; williamr@2: /** number of glyph groups to be letterspaced */ williamr@2: TInt iCharJustNum; williamr@2: /** amount of space to be used for letterspacing */ williamr@2: TInt iCharJustExcess; williamr@2: /** number of spaces to be used for wordspacing*/ williamr@2: TInt iWordJustNum; williamr@2: /** amount of space to be used for wordspacing*/ williamr@2: TInt iWordJustExcess; williamr@2: }; williamr@2: williamr@2: williamr@2: /** Parameters for extended text drawing and measuring. It is used by williamr@2: CGraphicsContext::DrawTextExtended() to indicate whether text should be williamr@2: drawn from right-to-left or left-to-right. */ williamr@2: struct TDrawTextExtendedParam : public TDrawTextParam williamr@2: { williamr@2: public: williamr@2: /** Constructor. Initialises iParRightToLeft to EFalse. */ williamr@2: TDrawTextExtendedParam(): williamr@2: iParRightToLeft(EFalse) williamr@2: {} williamr@2: public: williamr@2: /** ETrue if the text direction is right-to-left (for scripts like williamr@2: Arabic and Hebrew). EFalse if left-to-right. */ williamr@2: TBool iParRightToLeft; williamr@2: }; williamr@4: williamr@4: /** williamr@4: Parameters used in drawing text within supplied context. williamr@4: It is used by CGraphicsContext::DrawText() and CGraphicsContext::DrawTextVertical() family of API's williamr@4: to draw text from iStart to iEnd withing the supplied text descriptor. williamr@4: */ williamr@4: class TTextParameters williamr@4: { williamr@4: public: williamr@4: TTextParameters(): williamr@4: iStart(0), williamr@4: iEnd(KMaxTInt), williamr@4: iFlags(0) williamr@4: { williamr@4: } williamr@4: TInt iStart; williamr@4: TInt iEnd; williamr@4: TUint16 iFlags; williamr@4: /* Reserved for future use */ williamr@4: TAny* iReserved1; williamr@4: TAny* iReserved2; williamr@4: TAny* iReserved3; williamr@4: TAny* iReserved4; williamr@4: }; williamr@2: public: williamr@2: /** Gets a pointer to the graphics context's graphics device. williamr@2: williamr@2: @return A pointer to the graphics device. */ williamr@2: virtual CGraphicsDevice* Device() const=0; williamr@2: williamr@2: /** Sets the position of the co-ordinate origin. williamr@2: williamr@2: All subsequent drawing operations are done relative to this origin. williamr@2: williamr@2: @param aPos The origin. The default origin is TPoint(0,0) the top left williamr@2: corner of the screen. */ williamr@2: virtual void SetOrigin(const TPoint& aPos=TPoint(0,0))=0; williamr@2: williamr@2: /** Sets the drawing mode. williamr@2: williamr@2: The way that the pen and brush draw depends on the drawing mode. The drawing williamr@2: mode affects the colour that is actually drawn, because it defines the way williamr@2: that the current screen colour logically combines with the current pen colour williamr@2: and brush colour. There are many drawing modes, each giving different logical williamr@2: combinations of pen, brush and screen colours. Each mode is produced by ORing williamr@2: together different combinations of seven drawing mode components. williamr@2: williamr@2: The three most important modes are TDrawMode::EDrawModePEN, TDrawMode::EDrawModeNOTSCREEN williamr@2: and TDrawMode::EDrawModeXOR. The default drawing mode is TDrawMode::EDrawModePEN. williamr@2: williamr@2: The drawing mode is over-ridden for line and shape drawing functions when williamr@2: a wide pen line has been selected. It is forced to TDrawMode::EDrawModePEN. williamr@2: This is to prevent undesired effects at line joins (vertexes). williamr@2: williamr@2: Notes: williamr@2: williamr@2: TDrawMode::EDrawModeAND gives a "colour filter" effect. For example: williamr@2: williamr@2: - ANDing with white gives the original colour williamr@2: - ANDing with black gives black williamr@2: williamr@2: TDrawMode::EDrawModeOR gives a "colour boost" effect. For example: williamr@2: williamr@2: - ORing with black gives the original colour williamr@2: - ORing with white gives white williamr@2: williamr@2: TDrawMode::EDrawModeXOR gives an "Exclusive OR" effect. For example: williamr@2: williamr@2: - white XOR black gives white williamr@2: - white XOR white gives black williamr@2: - black XOR black gives black williamr@2: williamr@2: TDrawMode::EDrawModeWriteAlpha should not normally need to be used by client code. williamr@2: The following are exceptions:- williamr@2: williamr@2: - When a client side EColor16MA bitmap needs to have a transparent background williamr@2: (because you are intending to blend it onto something else), then you need to set williamr@2: EDrawModeWriteAlpha to Clear() it. williamr@2: - When you want to BitBlt() with an EColor16MA source bitmap that is opaque everywhere, williamr@2: then using EDrawModeWriteAlpha is more efficient than EDrawModePEN, because the bitmap williamr@2: does not need to be blended. williamr@2: williamr@2: Note that if you have a transparent brush or source bitmap and you are drawing to a window, williamr@2: then it is a defect to use EDrawModeWriteAlpha. williamr@2: williamr@2: @param aDrawingMode The drawing mode. williamr@2: @see CGraphicsContext::TDrawMode williamr@2: @see CGraphicsContext::TDrawModeComponents */ williamr@2: virtual void SetDrawMode(TDrawMode aDrawingMode)=0; williamr@2: williamr@4: /** Sets the clipping rectangle. williamr@4: williamr@4: The area of visible drawing depends on the clipping rectangle, any items williamr@4: that fall outside the extent of the clipping rectangle will not be drawn. williamr@4: The default clipping rectangle is the full device area. williamr@4: williamr@4: Note that clipping is additive. If a clipping region has been set using SetClippingRegion() williamr@4: then clipping will be to the intersection of that region and this rectangle. williamr@4: williamr@4: @param aRect The rectangle to be used as the clipping rectangle. Note that williamr@4: this rectangle is tranformed by the current co-ordinate origin before it is used. williamr@4: The co-ordinate origin is set using SetOrigin(). williamr@4: williamr@4: @see CGraphicsContext::SetClippingRegion() williamr@4: @see CGraphicsContext::SetOrigin() */ williamr@2: virtual void SetClippingRect(const TRect& aRect)=0; williamr@2: williamr@2: /** Cancels any clipping rectangle. williamr@2: williamr@2: Clipping thus reverts to the full device area, the default. williamr@2: williamr@2: @see SetClippingRect() */ williamr@2: virtual void CancelClippingRect()=0; williamr@2: williamr@2: /** Resets the graphics context to its default settings: williamr@2: williamr@2: the drawing mode is TDrawMode::EDrawModePen (pen and brush colours used as williamr@2: they are) williamr@2: williamr@2: there is no clipping rectangle williamr@2: williamr@2: the pen settings are: black, solid, single pixel size williamr@2: williamr@2: the brush style is null williamr@2: williamr@2: no text font is selected */ williamr@2: virtual void Reset()=0; williamr@2: williamr@2: /** Sets the device font to be used for text drawing. williamr@2: williamr@2: If the font is already in memory, then that copy is shared. williamr@2: williamr@2: Notes: williamr@2: williamr@2: The CFont* argument must have been previously initialised by calling williamr@2: MGraphicsDeviceMap::GetNearestFontInTwips() with the required williamr@2: font-specification. If the CFont* has not been initialised williamr@2: correctly, and therefore does not point to an available font-bitmap, williamr@2: then a panic is raised. williamr@2: williamr@2: When the font is no longer required, use DiscardFont() to free up the williamr@2: memory used. If UseFont() is used again without using DiscardFont() then williamr@2: the previous font is discarded automatically. williamr@2: williamr@2: If no font has been selected, and an attempt is made to draw text with williamr@2: DrawText(), then a panic is raised. williamr@2: williamr@2: @param aFont A device font williamr@2: @see MGraphicsDeviceMap::GetNearestFontInTwips() */ williamr@2: virtual void UseFont(const CFont* aFont)=0; williamr@2: williamr@2: /** Discards a font. williamr@2: williamr@2: This frees up the memory used, if the font is not being shared. williamr@2: williamr@2: The function can be called when no font is in use. */ williamr@2: virtual void DiscardFont()=0; williamr@2: williamr@2: /** Sets the underline style. williamr@2: williamr@2: This is applied to all subsequently drawn text. williamr@2: williamr@2: @param aUnderlineStyle The underline style on or off. */ williamr@2: virtual void SetUnderlineStyle(TFontUnderline aUnderlineStyle)=0; williamr@2: williamr@2: /** Sets the strikethrough style. williamr@2: williamr@2: This is applied to all subsequently drawn text. williamr@2: williamr@2: @param aStrikethroughStyle The strikethrough style on or off. */ williamr@2: virtual void SetStrikethroughStyle(TFontStrikethrough aStrikethroughStyle)=0; williamr@2: IMPORT_C static TInt JustificationInPixels(TInt aExcessPixels,TInt aTotalUnits,TInt aFirstUnit,TInt aNumUnits); williamr@2: IMPORT_C static TInt JustificationInPixels(TInt& aExcessPixels,TInt& aTotalUnits); williamr@2: williamr@2: /** Adjusts the spaces between words to stretch or squeeze to a certain williamr@2: width. williamr@2: williamr@2: The function is required by the Text Views API, and is not intended for williamr@2: regular use by developers. williamr@2: williamr@2: The text line that is to be justified has a certain number of gaps (spaces) williamr@2: between the words. It also has a distance (in pixels) between the end of williamr@2: the last word and the actual end of the line (right hand margin, usually). williamr@2: These excess width pixels are distributed amongst the gaps between the words williamr@2: to achieve full justification of the text line. Spaces become fat spaces to williamr@2: keep underlining/strikethrough consistent. Pixels are distributed to the williamr@2: inter-word gaps starting from the left end of the string. The spacing williamr@2: between characters in each word remains unchanged. williamr@2: williamr@2: After a call to SetWordJustification(), subsequent calls to either of the williamr@2: two DrawText() functions are affected until the number of spaces specified williamr@2: by aNumSpaces is used up. williamr@2: williamr@2: The easiest way to find out the excess width and number of spaces is to call williamr@2: CFont::MeasureText(). This function can also perform counting, which is williamr@2: finding how much of some text will fit into a given width. williamr@2: williamr@2: Use CFont::TextCount() to return the excess width. williamr@2: williamr@2: For example, in the string "To be, or not to be", there are five inter-word williamr@2: gaps. If there are six excess pixels they will be distributed in the williamr@2: proportion 2, 1, 1, 1, 1 between the words. If there are nine excess pixels williamr@2: they will be distributed in the proportion 2, 2, 2, 2, 1 between the words. williamr@2: williamr@2: Notes: williamr@2: williamr@2: If the excess width is zero, then calling SetWordJustification() has no williamr@2: effect. williamr@2: williamr@2: At first sight it may appear that SetWordJustification() is not required williamr@2: because you can simply call DrawText() for each word. However, underlined williamr@2: justified text does not work using this strategy you get a non-underlined williamr@2: gap between the space and the beginning of the next word. williamr@2: williamr@2: @param aExcessWidth The width (in pixels) to be distributed between the williamr@4: specified number of spaces. williamr@2: @param aNumGaps The number of word spaces (characters with the code U+0020) williamr@2: over which the change in width is distributed. */ williamr@2: virtual void SetWordJustification(TInt aExcessWidth,TInt aNumGaps)=0; williamr@2: williamr@2: /** Sets character justification. williamr@2: williamr@2: This function is required by the Text Views API, and is not intended for williamr@2: regular use by developers. williamr@2: williamr@2: It affects the strings of text used in the calls to DrawText() that follow, williamr@2: until the number of characters drawn equals aNumChars. williamr@2: williamr@2: The text line that is to be justified has a certain number of characters williamr@2: this includes the spaces between the words. It also has a distance (in williamr@2: pixels) between the end of the last word and the actual end of the line williamr@2: (right hand margin, usually). These excess width pixels are distributed williamr@2: amongst all the characters, increasing the gaps between them, to achieve williamr@2: full justification of the text line. williamr@2: williamr@2: Use CFont::TextCount() to return the excess width. williamr@2: williamr@2: Notes: williamr@2: williamr@2: This function is provided to allow simulation of printer fonts on screen. williamr@2: Due to the fact that fully-scalable fonts are not used before v5, large williamr@2: printer fonts can be simulated by using the nearest smaller font and williamr@2: widening it slightly. williamr@2: williamr@2: If the excess width is zero, then calling SetCharJustification() has no williamr@2: effect. williamr@2: williamr@2: SetCharJustification() is required for WYSIWYG where the layout uses williamr@2: printer font metrics but screen fonts have to be drawn on the screen. williamr@2: Because continuously scalable typefaces (c.f. TrueType) are not used williamr@2: before v5 and because screen fonts are coarser and less numerous in williamr@2: their variety than the printer fonts, the best matching smaller screen williamr@2: font must be used with character justification to simulate the printer williamr@2: font on the screen. williamr@2: williamr@2: There is also a situation where the gaps between characters on screen have williamr@2: to be reduced with character clipping. The screen font that best matches williamr@2: the printer font may have the required height, but has characters that are williamr@2: too wide. A line of text that works on the printer will then be too long williamr@2: on the screen, unless it is squashed horizontally. The number of pixels williamr@2: that overlap the end of the screen line must now be removed from the gaps williamr@2: between the characters, i.e. there is a negative excess width. This williamr@2: situation is especially important where adding a TAB on screen gives williamr@2: perfectly acceptable printout, but would push the last character of the williamr@2: line off the right hand side of the screen. williamr@2: williamr@2: In practice what you do in printer layout mode is: williamr@2: williamr@2: Calculate where the line breaks will come on the printer. To do this you williamr@2: use a printer font (which in practice means a table of character widths williamr@2: of the font that the printer will use). williamr@2: williamr@2: Now change to use a screen font that is the closest font which is no taller williamr@2: that the printer font. In practice it will often be fatter maybe only for williamr@2: certain characters such as 'i'. williamr@2: williamr@2: You have to recalculate the width of the characters using the screen fonts. williamr@2: You can do this using CFont::TextWidth() as you have already determined how williamr@2: many characters will fit on the line. williamr@2: williamr@2: If, in the screen font, the characters are not as wide as the line then you williamr@2: can just use word justification to expand the line. You would only do this williamr@2: if the text is to be justified. williamr@2: williamr@2: If, however, the characters are wider than the line then you would use williamr@2: character justification to clip each character. You would need to do this williamr@2: even if the line is not justified. williamr@2: williamr@2: Thus, in practice, character justification will only very rarely be used to williamr@2: expand a line of characters. williamr@2: williamr@2: @param aExcessWidth The excess width (in pixels) to be distributed between williamr@4: the specified number of characters. It may be positive, in which case the text is williamr@4: stretched, or negative, in which case it is shrunk. williamr@2: @param aNumChars The number of characters involved. */ williamr@2: virtual void SetCharJustification(TInt aExcessWidth,TInt aNumChars)=0; williamr@2: williamr@2: /** Sets the pen colour. williamr@2: williamr@2: The effective pen colour depends on the drawing mode. The default pen colour williamr@2: is black. williamr@2: williamr@2: Note: williamr@2: williamr@2: The pen is used to draw lines, the outlines of filled shapes, and text. The williamr@2: class provides member functions to set the colour of the pen, the style of williamr@2: line and the line size drawn. williamr@2: williamr@2: @param aColor An RGB colour for the pen. williamr@2: @see CGraphicsContext::SetDrawMode() */ williamr@2: virtual void SetPenColor(const TRgb& aColor)=0; williamr@2: williamr@2: /** Sets the line drawing style for the pen. williamr@2: williamr@2: There are 6 pen styles. If no pen style is set, then the default is williamr@2: TPenStyle::ESolidPen. To use a pen style, its full context must be given, williamr@2: e.g. for a null pen: williamr@2: williamr@2: CGraphicsContext::TPenStyle::ENullPen williamr@2: Notes: williamr@2: williamr@2: The pen is used to draw lines, the outlines of filled shapes, and text. williamr@2: CGraphicsContext member functions are provided to set the colour of the williamr@2: pen, the style of line and the line size drawn. williamr@2: williamr@2: The TPenStyle::ENullPen style should be used if a border is not required williamr@2: around a filled shape. williamr@2: williamr@2: Dotted and dashed pen styles have a device dependant implementation, always williamr@2: give single-pixel size lines on the screen whatever the pen size set williamr@2: by SetPenSize() and can only be used for straight lines, polylines, williamr@2: non-rounded rectangles and polygons. williamr@2: williamr@2: The dotted/dashed pattern is continued, without re-starting, for all williamr@2: consecutively drawn straight lines, i.e. williamr@2: williamr@2: the outlines of rectangles the pattern starts in the top left corner. williamr@2: It is reset at the end of the function call. williamr@2: williamr@2: the outlines of polygons the pattern starts at the first point. It is williamr@2: reset at the end of the function call. williamr@2: williamr@2: polylines and straight lines the pattern starts at the first point williamr@2: initially. Consecutive calls to DrawLine() and/or DrawPolyLine(), whether williamr@2: the lines are concatenated or not, continue the pattern. It can be reset williamr@2: by a further call to SetPenStyle() using the same dotted/dashed style williamr@2: parameter. williamr@2: williamr@2: @param aPenStyle A pen style. williamr@2: @see CGraphicsContext::TPenStyle */ williamr@2: virtual void SetPenStyle(TPenStyle aPenStyle)=0; williamr@2: williamr@2: /** Sets the line drawing size for the pen. williamr@2: williamr@2: Lines of size greater than one pixel: williamr@2: williamr@2: are drawn with rounded ends that extend beyond the end points, (as if the williamr@2: line is drawn using a circular pen tip of the specified size). williamr@2: williamr@2: are always drawn in TDrawMode::EDrawModePEN mode, overriding whatever mode williamr@2: has been set using SetDrawMode(). williamr@2: williamr@2: Notes: williamr@2: williamr@2: The pen is used to draw lines, the outlines of filled shapes, and text. The williamr@2: class provides member functions to set the colour of the pen, the style of williamr@2: line and the line size drawn. williamr@2: williamr@2: Wide straight lines and arcs have rounded ends so that concatenated wide williamr@2: lines have smoothly rounded corners at the vertexes. williamr@2: williamr@2: When lines are made wide, the extra strips of pixels are added equally to williamr@2: both sides of the line. This works precisely for lines of odd pixel size williamr@2: (3, 5, 7, etc.). Wide lines of even pixel size, (2, 4, 6, etc.), williamr@2: have the extra strip of pixels added to the right and/or below the line. williamr@2: williamr@2: Wide outlines of ellipses and wide line arcs are drawn with the pixels williamr@2: distributed either side of a thin (single pixel wide) true ellipse williamr@2: constructed in the normal manner. Wide ellipses and arcs of even pixel williamr@2: size have the extra strip of pixels added to the right and/or below the williamr@2: curved line. This gives a slight asymmetry to ellipses. williamr@2: williamr@2: If the pen style is dotted or dashed, the size specification is ignored: a williamr@2: single-pixel wide primitive is drawn, (this is device dependant). williamr@2: williamr@2: A line size of zero is handled as if the pen style had been set to williamr@2: TPenStyle::ENullPen. williamr@2: williamr@2: @param aSize A line size. The default is 1 pixel. */ williamr@2: virtual void SetPenSize(const TSize& aSize)=0; williamr@2: williamr@2: /** Sets the brush colour. williamr@2: williamr@2: The effective brush colour depends on the drawing mode. williamr@2: williamr@2: Notes: williamr@2: williamr@2: The brush is used for filling shapes and the background of text boxes. The williamr@2: brush has colour, style, pattern and pattern origin parameters. williamr@2: williamr@2: If no brush colour has been set, it defaults to white. However the default williamr@2: brush style is null, so when drawing to a window the default appears to be williamr@2: the window's background colour. williamr@2: williamr@2: @param aColor An RGB colour for the brush. williamr@2: @see SetDrawMode() */ williamr@2: virtual void SetBrushColor(const TRgb& aColor)=0; williamr@2: williamr@2: /** Sets the brush style. williamr@2: williamr@2: Ten brush styles are provided, including six built-in hatching patterns. williamr@2: Note: The brush is used for filling shapes and the background of text boxes. williamr@2: The brush has colour, style, pattern and pattern origin parameters. williamr@2: Note: Use TBrushStyle::ENullBrush to draw the outline of a fillable williamr@2: shape on its own, without filling. williamr@2: Note: If the TBrushStyle::EPatternedBrush style is set, but no bitmap williamr@2: pattern has been selected using UseBrushPattern(), then the function panics. williamr@2: Note: Hatching lines are done in the current pen colour, set using SetPenColor(). williamr@2: The hatching pattern starts at the brush origin, set using SetBrushOrigin(). williamr@2: @see TBrushStyle::ENullBrush williamr@2: @see TBrushStyle::EPatternedBrush williamr@2: @see UseBrushPattern() williamr@2: @see SetPenColor() williamr@2: @see SetBrushOrigin() williamr@2: @publishedAll williamr@2: @released williamr@2: @param aBrushStyle A brush style. */ williamr@2: virtual void SetBrushStyle(TBrushStyle aBrushStyle)=0; williamr@2: williamr@2: /** Sets the brush pattern origin. williamr@2: williamr@2: This specifies the top left-hand corner position for the pattern tile around williamr@2: which copies of the pattern are tiled. williamr@2: williamr@2: The brush pattern may be a built-in style, or a bitmap. To use a bitmap, the williamr@2: brush must have a pattern set and the brush style must be set to williamr@2: TBrushStyle::EPatternedBrush. williamr@2: williamr@2: Notes williamr@2: williamr@2: The brush is used for filling shapes and the background of text boxes. The williamr@2: brush has colour, style, pattern and pattern origin parameters. williamr@2: williamr@2: If SetBrushOrigin() is not used, then the origin defaults to (0,0). williamr@2: williamr@2: This brush origin remains in effect for all fillable shapes drawn williamr@2: subsequently, until a new brush origin is set. Shapes can thus be williamr@2: considered as windows onto a continuous pattern field (covering the whole williamr@2: clipping region of a screen device, or the whole device area of a printer). williamr@2: williamr@2: @param aOrigin An origin point for the brush. The coordinates are relative williamr@2: to the rectangle to fill, i.e. specify 0,0 to align the pattern flush with williamr@2: the top and left hand sides of the rectangle. williamr@2: @see SetBrushStyle() williamr@2: @see UseBrushPattern() */ williamr@2: virtual void SetBrushOrigin(const TPoint& aOrigin)=0; williamr@2: williamr@2: /** Sets the brush pattern to the specified bitmap. williamr@2: williamr@2: For the brush to actually use the bitmap, TBrushStyle::EPatternedBrush must williamr@2: be used to set the brush style. williamr@2: williamr@2: When the brush pattern is no longer required, use DiscardBrushPattern() to williamr@2: free up the memory used, if the bitmap is not being shared. williamr@2: If UseBrushPattern() is used again without using DiscardBrushPattern() williamr@2: then the previous pattern is discarded automatically. williamr@2: williamr@2: Notes: williamr@2: williamr@2: The brush is used for filling shapes and the background of text boxes. The williamr@2: brush has colour, style, pattern and pattern origin parameters. williamr@2: williamr@2: When loading a bitmap, the bitmap is checked to see if it is already in williamr@2: memory. If the bitmap is already there, then that copy is shared. williamr@2: williamr@2: The brush does not need to have a pattern set at all. There are several williamr@2: built-in hatching patterns which can be selected using SetBrushStyle(). williamr@2: williamr@2: @param aBitmap A bitmap pattern for the brush. williamr@2: @see SetBrushStyle() */ williamr@2: virtual void UseBrushPattern(const CFbsBitmap* aBitmap)=0; williamr@2: williamr@2: /** Discards a non-built-in brush pattern. williamr@2: williamr@2: This frees up the memory used by the bitmap, if it is not being shared by williamr@2: another process. williamr@2: williamr@2: Notes: williamr@2: williamr@2: The brush is used for filling shapes and the background of text boxes. The williamr@2: brush has colour, style, pattern and pattern origin parameters. williamr@2: williamr@2: If DiscardBrushPattern() is used, with no brush pattern set, then there is williamr@2: no effect. */ williamr@2: virtual void DiscardBrushPattern()=0; williamr@2: williamr@2: williamr@2: /** Sets the drawing point relative to the co-ordinate origin. williamr@2: williamr@2: A subsequent call to DrawLineTo() or DrawLineBy() uses the new drawing williamr@2: point as the start point for the line drawn. williamr@2: williamr@2: Notes williamr@2: williamr@2: The operations DrawLine(), DrawLineTo(), DrawLineBy() and DrawPolyline() williamr@2: also change the internal drawing position to the last point of the drawn williamr@2: line(s). williamr@2: williamr@2: The internal drawing position is set to the co-ordinate origin if no drawing williamr@2: or moving operations have yet taken place. williamr@2: williamr@2: @param aPoint The new internal drawing position. */ williamr@2: virtual void MoveTo(const TPoint& aPoint)=0; williamr@2: williamr@2: /** Sets the drawing point relative to the current co-ordinates. williamr@2: williamr@2: A subsequent call to DrawLineTo() or DrawLineBy() uses the new drawing point williamr@2: as the start point for the line drawn. williamr@2: williamr@2: Notes williamr@2: williamr@2: The operations DrawLine(), DrawLineTo(), DrawLineBy() and DrawPolyline() williamr@2: also change the internal drawing position to the last point of the drawn williamr@2: line(s). williamr@2: williamr@2: The internal drawing position is set to the co-ordinate origin if no drawing williamr@2: or moving operations have yet taken place. williamr@2: williamr@2: @param aVector The amount by which the internal drawing position is to move. */ williamr@2: virtual void MoveBy(const TPoint& aVector)=0; williamr@2: williamr@2: /** Draws a single point. The point is drawn with the current pen settings williamr@2: using the current drawing mode. williamr@2: williamr@2: Note: williamr@2: williamr@2: If the pen size is greater than one pixel, a filled circle of the current williamr@2: pen colour is drawn, with the pen size as the diameter and the plotted point williamr@2: as the centre. If the pen size is an even number of pixels, the extra pixels williamr@2: are drawn below and to the right of the centre. williamr@2: williamr@2: @param aPoint The point to be drawn. williamr@2: @see SetPenSize() */ williamr@2: virtual void Plot(const TPoint& aPoint)=0; williamr@2: williamr@2: /** Draws an arc. williamr@2: williamr@2: The arc is considered a portion of an ellipse. The ellipse is defined by the williamr@2: TRect argument. williamr@2: williamr@2: The pixels at both the start point and the end point are drawn. williamr@2: williamr@2: The arc itself is the segment of the ellipse drawn in an anti-clockwise williamr@2: direction from the start point to the end point. williamr@2: williamr@2: Notes: williamr@2: williamr@2: A rectangle is used in the construction of the ellipse of which the arc is williamr@2: a segment. This rectangle is passed as an argument of type TRect. williamr@2: williamr@2: A wide line arc is drawn with the pixels distributed either side of a true williamr@2: ellipse, in such a way that the outer edge of the line would touch the edge williamr@2: of the construction rectangle. In other words, the ellipse used to williamr@2: construct it is slightly smaller than that for a single pixel line size. williamr@2: williamr@2: If the specified start or end point is at the centre of the ellipse, then williamr@2: the line that defines the start or end of the arc defaults to one extending williamr@2: vertically above the centre point. williamr@2: williamr@2: If the start and end point are the same point or are points on the same line williamr@2: through the ellipse centre then a complete unfilled ellipse is drawn. williamr@2: williamr@2: @param aRect A rectangle in which to draw the ellipse, of which the arc is williamr@2: a segment. williamr@2: @param aStart The point defining the start of the arc. It defines one end of williamr@2: a line from the geometric centre of the ellipse. The point of intersection williamr@2: between this line and the ellipse defines the start point of the arc. williamr@2: @param aEnd The point defining the end of the arc. It defines one end of a williamr@2: second line from the geometric centre of the ellipse. The point of williamr@2: intersection between this line and the ellipse defines the end point of the williamr@2: arc. williamr@2: @see DrawEllipse() */ williamr@2: virtual void DrawArc(const TRect& aRect,const TPoint& aStart,const TPoint& aEnd)=0; williamr@2: williamr@2: /** Draws a straight line between two points. williamr@2: williamr@2: @param aPoint1 The point at the start of the line. williamr@2: @param aPoint2 The point at the end of the line. */ williamr@2: virtual void DrawLine(const TPoint& aPoint1,const TPoint& aPoint2)=0; williamr@2: williamr@2: /** Draws a straight line from the current drawing point to a specified williamr@2: point. williamr@2: williamr@2: @param aPoint The point at the end of the line. williamr@2: @see MoveTo() williamr@2: @see MoveBy() */ williamr@2: virtual void DrawLineTo(const TPoint& aPoint)=0; williamr@2: williamr@2: /** Draws a straight line relative to the current drawing point, using a williamr@2: vector. williamr@2: williamr@2: The start point of the line is the current drawing point. The specified williamr@2: vector williamr@2: is added to the drawing point to give the end point of the line williamr@2: williamr@2: @param aVector The vector to add to the current internal drawing position, williamr@2: giving the end point of the line. williamr@2: @see MoveTo() williamr@2: @see MoveBy() */ williamr@2: virtual void DrawLineBy(const TPoint& aVector)=0; williamr@2: williamr@2: /** Draws a polyline from a set of points in an array. williamr@2: williamr@2: A polyline is a series of concatenated straight lines joining a set of williamr@2: points. williamr@2: williamr@2: @param aPointList An array containing the points on the polyline. */ williamr@2: virtual void DrawPolyLine(const CArrayFix* aPointList)=0; williamr@2: williamr@2: /** Draws a polyline from a set of points in a list. williamr@2: williamr@2: A polyline is a series of concatenated straight lines joining a set of williamr@2: points. williamr@2: williamr@2: @param aPointList Pointer to a set of points on the polyline. williamr@2: @param aNumPoints Number of points in the list. */ williamr@2: virtual void DrawPolyLine(const TPoint* aPointList,TInt aNumPoints)=0; williamr@2: williamr@2: /** Draws and fills a pie slice. williamr@2: williamr@2: The pie slice is an area bounded by: williamr@2: williamr@2: the arc of an ellipse drawn in an anticlockwise direction from the start williamr@2: point to the end point williamr@2: williamr@2: the straight line drawn to the start point from the geometric centre of the williamr@2: ellipse. williamr@2: williamr@2: the straight line to the end point from the geometric centre of the ellipse. williamr@2: williamr@2: Notes: williamr@2: williamr@2: A rectangle is used in the construction of the pie slice. This rectangle is williamr@2: passed as an argument of type TRect. The curved edge of the pie slice is an williamr@2: arc of an ellipse constructed within the rectangle. williamr@2: williamr@2: The line drawn by the pen goes inside the specified rectangle. williamr@2: williamr@2: The pixels at the end point of the arc are not drawn. williamr@2: williamr@2: A wide line edged pie slice has the arc drawn with the pixels distributed williamr@2: either side of a true ellipse. This is done in such a way that the outer williamr@2: edge of the line touches the edge of the construction rectangle. In other williamr@2: words, the ellipse used to construct it is slightly smaller than that for williamr@2: a single pixel line size. williamr@2: williamr@2: If the specified start or end point is at the centre of the ellipse, then williamr@2: the line that defines the start or end of the arc defaults to one extending williamr@2: vertically above the centre point. williamr@2: williamr@2: If the start and end point are the same point or are points on the same line williamr@2: through the ellipse centre then a complete filled ellipse is drawn. A line williamr@2: is also drawn from the edge to the ellipse centre. williamr@2: williamr@2: @param aRect A rectangle in which to draw the ellipse bounding the pie slice. williamr@2: @param aStart A point defining the start of the arc bounding the pie slice. williamr@2: It defines one end of a line from the geometrical centre of the ellipse. The williamr@2: point of intersection between this line and the ellipse defines the start williamr@2: point of the arc. williamr@2: @param aEnd A point to define the end of the arc bounding the pie slice. It williamr@2: defines one end of a second line from the geometrical centre of the ellipse. williamr@2: The point of intersection between this line and the ellipse defines the end williamr@2: point of the arc. */ williamr@2: virtual void DrawPie(const TRect& aRect,const TPoint& aStart,const TPoint& aEnd)=0; williamr@2: williamr@2: /** Draws and fills an ellipse. williamr@2: williamr@2: The ellipse is drawn inside the rectangle defined by the TRect argument. Any williamr@2: rectangle that has odd pixel dimensions, has the bottom right corner trimmed williamr@2: to give even pixel dimensions before the ellipse is constructed. williamr@2: williamr@2: Note: williamr@2: williamr@2: A wide outline ellipse is drawn with the pixels distributed either side of williamr@2: a true ellipse, in such a way that the outer edge of the line touches the williamr@2: edge of the construction rectangle. In other words, the ellipse used to williamr@2: construct it is smaller than that for a single pixel line size. williamr@2: williamr@2: @param aRect The rectangle in which the ellipse is drawn. */ williamr@2: virtual void DrawEllipse(const TRect& aRect)=0; williamr@2: williamr@2: /** Draws and fills a rectangle. williamr@2: williamr@2: @param aRect The rectangle to be drawn. */ williamr@2: virtual void DrawRect(const TRect& aRect)=0; williamr@2: williamr@2: /** Draws and fills a rectangle with rounded corners. williamr@2: williamr@2: The rounded corners are each constructed as an arc of an ellipse. williamr@2: williamr@2: The line drawn by the pen, if any, goes inside the specified rectangle. williamr@2: williamr@2: Notes: williamr@2: williamr@2: Dotted and dashed pen styles cannot be used for the outline of a rounded williamr@2: rectangle. williamr@2: williamr@2: If either corner size dimension is greater than half the corresponding williamr@2: rectangle length, the corner size dimension is reduced to half the williamr@2: rectangle size. williamr@2: williamr@2: @param aRect The rectangle to be drawn. williamr@2: @param aCornerSize The dimensions of each corner. williamr@2: @see DrawArc() */ williamr@2: virtual void DrawRoundRect(const TRect& aRect,const TSize& aCornerSize)=0; williamr@2: williamr@2: /** Draws and fills a polygon defined using an array of points. williamr@2: williamr@2: The first point in the array defines the start of the first side of the williamr@2: polygon. The second point defines the second vertex (the end point of the williamr@2: first side and the start point of the second side). williamr@2: williamr@2: The final side of the polygon is drawn using the last point from the array, williamr@2: and the line is drawn to the start point of the first side. williamr@2: williamr@2: Self-crossing polygons are filled according to the specified fill rule. williamr@2: williamr@2: @param aPointList An array of points, specifying the vertices of the polygon. williamr@2: @param aFillRule The fill rule. By default, this is TFillRule::EAlternate. williamr@2: @return KErrNone, if successful; otherwise, another of the system-wide error williamr@2: codes. */ williamr@2: virtual TInt DrawPolygon(const CArrayFix* aPointList,TFillRule aFillRule=EAlternate)=0; williamr@2: williamr@2: /** Draws and fills a polygon defined using a list of points. williamr@2: williamr@2: The first point in the list defines the start of the first side of the williamr@2: polygon. The second point defines the second vertex (the end point of the williamr@2: first side and the start point of the second side). williamr@2: williamr@2: The final side of the polygon is drawn using the last point from the list, williamr@2: and the line is drawn to the start point of the first side. williamr@2: williamr@2: Self-crossing polygons are filled according to the specified fill rule. williamr@2: williamr@2: @param aPointList Pointer to list of points, specifying the vertices of the williamr@2: polygon. williamr@2: @param aNumPoints The number of points in the list. williamr@2: @param aFillRule The fill rule. By default this is TFillRule::EAlternate. williamr@2: @return KErrNone, if successful; otherwise, another of the system-wide error williamr@2: codes. */ williamr@2: virtual TInt DrawPolygon(const TPoint* aPointList,TInt aNumPoints,TFillRule aFillRule=EAlternate)=0; williamr@2: williamr@2: /** Draws a bitmap at the specified point. williamr@2: williamr@2: The point specifies the top left hand corner of the bitmap. The bitmap is williamr@2: compressed or stretched based on its internally stored size in twips. williamr@2: williamr@2: Notes: williamr@2: williamr@2: This member function uses the bitmap's size in twips and does a williamr@2: stretch/compress blit using a linear DDA. williamr@2: williamr@2: As this function scales the bitmap, it is unavoidably slow. Therefore, where williamr@2: possible, use CBitmapContext::BitBlt() instead. If the bitmap has to be williamr@2: scaled, consider creating another bitmap along with an CFbsBitmapDevice etc, williamr@2: doing DrawBitmap() once and using BitBlt() subsequently. williamr@2: williamr@2: Note that all bitmaps are clipped to the device boundaries. williamr@2: williamr@2: @param aTopLeft The point where the top left pixel of the bitmap is to be williamr@2: drawn williamr@2: @param aSource A source bitmap williamr@2: @see TLinearDDA */ williamr@2: virtual void DrawBitmap(const TPoint& aTopLeft,const CFbsBitmap* aSource)=0; williamr@2: williamr@2: /** Draws a bitmap to fit a given rectangle. williamr@2: williamr@2: The bitmap is compressed or stretched based on its internally stored size williamr@2: in pixels. williamr@2: williamr@2: Notes: williamr@2: williamr@2: This member function uses the bitmap's size in pixels and does a williamr@2: stretch/compress blit using a linear DDA. williamr@2: williamr@2: As this function scales the bitmap, it is unavoidably slow. Therefore, williamr@2: where possible, use CBitmapContext::BitBlt() instead. If the bitmap has williamr@2: to be scaled, consider creating another bitmap along with an williamr@2: CFbsBitmapDevice etc., doing DrawBitmap() once and using BitBlt() williamr@2: subsequently. williamr@2: williamr@2: Note that all bitmaps are clipped to the device boundaries. williamr@2: williamr@2: @param aDestRect The rectangle within which the bitmap is to be drawn. williamr@2: @param aSource A source bitmap. williamr@2: @see TLinearDDA */ williamr@2: virtual void DrawBitmap(const TRect& aDestRect,const CFbsBitmap* aSource)=0; williamr@2: williamr@2: /** Draws a specified rectangle of a source bitmap to fit into a given williamr@2: destination rectangle. williamr@2: williamr@2: Notes: williamr@2: williamr@2: This member function uses rectangle sizes in pixels and does a williamr@2: stretch/compress blit using a linear DDA. williamr@2: williamr@2: As this function scales the bitmap, it is unavoidably slow. Therefore, williamr@2: where possible, use CBitmapContext::BitBlt() instead. If the bitmap has williamr@2: to be scaled, consider creating another bitmap along with an williamr@2: CFbsBitmapDevice etc., doing DrawBitmap() once and using BitBlt() williamr@2: subsequently. williamr@2: williamr@2: Note that all bitmaps are clipped to the device boundaries. williamr@2: williamr@2: @param aDestRect The rectangle within which the bitmap is to be drawn. williamr@2: @param aSource A source bitmap. williamr@2: @param aSourceRect The rectangle in the source bitmap that is copied to the williamr@2: destination rectangle. williamr@2: @see TLinearDDA */ williamr@2: virtual void DrawBitmap(const TRect& aDestRect,const CFbsBitmap* aSource,const TRect& aSourceRect)=0; williamr@2: williamr@2: /** Draws a specified rectangle of a source bitmap to fit into a given rectangle using a given mask. williamr@2: williamr@2: Notes: williamr@2: williamr@2: This member function uses rectangle sizes in pixels and does a williamr@2: stretch/compress blit using a linear DDA. williamr@2: williamr@2: williamr@2: @param aDestRect The rectangle within which the bitmap is to be drawn. williamr@2: @param aBitmap The source bitmap williamr@2: @param aSourceRect The rectangle in the source bitmap that is to be drawn williamr@2: @param aMaskBitmap The mask to be applied to the source bitmap while drawing williamr@2: @param aInvertMask Flag to indicate if the mask should be inverted. williamr@2: */ williamr@2: virtual void DrawBitmapMasked(const TRect& aDestRect,const CFbsBitmap* aBitmap,const TRect& aSourceRect,const CFbsBitmap* aMaskBitmap,TBool aInvertMask)=0; williamr@2: williamr@2: /** Draws a specified rectangle from a wserv bitmap and its mask into williamr@2: another rectangle. williamr@2: williamr@2: The function compresses/stretches the specified rectangle from the bitmap williamr@2: to fit the destination rectangle. williamr@2: The mask bitmap can be used as either a positive or negative mask. Masked williamr@2: pixels are not mapped to the destination rectangle. williamr@2: williamr@2: A black and white (binary) mask bitmap is used. With aInvertMask=EFalse, black williamr@2: pixels in the mask bitmap stop corresponding pixels in the source bitmap from williamr@2: being transferred to the destination rectangle. With aInvertMask=ETrue, white williamr@2: pixels in the mask bitmap stop corresponding pixels in the source bitmap from williamr@2: being transferred to the destination rectangle. williamr@2: williamr@2: Note: this member function uses rectangle sizes in pixels and does a stretch/compress williamr@2: blit using a linear DDA. williamr@2: williamr@2: @param aDestRect The rectangle within which the masked bitmap is to be drawn. williamr@2: @param aBitmap A source wserv bitmap. williamr@2: @param aSourceRect The rectangle in the source bitmap that is copied to the williamr@2: destination rectangle. williamr@2: @param aMaskBitmap A mask wserv bitmap. williamr@2: @param aInvertMask If false, a source pixel that is masked by a black pixel williamr@2: is not transferred to the destination rectangle. If true, then a source pixel williamr@2: that is masked by a white pixel is not transferred to the destination rectangle. */ williamr@2: virtual void DrawBitmapMasked(const TRect& aDestRect,const CWsBitmap* aBitmap,const TRect& aSourceRect,const CWsBitmap* aMaskBitmap,TBool aInvertMask)=0; williamr@2: williamr@2: /** Draws text without a surrounding box. williamr@2: williamr@2: The text baseline is aligned with the y co-ordinate of the specified point, williamr@2: and the left end of the text is aligned with the x co-ordinate of the williamr@2: specified point. williamr@2: williamr@2: Note: williamr@2: williamr@2: Text drawing is done with the pen, and is subject to the pen colour. The williamr@2: effective text colour also depends on the drawing mode. The size and style williamr@2: of the text depends on the font used. The layout of the text depends on the williamr@2: justification mode set. williamr@2: williamr@2: @param aText The text string to be drawn. williamr@2: @param aPosition A point specifying the position of the left end of the text. */ williamr@2: virtual void DrawText(const TDesC& aText,const TPoint& aPosition) = 0; williamr@2: williamr@2: /** Draws text inside a box. williamr@2: williamr@2: The surrounding box is filled with the current brush colour (not a pattern) williamr@2: and is drawn without any outline. The effective box colour depends on the williamr@2: drawing mode - if a brush colour has not been set then the brush defaults williamr@2: to white. The brush may be set to TBrushStyle::ENullBrush if text williamr@2: positioning relative to a box is required, but the box should not be filled. williamr@2: williamr@2: The font used is that set by UseFont(). If no font is in use then a panic williamr@2: occurs. williamr@2: williamr@2: The alignment of the text within the box can be specified. williamr@2: williamr@2: Text drawn within a box is also clipped to that box. Unless you intend to williamr@2: clip the top off the text, aBaselineOffset should be greater than or equal williamr@2: to the ascent of the current font. williamr@2: williamr@2: Offsets: williamr@2: williamr@2: If the offset is negative, zero, or less than font height this is handled williamr@2: as would be expected, i.e. no text will be seen in the box in the first two williamr@2: instances, and the top of the text will be clipped in the latter case. williamr@2: williamr@2: Margins: williamr@2: williamr@2: For the drawing of right-aligned text, aLeftMargin indicates the margin from williamr@2: the right of aBox - where a positive value results in a leftwards offset. williamr@2: williamr@2: Negative margins can be used to display portions of the text string clipped williamr@2: by the box. A negative margin for left aligned text would clip the start of williamr@2: the text string. Similarly, a negative margin for right aligned text would williamr@2: clip the end of the text string. williamr@2: williamr@2: If the margin is greater than the width of the box then no text will be williamr@2: visible. williamr@2: williamr@2: The margin is still honoured for centred text - centred text will not be williamr@2: centred in the box, unless the margin is zero. williamr@2: williamr@2: Note: williamr@2: williamr@2: Text drawing is done with the pen, and is thus subject to the pen colour. williamr@2: The effective text colour also depends on the drawing mode. The size and williamr@2: style of the text depends on the used font. The layout of the text depends williamr@2: on the justification mode set. williamr@2: williamr@2: @param aText The text string to be drawn. williamr@2: @param aBox The box to draw the text in. williamr@2: @param aBaselineOffset An offset from the top of the box to the text williamr@2: baseline. williamr@2: @param aAlignment The text alignment mode default is left aligned. williamr@2: @param aLeftMargin The left margin for left-aligned text, or the right williamr@2: margin williamr@2: for right-aligned text default is zero. */ williamr@2: virtual void DrawText(const TDesC& aText,const TRect& aBox,TInt aBaselineOffset,TTextAlign aAlignment = ELeft, williamr@2: TInt aLeftMargin = 0) = 0; williamr@2: IMPORT_C virtual void DrawText(const TDesC& aText,const TPoint& aPosition,const TDrawTextParam& aParam); williamr@2: IMPORT_C virtual void Reserved(); williamr@2: IMPORT_C TInt DrawTextExtended(const TDesC& aText,const TPoint& aPosition,const TDrawTextExtendedParam& aParam); williamr@2: williamr@2: /** Maps pixels in the specified rectangle. williamr@2: The function tries to match the colour of a pixel with one of the RGB values williamr@2: in an array of RGB pairs. If there is a match, the colour is changed to the williamr@2: value specified in the other RGB in the RGB pair. williamr@2: @param aRect The rectangle in which pixels are to be mapped. williamr@2: @param aColors A pointer to a set of RGB pairs. williamr@2: @param aNumPairs The number of pairs williamr@2: @param aMapForwards ETrue, mapping is done from the first RGB to the second williamr@2: RGB in the pair; EFalse, mapping is done from the second RGB to the first williamr@2: RGB in the pair. */ williamr@2: virtual void MapColors(const TRect &aRect,const TRgb *aColors,TInt aNumPairs,TBool aMapForwards) = 0; williamr@2: williamr@4: /** Sets the clipping region, any items that fall outside the extent of the clipping williamr@4: region will not be drawn. williamr@4: williamr@4: Note that clipping is additive. If a clipping rectangle has been set using SetClippingRect() williamr@4: then clipping will be to the intersection of that rectangle and this region. williamr@4: williamr@4: @param aRegion The new clipping region. Note that clipping region co-ordinates are williamr@4: used as absolute co-ordinates, they are not transformed by the current co-ordinate williamr@4: origin before use (as occurs in SetClippingRect()). williamr@4: williamr@2: @return KErrNone if successful; KErrArgument if the TRegion is not valid; KErrNoMemory if there is insufficient memory. williamr@4: williamr@4: @see CGraphicsContext::CancelClippingRegion() williamr@4: @see CGraphicsContext::SetClippingRect() */ williamr@2: virtual TInt SetClippingRegion(const TRegion &aRegion) = 0; williamr@2: williamr@2: /** Cancels the current clipping region. williamr@2: @see CGraphicsContext::SetClippingRegion()*/ williamr@2: virtual void CancelClippingRegion() = 0; williamr@2: williamr@2: /** Draws vertical text in the specified direction. williamr@2: @param aText The text to be drawn. williamr@2: @param aPos Point of origin of the text baseline. williamr@2: @param aUp Direction. ETrue for up, EFalse for down. */ williamr@2: virtual void DrawTextVertical(const TDesC& aText,const TPoint& aPos,TBool aUp) = 0; williamr@2: williamr@2: /** Draws text vertically in the specified direction, within a box of the specified size. williamr@2: @param aText The text to be drawn. williamr@2: @param aBox The bounding box within which the text should be drawn, and which it is clipped to. williamr@2: @param aBaselineOffset The height of the top of the characters from their text baseline. williamr@2: @param aUp The direction. ETrue for up, EFalse for down. williamr@2: @param aVert The text alignment. williamr@2: @param aMargin The margin. */ williamr@2: virtual void DrawTextVertical(const TDesC& aText,const TRect& aBox,TInt aBaselineOffset,TBool aUp,TTextAlign aVert=ELeft,TInt aMargin=0) = 0; williamr@2: williamr@2: IMPORT_C TInt GetUnderlineMetrics(TInt& aTop,TInt& aBottom); williamr@2: williamr@2: /** Set the font's shadow colour williamr@2: @param aShadowColor Shadow colour to be set. williamr@2: @return KErrNone, if successful; otherwise, another of the system-wide errors. */ williamr@2: IMPORT_C TInt SetShadowColor(const TRgb& aShadowColor); williamr@2: williamr@2: /** Get the font's shadow colour williamr@2: @param aShadowColor Shadow colour of the font returned by the funtion. williamr@2: @return KErrNone, if successful; otherwise, another of the system-wide errors. */ williamr@2: IMPORT_C TInt GetShadowColor(TRgb& aShadowColor); williamr@4: williamr@2: /** Determine if the Gc is a CFbsBitGc williamr@2: @return ETrue, if the Gc is a CFbsBitGc, EFalse otherwise williamr@4: @publishedAll williamr@4: WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. williamr@2: */ williamr@2: IMPORT_C TBool IsFbsBitGc() const; williamr@4: williamr@4: IMPORT_C void DrawText(const TDesC& aText,const TTextParameters* iParam,const TPoint& aPosition); williamr@4: IMPORT_C void DrawText(const TDesC& aText,const TTextParameters* iParam,const TRect& aBox,TInt aBaselineOffset,TTextAlign aHrz=ELeft,TInt aMargin=0); williamr@4: IMPORT_C void DrawText(const TDesC& aText,const TTextParameters* iParam,const TPoint& aPosition,const TDrawTextParam& aParam); williamr@4: williamr@4: IMPORT_C void DrawTextVertical(const TDesC& aText,const TTextParameters* iParam,const TPoint& aPos,TBool aUp); williamr@4: IMPORT_C void DrawTextVertical(const TDesC& aText,const TTextParameters* iParam,const TRect& aBox,TInt aBaselineOffset,TBool aUp,TTextAlign aVert=ELeft,TInt aMargin=0); williamr@4: williamr@4: IMPORT_C TInt DrawTextExtended(const TDesC& aText,const TTextParameters* iParam,const TPoint& aPosition,const TDrawTextExtendedParam& aParam); williamr@2: williamr@2: protected: williamr@4: williamr@2: /** williamr@2: An APIExtension method to allow the addition of new APIs to retain compatibility williamr@2: with previous versions of gdi.dll williamr@2: @param aOutput is for output williamr@2: @param aInput is for input williamr@2: @see CGraphicsContext williamr@4: @publishedAll williamr@4: WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. williamr@2: */ williamr@2: IMPORT_C virtual TInt APIExtension(TUid aUid, TAny*& aOutput, TAny* aInput); williamr@2: williamr@2: /** williamr@2: A reserved virtual function for future use. williamr@2: */ williamr@2: IMPORT_C virtual void Reserved_CGraphicsContext_2(); williamr@2: }; williamr@2: williamr@2: williamr@2: /** An abstract, device-independent, interface to bitmapped graphics contexts. williamr@2: williamr@2: This holds the setting used to draw to a CBitmapDevice. williamr@2: williamr@2: The default settings of a CBitmapContext object immediately after construction williamr@2: are: williamr@2: williamr@2: drawing mode is EDrawModePen (pen and brush colours used as they are) williamr@2: williamr@2: no clipping rectangle williamr@2: williamr@2: pen settings are: black, solid, single pixel width williamr@2: williamr@2: brush style is null williamr@2: williamr@2: no text font selected williamr@2: williamr@2: The classes CFbsBitGc and CWindowGc are derived from this class. williamr@2: williamr@2: @see CFbsBitGc williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CBitmapContext : public CGraphicsContext williamr@2: { williamr@2: public: williamr@2: /** Clears the whole bitmap. williamr@2: williamr@2: The cleared area is filled with the current brush colour. williamr@2: williamr@2: This pure virtual function is implemented in derived classes. */ williamr@2: virtual void Clear()=0; williamr@2: williamr@2: /** Clears a rectangular area of a bitmap. williamr@2: williamr@2: The cleared area is filled with the current brush colour. williamr@2: williamr@2: This pure virtual function is implemented in derived classes. williamr@2: williamr@2: @param aRect The rectangle to clear. */ williamr@2: virtual void Clear(const TRect& aRect)=0; williamr@2: williamr@2: /** Copies a rectangle. williamr@2: williamr@2: This pure virtual function is implemented in derived classes. williamr@2: williamr@2: @param aOffset The offset from the top left corner of the rectangle to be williamr@2: copied to the top left corner of the copy. williamr@2: @param aRect The rectangular area to be copied. */ williamr@2: virtual void CopyRect(const TPoint& aOffset,const TRect& aRect)=0; williamr@2: williamr@2: /** Performs a bitmap block transfer. williamr@2: williamr@2: This pure virtual function is implemented in derived classes. williamr@2: williamr@2: @param aPoint The destination for the top left corner of the transferred bitmap. williamr@2: It is relative to the top left corner of the destination bitmap, which may be the screen. williamr@2: @param aBitmap A memory-resident bitmap. */ williamr@2: virtual void BitBlt(const TPoint& aPoint,const CFbsBitmap* aBitmap)=0; williamr@2: williamr@2: /** Performs a bitmap block transfer of a rectangular piece of a bitmap. williamr@2: williamr@2: If the specified rectangle is larger than the bitmap then the bitmap is williamr@2: padded with white. williamr@2: williamr@2: This pure virtual function is implemented in derived classes. williamr@2: williamr@2: @param aPoint The destination for the top left corner of the transferred bitmap. williamr@2: It is relative to the top left corner of the destination bitmap, which may be the screen. williamr@2: williamr@2: @param aBitmap A memory-resident bitmap williamr@2: @param aRect A rectangle defining the portion of the bitmap to transfer. williamr@2: Its coordinates are relative to the top left corner of the source bitmap. */ williamr@2: virtual void BitBlt(const TPoint& aPoint,const CFbsBitmap* aBitmap,const TRect& aRect)=0; williamr@2: williamr@2: /** Performs a masked bitmap block transfer. williamr@2: williamr@2: The mask bitmap can be used as either a positive or negative mask. Masked williamr@2: pixels are not mapped to the destination rectangle. williamr@2: williamr@2: This function uses either a black and white (binary) mask bitmap, or if williamr@2: aMaskBitmap's display mode is EGray256, alpha blending is used. Use of williamr@2: any other mode may result in unpredictable results williamr@2: williamr@2: With aInvertMask=EFalse, black pixels in the mask bitmap stop corresponding williamr@2: pixels in the source bitmap from being transferred to the destination rectangle. williamr@2: With aInvertMask=ETrue, white pixels in the mask bitmap stop corresponding williamr@2: pixels in the source bitmap from being transferred to the destination williamr@2: rectangle. williamr@2: williamr@2: Note that if the mask bitmap is smaller than the source bitmap, then it is williamr@2: tiled across the bitmap. Note that the mask is applied before the piece of williamr@2: the bitmap is defined - the mask is tiled relative to the top left of the williamr@2: original source bitmap rather than the top left of the bitmap piece. williamr@2: williamr@2: This pure virtual function is implemented in derived classes. williamr@2: williamr@2: @param aPoint The destination for the top left corner of the transferred bitmap. williamr@2: It is relative to the top left corner of the destination bitmap, which may be the screen. williamr@2: @param aBitmap A memory-resident source bitmap. williamr@2: @param aSourceRect A rectangle defining the piece of the bitmap to be drawn, williamr@2: with co-ordinates relative to the top left corner of the bitmap. williamr@2: @param aMaskBitmap A mask bitmap williamr@2: @param aInvertMask If EFalse, a source pixel that is masked by a black pixel williamr@2: is not transferred to the destination rectangle. If ETrue, then a source williamr@2: pixel that is masked by a white pixel is not transferred to the destination williamr@2: rectangle. */ williamr@2: virtual void BitBltMasked(const TPoint& aPoint,const CFbsBitmap* aBitmap,const TRect& aSourceRect,const CFbsBitmap* aMaskBitmap,TBool aInvertMask)=0; williamr@2: williamr@2: /** Sets whether the graphics context is faded. williamr@2: williamr@2: @param aFaded ETrue to fade the GC; EFalse to unfade it. */ williamr@2: virtual void SetFaded(TBool aFaded)=0; williamr@2: williamr@2: /** Sets the fading parameters. williamr@2: williamr@2: This function allows you to override the map used when drawing with a faded williamr@2: graphics context (GC). However if you draw to a faded window with a faded williamr@2: GC, then fading on the GC is ignored and the fading of the window is used. williamr@2: williamr@2: Fading is used to change the colour of a window to make other windows stand williamr@2: out. Fading can either make a faded window closer to white or closer to williamr@2: black. williamr@2: williamr@2: Fading re-maps colours in the faded GC to fall between the specified black williamr@2: and white map values. If aBlackMap=0 and aWhiteMap=255 then the colours are williamr@2: mapped unchanged. As the values converge the colours are mapped to a smaller williamr@2: range - so the differences between colours in the faded GC decrease. If williamr@2: the values are reversed then the colours are inverted (i.e. where the GC williamr@2: would be black, it is now white). williamr@2: williamr@2: @param aBlackMap Black map fading parameter. Unfaded this is 0. williamr@2: @param aWhiteMap White map fading parameter. Unfaded this is 255. */ williamr@2: virtual void SetFadingParameters(TUint8 aBlackMap,TUint8 aWhiteMap)=0; williamr@2: williamr@2: /** williamr@2: Performs an alpha blending of the source data, aSrcBmp, with the CBitmapContext, using williamr@2: the data from aAlphaBmp as an alpha blending factor. williamr@2: The formula used is: williamr@2: (S * A + W * (255 - A)) / 255, where: williamr@2: - S - a pixel from aSrcBmp; williamr@2: - W - a pixel from the window; williamr@2: - A - a pixel from aAlphaBmp; williamr@2: The contents of source and alpha bitmap are preserved. williamr@2: The calculated alpha blended pixels are written to the destination CBitmapContext. williamr@2: @param aDestPt Position in the target the result should be drawn to. williamr@2: @param aSrcBmp A pointer to the source bitmap. williamr@2: @param aSrcRect The part of the source bitmap that should be used. williamr@2: @param aAlphaBmp A pointer to the bitmap used as an alpha blending factor. williamr@2: @param aAlphaPt Position of the first pixel in the alpha bitmap that should be used as a source williamr@2: for the alpha blending. The size of the area is the same as the williamr@4: source bitmap area - aSrcRect parameter.*/ williamr@2: williamr@2: virtual TInt AlphaBlendBitmaps(const TPoint& aDestPt, const CFbsBitmap* aSrcBmp, const TRect& aSrcRect, const CFbsBitmap* aAlphaBmp, const TPoint& aAlphaPt) = 0; williamr@2: williamr@2: /** williamr@2: The method performs an alpha blending of the source data, aSrcBmp, with the CBitmapContext, using williamr@2: the data from aAlphaBmp as an alpha blending factor. williamr@2: For information on how this function works, see the other overload. williamr@2: @param aDestPt Position in the target the result should be drawn to. williamr@2: @param aSrcBmp A pointer to the source bitmap. williamr@2: @param aSrcRect The part of the source bitmap that should be used. williamr@2: @param aAlphaBmp A pointer to the bitmap used as an alpha blending factor. williamr@2: @param aAlphaPt Position of the first pixel in the alpha bitmap that should be used as a source williamr@2: for the alpha blending. The size of the area is the same as the williamr@4: source bitmap area - aSrcRect parameter.*/ williamr@2: virtual TInt AlphaBlendBitmaps(const TPoint& aDestPt, const CWsBitmap* aSrcBmp, const TRect& aSrcRect, const CWsBitmap* aAlphaBmp, const TPoint& aAlphaPt) = 0; williamr@2: williamr@2: protected: williamr@2: williamr@2: /* williamr@2: Implementations from CGraphicsContext williamr@2: @see CGraphicsContext::APIExtension(TUid, TAny*&, TAny*) williamr@2: */ williamr@2: IMPORT_C TInt APIExtension(TUid aUid, TAny*& aOutput, TAny* aInput); williamr@2: /* williamr@2: Implementations from CGraphicsContext williamr@2: @see CGraphicsContext::Reserved_CGraphicsContext_2() williamr@2: */ williamr@2: IMPORT_C void Reserved_CGraphicsContext_2(); williamr@2: williamr@2: IMPORT_C virtual void Reserved_CBitmapContext_1(); williamr@2: IMPORT_C virtual void Reserved_CBitmapContext_2(); williamr@2: IMPORT_C virtual void Reserved_CBitmapContext_3(); williamr@2: }; williamr@2: williamr@2: /** Defines an abstract interface for the capabilities and attributes of a williamr@2: bitmapped graphics device. williamr@2: williamr@2: The class specialises the graphics device interface CGraphicsDevice for bitmaps williamr@2: graphics. The Window Server Client-Side API provides one implementation of williamr@2: the interface, CWsScreenDevice, for screen drawing. Another implementation, williamr@2: CFbsBitmapDevice, is used for drawing to in-memory bitmaps. A third, williamr@2: CFbsScreenDevice, is used (rarely) to access the screen directly, without the williamr@2: mediation of the window server. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CBitmapDevice : public CGraphicsDevice williamr@2: { williamr@2: public: williamr@2: /** Gets the RGB colour of an individual pixel on a bitmapped graphics williamr@2: device. williamr@2: williamr@2: This pure virtual function is implemented in derived classes. williamr@2: williamr@2: @param aColor On return, should contain the RGB colour of the pixel. williamr@2: @param aPixel The (x,y) co-ordinates of the pixel. The top left pixel is williamr@2: (0,0). */ williamr@2: virtual void GetPixel(TRgb& aColor,const TPoint& aPixel) const=0; williamr@2: williamr@2: /** Copies a scanline into a buffer. williamr@2: williamr@2: The pixels are converted from the display mode format on the bitmapped williamr@2: graphics device to the format of the specified device display mode. williamr@2: williamr@2: By specifying the start pixel and the number of pixels, either the whole or williamr@2: a portion of a bitmapped graphics device pixel row may be copied. williamr@2: williamr@2: This pure virtual function is implemented in derived classes. williamr@2: williamr@2: @param aBuf An 8 bit modifiable descriptor buffer into which pixels are williamr@2: copied; it must be sufficiently large to store all the scanline pixels. williamr@2: @param aStartPixel The (x,y) co-ordinates of the first pixel of the bitmap williamr@2: scanline to be put into the buffer. williamr@2: @param aLength The number of pixels to put into the buffer. williamr@2: @param aDispMode The display mode into which to convert the pixels. */ williamr@2: virtual void GetScanLine(TDes8& aBuf,const TPoint& aStartPixel,TInt aLength,TDisplayMode aDispMode) const=0; williamr@2: williamr@2: /** Adds a font file to the device's typeface store. The specified font williamr@2: file must be accessible to any process, i.e. not located inside an williamr@2: application's private directory. williamr@2: williamr@2: This pure virtual function is implemented in derived classes. williamr@2: williamr@2: @param aName The name of the font file. williamr@2: @param aId On return, contains an ID for the font file. williamr@2: @return KErrNone, if successful; otherwise, another of the system-wide error williamr@2: codes. */ williamr@2: virtual TInt AddFile(const TDesC& aName,TInt& aId)=0; williamr@2: williamr@2: /** Removes a font file from the font store. williamr@2: williamr@2: This pure virtual function is implemented in derived classes. williamr@2: williamr@2: @param aId The ID of the font file to be removed. The default is 0. */ williamr@2: virtual void RemoveFile(TInt aId=0)=0; williamr@2: williamr@2: /** williamr@2: Gets the font which is the nearest to the given font specification. williamr@2: williamr@2: When the font is no longer needed, call @c ReleaseFont(). williamr@2: williamr@2: Note that this deprecated function is replaced by the new @c GetNearestFontToDesignHeightInPixels() williamr@2: yielding (virtually) the same result. However clients are strongly encouraged to use the new williamr@2: @c GetNearestFontToMaxHeightInPixels() function instead. This will guarantee that every williamr@2: character within any given text string will fit within the given amount of pixels, whereas the design williamr@2: height is an aesthetic unit decided by the font designer without strict physical meaning, which williamr@2: may result in cropped characters. williamr@2: williamr@2: @param aFont On return, contains a pointer to the nearest font. williamr@2: @param aFontSpec The specification of the font to be matched. williamr@2: @return KErrNone if successful; a system-wide error code otherwise. williamr@2: @publishedAll williamr@2: @deprecated Use GetNearestFontToDesignHeightInPixels williamr@2: */ williamr@2: virtual TInt GetNearestFontInPixels(CFont*& aFont, const TFontSpec& aFontSpec) = 0; williamr@2: williamr@2: /** williamr@2: Gets the font which is the nearest to the given font specification. williamr@2: williamr@2: When the font is no longer needed, call @c ReleaseFont(). williamr@2: williamr@2: This new function replaces the deprecated @c GetNearestFontInPixels() yielding (virtually) the williamr@2: same result. However clients are strongly encouraged to use the new williamr@2: @c GetNearestFontToMaxHeightInPixels() function instead. This will guarantee that every williamr@2: character within any given text string will fit within the given amount of pixels, whereas the design williamr@2: height is an aesthetic unit decided by the font designer without strict physical meaning, which williamr@2: may result in cropped characters. williamr@2: williamr@2: @param aFont On return, contains a pointer to the nearest font. williamr@2: @param aFontSpec The specification of the font to be matched. williamr@2: @return KErrNone if successful; a system-wide error code otherwise. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: virtual TInt GetNearestFontToDesignHeightInPixels( williamr@2: CFont*& /*aFont*/, const TFontSpec& /*aFontSpec*/) { return KErrNotSupported; } williamr@2: williamr@2: /** williamr@2: Gets the font which is the nearest to the given font specification. williamr@2: williamr@2: When the font is no longer needed, call @c ReleaseFont(). williamr@2: williamr@2: The font and bitmap server returns a pointer to the nearest matching font williamr@2: from those available. Matches to max height of font - this does its best williamr@2: to return a font that will fit within the maximum height specified (but williamr@2: note that variations due to hinting algorithms may rarely result in this williamr@2: height being exceeded by up to one pixel). Problems can also be williamr@2: encountered with bitmap fonts where the typeface exists but doesn't have williamr@2: a font small enough. williamr@2: williamr@2: @param aFont On return, contains a pointer to the nearest font. williamr@2: @param aFontSpec The specification of the font to be matched. williamr@2: @param aMaxHeight The maximum height within which the font must fit. williamr@2: This overrides the height specified in aFontSpec. williamr@2: @return KErrNone if successful; a system-wide error code otherwise. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: virtual TInt GetNearestFontToMaxHeightInPixels( williamr@2: CFont*& /*aFont*/, const TFontSpec& /*aFontSpec*/, TInt /*aMaxHeight*/) { return KErrNotSupported; } williamr@2: williamr@2: /** Gets the height, in pixels, of the specified typeface at one of its williamr@2: defined heights. williamr@2: williamr@2: The typeface is identified by by an index. For a given typeface, there are williamr@2: a discrete number of heights; the specific height is also identified by an williamr@2: index. williamr@2: williamr@2: The value returned is rounded up or down to the nearest font height in williamr@2: pixels. williamr@2: williamr@2: This pure virtual function is implemented in derived classes. williamr@2: williamr@2: @param aTypefaceIndex A typeface index number, in the range: 0 to williamr@2: (NumTypefaces() - 1). williamr@2: @param aHeightIndex A font height index number, in the range: 0 to williamr@2: (iNumHeights - 1) where iNumHeights is a public data member of the williamr@2: TTypefaceSupport object returned by TypefaceSupport(). williamr@2: @return The height of the font, in pixels. williamr@2: @see TTypefaceSupport williamr@2: @see CGraphicsDevice::NumTypefaces() williamr@2: @see CGraphicsDevice::TypefaceSupport() */ williamr@2: virtual TInt FontHeightInPixels(TInt aTypefaceIndex,TInt aHeightIndex) const=0; williamr@2: inline TInt CreateBitmapContext(CBitmapContext*& aGC); williamr@2: }; williamr@2: williamr@2: /** A set of margins used for cropping a picture. williamr@2: williamr@2: Margins are specified in twips or pixels. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TMargins williamr@2: { williamr@2: public: williamr@2: IMPORT_C void InternalizeL(RReadStream& aStream); williamr@2: IMPORT_C void ExternalizeL(RWriteStream& aStream) const; williamr@2: IMPORT_C TBool operator==(const TMargins& aMargins) const; williamr@2: IMPORT_C TBool operator!=(const TMargins& aMargins) const; williamr@2: public: williamr@2: /** Left margin, (in twips or pixels). */ williamr@2: TInt iLeft; williamr@2: /** Right margin, (in twips or pixels). */ williamr@2: TInt iRight; williamr@2: /** Top margin, (in twips or pixels). */ williamr@2: TInt iTop; williamr@2: /** Bottom margin, (in twips or pixels). */ williamr@2: TInt iBottom; williamr@2: }; williamr@2: williamr@2: /** Picture capabilities. williamr@2: williamr@2: These include the types of scaling that can be applied to a picture, and whether williamr@2: or not it is croppable. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TPictureCapability williamr@2: { williamr@2: public: williamr@2: /** Scaling types. */ williamr@2: enum TScalingType williamr@2: { williamr@2: /** The picture is not scalable. */ williamr@2: ENotScaleable, williamr@2: /** The picture is fully scalable. */ williamr@2: EFullyScaleable, williamr@2: /** The picture is scalable to any size, as long as its aspect ratio williamr@2: (the ratio of its height to its width) remains constant. */ williamr@2: EScaleableMaintainingAspectRatio williamr@2: }; williamr@2: public: williamr@2: inline TPictureCapability(TScalingType aScalingType,TBool aCroppable); williamr@2: public: williamr@2: /** Whether or not the picture is croppable. */ williamr@2: TScalingType iScalingType; williamr@2: /** Scaling type. */ williamr@2: TBool iIsCroppable; williamr@2: }; williamr@2: williamr@2: /** Abstract base class for: drawing a picture to a graphics context, storing williamr@2: and restoring the picture. williamr@2: williamr@2: The class defines the protocol for a number of concrete picture classes. Its williamr@2: main role is to support glass doors used in object embedding. williamr@2: williamr@2: The class provides a protocol for the provision of scaling and cropping williamr@2: functions by derived classes, together with default implementations. williamr@2: williamr@2: Its main function is Draw(), which draws the picture onto the graphics context williamr@2: at a particular point. It also has two important pure virtual functions: williamr@2: ExternalizeL() and GetOriginalSizeInTwips(). williamr@2: williamr@2: A picture has both an original representation and an on-screen representation. williamr@2: The original representation has a size in twips, and can somehow be drawn. williamr@2: The on-screen representation is assumed to be drawn under the control of an williamr@2: application which may wish to re-size or scale the original in some way, to williamr@2: crop it at the edges, and/or to ensure it fits within a particular defined williamr@2: area on the screen. williamr@2: williamr@2: The class provides several functions that allow an application to set scaling williamr@2: and cropping before invoking the Draw() function to draw the picture on-screen. williamr@2: It is up to the internal workings of the function to determine the order of williamr@2: application cropping and scaling. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CPicture : public CBase williamr@2: { williamr@2: public: williamr@2: /** Options for detaching pictures from stores. Used by DetachFromStoreL(). */ williamr@2: enum TDetach williamr@2: { williamr@2: /** Internalise all data that is required to fully store the picture williamr@2: later; null any references to containing stores. */ williamr@2: EDetachFull, williamr@2: /** Internalise enough information to draw the picture (and no more); williamr@2: null any references to containing stores. */ williamr@2: EDetachDraw williamr@2: }; williamr@2: public: williamr@2: IMPORT_C virtual ~CPicture(); williamr@2: /** Draws a picture. williamr@2: williamr@2: @param aGc The graphics context. williamr@2: @param aTopLeft The co-ordinates where the top left corner pixel of the williamr@2: picture should be placed. Note that whether this is actually drawn depends williamr@2: on the clipping area defined. williamr@2: @param aClipRect A clipping rectangle that defines the area to which the williamr@2: function should draw. An implementation should never draw outside this williamr@2: rectangle. Note that the graphics context may also have a clipping rectangle williamr@2: set on it. williamr@2: @param aMap The device map for the graphics device. The implementation williamr@2: should use this to find the scaling to apply to the picture. */ williamr@2: virtual void Draw(CGraphicsContext& aGc,const TPoint& aTopLeft,const TRect& aClipRect,MGraphicsDeviceMap* aMap) const=0; williamr@2: IMPORT_C virtual TStreamId StoreL(CStreamStore& aStore) const; // assumes no sub streams williamr@2: virtual void DetachFromStoreL(TDetach /*aDegree*/=EDetachFull) {} williamr@2: williamr@2: /** Externalises the picture to a stream. williamr@2: williamr@2: The presence of this function means that the standard templated stream williamr@2: operator<<() is available to externalise objects of this class. williamr@2: williamr@2: A derived class must supply an implementation of this function. williamr@2: williamr@2: @param aStream The write stream. */ williamr@2: virtual void ExternalizeL(RWriteStream& aStream) const =0; williamr@2: williamr@2: /** Gets the pictur's original size, in twips. williamr@2: williamr@2: @param aSize The size of the picture, in twips */ williamr@2: virtual void GetOriginalSizeInTwips(TSize& aSize) const =0; williamr@2: IMPORT_C virtual void SetScaleFactor(TInt aScaleFactorWidth,TInt aScaleFactorHeight); // does nothing williamr@2: IMPORT_C virtual void SetCropInTwips(const TMargins& aMargins); // does nothing williamr@2: IMPORT_C virtual TPictureCapability Capability() const; // no scale, no crop williamr@2: IMPORT_C virtual void GetCropInTwips(TMargins& aMargins) const; // returns no crop williamr@2: IMPORT_C virtual TInt ScaleFactorWidth() const; // returns no scaling williamr@2: IMPORT_C virtual TInt ScaleFactorHeight() const; // returns no scaling williamr@2: IMPORT_C virtual TBool LineBreakPossible(TUint aClass,TBool aBeforePicture,TBool aHaveSpaces) const; williamr@2: IMPORT_C virtual TBool NativePixelSize(TSize& aPixelSize); williamr@2: williamr@2: IMPORT_C void GetSizeInPixels(MGraphicsDeviceMap* aMap, TSize& aSize) const; williamr@2: IMPORT_C void SetSizeInPixels(MGraphicsDeviceMap* aMap, const TSize& aSize); williamr@2: IMPORT_C void AddCropInPixels(MGraphicsDeviceMap* aMap, const TMargins& aMargins); williamr@2: IMPORT_C void GetSizeInTwips(TSize& aSize) const; williamr@2: IMPORT_C void SetSizeInTwips(const TSize& aSize); williamr@2: IMPORT_C void ResetToOriginal(); williamr@2: protected: williamr@2: IMPORT_C CPicture(); williamr@2: }; williamr@2: williamr@2: williamr@2: /** Picture header providing an interface to a stored picture. The header holds: williamr@2: williamr@2: the picture's type, encoded as a UID, which ensures that it will be restored williamr@2: to the correct picture type williamr@2: williamr@2: the picture's size, which facilitates deferred loading williamr@2: williamr@2: the stream ID of the picture body, which is replaced by a pointer to the picture williamr@2: object when it has been restored. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TPictureHeader williamr@2: { williamr@2: public: williamr@2: IMPORT_C TPictureHeader(); williamr@2: IMPORT_C void InternalizeL(RReadStream& aStream); williamr@2: IMPORT_C void ExternalizeL(RWriteStream& aStream) const; williamr@2: IMPORT_C void DeletePicture(); williamr@2: public: williamr@2: /** A swizzle storing either the ID of the stream in which the picture is williamr@2: stored, or a pointer to the internalised picture. */ williamr@2: TSwizzle iPicture; williamr@2: /** A UID specifying the type of the picture. */ williamr@2: TUid iPictureType; williamr@2: /** The original size of the picture. */ williamr@2: TSize iSize; williamr@2: }; williamr@2: williamr@2: williamr@2: /** Abstract interface for instantiating and restoring new CPicture derived williamr@2: objects. williamr@2: williamr@2: A concrete derived class creates pictures of one or more specific types. The williamr@2: class has no member data and just one function, NewPictureL, that needs to williamr@2: be provided by derived classes. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class MPictureFactory williamr@2: { williamr@2: public: williamr@2: /** Interface to the picture restoration process that ensures that a williamr@2: picture of the correct type is restored. williamr@2: williamr@2: The class of the object to be restored is determined by the UID of the williamr@2: stored picture, contained in the specified picture header. williamr@2: williamr@2: The function can allow the restoration of: williamr@2: williamr@2: just one CPicture-derived class, returning an error if the UID indicates williamr@2: that the stored picture is not of the required type williamr@2: williamr@2: many different CPicture-derived classes, using the UID to choose which of williamr@2: the possible CPicture-derived classes should be instantiated williamr@2: williamr@2: @param aHeader The picture header that should be restored. williamr@2: @param aDeferredPictureStore The store in which both the header and picture williamr@2: reside. */ williamr@2: virtual void NewPictureL(TPictureHeader& aHeader,const CStreamStore& aDeferredPictureStore)const=0; williamr@2: }; williamr@2: williamr@2: // printing classes williamr@2: williamr@2: /** williamr@2: The maximum length of a printer model name. williamr@2: @see TPrinterModelName williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: const TInt KMaxPrinterModelNameLength=0x20; williamr@2: williamr@2: /** williamr@2: Defines a modifiable buffer descriptor that can contain the name of a williamr@2: printer model. The maximum length of the buffer is 32. williamr@2: @since 5.0 williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: typedef TBuf TPrinterModelName; williamr@2: williamr@2: /** Page specification for a print operation. williamr@2: williamr@2: The page specification consists of the page orientation and the page williamr@2: size in twips or pixels. By default, the page orientation is portrait. williamr@2: When using landscape orientation, the left hand side of the page williamr@2: becomes the top. williamr@2: "gdi.lib" williamr@2: @since 5.0 williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TPageSpec williamr@2: { williamr@2: public: williamr@2: /**The available page orientations. */ williamr@2: enum TPageOrientation williamr@2: { williamr@2: /** Portrait page orientation */ williamr@2: EPortrait, williamr@2: /** Landscape page orientation */ williamr@2: ELandscape williamr@2: }; williamr@2: public: williamr@2: IMPORT_C TPageSpec(); williamr@2: IMPORT_C TPageSpec(TPageOrientation aOrientation,const TSize& aSize); williamr@2: IMPORT_C void InternalizeL(RReadStream& aStream); williamr@2: IMPORT_C void ExternalizeL(RWriteStream& aStream) const; williamr@2: IMPORT_C TSize OrientedPageSize() const; williamr@2: IMPORT_C TBool operator==(const TPageSpec& aPageSpec) const; williamr@2: IMPORT_C TBool operator!=(const TPageSpec& aPageSpec) const; williamr@2: public: williamr@2: /** The width and height of the page in portrait orientation in twips or williamr@2: pixels. williamr@2: williamr@2: Note that OrientedPageSize() returns the width and height in reverse order williamr@2: for a landscape portrait. */ williamr@2: TSize iPortraitPageSize; williamr@2: /** The page orientation. */ williamr@2: TPageOrientation iOrientation; williamr@2: }; williamr@2: williamr@2: williamr@2: /** Controls the attributes of the band to be printed. williamr@2: williamr@2: An object of this type is passed as a parameter to functions. williamr@2: MPageRegionPrinter::PrintBandL() and CPrinterControl::QueueGetBand(). williamr@2: @see MPageRegionPrinter::PrintBandL() williamr@2: @see CPrinterControl::QueueGetBand() williamr@2: @since 5.0 williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TBandAttributes williamr@2: { williamr@2: public: williamr@2: /** The width and height of the band in twips or pixels. */ williamr@2: TRect iRect; williamr@2: /** ETrue to draw no text to the band; EFalse to draw text. */ williamr@2: TBool iTextIsIgnored; // any text drawing to this band is ignored williamr@2: /** ETrue to draw no graphics to the band; EFalse to draw graphics. */ williamr@2: TBool iGraphicsIsIgnored; // any graphics drawing to this band is ignored williamr@2: /** ETrue if band is the first band on the page; EFalse if not. */ williamr@2: TBool iFirstBandOnPage; williamr@2: }; williamr@2: williamr@2: /** Printer port interface. williamr@2: williamr@2: This interface is used as the base class for the various types of williamr@2: printer port. New printer port classes should be derived from this williamr@2: class.After allocation and construction, a pointer to a concrete williamr@2: printer port should be passed to williamr@2: CPrintSetup::StartPrintL(). williamr@2: @see CPrintSetup::StartPrintL() williamr@2: @since 5.0 williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CPrinterPort : public CBase williamr@2: { williamr@2: public: williamr@2: /** Writes data asynchronously to the printer port. williamr@2: williamr@2: @param aBuf Data to be written to the port williamr@2: @param aRequestStatus A reference to the request status object. If the williamr@2: request is cancelled, this should be set to KErrCancel; if the request williamr@2: completes normally, this should be set to KErrNone. */ williamr@2: virtual void WriteRequest(const TDesC8& aBuf,TRequestStatus& aRequestStatus)=0; williamr@2: williamr@2: /** Cancels an outstanding WriteRequest() operation. */ williamr@2: virtual void Cancel()=0; williamr@2: }; williamr@2: williamr@2: williamr@2: /** Detailed information about a printer model. williamr@2: "gdi.lib" williamr@2: @since 5.0 williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TPrinterModelEntry williamr@2: { williamr@2: public: williamr@2: /** The name of the printer model. */ williamr@2: TPrinterModelName iModelName; williamr@2: /** If ETrue, then a printer port is required. */ williamr@2: TBool iRequiresPrinterPort; williamr@2: /** The UID associated with this printer model. */ williamr@2: TUid iUid; williamr@2: public: williamr@2: IMPORT_C void InternalizeL(RReadStream& aStream); williamr@2: IMPORT_C void ExternalizeL(RWriteStream& aStream) const; williamr@2: }; williamr@2: williamr@2: williamr@2: /** Information about a printer model. williamr@2: williamr@2: An instance of this class consists of a TPrinterModelEntry and a stream ID, williamr@2: and is passed to CPrinterDevice::SetModel(). williamr@2: williamr@2: @see CPrinterDevice williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TPrinterModelHeader williamr@2: { williamr@2: public: williamr@2: /** The printer model. */ williamr@2: TPrinterModelEntry iEntry; williamr@2: /** The stream ID for model data. */ williamr@2: TStreamId iModelDataStreamId; williamr@2: public: williamr@2: IMPORT_C void InternalizeL(RReadStream& aStream); williamr@2: IMPORT_C void ExternalizeL(RWriteStream& aStream) const; williamr@2: }; williamr@2: williamr@2: williamr@2: /** Printer control interface. williamr@2: williamr@2: This abstract base class acts as the interface between a CPrinterDevice object williamr@2: and the printer. It creates the context for, and controls the progress and williamr@2: termination of the print job. williamr@2: williamr@2: Only those who need to add new printer drivers should write derived classes. williamr@2: After instantiation of such a class, using CPrinterDevice::CreateControlL(), williamr@2: the object can be accessed via the iControl member of CPrinterDevice. williamr@2: williamr@2: @see CPrinterDevice williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CPrinterControl : public CBase williamr@2: { williamr@2: public: williamr@2: /** Flags indicating whether there is more on the page to print. */ williamr@2: enum TMoreOnPage williamr@2: { williamr@2: /** Indicates there is more to print on the current page. */ williamr@2: EMoreOnPage, williamr@2: /** Indicates there is no more to print on the current page. */ williamr@2: ENoMoreOnPage williamr@2: }; williamr@2: public: williamr@2: IMPORT_C ~CPrinterControl(); williamr@2: williamr@2: /** Gets the number of bands per page. williamr@2: williamr@2: @return The number of bands on each page. */ williamr@2: virtual TInt BandsPerPage()=0; williamr@2: williamr@2: /** Prints the next band on the page. williamr@2: williamr@2: This is an asynchronous function. williamr@2: @param aStatus Request status object. On successful completion williamr@2: contains KErrNone, otherwise another of the system-wide williamr@2: error codes. williamr@2: @param aBand On return, indicates the attributes of the band, including williamr@2: its height and width and whether or not the device will ignore one or williamr@2: other of graphics or text output. This information may be used by williamr@2: applications to draw more efficiently, or may be ignored williamr@2: @return EMoreOnPage, if any unprinted bands remain on the williamr@2: current page. ENoMoreOnPage, if the current band is last on williamr@2: page. */ williamr@2: virtual TMoreOnPage QueueGetBand(TRequestStatus& aStatus, TBandAttributes& aBand)=0; // returns affirmative if more to print on current page williamr@2: williamr@2: /** Terminates the print process. williamr@2: williamr@2: This is an asynchronous function and is called when no more bands in williamr@2: the document remain to be printed.Note that all bands have been williamr@2: printed when no more pages or copies remain to be printed, and williamr@2: QueueGetBand() returns ENoMoreToPrint. williamr@2: williamr@2: @param aStatus Request status object. On successful completion contains williamr@2: KErrNone, otherwise another of the system-wide error codes. */ williamr@2: virtual void QueueEndPrint(TRequestStatus& aStatus)=0; williamr@2: williamr@2: /** Aborts the print process before it has completed. williamr@2: williamr@2: This function should be called if QueueGetBand() reports an error. */ williamr@2: virtual void AbortPrint()=0; // tidy up synchronously in a short time, return success code williamr@2: protected: williamr@2: IMPORT_C CPrinterControl(CPrinterPort* aPrinterPort); williamr@2: protected: williamr@2: /** State flags. */ williamr@2: enum TState williamr@2: { williamr@2: /** Not printing. */ williamr@2: ENotPrinting, williamr@2: /** Printing. */ williamr@2: EPrinting williamr@2: }; williamr@2: /** Printing state. */ williamr@2: TState iState; williamr@2: /** Printer port. */ williamr@2: CPrinterPort* iPrinterPort; williamr@2: }; williamr@2: williamr@2: class CDictionaryStore; williamr@2: class RFs; williamr@2: williamr@2: /** Printer graphics device interface. williamr@2: williamr@2: This abstract class represents a physical graphics device that is used for williamr@2: printing. williamr@2: williamr@2: This class is used to: williamr@2: williamr@2: set and get the page specification williamr@2: williamr@2: map between the co-ordinates of the printed page (in twips) and the co-ordinates williamr@2: of the image device (in pixels) williamr@2: williamr@2: get and set the printer model entry williamr@2: williamr@2: create and delete a printer control. williamr@2: williamr@2: A printer driver is defined in terms of a printer device and a printer control. williamr@2: A printer device can own either a single or no printer control. The control williamr@2: determines the progress and termination of the print job and is responsible williamr@2: for producing output. williamr@2: williamr@2: @see CPrinterControl williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CPrinterDevice : public CGraphicsDevice williamr@2: { williamr@2: public: williamr@2: IMPORT_C ~CPrinterDevice(); williamr@2: williamr@2: /** Gets the current page specification in twips. williamr@2: williamr@2: @return The current page specification, in twips. */ williamr@2: inline TPageSpec CurrentPageSpecInTwips() const {return(iCurrentPageSpecInTwips);} williamr@2: williamr@2: /** Sets the page specification in twips. williamr@2: williamr@2: @param aPageSpec The page specification in twips. */ williamr@2: IMPORT_C virtual void SelectPageSpecInTwips(const TPageSpec& aPageSpec); williamr@2: IMPORT_C virtual TRect PrintablePageInPixels() const; williamr@2: williamr@2: /** Gets the printer model entry. williamr@2: williamr@2: @return The printer model entry. */ williamr@2: virtual TPrinterModelEntry Model()const =0; williamr@2: williamr@2: /** Sets the printer model header and the store. williamr@2: williamr@2: @param aModel The printer model header. williamr@2: @param aStore The store. williamr@2: @return KErrNone if successful; otherwise, another of the system-wide williamr@2: error codes.*/ williamr@2: virtual TInt SetModel(const TPrinterModelHeader& aModel,CStreamStore& aStore)=0; williamr@2: williamr@2: /** Creates a printer control. williamr@2: williamr@2: The printer control is an instance of a CPrinterControl derived class; it williamr@2: is assigned to this printer device's iControl member. williamr@2: williamr@2: Note that this function is called by CPrintSetup::StartPrintL(). williamr@2: williamr@2: @param aPrinterPort Pointer to an instance of a printer port. */ williamr@2: virtual void CreateControlL(CPrinterPort* aPrinterPort)=0; williamr@2: IMPORT_C virtual void DeleteControl(); williamr@2: williamr@2: /** Externalizes printer properties to the store. williamr@2: williamr@2: The default implementation is empty. williamr@2: williamr@2: @param aStream The read stream. */ williamr@2: virtual void InternalizePropertiesL(RReadStream& /*aStream*/) {} williamr@2: williamr@2: /** Externalizes printer properties to the store. williamr@2: williamr@2: The default implementation is empty. williamr@2: williamr@2: @param aStream The write stream. */ williamr@2: virtual void ExternalizePropertiesL(RWriteStream& /*aStream*/) const {} williamr@2: IMPORT_C void RestorePropertiesL(); williamr@2: IMPORT_C void StorePropertiesL() const; williamr@2: protected: williamr@2: IMPORT_C CPrinterDevice(); williamr@2: public: williamr@2: /** The printer control. williamr@2: williamr@2: This may be NULL. If implemented, it provides control over the print williamr@2: operation. */ williamr@2: CPrinterControl* iControl; williamr@2: protected: williamr@2: /** Current page specification in twips. */ williamr@2: TPageSpec iCurrentPageSpecInTwips; williamr@2: }; williamr@2: williamr@2: williamr@2: /** Printer model list interface. williamr@2: williamr@2: Functions provided by this abstract base class can be used to extract printer williamr@2: model information from the list of printer models. This class would typically williamr@2: be used to implement printer selection in a dialog box. williamr@2: williamr@2: @see CPdrModelList williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CPrinterModelList : public CBase williamr@2: { williamr@2: public: williamr@2: /** Gets the number of printer models in the printer model list. williamr@2: williamr@2: @return The number of printer models. */ williamr@2: virtual TInt ModelCount() const=0; williamr@2: williamr@2: /**Gets printer model name. williamr@2: williamr@2: This is the name of the printer model at the specified index within williamr@2: the list of printer models. williamr@2: williamr@2: @param anIndex The index of the printer model within the array of williamr@2: printer models. Note that this number must be between zero and williamr@2: ModelCount(). williamr@2: @return Name of printer model, up to 32 characters long */ williamr@2: virtual const TPrinterModelEntry operator[](TInt anIndex)=0; williamr@2: williamr@2: /** Gets a printer models index within the model list from its UID. williamr@2: williamr@2: @param aModelUid The UID of the printer model. williamr@2: @return The index of the printer model within the array of printer models.*/ williamr@2: virtual TInt UidToNum(TUid aModelUid) const=0; williamr@2: }; williamr@2: williamr@2: williamr@2: /** Interface for printing in bands. williamr@2: williamr@2: This class provides a single PrintBandL() function that prints williamr@2: the body of each page band by band. Classes derived from this interface must williamr@2: provide an implementation of the PrintBandL() function. williamr@2: @since 5.0 williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class MPageRegionPrinter williamr@2: { williamr@2: public: williamr@2: /** Prints a band. williamr@2: williamr@2: Implementations should set up a graphics context to which all drawing should williamr@2: take place using CGraphicsDevice::CreateContext(). All co-ordinate williamr@2: calculations should be done in twips, and converted into pixels before williamr@2: starting the print job. williamr@2: williamr@2: @param aDevice Pointer to the graphics device representing the printer. williamr@2: @param aPageNo The number of the page containing the band to be printed. williamr@2: @param aBandInPixels Attributes of the band to be printed. */ williamr@2: virtual void PrintBandL(CGraphicsDevice* aDevice,TInt aPageNo,const TBandAttributes& aBandInPixels)=0; williamr@2: }; williamr@2: williamr@2: /** williamr@2: The UID value of a printer specification data store. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: const TInt KPdrStoreFileUidVal=268435514; williamr@2: williamr@2: const TInt KPdlUidVal=268450588; williamr@2: const TInt KUdlUidVal=268450589; williamr@2: williamr@2: williamr@2: /** Printer specific user interface. williamr@2: williamr@2: The class is used to implement a printer specific setup dialog. A concrete williamr@2: implementation of the class is supplied in a UDL (i.e. a UI DLL). williamr@2: williamr@2: CPrinterDriver::CreatePrinterDriverUIL() is used to construct a CPrinterDriverUI williamr@2: object for a specific printer. (This function calls the ordinal 1 exported williamr@2: function of the UDL that performs the construction of the CPrinterDriverUI williamr@2: object). williamr@2: williamr@2: @see CPrinterDriver::CreatePrinterDriverUIL() williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CPrinterDriverUI : public CBase williamr@2: { williamr@2: protected: williamr@2: IMPORT_C CPrinterDriverUI(); williamr@2: public: williamr@2: IMPORT_C virtual TBool BeforePrintL(); williamr@2: IMPORT_C virtual void AfterPrintL(); williamr@2: IMPORT_C virtual void SetPropertiesL(); williamr@2: IMPORT_C virtual TBool CanSetProperties(); williamr@2: williamr@2: /** Sets the printer device. williamr@2: williamr@2: @param aPrinterDevice The printer device. */ williamr@2: virtual TInt SetPrinterDevice(CPrinterDevice* aPrinterDevice)=0; williamr@2: }; williamr@2: williamr@2: class CFileStore; williamr@2: williamr@2: williamr@2: /** Provides access to a store containing printer specification data. williamr@2: williamr@2: Printer specification data is held as a direct file store, and usually has williamr@2: a .pdr file type. williamr@2: williamr@2: A printer driver is implemented as two files: a PDR file containing the printer williamr@2: specification data and a PDL file containing the code to link the printer williamr@2: with the graphics printing system. williamr@2: williamr@2: The printer specification data is generated by compiling a text file (a .pd williamr@2: file type) using the pdrtran tool. Printer specification data defines: williamr@2: williamr@2: the name of the associated PDL williamr@2: williamr@2: a list of one or more models supported by this driver, identified by name williamr@2: and UID williamr@2: williamr@2: device information such as the size of the device, typeface information for williamr@2: each model, including which typefaces are supported, the heights available williamr@2: in each typeface and the width of each character in a font. williamr@2: williamr@2: @see CPrinterDriverUI williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CPrinterDriver : public CBase williamr@2: { williamr@2: public: williamr@2: IMPORT_C static CPrinterDriver* NewL(); williamr@2: IMPORT_C ~CPrinterDriver(); williamr@2: IMPORT_C void OpenPdrL(const TDesC &aName); williamr@2: IMPORT_C void Close(); williamr@2: IMPORT_C TInt NumModels() const; williamr@2: IMPORT_C TPrinterModelEntry Model(TInt aNum) const; williamr@2: williamr@2: /** Gets the associated graphics printer device. williamr@2: williamr@2: @return The physical graphics device used for printing. */ williamr@2: inline CPrinterDevice* PrinterDevice() {return iPrinterDevice;} williamr@2: IMPORT_C CPrinterDevice* CreatePrinterDeviceL(TUid aModelUid); williamr@2: IMPORT_C CPrinterDriverUI* CreatePrinterDriverUIL(); williamr@2: private: williamr@2: CPrinterDriver(); williamr@2: void DeletePrinterDevice(); williamr@2: void DoOpenPdrL(const TDesC &aName); williamr@2: void DoCreatePrinterDeviceL(TUid aModelUid); williamr@2: void LoadLibraryL(RLibrary& aLibrary,const TDesC& aExt,TUid aUid2); williamr@2: private: williamr@2: RFs iFs; williamr@2: CFileStore *iPdrStore; williamr@2: TInt iNumModels; williamr@2: TPrinterModelHeader* iModelList; williamr@2: TFileName iPdlName; williamr@2: TUid iPdlUid; williamr@2: RLibrary iPdlLibrary; williamr@2: CPrinterDevice* iPrinterDevice; williamr@2: RLibrary iUdlLibrary; williamr@2: }; williamr@2: williamr@2: class RResourceFile; williamr@2: williamr@2: williamr@2: /** Implements a printer model list interface for a collection of PDR files. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CPdrModelList : public CPrinterModelList williamr@2: { williamr@2: public: williamr@2: IMPORT_C static CPdrModelList* NewL(); williamr@2: IMPORT_C virtual ~CPdrModelList(); williamr@2: IMPORT_C TInt ModelCount() const; williamr@2: IMPORT_C const TPrinterModelEntry operator [] (TInt anIndex); williamr@2: IMPORT_C TInt UidToNum(TUid aModelUid) const; // returns KErrNotFound the model uid is not matched williamr@2: IMPORT_C void AddDirectoryL(const TDesC& aDir); williamr@2: IMPORT_C CPrinterModelList* ScanForModelsL(); williamr@2: IMPORT_C CPrinterDriver* CreatePrinterDriverL(TInt anIndex); williamr@2: private: williamr@2: CPdrModelList(); williamr@2: void ConstructL(); williamr@2: private: williamr@2: class TFileEntry williamr@2: { williamr@2: public: williamr@2: TFileName iFileName; williamr@2: TDesC* iDirectory; williamr@2: }; williamr@2: class TModelEntry williamr@2: { williamr@2: public: williamr@2: TPrinterModelEntry iEntry; williamr@2: TFileEntry* iFile; williamr@2: }; williamr@2: private: williamr@2: void ScanDirectoryL(TInt aDirIndex); williamr@2: void ListModelsL(TInt aFileIndex, TParse& aParser, TFileName& aNameOfLoadedResourceFile, TFileName& aTempFileName, RResourceFile& aResourceFile, HBufC8*& aResource); williamr@2: HBufC* NewPathBufL(const TFileEntry& aFileEntry); williamr@2: private: williamr@2: CArrayFixSeg* iModelArray; williamr@2: CArrayFixFlat* iFileArray; williamr@2: CArrayFixFlat* iDirectoryArray; williamr@2: RFs iFileServer; williamr@2: }; williamr@2: williamr@2: williamr@2: /** The interface for mapping between twips and device-specific units enriched williamr@2: with facilities to allow zooming. williamr@2: williamr@2: The class is recursive, because a TZoomFactor object can have a williamr@2: MGraphicsDeviceMap (which could itself be a TZoomFactor) in its member data. williamr@2: This allows a zoom factor object to contain another zoom factor object, and williamr@2: is used to allow objects with different zoom factors to be embedded in each williamr@2: other to an arbitrary depth by the application architecture. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class TZoomFactor : public MGraphicsDeviceMap williamr@2: { williamr@2: public: williamr@2: IMPORT_C TZoomFactor(); williamr@2: IMPORT_C ~TZoomFactor(); williamr@2: inline TZoomFactor(const MGraphicsDeviceMap* aDevice); williamr@2: inline TZoomFactor(const TZoomFactor* aDevice); williamr@2: IMPORT_C TInt ZoomFactor() const; williamr@2: IMPORT_C void SetZoomFactor(TInt aZoomFactor); williamr@2: inline void SetGraphicsDeviceMap(const MGraphicsDeviceMap* aDevice); williamr@2: inline const MGraphicsDeviceMap* GraphicsDeviceMap() const; williamr@2: IMPORT_C void SetTwipToPixelMapping(const TSize& aSizeInPixels,const TSize& aSizeInTwips); williamr@2: IMPORT_C TInt HorizontalTwipsToPixels(TInt aTwipWidth) const; williamr@2: IMPORT_C TInt VerticalTwipsToPixels(TInt aTwipHeight) const; williamr@2: IMPORT_C TInt HorizontalPixelsToTwips(TInt aPixelWidth) const; williamr@2: IMPORT_C TInt VerticalPixelsToTwips(TInt aPixelHeight) const; williamr@2: IMPORT_C TInt GetNearestFontInTwips(CFont*& aFont, const TFontSpec& aFontSpec); williamr@2: IMPORT_C TInt GetNearestFontToDesignHeightInTwips(CFont*& aFont, const TFontSpec& aFontSpec); williamr@2: IMPORT_C TInt GetNearestFontToMaxHeightInTwips(CFont*& aFont, const TFontSpec& aFontSpec, TInt aMaxHeight); williamr@2: IMPORT_C void ReleaseFont(CFont* aFont); williamr@2: public: williamr@2: williamr@2: /** One to one zoom factor. */ williamr@2: enum {EZoomOneToOne=1000}; williamr@2: private: williamr@2: TInt iZoomFactor; williamr@2: const MGraphicsDeviceMap* iDevice; williamr@2: }; williamr@2: williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS williamr@4: #include williamr@4: #include williamr@4: #endif //SYMBIAN_ENABLE_SPLIT_HEADERS williamr@4: williamr@2: #include williamr@4: williamr@2: #endif // __GDI_H__