/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @author Alexey A. Petrenko
* @version $Revision$
*/
package java.awt;
import java.awt.image.ImageObserver;
import java.text.AttributedCharacterIterator;
/**
* The abstract Graphics class allows applications to draw on a screen or other
* rendering target. There are several properties which define rendering
* options: origin point, clipping area, color, font. <br>
* <br>
* The origin point specifies the beginning of the clipping area coordinate
* system. All coordinates used in rendering operations are computed with
* respect to this point. The clipping area defines the boundaries where
* rendering operations can be performed. Rendering operations can't modify
* pixels outside of the clipping area. <br>
* <br>
* The draw and fill methods allow applications to drawing shapes, text, images
* with specified font and color options in the specified part of the screen.
*
* @since Android 1.0
*/
public abstract class Graphics {
// Constructors
/**
* Instantiates a new Graphics. This constructor is default for Graphics and
* can not be called directly.
*/
protected Graphics() {
}
// Public methods
/**
* Creates a copy of the Graphics object with a new origin and a new
* specified clip area. The new clip area is the rectangle defined by the
* origin point with coordinates X,Y and the given width and height. The
* coordinates of all subsequent rendering operations will be computed with
* respect to the new origin and can be performed only within the range of
* the clipping area dimensions.
*
* @param x
* the X coordinate of the original point.
* @param y
* the Y coordinate of the original point.
* @param width
* the width of clipping area.
* @param height
* the height of clipping area.
* @return the Graphics object with new origin point and clipping area.
*/
public Graphics create(int x, int y, int width, int height) {
Graphics res = create();
res.translate(x, y);
res.clipRect(0, 0, width, height);
return res;
}
/**
* Draws the highlighted outline of a rectangle.
*
* @param x
* the X coordinate of the rectangle's top left corner.
* @param y
* the Y coordinate of the rectangle's top left corner.
* @param width
* the width of rectangle.
* @param height
* the height of rectangle.
* @param raised
* a boolean value that determines whether the rectangle is drawn
* as raised or indented.
*/
public void draw3DRect(int x, int y, int width, int height, boolean raised) {
// Note: lighter/darker colors should be used to draw 3d rect.
// The resulting rect is (width+1)x(height+1). Stroke and paint
// attributes of
// the Graphics2D should be reset to the default values.
// fillRect is used instead of drawLine to bypass stroke
// reset/set and rasterization.
Color color = getColor();
Color colorUp, colorDown;
if (raised) {
colorUp = color.brighter();
colorDown = color.darker();
} else {
colorUp = color.darker();
colorDown = color.brighter();
}
setColor(colorUp);
fillRect(x, y, width, 1);
fillRect(x, y + 1, 1, height);
setColor(colorDown);
fillRect(x + width, y, 1, height);
fillRect(x + 1, y + height, width, 1);
}
/**
* Draws the text represented by byte array. This method uses the current
* font and color for rendering.
*
* @param bytes
* the byte array which contains the text to be drawn.
* @param off
* the offset within the byte array of the text to be drawn.
* @param len
* the number of bytes of text to draw.
* @param x
* the X coordinate where the text is to be drawn.
* @param y
* the Y coordinate where the text is to be drawn.
*/
public void drawBytes(byte[] bytes, int off, int len, int x, int y) {
drawString(new String(bytes, off, len), x, y);
}
/**
* Draws the text represented by character array. This method uses the
* current font and color for rendering.
*
* @param chars
* the character array.
* @param off
* the offset within the character array of the text to be drawn.
* @param len
* the number of characters which will be drawn.
* @param x
* the X coordinate where the text is to be drawn.
* @param y
* the Y coordinate where the text is to be drawn.
*/
public void drawChars(char[] chars, int off, int len, int x, int y) {
drawString(new String(chars, off, len), x, y);
}
/**
* Draws the outline of a polygon which is defined by Polygon object.
*
* @param p
* the Polygon object.
*/
public void drawPolygon(Polygon p) {
drawPolygon(p.xpoints, p.ypoints, p.npoints);
}
/**
* Draws the rectangle with the specified width and length and top left
* corner coordinates.
*
* @param x
* the X coordinate of the rectangle's top left corner.
* @param y
* the Y coordinate of the rectangle's top left corner.
* @param width
* the width of the rectangle.
* @param height
* the height of the rectangle.
*/
public void drawRect(int x, int y, int width, int height) {
int[] xpoints = {
x, x, x + width, x + width
};
int[] ypoints = {
y, y + height, y + height, y
};
drawPolygon(xpoints, ypoints, 4);
}
/**
* Fills the highlighted outline of a rectangle.
*
* @param x
* the X coordinate of the rectangle's top left corner.
* @param y
* the Y coordinate of the rectangle's top left corner.
* @param width
* the width of the rectangle.
* @param height
* the height of the rectangle.
* @param raised
* a boolean value that determines whether the rectangle is drawn
* as raised or indented.
*/
public void fill3DRect(int x, int y, int width, int height, boolean raised) {
// Note: lighter/darker colors should be used to draw 3d rect.
// The resulting rect is (width)x(height), same as fillRect.
// Stroke and paint attributes of the Graphics2D should be reset
// to the default values. fillRect is used instead of drawLine to
// bypass stroke reset/set and line rasterization.
Color color = getColor();
Color colorUp, colorDown;
if (raised) {
colorUp = color.brighter();
colorDown = color.darker();
setColor(color);
} else {
colorUp = color.darker();
colorDown = color.brighter();
setColor(colorUp);
}
width--;
height--;
fillRect(x + 1, y + 1, width - 1, height - 1);
setColor(colorUp);
fillRect(x, y, width, 1);
fillRect(x, y + 1, 1, height);
setColor(colorDown);
fillRect(x + width, y, 1, height);
fillRect(x + 1, y + height, width, 1);
}
/**
* Fills the polygon with the current color.
*
* @param p
* the Polygon object.
*/
public void fillPolygon(Polygon p) {
fillPolygon(p.xpoints, p.ypoints, p.npoints);
}
/**
* Disposes of the Graphics.
*/
@Override
public void finalize() {
}
/**
* Gets the bounds of the current clipping area as a rectangle and copies it
* to an existing rectangle.
*
* @param r
* a Rectangle object where the current clipping area bounds are
* to be copied.
* @return the bounds of the current clipping area.
*/
public Rectangle getClipBounds(Rectangle r) {
Shape clip = getClip();
if (clip != null) {
// TODO: Can we get shape bounds without creating Rectangle object?
Rectangle b = clip.getBounds();
r.x = b.x;
r.y = b.y;
r.width = b.width;
r.height = b.height;
}
return r;
}
/**
* Gets the bounds of the current clipping area as a rectangle.
*
* @return a Rectangle object.
* @deprecated Use {@link #getClipBounds()}
*/
@Deprecated
public Rectangle getClipRect() {
return getClipBounds();
}
/**
* Gets the font metrics of the current font. The font metrics object
* contains information about the rendering of a particular font.
*
* @return the font metrics of current font.
*/
public FontMetrics getFontMetrics() {
return getFontMetrics(getFont());
}
/**
* Determines whether or not the specified rectangle intersects the current
* clipping area.
*
* @param x
* the X coordinate of the rectangle.
* @param y
* the Y coordinate of the rectangle.
* @param width
* the width of the rectangle.
* @param height
* the height of the rectangle.
* @return true, if the specified rectangle intersects the current clipping
* area, false otherwise.
*/
public boolean hitClip(int x, int y, int width, int height) {
// TODO: Create package private method Rectangle.intersects(int, int,
// int, int);
return getClipBounds().intersects(new Rectangle(x, y, width, height));
}
/**
* Returns string which represents this Graphics object.
*
* @return the string which represents this Graphics object.
*/
@Override
public String toString() {
// TODO: Think about string representation of Graphics.
return "Graphics"; //$NON-NLS-1$
}
// Abstract methods
/**
* Clears the specified rectangle. This method fills specified rectangle
* with background color.
*
* @param x
* the X coordinate of the rectangle.
* @param y
* the Y coordinate of the rectangle.
* @param width
* the width of the rectangle.
* @param height
* the height of the rectangle.
*/
public abstract void clearRect(int x, int y, int width, int height);
/**
* Intersects the current clipping area with a new rectangle. If the current
* clipping area is not defined, the rectangle becomes a new clipping area.
* Rendering operations are only allowed within the new the clipping area.
*
* @param x
* the X coordinate of the rectangle for intersection.
* @param y
* the Y coordinate of the rectangle for intersection.
* @param width
* the width of the rectangle for intersection.
* @param height
* the height of the rectangle for intersection.
*/
public abstract void clipRect(int x, int y, int width, int height);
/**
* Copies the rectangle area to another area specified by a distance (dx,
* dy) from the original rectangle's location. Positive dx and dy values
* give a new location defined by translation to the right and down from the
* original location, negative dx and dy values - to the left and up.
*
* @param sx
* the X coordinate of the rectangle which will be copied.
* @param sy
* the Y coordinate of the rectangle which will be copied.
* @param width
* the width of the rectangle which will be copied.
* @param height
* the height of the rectangle which will be copied.
* @param dx
* the horizontal distance from the source rectangle's location
* to the copy's location.
* @param dy
* the vertical distance from the source rectangle's location to
* the copy's location.
*/
public abstract void copyArea(int sx, int sy, int width, int height, int dx, int dy);
/**
* Creates a new copy of this Graphics.
*
* @return a new Graphics context which is a copy of this Graphics.
*/
public abstract Graphics create();
/**
* Disposes of the Graphics. This Graphics object can not be used after
* calling this method.
*/
public abstract void dispose();
/**
* Draws the arc covering the specified rectangle and using the current
* color. The rectangle is defined by the origin point (X, Y) and dimensions
* (width and height). The arc center is the the center of specified
* rectangle. The angle origin is 3 o'clock position, the positive angle is
* counted as a counter-clockwise rotation, the negative angle is counted as
* clockwise rotation.
*
* @param x
* the X origin coordinate of the rectangle which scales the arc.
* @param y
* the Y origin coordinate of the rectangle which scales the arc.
* @param width
* the width of the rectangle which scales the arc.
* @param height
* the height of the rectangle which scales the arc.
* @param sa
* start angle - the origin angle of arc.
* @param ea
* arc angle - the angular arc value relative to the start angle.
*/
public abstract void drawArc(int x, int y, int width, int height, int sa, int ea);
/**
* Draws the specified image with the defined background color. The top left
* corner of image will be drawn at point (x, y) in current coordinate
* system. The image loading process notifies the specified Image Observer.
* This method returns true if the image has loaded, otherwise it returns
* false.
*
* @param img
* the image which will be drawn.
* @param x
* the X coordinate of the image top left corner.
* @param y
* the Y coordinate of the image top left corner.
* @param bgcolor
* the background color.
* @param observer
* the ImageObserver object which should be notified about image
* loading process.
* @return true, if loading image is successful or image is null, false
* otherwise.
*/
public abstract boolean drawImage(Image img, int x, int y, Color bgcolor, ImageObserver observer);
/**
* Draws the specified image. The top left corner of image will be drawn at
* point (x, y) in current coordinate system. The image loading process
* notifies the specified Image Observer. This method returns true if the
* image has loaded, otherwise it returns false.
*
* @param img
* the image which will be drawn.
* @param x
* the X coordinate of the image top left corner.
* @param y
* the Y coordinate of the image top left corner.
* @param observer
* the ImageObserver object which should be notified about image
* loading process.
* @return true, if loading image is successful or image is null, otherwise
* false.
*/
public abstract boolean drawImage(Image img, int x, int y, ImageObserver observer);
/**
* Scales the specified image to fit in the specified rectangle and draws it
* with the defined background color. The top left corner of the image will
* be drawn at the point (x, y) in current coordinate system. The non-opaque
* pixels will be drawn in the background color. The image loading process
* notifies the specified Image Observer. This method returns true if the
* image has loaded, otherwise it returns false.
*
* @param img
* the image which will be drawn.
* @param x
* the X coordinate of the image's top left corner.
* @param y
* the Y coordinate of the image's top left corner.
* @param width
* the width of rectangle which scales the image.
* @param height
* the height of rectangle which scales the image.
* @param bgcolor
* the background color.
* @param observer
* the ImageObserver object which should be notified about image
* loading process.
* @return true, if loading image is successful or image is null, otherwise
* false.
*/
public abstract boolean drawImage(Image img, int x, int y, int width, int height,
Color bgcolor, ImageObserver observer);
/**
* Scales the specified image to fit in the specified rectangle and draws
* it. The top left corner of the image will be drawn at the point (x, y) in
* current coordinate system. The image loading process notifies the
* specified Image Observer. This method returns true if the image has
* loaded, otherwise it returns false.
*
* @param img
* the image which will be drawn.
* @param x
* the X coordinate of the image top left corner.
* @param y
* the Y coordinate of the image top left corner.
* @param width
* the width of rectangle which scales the image.
* @param height
* the height of rectangle which scales the image.
* @param observer
* the ImageObserver object which should be notified about image
* loading process.
* @return true, if loading image is successful or image is null, otherwise
* false.
*/
public abstract boolean drawImage(Image img, int x, int y, int width, int height,
ImageObserver observer);
/**
* Scales the specified area of the specified image to fit in the rectangle
* area defined by its corners coordinates and draws the sub-image with the
* specified background color. The sub-image to be drawn is defined by its
* top left corner coordinates (sx1, sy1) and bottom right corner
* coordinates (sx2, sy2) computed with respect to the origin (top left
* corner) of the source image. The non opaque pixels will be drawn in the
* background color. The image loading process notifies specified Image
* Observer. This method returns true if the image has loaded, otherwise it
* returns false.
*
* @param img
* the image which will be drawn.
* @param dx1
* the X top left corner coordinate of the destination rectangle
* area.
* @param dy1
* the Y top left corner coordinate of the destination rectangle
* area.
* @param dx2
* the X bottom right corner coordinate of the destination
* rectangle area.
* @param dy2
* the Y bottom right corner coordinate of the destination
* rectangle area.
* @param sx1
* the X top left corner coordinate of the area to be drawn
* within the source image.
* @param sy1
* the Y top left corner coordinate of the area to be drawn
* within the source image.
* @param sx2
* the X bottom right corner coordinate of the area to be drawn
* within the source image.
* @param sy2
* the Y bottom right corner coordinate of the area to be drawn
* within the source image.
* @param bgcolor
* the background color.
* @param observer
* the ImageObserver object which should be notified about image
* loading process.
* @return true, if loading image is successful or image is null, false
* otherwise.
*/
public abstract boolean drawImage(Image img, int dx1, int dy1, int dx2, int dy2, int sx1,
int sy1, int sx2, int sy2, Color bgcolor, ImageObserver observer);
/**
* Scales the specified area of the specified image to fit in the rectangle
* area defined by its corners coordinates and draws the sub-image. The
* sub-image to be drawn is defined by its top left corner coordinates (sx1,
* sy1) and bottom right corner coordinates (sx2, sy2) computed with respect
* to the origin (top left corner) of the source image. The image loading
* process notifies specified Image Observer. This method returns true if
* the image has loaded, otherwise it returns false.
*
* @param img
* the image which will be drawn.
* @param dx1
* the X top left corner coordinate of the destination rectangle
* area.
* @param dy1
* the Y top left corner coordinate of the destination rectangle
* area.
* @param dx2
* the X bottom right corner coordinate of the destination
* rectangle area.
* @param dy2
* the Y bottom right corner coordinate of the destination
* rectangle area.
* @param sx1
* the X top left corner coordinate of the area to be drawn
* within the source image.
* @param sy1
* the Y top left corner coordinate of the area to be drawn
* within the source image.
* @param sx2
* the X bottom right corner coordinate of the area to be drawn
* within the source image.
* @param sy2
* the Y bottom right corner coordinate of the area to be drawn
* within the source image.
* @param observer
* the ImageObserver object which should be notified about image
* loading process.
* @return true, if loading image is successful or image is null, false
* otherwise.
*/
public abstract boolean drawImage(Image img, int dx1, int dy1, int dx2, int dy2, int sx1,
int sy1, int sx2, int sy2, ImageObserver observer);
/**
* Draws a line from the point (x1, y1) to the point (x2, y2). This method
* draws the line with current color which can be changed by setColor(Color
* c) method.
*
* @param x1
* the X coordinate of the first point.
* @param y1
* the Y coordinate of the first point.
* @param x2
* the X coordinate of the second point.
* @param y2
* the Y coordinate of the second point.
*/
public abstract void drawLine(int x1, int y1, int x2, int y2);
/**
* Draws the outline of an oval to fit in the rectangle defined by the given
* width, height, and top left corner.
*
* @param x
* the X top left corner oval coordinate.
* @param y
* the Y top left corner oval coordinate.
* @param width
* the oval width.
* @param height
* the oval height.
*/
public abstract void drawOval(int x, int y, int width, int height);
/**
* Draws the outline of a polygon. The polygon vertices are defined by
* points with xpoints[i], ypoints[i] as coordinates. The polygon edges are
* the lines from the points with (xpoints[i-1], ypoints[i-1]) coordinates
* to the points with (xpoints[i], ypoints[i]) coordinates, for 0 < i <
* npoints +1.
*
* @param xpoints
* the array of X coordinates of the polygon vertices.
* @param ypoints
* the array of Y coordinates of the polygon vertices.
* @param npoints
* the number of polygon vertices/points.
*/
public abstract void drawPolygon(int[] xpoints, int[] ypoints, int npoints);
/**
* Draws a set of connected lines which are defined by the x and y
* coordinate arrays. The polyline is closed if coordinates of the first
* point are the same as coordinates of the last point.
*
* @param xpoints
* the array of X point coordinates.
* @param ypoints
* the array of Y point coordinates.
* @param npoints
* the number of points.
*/
public abstract void drawPolyline(int[] xpoints, int[] ypoints, int npoints);
/**
* Draws the outline of a rectangle with round corners.
*
* @param x
* the X coordinate of the rectangle's top left corner.
* @param y
* the Y coordinate of the rectangle's top left corner.
* @param width
* the width of the rectangle.
* @param height
* the height of the rectangle.
* @param arcWidth
* the arc width for the corners.
* @param arcHeight
* the arc height for the corners.
*/
public abstract void drawRoundRect(int x, int y, int width, int height, int arcWidth,
int arcHeight);
/**
* Draws a text defined by an iterator. The iterator should specify the font
* for every character.
*
* @param iterator
* the iterator.
* @param x
* the X coordinate of the first character.
* @param y
* the Y coordinate of the first character.
*/
public abstract void drawString(AttributedCharacterIterator iterator, int x, int y);
/**
* Draws a text defined by a string. This method draws the text with current
* font and color.
*
* @param str
* the string.
* @param x
* the X coordinate of the first character.
* @param y
* the Y coordinate of the first character.
*/
public abstract void drawString(String str, int x, int y);
/**
* Fills the arc covering the rectangle and using the current color. The
* rectangle is defined by the origin point (X, Y) and dimensions (width and
* height). The arc center is the the center of specified rectangle. The
* angle origin is at the 3 o'clock position, and a positive angle gives
* counter-clockwise rotation, a negative angle gives clockwise rotation.
*
* @param x
* the X origin coordinate of the rectangle which scales the arc.
* @param y
* the Y origin coordinate of the rectangle which scales the arc.
* @param width
* the width of the rectangle which scales the arc.
* @param height
* the height of the rectangle which scales the arc.
* @param sa
* start angle - the origin angle of arc.
* @param ea
* arc angle - the angular arc value relative to the start angle.
*/
public abstract void fillArc(int x, int y, int width, int height, int sa, int ea);
/**
* Fills an oval with the current color where the oval is defined by the
* bounding rectangle with the given width, height, and top left corner.
*
* @param x
* the X top left corner oval coordinate.
* @param y
* the Y top left corner oval coordinate.
* @param width
* the oval width.
* @param height
* the oval height.
*/
public abstract void fillOval(int x, int y, int width, int height);
/**
* Fills a polygon with the current color. The polygon vertices are defined
* by the points with xpoints[i], ypoints[i] as coordinates. The polygon
* edges are the lines from the points with (xpoints[i-1], ypoints[i-1])
* coordinates to the points with (xpoints[i], ypoints[i]) coordinates, for
* 0 < i < npoints +1.
*
* @param xpoints
* the array of X coordinates of the polygon vertices.
* @param ypoints
* the array of Y coordinates of the polygon vertices.
* @param npoints
* the number of polygon vertices/points.
*/
public abstract void fillPolygon(int[] xpoints, int[] ypoints, int npoints);
/**
* Fills a rectangle with the current color. The rectangle is defined by its
* width and length and top left corner coordinates.
*
* @param x
* the X coordinate of the rectangle's top left corner.
* @param y
* the Y coordinate of the rectangle's top left corner.
* @param width
* the width of rectangle.
* @param height
* the height of rectangle.
*/
public abstract void fillRect(int x, int y, int width, int height);
/**
* Fills a round cornered rectangle with the current color.
*
* @param x
* the X coordinate of the top left corner of the bounding
* rectangle.
* @param y
* the Y coordinate of the top left corner of the bounding
* rectangle.
* @param width
* the width of the bounding rectangle.
* @param height
* the height of the bounding rectangle.
* @param arcWidth
* the arc width at the corners.
* @param arcHeight
* the arc height at the corners.
*/
public abstract void fillRoundRect(int x, int y, int width, int height, int arcWidth,
int arcHeight);
/**
* Gets the clipping area. <br>
* <br>
*
* @return a Shape object of the clipping area or null if it is not set.
*/
public abstract Shape getClip();
/**
* Gets the bounds of the current clipping area as a rectangle.
*
* @return a Rectangle object which represents the bounds of the current
* clipping area.
*/
public abstract Rectangle getClipBounds();
/**
* Gets the current color of Graphics.
*
* @return the current color.
*/
public abstract Color getColor();
/**
* Gets the current font of Graphics.
*
* @return the current font.
*/
public abstract Font getFont();
/**
* Gets the font metrics of the specified font. The font metrics object
* contains information about the rendering of a particular font.
*
* @param font
* the specified font.
* @return the font metrics for the specified font.
*/
public abstract FontMetrics getFontMetrics(Font font);
/**
* Sets the new clipping area specified by rectangle. The new clipping area
* doesn't depend on the window's visibility. Rendering operations can't be
* performed outside new clipping area.
*
* @param x
* the X coordinate of the new clipping rectangle.
* @param y
* the Y coordinate of the new clipping rectangle.
* @param width
* the width of the new clipping rectangle.
* @param height
* the height of the new clipping rectangle.
*/
public abstract void setClip(int x, int y, int width, int height);
/**
* Sets the new clipping area to be the area specified by Shape object. The
* new clipping area doesn't depend on the window's visibility. Rendering
* operations can't be performed outside new clipping area.
*
* @param clip
* the Shape object which represents new clipping area.
*/
public abstract void setClip(Shape clip);
/**
* Sets the current Graphics color. All rendering operations with this
* Graphics will use this color.
*
* @param c
* the new color.
*/
public abstract void setColor(Color c);
/**
* Sets the current Graphics font. All rendering operations with this
* Graphics will use this font.
*
* @param font
* the new font.
*/
public abstract void setFont(Font font);
/**
* Sets the paint mode for the Graphics which overwrites all rendering
* operations with the current color.
*/
public abstract void setPaintMode();
/**
* Sets the XOR mode for the Graphics which changes a pixel from the current
* color to the specified XOR color. <br>
* <br>
*
* @param color
* the new XOR mode.
*/
public abstract void setXORMode(Color color);
/**
* Translates the origin of Graphics current coordinate system to the point
* with X, Y coordinates in the current coordinate system. All rendering
* operation in this Graphics will be related to the new origin.
*
* @param x
* the X coordinate of the origin.
* @param y
* the Y coordinate of the origin.
*/
public abstract void translate(int x, int y);
}