graphics.java

j2me设计的界面包

/*
 * Copyright 2008 Sun Microsystems, Inc.  All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Sun designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Sun in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
 * CA 95054 USA or visit www.sun.com if you need additional information or
 * have any questions.
 */
package com.sun.lwuit;

/**
 * Abstracts the underlying platform graphics context thus allowing us to achieve
 * portability between MIDP devices and CDC devices. This abstaction simplifies
 * and unifies the Graphics implementations of various platforms.
 * 
 * <p>A graphics instance is never created by the developer and is always accessed
 * using either a paint callback or a mutable image. There is no way to create this
 * object directly.
 */
public final class Graphics {

    private javax.microedition.lcdui.Graphics g;
    private int xTranslate;
    private int yTranslate;
    private Font current = Font.getDefaultFont();
    /**
     * Cache value for the fillRect method
     */
    private int[] rgbArr;

    /**
     * This flag indicates if the drawRGB method is able to draw negative x and y
     * In drawRGB method, some devices such as BlackBerry throw exceptions if you
     * try to give negative values to drawRGB method.
     */
    private static boolean drawNegativeOffsetsInRGB = true;

    /**
     * Constructs a new Graphics object.
     */
    Graphics() {
    }

    /**
     * Constructing new graphics with a given javax.microedition.lcdui.Graphics 
     * @param g a given javax.microedition.lcdui.Graphics
     */
    Graphics(javax.microedition.lcdui.Graphics g) {
        setGraphics(g);
    }

    /**
     * Setting graphics with a given javax.microedition.lcdui.Graphics
     * 
     * @param g a given javax.microedition.lcdui.Graphics
     */
    void setGraphics(javax.microedition.lcdui.Graphics g) {
        this.g = g;
    }

    /**
     * Returns javax.microedition.lcdui.Graphics
     * 
     * @return a javax.microedition.lcdui.Graphics object
     */
    javax.microedition.lcdui.Graphics getGraphics() {
        return g;
    }

    /**
     * Translates the X/Y location for drawing on the underlying surface. Translation
     * is incremental so the new value will be added to the current translation and
     * in order to reset translation we have to invoke 
     * {@code translate(-getTranslateX(), -getTranslateY()) }
     * 
     * @param x the x coordinate
     * @param y the y coordinate
     */
    public void translate(int x, int y) {
        xTranslate += x;
        yTranslate += y;
    }

    /**
     * Returns the current x translate value 
     * 
     * @return the current x translate value 
     */
    public int getTranslateX() {
        return xTranslate;
    }

    /**
     * Returns the current y translate value 
     * 
     * @return the current y translate value 
     */
    public int getTranslateY() {
        return yTranslate;
    }

    /**
     * Returns the current color
     * 
     * @return the RGB graphics color 
     */
    public int getColor() {
        return g.getColor();
    }

    /**
     * Sets the current rgb color while ignoring any potential alpha component within
     * said color value.
     * 
     * @param RGB the RGB value for the color.
     */
    public void setColor(int RGB) {
        g.setColor(RGB);
    }

    /**
     * Returns the font used with the drawString method calls 
     * 
     * @return the font used with the drawString method calls
     */
    public Font getFont() {
        return current;
    }

    /**
     * Sets the font to use with the drawString method calls 
     * 
     * @param font the font used with the drawString method calls
     */
    public void setFont(Font font) {
        this.current = font;
    }

    /**
     * Sets the javax.microedition.lcdui.Font to use with the 
     * drawString method calls
     * 
     * @param font the javax.microedition.lcdui.Font
     */
    void setFont(javax.microedition.lcdui.Font font) {
        g.setFont(font);
    }

    /**
     * Returns the x clipping position
     * 
     * @return the x clipping position
     */
    public int getClipX() {
        return g.getClipX() - xTranslate;
    }

    /**
     * Returns the y clipping position
     * 
     * @return the y clipping position
     */
    public int getClipY() {
        return g.getClipY() - yTranslate;
    }

    /**
     * Returns the clip width
     * 
     * @return the clip width
     */
    public int getClipWidth() {
        return g.getClipWidth();
    }

    /**
     * Returns the clip height
     * 
     * @return the clip height
     */
    public int getClipHeight() {
        return g.getClipHeight();
    }

    /**
     * Clips the given rectangle by intersecting with the current clipping region, this
     * method can thus only shrink the clipping region and never increase it.
     * 
     * @param x the x coordinate of the rectangle to intersect the clip with
     * @param y the y coordinate of the rectangle to intersect the clip with
     * @param width the width of the rectangle to intersect the clip with
     * @param height the height of the rectangle to intersect the clip with
     */
    public void clipRect(int x, int y, int width, int height) {
        g.clipRect(xTranslate + x, yTranslate + y, width, height);
    }

