|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.microedition.lcdui.Graphics
Provides simple 2D geometric rendering capability. 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.
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.
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 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.
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 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.
A graphics
object for rendering to an off-screen image buffer may be obtained by
calling the 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.
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.
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).
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
paints exactly six pixels. (In this example,
and in all subsequent examples, the variable g is assumed to contain
a reference to a Graphics object g.fillRect(0, 0, 3, 2)
Lines, arcs, rectangles, and rounded rectangles may be drawn with either a
SOLID
or DOTTED
stroke style, as set by the
setStrokeStyle(int)
method. The stroke style
does not affect 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. Thus, the operation
paints exactly one pixel, the first pixel in the upper left corner of the
display. g.drawLine(0, 0, 0, 0)
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. Dots are drawn by painting with the current color; spaces between dots are left untouched.
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
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.
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.
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,
Anchor Points
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:
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.
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 f is
g's current font (as returned by g.getFont()), the
following calls all have identical results:
The
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
Value 64 is assigned to BASELINE.
Value 32 is assigned to BOTTOM.
Value 1 is assigned to DOTTED.
Value 1 is assigned to HCENTER.
Value 4 is assigned to LEFT.
Value 8 is assigned to RIGHT.
Value 0 is assigned to SOLID
Value 16 is assigned to TOP.
Value 2 is assigned to VCENTER.
The resulting arc begins at startAngle and extends for
arcAngle degrees, using the current color. Angles are
interpreted such that 0 degrees is at the 3 o'clock position. A
positive value indicates a counter-clockwise rotation while a
negative value indicates a clockwise rotation.
The center of the arc is the center of the rectangle whose origin
is (x, y) and whose size is specified by the
width and height arguments.
The resulting arc 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 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 will be skewed farther along
the longer axis of the bounds.
The resulting arc begins at startAngle and extends for
arcAngle degrees. Angles are interpreted such that 0 degrees
is at the 3 o'clock position. A positive value indicates a
counter-clockwise rotation while a negative value indicates a
clockwise rotation.
The center of the arc is the center of the rectangle whose origin is
(x, y) and whose size is specified by the
width and height arguments.
If either width or height is zero or less, nothing is drawn.
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 radius extending from the
center to this arc at startAngle + arcAngle degrees.
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 will be
skewed farther along the longer axis of the bounds.
The effect of calls to translate() are cumulative. For example,
calling translate(1, 2) and then translate(3, 4) results in a
translation of (4, 6).
The application can set an absolute origin (ax, ay) using the
following technique:
g.fillRect(x, y, w, h); // 1
g.drawRect(x, y, w, h); // 2
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
has an effect identical to statement (2) above.
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);
The pixels touched by statement (4) must be identical to the
pixels within (cx, cy, cw, ch) touched by statement (3).
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
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 (
public void drawString(String text, int x, int y, int anchor);
LEFT
,
HCENTER
, RIGHT
) combined
with one of the vertical constants (TOP
,
BASELINE
, BOTTOM
) using the logical OR
operator.
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
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);
g.drawString(str, x,
y + f.getHeight(), BOTTOM|LEFT);
g.drawString(str, x + f.stringWidth(str)/2,
y + f.getHeight(), BOTTOM|HCENTER);
g.drawString(str, x + f.stringWidth(str),
y + f.getHeight(), BOTTOM|RIGHT);
stringWidth()
and getHeight()
calls. For example, given the
following code:
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:
// (5)
g.drawString(string1+string2, x, y, TOP|LEFT);
// (6)
g.drawString(string1, x, y, TOP|LEFT);
Font f = Font.getFont();
g.drawString(string2, x + f.stringWidth(string1), y, TOP|LEFT);
draws string1 and string2 on separate lines with an
appropriate amount of inter-line spacing.
g.drawString(string1, x, y, TOP|LEFT);
g.drawString(string2, x, y + getFont().getHeight(), TOP|LEFT);
stringWidth()
of the string and the
getHeight()
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 no space above and to the left of the string. 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.
Field Summary
static int
BASELINE
Constant for positioning the anchor point at the baseline of text.
static int
BOTTOM
Constant for positioning the anchor point of text and images
below the text or image.
static int
DOTTED
Constant for DOTTED stroke style.
static int
HCENTER
Constant for centering text and images horizontally around the
anchor point
static int
LEFT
Constant for positioning the anchor point of text and images
to the left of the text or image.
static int
RIGHT
Constant for positioning the anchor point of text and images
to the right of the text or image.
static int
SOLID
Constant for the SOLID stroke style
static int
TOP
Constant for positioning the anchor point of text and images
above the text or image.
static int
VCENTER
Constant for centering images vertically around the anchor point.
Method Summary
void
clipRect(int x,
int y,
int width,
int height)
Intersects the current clip with the specified rectangle.
void
drawArc(int x,
int y,
int width,
int height,
int startAngle,
int arcAngle)
Draws the outline of a circular or elliptical arc covering the
specified rectangle, using the current color and stroke style.
void
drawChar(char character,
int x,
int y,
int anchor)
Draws the specified character using the current font and color.
void
drawChars(char[] data,
int offset,
int length,
int x,
int y,
int anchor)
Draws the specified characters using the current font and color.
void
drawImage(Image img,
int x,
int y,
int anchor)
Draws the specified image by using the anchor point.
void
drawLine(int x1,
int y1,
int x2,
int y2)
Draws a line between the coordinates (x1, y1) and (x2, y2) using
the current color and stroke style.
void
drawRect(int x,
int y,
int width,
int height)
Draws the outline of the specified rectangle using the current
color and stroke style.
void
drawRoundRect(int x,
int y,
int width,
int height,
int arcWidth,
int arcHeight)
Draws the outline of the specified rounded corner rectangle using
the current color and stroke style.
void
drawString(String str,
int x,
int y,
int anchor)
Draws the specified String using the current font and color.
void
drawSubstring(String str,
int offset,
int len,
int x,
int y,
int anchor)
Draws the specified String using the current font and color.
void
fillArc(int x,
int y,
int width,
int height,
int startAngle,
int arcAngle)
Fills a circular or elliptical arc covering the specified rectangle.
void
fillRect(int x,
int y,
int width,
int height)
Fills the specified rectangle with the current color.
void
fillRoundRect(int x,
int y,
int width,
int height,
int arcWidth,
int arcHeight)
Fills the specified rounded corner rectangle with the current
color.
int
getBlueComponent()
Gets the blue component of the current color.
int
getClipHeight()
Gets the height of the current clipping area.
int
getClipWidth()
Gets the width of the current clipping area.
int
getClipX()
Gets the X offset of the current clipping area, relative to the
coordinate system origin of this graphics context.
int
getClipY()
Gets the Y offset of the current clipping area, relative to the
coordinate system origin of this graphics context.
int
getColor()
Gets the current color.
Font
getFont()
Gets the current font.
int
getGrayScale()
Gets the current grayscale value of the color being used for
rendering operations.
int
getGreenComponent()
Gets the green component of the current color.
int
getRedComponent()
Gets the red component of the current color.
int
getStrokeStyle()
Gets the stroke style used for drawing operations.
int
getTranslateX()
Gets the X coordinate of the translated origin of this graphics
context.
int
getTranslateY()
Gets the Y coordinate of the translated origin of this graphics
context.
void
setClip(int x,
int y,
int width,
int height)
Sets the current clip to the rectangle specified by the given
coordinates.
void
setColor(int RGB)
Sets the current color to the specified RGB values.
void
setColor(int red,
int green,
int blue)
Sets the current color to the specified RGB values.
void
setFont(Font font)
Sets the font for all subsequent text rendering operations.
void
setGrayScale(int value)
Sets the current grayscale to be used for all subsequent
rendering operations.
void
setStrokeStyle(int style)
Sets the stroke style used for drawing lines, arcs, rectangles, and
rounded rectangles.
void
translate(int x,
int y)
Translates the origin of the graphics context to the point
(x,y)
in the current coordinate system.
Methods inherited from class java.lang.Object
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Field Detail
BASELINE
public static final int BASELINE
BOTTOM
public static final int BOTTOM
DOTTED
public static final int DOTTED
HCENTER
public static final int HCENTER
LEFT
public static final int LEFT
RIGHT
public static final int RIGHT
SOLID
public static final int SOLID
TOP
public static final int TOP
VCENTER
public static final int VCENTER
Method Detail
clipRect
public void clipRect(int x,
int y,
int width,
int height)
x
- the x coordinate of the rectangle to intersect the clip
withy
- the y coordinate of the rectangle to intersect the clip
withwidth
- the width of the rectangle to intersect the clip
withheight
- the height of the rectangle to intersect the clip
withsetClip(int, int, int, int)
drawArc
public void drawArc(int x,
int y,
int width,
int height,
int startAngle,
int arcAngle)
x
- the x coordinate of the upper-left corner of the
arc to be drawn.y
- the y coordinate of the upper-left corner of the
arc to be drawn.width
- the width of the arc to be drawnheight
- the height of the arc to be drawnstartAngle
- the beginning anglearcAngle
- the angular extent of the arc, relative to the
start angle.fillArc(int, int, int, int, int, int)
drawChar
public void drawChar(char character,
int x,
int y,
int anchor)
character
- the character to be drawnx
- the x coordinate of the anchor pointy
- the y coordinate of the anchor pointanchor
- the anchor point for positioning the textdrawString(java.lang.String, int, int, int)
,
drawChars(char[], int, int, int, int, int)
drawChars
public void drawChars(char[] data,
int offset,
int length,
int x,
int y,
int anchor)
data
- the array of characters to be drawnoffset
- the start offset in the datalength
- the number of characters to be drawnx
- the x coordinate of the anchor pointy
- the y coordinate of the anchor pointanchor
- the anchor point for positioning the textdrawString(java.lang.String, int, int, int)
drawImage
public void drawImage(Image img,
int x,
int y,
int anchor)
img
- the specified image to be drawnx
- the x coordinate of the anchor pointy
- the y coordinate of the anchor pointanchor
- the anchor point for positioning the imageImage
drawLine
public void drawLine(int x1,
int y1,
int x2,
int y2)
x1
- the x coordinate of the start of the liney1
- the y coordinate of the start of the linex2
- the x coordinate of the end of the liney2
- the y coordinate of the end of the line
drawRect
public void drawRect(int x,
int y,
int width,
int height)
x
- the x coordinate of the rectangle to be drawny
- the y coordinate of the rectangle to be drawnwidth
- the width of the rectangle to be drawnheight
- the height of the rectangle to be drawnfillRect(int, int, int, int)
drawRoundRect
public void drawRoundRect(int x,
int y,
int width,
int height,
int arcWidth,
int arcHeight)
x
- the x coordinate of the rectangle to be drawny
- the y coordinate of the rectangle to be drawnwidth
- the width of the rectangle to be drawnheight
- the height of the rectangle to be drawnarcWidth
- the horizontal diameter of the arc at the four
cornersarcHeight
- the vertical diameter of the arc at the four
cornersfillRoundRect(int, int, int, int, int, int)
drawString
public void drawString(String str,
int x,
int y,
int anchor)
str
- the String to be drawnx
- the x coordinate of the anchor pointy
- the y coordinate of the anchor pointanchor
- the anchor point for positioning the textdrawChars(char[], int, int, int, int, int)
drawSubstring
public void drawSubstring(String str,
int offset,
int len,
int x,
int y,
int anchor)
str
- the String to be drawnoffset
- zero-based index of first character in the
substringlen
- length of the substringx
- the x coordinate of the anchor pointy
- the y coordinate of the anchor pointanchor
- the anchor point for positioning the textdrawString(String, int, int, int).
fillArc
public void fillArc(int x,
int y,
int width,
int height,
int startAngle,
int arcAngle)
x
- the x coordinate of the upper-left corner of the
arc to be filled.y
- the y coordinate of the upper-left corner of the
arc to be filled.width
- the width of the arc to be filledheight
- the height of the arc to be filledstartAngle
- the beginning angle.arcAngle
- the angular extent of the arc, relative to the
start angle.drawArc(int, int, int, int, int, int)
fillRect
public void fillRect(int x,
int y,
int width,
int height)
x
- the x coordinate of the rectangle to be filledy
- the y coordinate of the rectangle to be filledwidth
- the width of the rectangle to be filledheight
- the height of the rectangle to be filleddrawRect(int, int, int, int)
fillRoundRect
public void fillRoundRect(int x,
int y,
int width,
int height,
int arcWidth,
int arcHeight)
x
- the x coordinate of the rectangle to be filledy
- the y coordinate of the rectangle to be filledwidth
- the width of the rectangle to be filledheight
- the height of the rectangle to be filledarcWidth
- the horizontal diameter of the arc at the four
cornersarcHeight
- the vertical diameter of the arc at the four
cornersdrawRoundRect(int, int, int, int, int, int)
getBlueComponent
public int getBlueComponent()
setColor(int, int, int)
getClipHeight
public int getClipHeight()
clipRect(int, int, int, int)
,
setClip(int, int, int, int)
getClipWidth
public int getClipWidth()
clipRect(int, int, int, int)
,
setClip(int, int, int, int)
getClipX
public int getClipX()
clipRect(int, int, int, int)
,
setClip(int, int, int, int)
getClipY
public int getClipY()
clipRect(int, int, int, int)
,
setClip(int, int, int, int)
getColor
public int getColor()
setColor(int, int, int)
getFont
public Font getFont()
Font
,
setFont(Font)
getGrayScale
public int getGrayScale()
getGreenComponent
public int getGreenComponent()
setColor(int, int, int)
getRedComponent
public int getRedComponent()
setColor(int, int, int)
getStrokeStyle
public int getStrokeStyle()
getTranslateX
public int getTranslateX()
getTranslateY
public int getTranslateY()
setClip
public void setClip(int x,
int y,
int width,
int height)
x
- the x coordinate of the new clip rectangley
- the y coordinate of the new clip rectanglewidth
- the width of the new clip rectangleheight
- the height of the new clip rectangleclipRect(int, int, int, int)
setColor
public void setColor(int RGB)
RGB
- the color being set
setColor
public void setColor(int red,
int green,
int blue)
red
- The red component of the color being set in range
0-255.green
- The green component of the color being set in range
0-255.blue
- The blue component of the color being set in range
0-255.
setFont
public void setFont(Font font)
font
- the specified fontFont
,
getFont()
,
drawString(String, int, int, int)
,
drawChars(char[], int, int, int, int, int)
setGrayScale
public void setGrayScale(int value)
value
- the desired grayscale value
setStrokeStyle
public void setStrokeStyle(int style)
translate
public void translate(int x,
int y)
g.translate(ax - g.getTranslateX(), ay - g.getTranslateY())
x
- the x coordinate of the new translation originy
- the y coordinate of the new translation origingetTranslateX()
,
getTranslateY()
Overview
Package
Class
Tree
Deprecated
Index
Help
PREV CLASS
NEXT CLASS
FRAMES
NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD
DETAIL: FIELD | CONSTR | METHOD