Class CBitmapDevice

class CBitmapDevice : public CGraphicsDevice;

Description

Defines an abstract interface for the capabilities and attributes of a bitmapped graphics device.

The class specialises the graphics device interface CGraphicsDevice for bitmaps graphics. The Window Server Client-Side API provides one implementation of the interface, CWsScreenDevice, for screen drawing. Another implementation, CFbsBitmapDevice, is used for drawing to in-memory bitmaps. A third, CFbsScreenDevice, is used (rarely) to access the screen directly, without the mediation of the window server.

Derivation

• MGraphicsDeviceMap - Interface class for mapping between twips and device-specific units (pixels).
• CBase - Base class for all classes to be instantiated on the heap.

• CGraphicsDevice - Specifies the interface for concrete device classes.

• CBitmapDevice - Defines an abstract interface for the capabilities and attributes of a bitmapped...

Members

Defined in CBitmapDevice:

• AddFile(const TDesC &,TInt &)Adds a font file to the device's typeface store. The specified font file must be...
• CreateBitmapContext(CBitmapContext *&)Creates a bitmap context for this bitmap device.
• FontHeightInPixels(TInt,TInt)constGets the height, in pixels, of the specified typeface at one of its defined heig...
• GetNearestFontInPixels(CFont *&,const TFontSpec &)Gets the font which is the nearest to the given font specification.
• GetNearestFontToDesignHeightInPixels(CFont *&,const TFontSpec &)Gets the font which is the nearest to the given font specification.
• GetNearestFontToMaxHeightInPixels(CFont *&,const TFontSpec &,TInt)Gets the font which is the nearest to the given font specification.
• GetPixel(TRgb &,const TPoint &)constGets the RGB colour of an individual pixel on a bitmapped graphics device.
• GetScanLine(TDes8 &,const TPoint &,TInt,TDisplayMode)constCopies a scanline into a buffer.
• RemoveFile(TInt)Removes a font file from the font store.

Inherited from CBase:

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

Inherited from CGraphicsDevice:

• CreateContext(CGraphicsContext *&)Creates a graphics context for the device.
• DisplayMode()constGets the display mode of the device.
• FontHeightInTwips(TInt,TInt)constGet the height of a font in twips.
• GetPalette(CPalette *&)constGets the device's current palette.
• NumTypefaces()constGets the number of typefaces supported by the graphics device.
• PaletteAttributes(TBool &,TInt &)constGets the palette attributes of the device.
• SetPalette(CPalette *)Sets the device's palette.
• SizeInPixels()constGets the size of the device area in pixels.
• SizeInTwips()constGets the size of the device area in twips.
• TypefaceSupport(TTypefaceSupport &,TInt)constGets typeface information for a specified typeface.

Inherited from MGraphicsDeviceMap:

• GetNearestFontInTwips(CFont *&,const TFontSpec &)Gets the font which is the nearest to the given font specification.
• GetNearestFontToDesignHeightInTwips(CFont *&,const TFontSpec &)Gets the font which is the nearest to the given font specification.
• GetNearestFontToMaxHeightInTwips(CFont *&,const TFontSpec &,TInt)Gets the font which is the nearest to the given font specification.
• HorizontalPixelsToTwips(TInt)constConverts a horizontal dimension from pixels to twips.
• HorizontalTwipsToPixels(TInt)constConverts a horizontal dimension from twips to pixels.
• PixelsToTwips(const TPoint &)constConverts a point in pixels to a point in twips.
• PixelsToTwips(const TRect &)constConverts a rectangle in pixels to a rectangle in twips.
• ReleaseFont(CFont *)Releases the specified font.
• TwipsToPixels(const TPoint &)constConverts a point in twips to a point in pixels.
• TwipsToPixels(const TRect &)constConverts a rectangle in twips to a rectangle in pixels.
• VerticalPixelsToTwips(TInt)constConverts a vertical dimension from pixels to twips.
• VerticalTwipsToPixels(TInt)constConverts a vertical dimension from twips to pixels.

virtual void GetPixel(TRgb &aColor, const TPoint &aPixel) const=0;

Description

Gets the RGB colour of an individual pixel on a bitmapped graphics device.

This pure virtual function is implemented in derived classes.

Parameters

TRgb &aColor On return, should contain the RGB colour of the pixel. const TPoint &aPixel The (x,y) co-ordinates of the pixel. The top left pixel is (0,0).

virtual void GetScanLine(TDes8 &aBuf, const TPoint &aStartPixel, TInt aLength, TDisplayMode aDispMode) const=0;

Description

Copies a scanline into a buffer.

The pixels are converted from the display mode format on the bitmapped graphics device to the format of the specified device display mode.

By specifying the start pixel and the number of pixels, either the whole or a portion of a bitmapped graphics device pixel row may be copied.

