graphics.java

有关j2me的很好的例子可以研究一下

/*
 * @(#)Graphics.java	1.49 01/08/09
 * Copyright (c) 1999-2001 Sun Microsystems, Inc. All Rights Reserved.
 *
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 *
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
 * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
 * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
 * THIS SOFTWARE OR ITS DERIVATIVES.
 */
package javax.microedition.lcdui;

/**
 * Provides simple 2D geometric rendering capability.
 *
 * NOTE: all calls are unsynchronized, because multiple threads
 * should not be accessing the (lone) screen graphics context.
 * See ImageGraphics for the synchronized versions.
 *
 * Drawing primitives are provided for text, images, lines, rectangles,
 * and arcs. Rectangles and arcs may also be filled with a solid color.
 * Rectangles may also be specified with rounded corners. <p>
 *
 * The only drawing operation provided is pixel replacement. The
 * destination pixel value is simply replaced by the current
 * pixel value specified in the graphics object being used for
 * rendering. No facility for combining pixel values, such as
 * raster-ops or alpha blending, is provided. <p>
 *
 * A 24-bit color model is provided, with 8 bits for each of red, green, and
 * blue components of a color. Not all devices support a full 24 bits' worth
 * of color and thus they will map colors requested by the application into
 * colors available on the device. Facilities are provided in the {@link
 * Display Display} class for obtaining device characteristics, such as
 * whether color is available and how many distinct gray levels are available.
 * This enables applications to adapt their behavior to a device without
 * compromising device independence. <p>
 *
 * Graphics may be rendered directly to the display or to an off-screen
 * image buffer. The destination of rendered graphics depends on the
 * provenance of the graphics object. A graphics object for rendering
 * to the display is passed to the Canvas object's
 * {@link Canvas#paint(Graphics) paint()}
 * method. This is the only means by which a graphics object may
 * be obtained whose destination is the display. Furthermore, applications
 * may draw using this graphics object only for the duration of the
 * paint() method. <p>
 *
 * A graphics object for rendering to an off-screen image buffer may
 * be obtained by calling the
 * {@link Image#getGraphics() getGraphics()}
 * method on the desired image.
 * A graphics object so obtained may be held indefinitely
 * by the application, and requests may be issued on this graphics
 * object at any time. <p>
 *
 * The default coordinate system's origin is at the
 * upper left-hand corner of the destination. The X-axis direction is
 * positive towards the right, and the Y-axis direction is positive
 * downwards. Applications may assume that horizontal and vertical
 * distances in the coordinate system represent equal distances on the
 * actual device display, that is, pixels are square. A facility is provided
 * for translating the origin of the coordinate system.
 * All coordinates are specified as integers. <p>
 *
 * The coordinate system represents locations between pixels, not the
 * pixels themselves. Therefore, the first pixel in the upper left corner
 * of the display lies in the square bounded by coordinates
 * (0,0) , (1,0) , (0,1) , (1,1). <p>
 *
 * Under this definition, the semantics for fill operations are clear.
 * Since coordinate grid lines lie between pixels, fill operations
 * affect pixels that lie entirely within the region bounded by the
 * coordinates of the operation. For example, the operation
 * <pre>
 *    g.fillRect(0, 0, 3, 2)
 * </pre>
 * paints exactly six pixels.  (In this example, and in all subsequent 
 * examples, the variable <code>g</code> is assumed to contain a reference to a 
 * Graphics object.) <p>
 *
 * Each character of a font contains a set of pixels that forms the shape of
 * the character.  When a character is painted, the pixels forming the
 * character's shape are filled with the Graphics object's current color, and
 * the pixels not part of the character's shape are left untouched.
 * The text drawing calls
 * {@link #drawChar drawChar()},
 * {@link #drawChars drawChars()},
 * {@link #drawString drawString()}, and
 * {@link #drawSubstring drawSubstring()}
 * all draw text in this manner. <p>
 *
 * Lines, arcs, rectangles, and rounded rectangles may be drawn with either a
 * SOLID or a DOTTED stroke style, as set by the {@link #setStrokeStyle
 * setStrokeStyle()} method.  The stroke style does not affect fill, text, and
 * image operations. <p>
 * 
 * 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. Thus, the operation
 * <pre>
 *    g.drawLine(0, 0, 0, 0)
 * </pre>
 * paints exactly one pixel, the first pixel in the upper left corner
 * of the display. <p>
 *
 * Drawing operations under the DOTTED stroke style will touch a subset of 
 * pixels that would have been touched under the SOLID stroke style.  The 
 * frequency and length of dots is implementation-dependent.  The endpoints of 
 * lines and arcs are not guaranteed to be drawn, nor are the corner points of 
 * rectangles guaranteed to be drawn.  Dots are drawn by painting with the 
 * current color; spaces between dots are left untouched. <p>
 *
 * An artifact of the coordinate system is that the area affected by a fill
 * operation differs slightly from the area affected by a draw operation given
 * the same coordinates. For example, consider the operations
 * <pre>
 *    g.fillRect(x, y, w, h); // 1
 *    g.drawRect(x, y, w, h); // 2
 * </pre>
 * Statement (1) fills a rectangle w pixels wide and h pixels high.
 * Statement (2) draws a rectangle whose left and top
 * edges are within the area filled by statement (1). However, the
 * bottom and right edges lie one pixel outside the filled area.
 * This is counterintuitive, but it preserves the invariant that
 * <pre>
 *    g.drawLine(x, y, x+w, y);
 *    g.drawLine(x+w, y, x+w, y+h);
 *    g.drawLine(x+w, y+h, x, y+h);
 *    g.drawLine(x, y+h, x, y);
 * </pre>
 * has an effect identical to statement (2) above. <p>
 *
 * The exact pixels painted by drawLine() and drawArc() are not
 * specified. Pixels touched by a fill operation must either
 * exactly overlap or directly abut pixels touched by the
 * corresponding draw operation. A fill operation must never leave
 * a gap between the filled area and the pixels touched by the
 * corresponding draw operation, nor may the fill operation touch
 * pixels outside the area bounded by the corresponding draw operation. <p>
 *
 * There is a single clipping rectangle. Operations are provided for
 * intersecting the current clip rectangle with a given rectangle and for
 * setting the current clip rectangle outright. The only pixels touched by
 * graphics operations are those that lie entirely within the clip rectangle.
 * Pixels outside the clip rectangle are not affected by any graphics
 * operations. It is legal to specify a clipping rectangle whose width or
 * height is zero or negative. In this case the clipping rectangle is
 * considered to be empty, that is, no pixels are contained within it.
 * Therefore, if any graphics operations are issued under such a clipping
 * rectangle, no pixels will be modified. <p>
 *
 * If a graphics operation is affected by the clip rectangle, the pixels
 * touched by that operation must be the same ones that would be touched
 * as if the clip rectangle did not affect the operation. For example,
 * consider a clip rectangle (cx, cy, cw, ch) and a point (x1, y1) that
 * lies outside this rectangle and a point (x2, y2) that lies within this
 * rectangle. In the following code fragment,
 * <pre>
 *    g.setClip(0, 0, canvas.getWidth(), canvas.getHeight());
 *    g.drawLine(x1, y1, x2, y2); // 3
 *    g.setClip(cx, cy, cw, ch);
 *    g.drawLine(x1, y1, x2, y2); // 4
 * </pre>
 * 
 * The pixels touched by statement (4) must be identical to the pixels
 * within (cx, cy, cw, ch) touched by statement (3). <p>
 *
 * <a name="anchor"></a>
 * <h3>Anchor Points</h3> <p>
 *
 * The drawing of text is based on "anchor points".
 * Anchor points are used to minimize the amount of
 * computation required when placing text.
 * For example, in order to center a piece of text,
 * an application needs to call stringWidth() or
 * charWidth() to get the width and then perform a
 * combination of subtraction and division to
 * compute the proper location.
 * The method to draw text is defined as follows:
 * <pre>
 *    public void drawString(String text, int x, int y, int anchor);
 * </pre>
 * This method draws text in the current color,
 * using the current font
 * with its anchor point at (x,y). The definition
 * of the anchor point must be one of the
 * horizontal constants (LEFT, HCENTER, RIGHT)
 * combined with one of the vertical constants
 * (TOP, BASELINE, BOTTOM) using the logical OR operator. <p>
 *
 * Vertical centering of the text is not specified since it is not considered
 * useful, it is hard to specify, and it is burdensome to implement. Thus,
 * the VCENTER value is not allowed in the anchor point parameter of text
 * drawing calls. <p>
 *
 * The actual position of the bounding box
 * of the text relative to the (x, y) location is
 * determined by the anchor point. These anchor
 * points occur at named locations along the
 * outer edge of the bounding box. Thus, if <code>f</code>
 * is <code>g</code>'s current font (as returned by
 * <code>g.getFont()</code>, the following calls will all have
 * identical results:
 * <pre>
 *    g.drawString(str, x, y, TOP|LEFT);
 *    g.drawString(str, x + f.stringWidth(str)/2, y, TOP|HCENTER);
 *    g.drawString(str, x + f.stringWidth(str), y, TOP|RIGHT);
 *
 *    g.drawString(str, x,
 *        y + f.getBaselinePosition(), BASELINE|LEFT);
 *    g.drawString(str, x + f.stringWidth(str)/2,
 *        y + f.getBaselinePosition(), BASELINE|HCENTER);
 *    g.drawString(str, x + f.stringWidth(str),
 *        y + f.getBaselinePosition(), BASELINE|RIGHT);
 *
 *    drawString(str, x,
 *        y + f.getHeight(), BOTTOM|LEFT);
 *    drawString(str, x + f.stringWidth(str)/2,
 *        y + f.getHeight(), BOTTOM|HCENTER);
 *    drawString(str, x + f.stringWidth(str),
 *        y + f.getHeight(), BOTTOM|RIGHT);
 * </pre> <p>
 *
 * For text drawing, the inter-character and inter-line spacing (leading)
 * specified by the font designer are included as part of the values returned
 * in the {@link Font#stringWidth(java.lang.String) stringWidth()} 
 * and {@link Font#getHeight() getHeight()} 
 * calls of class {@link Font Font}.
 * For example, given the following code:
 * <pre>
 *    // (5)
 *    g.drawString(string1+string2, x, y, TOP|LEFT);
 *
 *    // (6)
 *    g.drawString(string1, x, y, TOP|LEFT);
 *    g.drawString(string2, x + f.stringWidth(string1), y, TOP|LEFT);
 * </pre>
 * Code fragments (5) and (6) behave identically. This
 * occurs because f.stringWidth()
 * includes the inter-character spacing.
 * Similarly, reasonable vertical spacing may be
 * achieved simply by adding the font height
 * to the Y-position of subsequent lines. For example:
 * <pre>
 *    g.drawString(string1, x, y, TOP|LEFT);
 *    g.drawString(string2, x, y + f.fontHeight(), TOP|LEFT);
 * </pre>
 * draws string1 and string2 on separate lines with
 * an appropriate amount of inter-line spacing. <p>
 *
 * The stringWidth() of the string and the fontHeight() of the font in which
 * it is drawn define the size of the bounding box of a piece of text. As
 * described above, this box includes inter-line and inter-character spacing.
 * The implementation is required to put this space below and to right of the
 * pixels actually belonging to the characters drawn. Applications that wish
 * to position graphics closely with respect text (for example, to paint a
 * rectangle around a string of text) may assume that there is space below and
 * to the right of a string and that there is <em>no</em> space above and to the
 * left of the string. <p>
 *
 * Anchor points are also used for positioning of images. Similar to text
 * drawing, the anchor point for an image specifies the point on the bounding
 * rectangle of the destination that is to positioned at the (x,y) location
 * given in the graphics request. Unlike text, vertical centering of images
 * is well-defined, and thus the VCENTER value may be used within the anchor
 * point parameter of image drawing requests. Because images have no notion
 * of a baseline, the BASELINE value may not be used within the anchor point
 * parameter of image drawing requests.
 */
public class Graphics {

    // SYNC NOTE: the main Graphics class is entirely unlocked.  There is only
    // one instance of Graphics (created in Display) and it is only ever legal
    // for the application to use it when the system calls the paint() method
    // of a Canvas.  Since paint() calls are serialized, and these methods
    // modify only instance state, no locking is necessary.  (If any method
    // were to read or modify global state, locking would need to be done in
    // those cases.)

    /**
     * <P>Constant for centering text and images horizontally
     * around the anchor point</P>
     *
     * <P>Value 1 is assigned to HCENTER.</P>
     */
    public static final int HCENTER = 1;

    /**
     * <P>Constant for centering images vertically
     * around the anchor point.</P>
     *
     * <P>Value 2 is assigned to VCENTER.</P>
     */
    public static final int VCENTER = 2;

    /**
     * <P>Constant for positioning the anchor point of text and images
     * to the left of the text or image.</P>
     *
     * <P>Value 4 is assigned to LEFT.</P>
     */
    public static final int LEFT = 4;

    /**
     * <P>Constant for positioning the anchor point of text and images
     * to the right of the text or image.</P>
     *
     * <P>Value 8 is assigned to RIGHT.</P>
     */
    public static final int RIGHT = 8;

    /**