Graphics Device Interface Overview

Provides an abstract interface for drawing to devices, such as screens and printers.

This API provides abstract device-independent font interfaces. Applications use the API to get the fonts they require, and use it in a graphics context to draw text. The font and bitmap server provides bitmap fonts.

The API's embedding functionality provides a concept of a picture object, independent of whether it is a bitmap or drawing, and support for storing and restoring pictures. In device families that support document embedding, as defined in the Application Architecture Framework API, a picture is used to draw a representation of the embedded document's content (called a glass door). Rich text, as defined in the Text And Text Attributes API, can also contain pictures.

The API also provides printing to printer devices. Printing is treated as drawing to a graphics context, with the printer represented by a specialised graphics device. An application that supports printing should store its view data in (device-independent) twips, only converting into pixels when drawing to either the screen or a printer. Symbian OS can print to a range of printers, and has a framework for providing printer drivers. This API allows the installed drivers to be listed, and the appropriate one selected. UI variants may provide stock printing dialogs for users to initiate and control print jobs. It is normal for applications that provide printing to supply print job setup (from the Print Framework API) and their printing implementation (the band printing interface described below) to these dialogs, which can then use them as appropriate.

The Font and Bitmaps Server provides bitmap storage and bitmap fonts. The Window Server Client Side API extends the API's classes in turn for drawing in windows (the normal case). For some applications, this polymorphism can be important, as it allows shared code for screen drawing and printing.

Most drawing takes place within a control, as defined in the UI Control Framework. That API provides support functions for using graphics contexts.

Point: a pair of (x,y) co-ordinates. It is provided by TPoint.

Size: a width and height. It is provided by TSize.

Rectangle: described by the co-ordinates of its top-left and bottom-right corners, or by its top-left hand corner and its size. It is provided by TRect.

Region: defines an area made up a collection of rectangles. They are handled by a family of classes derived from TRegion.

A graphics device represents the medium being drawn to. It is the provider of graphics contexts through which drawing is done.

The base class for graphics devices is CGraphicsDevice. Concrete devices implement derived classes.

This specialises a graphics device (CGraphicsDevice) for bitmaps graphics.

The abstract interface is defined by CBitmapDevice. The Window Server Client-Side API provides one implementation, 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.

A graphics context provides a large number of drawing operations, with some state settings defining how the drawing is performed. The settings are:

• a pen, for drawing shape outlines and text, with colour, line size and style settings

• a brush, for filling areas, with colour, style and origin settings

• for text, a current font and a justification mode

• a drawing mode: controls how colours drawn interact with the screen colour

• a co-ordinate origin, typically the top left corner of the screen

• an internal drawing position, for relative drawing operations

Operations include drawing shapes (points, lines, polylines, arcs, rectangles, polygons, ellipses, rounded rectangles and pie slices), text, and bitmaps.

The base class for graphics contexts is CGraphicsContext. Concrete devices provide derived classes that can provide additional operations suitable to the device.

This specialises a graphics context (CGraphicsContext) for bitmaps graphics. It provides additional operations for clearing and copying rectangular areas, and bitmap block transfer.

The abstract interface is defined by CBitmapContext. The Window Server Client-Side API provides one implementation, CWindowGc, used for screen drawing. Another implementation, CFbsBitGc, is used for drawing to in-memory bitmaps.

A colour is specified by a 24-bit colour value. The system then maps these values into device-level values. The colour class is TRgb.

Graphics code can be written in a device-independent way by handling lengths/positions using twips (1/1440th inch), and only converting into pixels when actually drawing. Graphic devices implement a twips/pixels mapping interface for this conversion. The interface is defined by MGraphicsDeviceMap.

You might want drawing code to draw at different possible levels of magnification (zoom). In that case, the mapping is performed by a TZoomFactor, which also implements MGraphicsDeviceMap.

The bitmap utilities class provides functions to operate on the individual bits within a bitmap. It is provided by TBitmapUtil.

A font specification is used to specify a desired font in device-independent terms. This can include the typeface, font style (posture, weight, and position), and height.

It is provided by TFontSpec. The font style is provided by TFontStyle.

Applications obtain font objects from a graphics device by providing a font specification. The interface is device-independent, and is implemented by providers of fonts for particular devices.

The interface is CFont. Obtained fonts can be cached for quick retrieval through CFontCache.

A typeface is a group of related fonts of various sizes that share the same typeface name and typeface attributes (e.g. proportional/non-proportional, serif/sans-serif).

Typeface information is encapsulated in a TTypefaceSupport, including a TTypeface class member.

A typeface store allows you to discover the typefaces provided by a graphics device.

A device-independent interface is defined by CTypefaceStore. CFbsTypefaceStore implements this for bitmap devices.

The picture interface defines a drawable item, that can be stored and restored, and possibly cropped and scaled. Derived classes implement the interface for particular types of picture.

The interface is provided by CPicture. The capabilities class, TPictureCapability, encapsulates whether the picture supports cropping and scaling.

When a picture is stored, a picture header must be as well. The header identifies which concrete picture class that should be used to restore the picture's data (through a UID), and how to access the picture's data (through a swizzle).

The picture header is provided by TPictureHeader.

The picture factory is an abstract interface for instantiating and restoring new CPicture-derived objects. A concrete derived class will create pictures of one or more specific types. Supplied with information from a picture header, a picture factory creates an instance of the appropriate picture class, and tells the instance to internalise the picture data from the store.

The interface is provided by MPictureFactory.

The printer model list gives the possible printers, obtained from the installed printer drivers. To create a printer device, a particular model must be chosen.

The printer model list is provided by CPrinterModelList. An entry in the list is a TPrinterModelEntry.

This encapsulates the printer being used as a graphics device. Applications draw to this device to print their output. It has:

• a page specification, giving the page orientation and the size (TPageSpec)

• a printer control, which controls the progress and termination of the print job (CPrinterControl)

• possibly, associated custom print setup dialogs (base class CPrinterDriverUI)

It is provided by CPrinterDevice.

Some printer models require a port to be specified (e.g. file, serial, parallel). The base class for ports is CPrinterPort.

Pages are printed in regions of a page, called bands. An application implements the band printing interface to draw the requested region to the printer device. The class is MPageRegionPrinter. The attributes of the band to be printed are passed in a TBandAttributes object.