This pure virtual function is implemented in derived classes.

Parameters

TDes8 &aBuf An 8 bit modifiable descriptor buffer into which pixels are copied; it must be sufficiently large to store all the scanline pixels. const TPoint &aStartPixel The (x,y) co-ordinates of the first pixel of the bitmap scanline to be put into the buffer. TInt aLength The number of pixels to put into the buffer. TDisplayMode aDispMode The display mode into which to convert the pixels.

virtual TInt AddFile(const TDesC &aName, TInt &aId)=0;

Description

Adds a font file to the device's typeface store. The specified font file must be accessible to any process, i.e. not located inside an application's private directory.

This pure virtual function is implemented in derived classes.

Parameters

const TDesC16 &aName The name of the font file. TInt &aId On return, contains an ID for the font file.

Return value

TInt KErrNone, if successful; otherwise, another of the system-wide error codes.

virtual void RemoveFile(TInt aId=0)=0;

Description

Removes a font file from the font store.

This pure virtual function is implemented in derived classes.

Parameters

TInt aId The ID of the font file to be removed. The default is 0.

Interface status:

deprecated

Use GetNearestFontToDesignHeightInPixels

virtual TInt GetNearestFontInPixels(CFont *&aFont, const TFontSpec &aFontSpec)=0;

Description

Gets the font which is the nearest to the given font specification.

When the font is no longer needed, call ReleaseFont() .

Note that this deprecated function is replaced by the new GetNearestFontToDesignHeightInPixels() yielding (virtually) the same result. However clients are strongly encouraged to use the new GetNearestFontToMaxHeightInPixels() function instead. This will guarantee that every character within any given text string will fit within the given amount of pixels, whereas the design height is an aesthetic unit decided by the font designer without strict physical meaning, which may result in cropped characters.

Parameters

CFont *&aFont On return, contains a pointer to the nearest font. const TFontSpec &aFontSpec The specification of the font to be matched.

Return value

TInt KErrNone if successful; a system-wide error code otherwise.

inline virtual TInt GetNearestFontToDesignHeightInPixels(CFont *&, const TFontSpec &);

Description

Gets the font which is the nearest to the given font specification.

When the font is no longer needed, call ReleaseFont() .

This new function replaces the deprecated GetNearestFontInPixels() yielding (virtually) the same result. However clients are strongly encouraged to use the new GetNearestFontToMaxHeightInPixels() function instead. This will guarantee that every character within any given text string will fit within the given amount of pixels, whereas the design height is an aesthetic unit decided by the font designer without strict physical meaning, which may result in cropped characters.

Parameters

CFont *& const TFontSpec &

Return value

TInt KErrNone if successful; a system-wide error code otherwise.

inline virtual TInt GetNearestFontToMaxHeightInPixels(CFont *&, const TFontSpec &, TInt);

Description

Gets the font which is the nearest to the given font specification.

When the font is no longer needed, call ReleaseFont() .

The font and bitmap server returns a pointer to the nearest matching font from those available. Matches to max height of font - this does its best to return a font that will fit within the maximum height specified (but note that variations due to hinting algorithms may rarely result in this height being exceeded by up to one pixel). Problems can also be encountered with bitmap fonts where the typeface exists but doesn't have a font small enough.

Parameters

CFont *& const TFontSpec & TInt

Return value

TInt KErrNone if successful; a system-wide error code otherwise.

virtual TInt FontHeightInPixels(TInt aTypefaceIndex, TInt aHeightIndex) const=0;

Description

Gets the height, in pixels, of the specified typeface at one of its defined heights.

The typeface is identified by by an index. For a given typeface, there are a discrete number of heights; the specific height is also identified by an index.

The value returned is rounded up or down to the nearest font height in pixels.

This pure virtual function is implemented in derived classes.

Parameters

TInt aTypefaceIndex A typeface index number, in the range: 0 to (CGraphicsDevice::NumTypefaces()const - 1). TInt aHeightIndex A font height index number, in the range: 0 to (iNumHeights - 1) where iNumHeights is a public data member of the TTypefaceSupport object returned by CGraphicsDevice::TypefaceSupport(TTypefaceSupport &,TInt)const.

Return value

TInt The height of the font, in pixels.

See also:

• TTypefaceSupportTypeface family support information.
• CGraphicsDevice::NumTypefaces()constGets the number of typefaces supported by the graphics device.
• CGraphicsDevice::TypefaceSupport(TTypefaceSupport &,TInt)constGets typeface information for a specified typeface.

inline TInt CreateBitmapContext(CBitmapContext *&aGC);

Description

Creates a bitmap context for this bitmap device.

Parameters

CBitmapContext *&aGC On return, holds a pointer to the created bitmap context.

Return value

TInt KErrNone, if successful; otherwise, another of the system-wide error codes.