<?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-A3B5381F-7D81-52D5-97DE-CCF56C2A49A9"><title>Shape Operations</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>A graphics context provides line and shape drawing graphics operations for points, lines, and fillable shapes. </p> <section><title>Lines</title> <p>There are three line primitives - straight line, <keyword>polyline</keyword> and arc. These are drawn with the pen, with all its current settings. Straight lines can be drawn between two given points, to a single given point from the current internal drawing position, or by moving the internal drawing position by a given vector. They are constructed with the help of a linear DDA. </p> </section> <section><title>Fillable shapes</title> <p>There are five shape drawing primitives - pie slice, ellipse, rectangle, rounded rectangle, and polygon. All may be drawn with or without an outline. </p> <p>Outlines are drawn with the pen, and thus subject to pen color, pen size and pen style settings. The effective outline color depends on the drawing mode. If the pen size has been set to greater than or equal to half the size of the shape, then the shape will be filled with solid pen color. The pen style should be set to null if no outline is required. </p> <p>Shapes are filled using the brush, and thus subject to the brush style (color, hash or pattern) and brush pattern origin. The effective fill color depends on the drawing mode. The brush style should be set to null if no fill is required. </p> </section> <section><title>Pen size</title> <p>Note that when the pen is a single pixel wide: </p> <ul><li id="GUID-75979B1B-2AED-5F65-A3B9-2E3C54B32005"><p>There is a guarantee that each pixel will be written only once on the display. This allows shapes to be drawn in exclusive-or mode, without the risk that multiple writes will cancel each other out. </p> </li> <li id="GUID-1FD0FD50-F349-5241-A716-2A94B7F11DEE"><p>When straight lines are drawn, their last point is not included. This allows a polyline to be constructed without the pixels at the joins being written twice. The single write guarantee can thus be maintained for multiple consecutive primitives. However, the last point of an arc is always drawn. </p> </li> </ul> <p>If the pen size is greater than one pixel, a straight line is drawn as a rectangular shaped region of pixels, with rounded ends that extend beyond the start and end points. See <codeph>CGraphicsContext::SetPenSize()</codeph> for details. </p> </section> <section><title>Rectangles</title> <p>All the fillable shape drawing primitives, (except <codeph>DrawPolygon()</codeph>), either use a rectangle directly or to define the position of an ellipse that is used in the construction of the shape. This rectangle is passed as an argument of type <codeph>TRect</codeph>. </p> <p>Care is needed when specifying rectangles. The <codeph>TRect</codeph> class is defined to include the pixel at its top left corner, but to exclude the pixel at its bottom right corner. Thus, a rectangle specified as: </p> <codeblock id="GUID-87FCDD0F-E8EE-580D-9277-9BA385A2C1A4" xml:space="preserve">TRect(TPoint(100,50),TPoint(300,150))</codeblock> <p>includes the point (100,50) but not the point (300,150). No pixels will be written to column 300, nor to row 150, on the display. The rectangle drawn on the screen will be 300-100=200 pixels wide, and 150-50=100 pixels high. </p> </section> <section><title>Ellipses</title> <p>Ellipses whose axes are aligned with the x and y axes of the co-ordinate system, are supported; other ellipses are not. Ellipses are defined with reference to their bounding rectangle. The comments above on the behavior of <codeph>TRect</codeph> also need to be observed when drawing ellipses. Arcs, pie slices and the corners of rounded rectangles are all defined as sections of an ellipse. </p> </section> </conbody><related-links><link href="GUID-55C8C429-1BEC-5A58-94EC-DA1E51F62867.dita"><linktext>Drawing

                to a Graphics Context Tutorials</linktext> </link> <link href="GUID-E3AC8F3E-9D5C-5E7D-9760-023B77C7C8A8.dita"><linktext>Drawing and Graphics Contexts</linktext> </link> <link href="GUID-25035286-5134-51F6-A3B6-C0DF0E802719.dita"><linktext>The Linear DDA</linktext> </link> </related-links></concept>