Programming Wireless Devices with the Java2 Platform

11.5 Drawing Primitives

The Graphics class provides various low-level drawing primitives. In general, drawing is started by calling the various methods of the Graphics object to set the color, translation, and clipping. Methods are available for drawing lines, various shapes, text, and Images. Each of the drawing primitives is explained next, along with a figure that illustrates their operation.

11.5.1 Drawing Lines

The Graphics.drawLine method draws a line from a starting point (x1,y1) to an ending point (x2,y2). The pixels are set to the value of the current color value. The lines are drawn with the current stroke style (see Section 11.3.5, "Line Styles.")

drawLine(int x1, int y1, int x2, int y2)

Since a pixel extends below and to the right of its point, the overall width and height of the line are one pixel larger than the difference between the two x values and the two y values, respectively. Thus, one pixel is drawn if (x1,y1) and (x2,y2) are identical.

Figure 11.5 shows the result of the following code:

g.drawLine(4, 1, 19, 7);

11.5.2 Drawing and Filling Arcs

The Graphics.drawArc method draws the outline of a circular or elliptical arc bounded by the a rectangle whose origin is (x,y) and whose size is specified by the width and height. The arc is drawn using the current color and stroke style, starting at startAngle degrees and extending for arcAngle degrees. The start angle is interpreted such that 0 degrees is at the 3 o'clock position. A positive angle indicates a counter-clockwise rotation, while a negative value indicates a clockwise rotation. See the following example code and Figure 11.6.

drawArc(int x, int y, int width, int height, int startAngle,
         int arcAngle)

The entire arc covers an area width+1 pixels wide by height+1 pixels tall. Nothing is drawn if either width or height is less than zero or if arcAngle is zero.

The angles are specified relative to the non-square extents of the bounding rectangle such that 45 degrees always falls on the line from the center of the ellipse to the upper-right corner of the bounding rectangle. As a result, if the bounding rectangle is noticeably longer in one axis than the other, the angles to the start and end of the arc segment are skewed farther along the longer axis of the bounds.

Figure 11.6 on the previous page shows an arc drawn starting at 45 degrees and extending for 315 degrees.

The Graphics.fillArc method draws and fills a circular or elliptical arc bounded by the specified rectangle. The filled region consists of the "pie wedge" region bounded by the arc segment as if drawn by drawArc, the radius extending from the center to this arc at startAngle degrees, and the radius extending from the center to this arc at startAngle + arcAngle degrees.

fillArc(int x, int y, int width, int height, int startAngle,
        int arcAngle)

Figure 11.7 shows the result of the following code:

g.fillArc(4, 1, 19, 7, 45, 315);

11.5.3 Drawing and Filling Rectangles

The Graphics.drawRect method draws a rectangle with the current color and stroke style. The upper-left corner of the resulting rectangle is located at (x,y) and covers an area width+1 pixels wide by height+1 pixels tall. Nothing is drawn if either width or height is less than zero.

drawRect(int x, int y, int width, int height)

Figure 11.8 shows the result of the following code:

g.drawRect(5, 2, 15, 8)

The Graphics.fillRect method fills rectangles with the current color. The upper-left corner of the resulting rectangle is located at (x,y) and covers an area width pixels wide by height pixels tall. Nothing is drawn if either width or height is less than one.

fillRect(int x, int y, int width, int height)

Figure 11.9 shows the result of the following code:

g.fillRect(5, 2, 15, 8);

11.5.4 Drawing and Filling Rounded Rectangles

The Graphics.drawRoundRect method draws a rectangle with rounded corners in the current color and stroke style. The resulting rectangle covers an area width+1 pixels wide by height+1 pixels tall. If either width or height is less than zero, nothing is drawn. The corners are rounded using a curve whose diameter measurements are arcWidth and arcHeight.

drawRoundRect(int x, int y, int width, int height, int arcWidth,
              int arcHeight)

Figure 11.10 shows the result of the following code:

g.drawRoundRect(4, 2, 16, 8, 6, 6);

The Graphics.fillRoundRect method fills rectangles with rounded corners in the current color. If either width or height is less than zero, nothing is drawn.

fillRoundRect(int x, int y, int width, int height, int arcWidth,
              int arcHeight)

Figure 11.11 shows the result of the following code:

g.fillRoundRect(4, 2, 16, 8, 6, 6);

11.5.5 Filling Triangles

The Graphics.fillTriangle method fills a triangle with the current color. The triangle is specified using three (x,y) coordinates which may be listed in any order.

fillTriangle(int x1, int y1, int x2, int y2, int x3, int y3)

Figure 11.12 shows the result of the following code:

