Programming Wireless Devices with the Java2 Platform

11.3 Graphics

All graphical operations are performed using a Graphics object. This object encapsulates a context for drawing to a particular target entity, including the current drawing color, clip region, line style, and so on.

11.3.1 Coordinate System

The coordinate system's default origin is located at the upper-left corner, with the numeric values of the x-coordinates monotonically increasing from left to right, and the numeric values of the y-coordinates monotonically increasing from top to bottom.

Applications may assume that the horizontal and vertical values of the coordinate system represent equal distances on the actual device display. If the shape of the pixels of the device is significantly different from square, the device does the required coordinate transformation.

The coordinate system represents the locations of pixels, not the pixels themselves. Pixels have a width and height equal to 1 and extend down and to the left of their locating point. For example, the pixel in the upper-left corner of the display is defined as (0,0) and covers the area where 0 <= x < 1 and 0 <= y < 1. All coordinates are specified as integers. (See Figure 11.1.)

11.3.2 Clipping

Each Graphics object has a single rectangular clip region; only those pixels within the clip region are modified by graphics operations. Operations are provided for intersecting the current clip rectangle with a given rectangle (Graphics.clipRect) and for setting the current clip rectangle outright (Graphics.setClip). The methods Graphics.getClipWidth, Graphics.getClipHeight, Graphics.getClipX, and Graphics.getClipY are used for obtaining the current clip region.

11.3.3 Translation

The coordinate system described above can be translated independently for each Graphics object. Translation is useful when a series of rendering operations need to be performed relative to some arbitrary point. Instead of recomputing the parameters for each rendering operation relative to the point, the origin can be translated to the point's location so that the rendering operations are performed relative to the new origin.

The method Graphics.translate moves the location of the origin by the specified horizontal and vertical offsets. All subsequent operations for that Graphics object will be performed relative to the translated origin. The current origin can be retrieved using the methods Graphics.getTranslateX and Graphics.getTranslateY.

Since the translation offsets are relative to the current origin, multiple translation operations have a cumulative effect. For example, calling translate(20, 50) followed by translate(3, 7) has the same effect as calling translate(23, 57).

Translation does not affect the physical location of the clip region; that is, it contains the same set of pixels before and after translation. However, since the methods for retrieving the clip region are in terms of the current coordinate system, their return values may change to reflect the new origin.

11.3.4 Color Model

Both color and gray-scale models are supported concurrently. The 24-bit color model has eight bits for each of red, green, and blue. The current drawing color is set using the method Graphics.setColor. The current color is used for all lines, text, and fills for rectangles and arcs. Separate background and foreground colors are not supported by the low-level user interface APIs.

Few devices support a full 24 bits of color, so the device maps the color requested by the application to the nearest color that is available on the device. The device color that is mapped to a given RGB color can be determined by calling the method Graphics.getDisplayColor.

The Display.isColor method returns true if the display is capable of supporting multiple colors, and false if the display supports gray-scale or black and white only. The number of distinct color or gray levels is available by calling the method Display.numColors. The color values are converted to gray-scale values by the device. The gray-scale equivalent can be retrieved with method getGrayScale after a color has been set.

Gray-scale is supported with values within the range of 0 to 255. The current gray-scale value is set with the method Graphics.setGrayScale. The device maps the values into the number of gray levels in the display. The corresponding color is available after setting a gray-scale value by calling the method Graphics.getColor.

11.3.5 Line Styles

Lines, arcs, rectangles, and rounded rectangles can be drawn with either a SOLID or a DOTTED stroke style, as set by the Graphics.setStrokeStyle method. The stroke style does not affect the fill, text, and image operations.

For the SOLID stroke style, drawing operations are performed with a one pixel-wide pen that fills the pixel immediately below and to the right of the specified coordinate. Drawn lines touch pixels at both endpoints.

Drawing operations under the DOTTED stroke style touches a subset of pixels that would have been touched under the SOLID stroke style. The frequency and length of dots is device-dependent. The endpoints of lines and arcs might not be drawn. Similarly, the corner points of rectangles might not be drawn. Dots are drawn by painting with the current color, and spaces between dots are left untouched.

11.3.6 Fonts

Each Graphics object has an associated Font object that is used for text rendering operations. The methods Graphics.setFont and Graphics.getFont are used to set and retrieve the current Font. Calling the method Graphics.setFont(null) restores the default font, which can be obtained by calling the method Font.getDefaultFont.

The Font.getFont method returns the Font object associated with a given set of style, size, and face attributes. The following attributes can be used to request a Font (from the Font class):

• Size: SMALL, MEDIUM, LARGE

• Face: PROPORTIONAL, MONOSPACE, SYSTEM

• Style: PLAIN, BOLD, ITALIC, UNDERLINED

It is up to the device to select a device font that most closely matches the requested attributes. J2ME devices typically have a limited number of fonts with a fixed set of styles, sizes, and faces; therefore, several attribute combinations may be mapped to the same device font.

The Font class also provides methods to access font metrics. These metrics allow an application to precisely place text relative to other graphics. The Font class methods charWidth, charsWidth, stringWidth, and substringWidth can be used to determine the widths of strings, characters, and arrays of characters. Vertical metrics can be obtained using the methods getHeight and getBaselinePosition. The white space for inter line and inter character spacing is included in the metrics, and is below and to the right of the characters, respectively.