<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept xml:lang="en" id="GUID-0AB9B221-38AE-576E-AC5A-C4C106E3D93B"><title> Graphics Device Interface (GDI) Component Overview</title><shortdesc>The GDI component provides abstract base classes that represent the graphics device and the context through which graphics and text can be drawn to it. The context maintains 'settings', such as the pen and brush colors and styles in use, and provides a rich API of drawing commands for creating graphical and textual output. The component also provides abstract device-independent APIs for a variety of graphics-related functions, such as for handling fonts, pictures and printers. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p>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. </p> <p>The API also provides printing to printer devices. Printing is treated as drawing to a graphics context, with the printer represented by a specialized 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 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. </p> <section><title>Architectural relationships</title> <p>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. </p> <p>Most drawing takes place within a control, as defined in the UI Control Framework. That API provides support functions for using graphics contexts. </p> </section> <section><title>Description</title> <p><b>Graphics device </b> </p> <p>A graphics device represents the medium being drawn to. It is the provider of graphics contexts through which drawing is done. </p> <p>The base class for graphics devices is <xref href="GUID-500FC564-35E9-3B66-A0C2-1269371A2EA0.dita"><apiname>CGraphicsDevice</apiname></xref>. Concrete devices implement derived classes. </p> <p><b>Bitmap graphics device </b> </p> <p>This specializes a graphics device (<xref href="GUID-500FC564-35E9-3B66-A0C2-1269371A2EA0.dita"><apiname>CGraphicsDevice</apiname></xref>) for bitmaps graphics. </p> <p>The abstract interface is defined by <codeph>CBitmapDevice</codeph>. The <xref href="GUID-DC5E8C7D-D697-53E8-87F4-344301430E61.dita">Window Server Client-Side API</xref> provides one implementation, <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita"><apiname>CWsScreenDevice</apiname></xref>, for screen drawing. The <xref href="GUID-EAAD1719-C02C-5705-A5C3-993E36441BE6.dita">BitGDI component</xref> provides the <xref href="GUID-71D27EBD-26B8-3D51-9798-1EAD461BCBCF.dita"><apiname>CFbsBitmapDevice</apiname></xref> implementation for drawing to in-memory bitmaps and the <xref href="GUID-B229156F-2344-3F46-8542-AC65882D80DE.dita"><apiname>CFbsScreenDevice</apiname></xref> implementation, which is used (rarely) to access the screen directly, without the mediation of the Window Server. </p> <p><b>Graphics context </b> </p> <p>A graphics context provides a large number of drawing operations, with some state settings defining how the drawing is performed. The settings are: </p> <ul><li id="GUID-0E356741-F861-5FB5-9559-5FDE99C46601"><p>a pen, for drawing shape outlines and text, with color, line size and style settings </p> </li> <li id="GUID-B8E6303A-E98B-58A0-8E4B-CF5DD8B30F0D"><p>a brush, for filling areas, with color, style and origin settings </p> </li> <li id="GUID-F60A8400-DA9F-5AC5-9B58-17AFBE31394E"><p>for text, a current font and justification mode </p> </li> <li id="GUID-0205A7FA-CA6F-5861-A8B3-998629F7F273"><p>a drawing mode, which controls how colors drawn interact with the screen color </p> </li> <li id="GUID-27534CB0-7321-55AB-A5F9-91141F8A78D4"><p>a co-ordinate origin, typically the top left corner of the screen </p> </li> <li id="GUID-A8292E3D-A086-5715-848C-D6CA70403B83"><p>an internal drawing position, for relative drawing operations </p> </li> </ul> <p>Operations include drawing shapes (points, lines, polylines, arcs, rectangles, polygons, ellipses, rounded rectangles and pie slices), text, and bitmaps. </p> <p>The base class for graphics contexts is <xref href="GUID-DAD09DCF-3123-38B4-99E9-91FB24B92138.dita"><apiname>CGraphicsContext</apiname></xref>. Concrete devices provide derived classes that can provide additional operations suitable to the device. </p> <p><b>Bitmap graphics context </b> </p> <p>This specializes a graphics context (<xref href="GUID-DAD09DCF-3123-38B4-99E9-91FB24B92138.dita"><apiname>CGraphicsContext</apiname></xref>) for bitmaps graphics. It provides additional operations for clearing and copying rectangular areas, and bitmap block transfer. </p> <p>The abstract interface is defined by <xref href="GUID-FC746873-0570-3900-AD89-42B205FDC0D3.dita"><apiname>CBitmapContext</apiname></xref>. The <xref href="GUID-DC5E8C7D-D697-53E8-87F4-344301430E61.dita">Window Server Client-Side API</xref> provides one implementation, <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref>, used for screen drawing. The <xref href="GUID-EAAD1719-C02C-5705-A5C3-993E36441BE6.dita">BitGDI component</xref> provides another implementation, <xref href="GUID-4A501086-7EFF-376D-8901-6D9B2EB4EFF2.dita"><apiname>CFbsBitGc</apiname></xref> for drawing to in-memory bitmaps. </p> <p><b>Basic geometry classes </b> </p> <p>Point: a pair of (x,y) co-ordinates. It is provided by <xref href="GUID-339EC4C5-89DC-3972-9579-6DD38D418317.dita"><apiname>TPoint</apiname></xref>. </p> <p>Size: a width and height. It is provided by <xref href="GUID-938244B2-5E1A-39F7-8ACA-E6DE4C44A313.dita"><apiname>TSize</apiname></xref>. </p> <p>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 <xref href="GUID-101762DC-E498-3325-88AB-B0FF17DC62B6.dita"><apiname>TRect</apiname></xref>. </p> <p>Region: defines an area made up of a collection of rectangles. They are handled by a family of classes derived from <xref href="GUID-740A218E-76FB-31BF-BD91-BA6780AC4DEE.dita"><apiname>TRegion</apiname></xref>. </p> <p><b>Color </b> </p> <p>A color is specified by a 24-bit color value. The system then maps these values into device-level values. The color class is <xref href="GUID-F84C7F40-6DEB-39D1-B172-CB0CC3918E27.dita"><apiname>TRgb</apiname></xref>. </p> <p><b>Units conversion and zooming </b> </p> <p>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 <xref href="GUID-4791F2C1-C351-3824-8784-3161F5B65DCA.dita"><apiname>MGraphicsDeviceMap</apiname></xref>. </p> <p>You might want drawing code to draw at different possible levels of magnification (zoom). In that case, the mapping is performed by a <xref href="GUID-DDE4C9C0-7218-385E-B239-0DEFDE19FCCC.dita"><apiname>TZoomFactor</apiname></xref>, which also implements <xref href="GUID-4791F2C1-C351-3824-8784-3161F5B65DCA.dita"><apiname>MGraphicsDeviceMap</apiname></xref>. </p> <p><b>Font specification </b> </p> <p>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. </p> <p>It is provided by <xref href="GUID-052E4F6B-71C5-304C-B387-07A2F6F9900B.dita"><apiname>TFontSpec</apiname></xref>. The font style is provided by <xref href="GUID-E35C6B6B-CF60-3B91-A174-1B09077CBD76.dita"><apiname>TFontStyle</apiname></xref>. </p> <p><b>Device-independent font interface </b> </p> <p>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. </p> <p>The interface is <xref href="GUID-2A12FE3B-47F2-3016-8161-A971CA506491.dita"><apiname>CFont</apiname></xref>. Obtained fonts can be cached for quick retrieval through <xref href="GUID-B68B7BC8-CFBA-32F4-A0BE-8378F0C105DA.dita"><apiname>CFontCache</apiname></xref>. </p> <p><b>Typeface </b> </p> <p>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). </p> <p>Typeface information is encapsulated in a <xref href="GUID-BC6BFC0A-B748-3545-8A14-D79F98338CBA.dita"><apiname>TTypefaceSupport</apiname></xref>, including a <xref href="GUID-91F0F645-F565-3B8A-8FB1-FF4751AB0928.dita"><apiname>TTypeface</apiname></xref> class member. </p> <p><b>Typeface store </b> </p> <p>A typeface store allows you to discover the typefaces provided by a graphics device. </p> <p>A device-independent interface is defined by <xref href="GUID-0CA79D2D-827F-3A20-A10C-1CC9C576E803.dita"><apiname>CTypefaceStore</apiname></xref>. The <xref href="GUID-A03FB1BF-F67B-519D-A904-74CA3F8375D9.dita">Font and Bitmap Server component</xref> provides bitmap fonts and implements this interface for bitmap devices. </p> <p><b>Picture </b> </p> <p>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. </p> <p>The interface is provided by <xref href="GUID-829D57CD-9659-347B-AAE9-5F0A0ECD555C.dita"><apiname>CPicture</apiname></xref>. The capabilities class, <xref href="GUID-912E395D-934D-39B0-89D7-520BB8A04424.dita"><apiname>TPictureCapability</apiname></xref>, encapsulates whether the picture supports cropping and scaling. </p> <p><b>Picture header </b> </p> <p>When a picture is stored, a picture header must be as well. The header identifies (through a UID) which concrete picture class should be used to restore the picture's data, and how to access the picture's data (through a swizzle). </p> <p>The picture header is provided by <xref href="GUID-B92F8FF8-6940-389D-96F4-2271ECCF15D1.dita"><apiname>TPictureHeader</apiname></xref>. </p> <p><b>Picture factory </b> </p> <p>The picture factory is an abstract interface for instantiating and restoring new <xref href="GUID-829D57CD-9659-347B-AAE9-5F0A0ECD555C.dita"><apiname>CPicture</apiname></xref> -derived objects. A concrete derived class creates 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 InternalizeL the picture data from the store. </p> <p>The interface is provided by <xref href="GUID-F991FEDD-DF42-390F-97E4-4204EB05AAB8.dita"><apiname>MPictureFactory</apiname></xref>. </p> <p><b>Printer model list </b> </p> <p>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. </p> <p>The printer model list is provided by <xref href="GUID-9A34F369-5968-376F-A758-4ED310FD84E9.dita"><apiname>CPrinterModelList</apiname></xref>. An entry in the list is a <xref href="GUID-5283437A-25EA-330E-9B93-F4288907A6E2.dita"><apiname>TPrinterModelEntry</apiname></xref>. </p> <p><b>Printer device </b> </p> <p>This encapsulates the printer being used as a graphics device. Applications draw to this device to print their output. It has: </p> <ul><li id="GUID-22E300DB-2DD2-58ED-84D9-2359B5E6C0EC"><p>a page specification, giving the page orientation and the size (<xref href="GUID-EAD42D35-CABC-3E21-AF87-DD87EF5BF835.dita"><apiname>TPageSpec</apiname></xref>) </p> </li> <li id="GUID-892B884E-6E1D-5963-99B9-A583F4A688A6"><p>a printer control, which controls the progress and termination of the print job (<xref href="GUID-2E0F522C-2A42-3E2E-ADE8-43398BB86906.dita"><apiname>CPrinterControl</apiname></xref>) </p> </li> <li id="GUID-5B89E00F-24C6-54CD-9F55-396627EE56E1"><p>possibly, associated custom print setup dialogs (base class <xref href="GUID-409C6A2C-1F51-36AA-8ADA-2B8657A111B1.dita"><apiname>CPrinterDriverUI</apiname></xref>) </p> </li> </ul> <p>It is provided by <xref href="GUID-02E9DA67-8CC0-3785-B917-A14C8AA7E714.dita"><apiname>CPrinterDevice</apiname></xref>. </p> <p><b>Printer port </b> </p> <p>Some printer models require a port to be specified (e.g. file, serial, parallel). The base class for ports is <xref href="GUID-4ED9EBF1-D6CB-3075-9E61-E4F26FD3DF15.dita"><apiname>CPrinterPort</apiname></xref>. </p> <p><b>Band printing interface </b> </p> <p>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 <xref href="GUID-2C4DA17D-16ED-35C7-B936-1FF121C86FB2.dita"><apiname>MPageRegionPrinter</apiname></xref>. The attributes of the band to be printed are passed in a <xref href="GUID-32521573-2959-31BD-A7AD-F62AC649BE33.dita"><apiname>TBandAttributes</apiname></xref> object. </p> </section> </conbody><related-links><link href="GUID-1C3455BE-2082-504D-9157-88D8C72B1B80.dita"><linktext>GDI Concepts</linktext> </link> <link href="GUID-1E68A78A-52E5-5DF7-B540-85C7194E4617.dita"><linktext>GDI Tutorials</linktext> </link> <link href="GUID-B6D4AEE9-5C17-51D9-BBDE-7CCB5218279D.dita"><linktext>GDI
                Component</linktext> </link> </related-links></concept>