g.fillTriangle(4, 2, 1, 14, 20, 10);

11.5.6 Drawing Text

Methods are provided for drawing text in the form of a single character, an array of characters, a string, or a portion of a string. The characters are rendered using the current drawing color of the Graphics object, and pixels within and around the characters are left unchanged.

drawChars(char[] ch, int offset, int length, int x, int y,
          int anchor)
drawChar(char ch, int x, int y, int anchor)
drawString(String s, int x, int y, int anchor)
drawSubstring(String s, int offset, int length, int x, int y,
             int anchor)

Character and line spacing are included in the values returned in the Font.stringWidth and Font.getHeight method calls. The inter line and inter character space is below and to the right of the pixels belonging to the characters drawn. Reasonable vertical spacing is achieved simply by adding the font height to the y-position of subsequent lines.

11.5.7 Drawing Images

Images can be drawn using the drawImage and drawRegion methods. The drawImage method is the simpler of the two and simply renders an entire Image at a specified location. Both methods use an anchor point to control where the image data is to be drawn.

[View full width]
drawImage(Image img, int x, int y, int anchor)
drawRegion(Image img, int x_src, int y_src, int width, int height, int transform, int x, 
int y, int anchor)

The drawImage method renders an entire Image at a location specified by x, y, and anchor. Figure 11.13 shows the result of the following example code:

drawImage(image, 11, 10, Graphics.RIGHT | Graphics.BOTTOM);

The drawRegion method is more complex. It renders a specific region in the source Image with one of several transforms applied. The transforms are defined in the Sprite class of the Game API and they provide rotations in 90-degree increments, with or without a mirror image across the vertical axis. (See Figure 11.14.)

Figure 11.15 shows the result of the following example code. (Note that the anchor point is evaluated in terms of the region to be drawn after the transform has been applied.)

drawRegion(image, 1, 1, 6, 4, Sprite.TRANS_ROT90,
          7, 7, Graphics.RIGHT | Graphics.BOTTOM);

11.5.8 Drawing RGB Data

The drawRGB method draws RGB color values to a rectangular region. The color values are provided in the form of an array of integers, with each element of the array containing one color value. The color values are drawn to a specified target region that is specified using a location, width, and height.

drawRGB(int[] rgb, int offset, int scanlength, int x, int y,
        int width, int height, boolean processAlpha)

The offset parameter specifies the index of the color value for the first pixel in the first row of the target region. The scanlength parameter controls the number of elements in the RGB array between the first pixel of successive rows of the target region. Any scanlength value can be used provided that the operation will not result in an invalid array index.

Color values are specified using the same form as the setColor method (0xAARRGGBB). The method's processAlpha parameter controls whether or not the alpha value (upper 8 bits) of each element is processed. If the alpha value is processed, the pixel will only be drawn if the alpha value is fully opaque (0xFF). For devices that support alpha blending, the pixel is blended with the target image based on the alpha value.

In the following code example, the offset is 2, so the color value for the first pixel in the first row corresponds to the array element with index 2. (Refer to Figure 11.16.) The scanlength is 7, so the index for the first pixel of the second row is obtained by adding 7 to the offset. The index for the first pixel of the third row is obtained by adding 7 once again.

int[] rgb = {
    0x848484, 0x4A4A4A, 0xBDBDBD, 0xFFFFFF, 0x4A4A4A, 0xDEDEDE,
    0xBDBDBD, 0x848484, 0x848484, 0x4A4A4A, 0xFFFFFF, 0x4A4A4A,
    0xBDBDBD, 0x848484, 0xFFFFFF, 0x848484, 0xDEDEDE, 0xBDBDBD,
    0xDEDEDE, 0xFFFFFF, 0xBDBDBD};
g.drawRGB(rgb, 2, 7, 4, 2, 5, 3, false);

11.5.9 Copying an Area of Pixels

The copyArea method copies a region of pixels from one location to another within the target Image. This method is useful for scrolling a region of pixels without having to render the pixels again. This method cannot be invoked on the screen Graphics object.

void copyArea(int x_src, int y_src, int width, int height,
              int x_dest, int y_dest, int anchor)

The source region is defined by the parameters x_src, y_src, width, and height. The contents of the region are copied to a region of the same dimensions at the location defined by x_dest, y_dest, and anchor.

The source and destination regions specified by this method may overlap; the implementation is responsible for copying the pixel data in the appropriate manner so that the rendered pixels appear to be a snapshot of the source pixels prior to the copy operation.

Figure 11.17 shows the result of the following line of code:

g.copyArea(4, 2, 6, 4, 18, 3, Graphics.TOP | Graphics.RIGHT);