    /**
     * Updates the clipping region to match the given region exactly
     * 
     * @param x the x coordinate of the new clip rectangle.
     * @param y the y coordinate of the new clip rectangle.
     * @param width the width of the new clip rectangle.
     * @param height the height of the new clip rectangle.
     */
    public void setClip(int x, int y, int width, int height) {
        g.setClip(xTranslate + x, yTranslate + y, width, height);
    }

    /**
     * Draws a line between the 2 X/Y coordinates
     * 
     * @param x1 first x position
     * @param y1 first y position
     * @param x2 second x position
     * @param y2 second y position
     */
    public void drawLine(int x1, int y1, int x2, int y2) {
        g.drawLine(xTranslate + x1, yTranslate + y1, xTranslate + x2, yTranslate + y2);
    }

    /**
     * Fills the rectangle from the given position according to the width/height
     * minus 1 pixel according to the convnetion in Java.
     * 
     * @param x the x coordinate of the rectangle to be filled.
     * @param y the y coordinate of the rectangle to be filled.
     * @param width the width of the rectangle to be filled.
     * @param height the height of the rectangle to be filled.
     */
    public void fillRect(int x, int y, int width, int height) {
        g.fillRect(xTranslate + x, yTranslate + y, width, height);
    }

    /**
     * Draws a rectangle in the given coordinates
     * 
     * @param x the x coordinate of the rectangle to be drawn.
     * @param y the y coordinate of the rectangle to be drawn.
     * @param width the width of the rectangle to be drawn.
     * @param height the height of the rectangle to be drawn.
     */
    public void drawRect(int x, int y, int width, int height) {
        g.drawRect(xTranslate + x, yTranslate + y, width, height);
    }

    /**
     * Draws a rounded corner rectangle in the given coordinates with the arcWidth/height
     * matching the last two arguments respectively.
     * 
     * @param x the x coordinate of the rectangle to be drawn.
     * @param y the y coordinate of the rectangle to be drawn.
     * @param width the width of the rectangle to be drawn.
     * @param height the height of the rectangle to be drawn.
     * @param arcWidth the horizontal diameter of the arc at the four corners.
     * @param arcHeight the vertical diameter of the arc at the four corners.
     */
    public void drawRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight) {
        g.drawRoundRect(xTranslate + x, yTranslate + y, width, height, arcWidth, arcHeight);
    }

    /**
     * Makes the current color slightly lighter, this is useful for many visual effects
     * 
     * @param factor the degree of lightening a color per channel a number from 1 to 255
     */
    public void lighterColor(int factor) {
        int color = getColor();
        int r = color >> 16 & 0xff;
        int g = color >> 8 & 0xff;
        int b = color & 0xff;
        r = Math.min(0xff, r + factor);
        g = Math.min(0xff, g + factor);
        g = Math.min(0xff, b + factor);
        setColor(((r << 16) & 0xff0000) | ((g << 8) & 0xff00) | (b & 0xff));
    }
    
    /**
     * Makes the current color slightly darker, this is useful for many visual effects
     * 
     * @param factor the degree of lightening a color per channel a number from 1 to 255
     */
    public void darkerColor(int factor) {
        int color = getColor();
        int r = color >> 16 & 0xff;
        int g = color >> 8 & 0xff;
        int b = color & 0xff;
        r = Math.max(0, r - factor);
        g = Math.max(0, g - factor);
        g = Math.max(0, b - factor);
        setColor(((r << 16) & 0xff0000) | ((g << 8) & 0xff00) | (b & 0xff));
    }
    
    /**
     * Fills a rounded rectangle in the same way as drawRoundRect
     * 
     * @param x the x coordinate of the rectangle to be filled.
     * @param y the y coordinate of the rectangle to be filled.
     * @param width the width of the rectangle to be filled.
     * @param height the height of the rectangle to be filled.
     * @param arcWidth the horizontal diameter of the arc at the four corners.
     * @param arcHeight the vertical diameter of the arc at the four corners.
     * @see #drawRoundRect
     */
    public void fillRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight) {
        g.fillRoundRect(xTranslate + x, yTranslate + y, width, height, arcWidth, arcHeight);
    }

    /**
     * Fills a circular or eliptical arc based on the given angles and bounding 
     * box. The resulting arc begins at startAngle and extends for arcAngle 
     * degrees.
     * 
     * @param x the x coordinate of the upper-left corner of the arc to be filled.
     * @param y the y coordinate of the upper-left corner of the arc to be filled.
     * @param width the width of the arc to be filled.
     * @param height the height of the arc to be filled.
     * @param startAngle the beginning angle.
     * @param arcAngle the angular extent of the arc, relative to the start angle.
     */
    public void fillArc(int x, int y, int width, int height, int startAngle, int arcAngle) {
        g.fillArc(xTranslate + x, yTranslate + y, width, height, startAngle, arcAngle);