Provides a surface on which applications can draw.
A graphics object encapsulates the state information needed for basic
rendering operations, making it accessible to applications (for example, the
current font, and drawing color).
Example
g = getGraphics();
// draw here
pushContext(...);
draw(g);
popContext();
draw(Graphics g) {
// draw or fill various objects
// might {push, recurse paint(), pop}
}
The context stack
Typically your application maintains one graphics object for each screen it
must present to the user. Each manager controlled by the screen uses that
graphics object to handle the layout and painting of each field the manager
contains.
To accomodate this model, the graphics object maintains an internal
context stack. Each stack element contains information about the
current drawing context, including the clipping region, the drawing offset
and the current foreground colour.
Typically, a field's manager pushes a transform on the stack that
describes the field's extent as the clipping region, and a drawing offset to
position drawing. Then it hands the graphics object to the field
when it requests the field to update itself.
Each transform pushed onto the stack describes the transform in terms of
the parent coordinates, so that each draw operation can be done using local
coordinates and translated back through the stack to finally appear on the
appropriate location of the screen.
The drawing anchor
When you use one of this class's methods to draw an object, or text, you must
set the drawing anchor. This anchor describes the pixel in the
drawing region where the invoked method begins to draw. The coordinate system
for the drawing anchor assumes that the top left pixel in the region is
coordinate 0,0.
The drawing anchor is not persistent. Each time you call one of these
methods, you must provide a position for the anchor, and if maintaining
information about relative positions of the anchor is important, then your
code must do that.
What happens to clipped objects
When you draw an object and the size of that object would have a portion of
it fall outside the clipping region, then those portions are clipped off
(i.e. the object or text is cropped to fit the clipping region).
Rendering text
This class provides a variety of drawText methods you use to
render text on the drawing region. The most fundamental of these methods
renders a single character's glyph on the drawing region. The exact position
of the drawn glyph, with respect to the drawing anchor, is determined by a
combination of constant drawing style values inherited from the
DrawStyle interface.
The drawn glyph appears...
LEFT
RIGHT
HCENTER
HFULL
TOP
Below and to the right of the drawing anchor.
Below and to the left of the drawing anchor.
Below and horizontally centered on the drawing anchor.
N/A
BOTTOM
Above and to the right of the drawing anchor.
Above and to the left of the drawing anchor.
Above and horizontally centered on the drawing anchor.
N/A
BASELINE
Baseline to the right of the drawing anchor.
Baseline to the left of the drawing ancrho.
Baseline horizontally centered on the drawing anchor.
N/A
VCENTER
Center of left edge to the right of the drawing anchor.
Center of right edge to the left of the drawing anchor.
Absolute center of glyph on the drawing anchor.
N/A
Note: the HFULL drawing position flag, to fully
justify text, has not yet been implemented.
By default, the drawText methods assume the drawing position
flags (TOP | LEFT). You can request another method of drawing
the glyphs by passing other combinations of this class's constant drawing
position values.
What happens to clipped text
The mechanism for handling clipping with drawText operations is
slightly more complex.
The text drawing methods clip in two ways: pixels that fall outside the
general clipping region, and pixels that fall outside a text width
parameter specified to the appropriate drawText method. Text
drawing methods that don't support a text width parameter assume a width
that's the equal to the width of the entire set of text glyphs they are to
draw.
If you pass the ELLIPSIS constant to a drawText
method, in combination with the drawing position constants, then clipping by
the text width parameter is handled specially. The method replaces the last
fully rendered glyph, and any pixels of a partially rendered glyph, with the
ellipsis glyph. If the ellipsis glyph would be clipped by the text width
parameter, then no ellipsis character appears to replace the glyphs clipped.
Width of text rendered
All of the drawText methods return the number of pixels of
block width of text drawn. Imagine that each glyph is mounted on a
little block that you would press onto paper to print the glyph. The
block width of a glyph is the size of that block: in all cases,
therefore, the block width is wider than the width of pixels used to actually
draw the glyph, since the block width also includes spacing pixels along the
right hand side to accomodate following glyphs.
You should also note that the block width of drawn text returned by the
drawText methods includes any pixels that are clipped
by the clipping region. However, if you pass a width parameter into the
drawText method to constrain the region available for drawing,
and this width parameter clips the drawn text, the clipped pixels do
not count in the width of text rendered returned by the method.
Italic text
Note that the "blocks" of italic glyphs form a parallelogram, not a
rectangle. The blocks lean over to ensure that italic characters positioned
next to one another will kern properly. When rendering italic text, the block
width returned by the drawText method measures the width from
one side of the parallelogram block to the other just as it does with roman
glyphs (and not from bottom-left corner across to a vertical line
dropped from top-right corner).
This means that a non-italic glyhph rendered just next to an italic glyph
may occlude the leaning corner of the italic glyph.
ROP_CONST_GLOBALALPHA
Raster operation constant for blending the constant foreground colour,
using a constant global alpha value with destination pixels.
static int
ROP_SRC_ALPHA
Raster operation constant for normal bitmap copy with an alpha channel.
static int
ROP_SRC_COPY
Raster operation constant for normal bitmap copy.
static int
ROP_SRC_GLOBALALPHA
Raster operation constant for blending a source bitmap using a
constant global alpha value with destination pixels.
static int
ROP_SRCMONOEXPAND_ALPHA
Raster operation constant for expanding a monochrome source bitmap
with current foreground and background drawing colours, respecting
the alpha channel.
static int
ROP_SRCMONOEXPAND_COPY
Raster operation constant for expanding a monochrome source bitmap with
the current foreground and background drawing colours.
static int
ROP2_0
Binary raster op constant for zeroing out the destination.
static int
ROP2_1
Binary raster op constant for filling dest with 1 values.
getScreenWidth()
Retrieves total drawing width of the screen.
int
getStipple()
Retrieves the current line stippling value.
int
getTranslateX()
Retrieves the horizontal component of the current drawing offset.
int
getTranslateY()
Retrieves the vertical component of the current drawing offset.
void
invert(int x,
int y,
int width,
int height)
Inverts a region.
void
invert(XYRect rect)
Inverts a region specified by an XYRect
object.
static boolean
isColor()
Determines if the device has a color display.
boolean
isDrawingStyleSet(int drawStyle)
Determines whether the specified drawing style is turned on.
boolean
isRopSupported(int rop)
Determines if a raster operation is supported.
void
popContext()
Pops a drawing context off the stack.
boolean
pushContext(int x,
int y,
int width,
int height,
int xOffset,
int yOffset)
Pushes a clipping region (and optional drawing offset) onto
the context stack.
boolean
pushContext(XYRect clip,
int xOffset,
int yOffset)
Pushes a clipping region (and optional drawing offset) onto
the context stack.
boolean
pushRegion(int x,
int y,
int width,
int height,
int xScroll,
int yScroll)
Pushes a drawing region (and optional scroll offset) onto
the context stack.
boolean
pushRegion(XYRect region)
Pushes a drawing region onto the context stack,
specified by a XYRect object.
boolean
pushRegion(XYRect region,
int xScroll,
int yScroll)
Pushes a drawing region (and optional scroll offset) onto
the context stack.
void
rop(int rop,
int x,
int y,
int width,
int height,
Bitmap source,
int left,
int top)
Executes an area raster operation on the specified region.
setDrawingStyle(int drawStyle,
boolean on)
Sets the current drawing style.
void
setFont(Font font)
Sets the current font for the current graphics context.
void
setGlobalAlpha(int alpha)
Sets the current global alpha value for drawing operations.
void
setStipple(int mask)
Sets the current line stippling value.
void
tileRop(int rop,
int x,
int y,
int width,
int height,
Bitmap source,
int left,
int top)
Executes an area raster operation on the specified region, tiling
the source bitmap if necessary.
void
translate(int x,
int y)
Apply a translation to the current drawing offset.
Raster operation constant for expanding a monochrome source bitmap with
the current foreground and background drawing colours.
Since:
JDE 3.6.0
ROP_SRC_ALPHA
public static final int ROP_SRC_ALPHA
Raster operation constant for normal bitmap copy with an alpha channel.
Since:
JDE 3.6.0
ROP_SRCMONOEXPAND_ALPHA
public static final int ROP_SRCMONOEXPAND_ALPHA
Raster operation constant for expanding a monochrome source bitmap
with current foreground and background drawing colours, respecting
the alpha channel.
Since:
JDE 3.6.0
ROP_CONST_GLOBALALPHA
public static final int ROP_CONST_GLOBALALPHA
Raster operation constant for blending the constant foreground colour,
using a constant global alpha value with destination pixels.
Set the global alpha value using setGlobalAlpha.
Since:
JDE 3.7.0
Category:
Colour: This call is only applicable on colour devices.
ROP_SRC_GLOBALALPHA
public static final int ROP_SRC_GLOBALALPHA
Raster operation constant for blending a source bitmap using a
constant global alpha value with destination pixels.
Set the global alpha value using setGlobalAlpha.
Since:
JDE 3.7.0
Category:
Colour: This call is only applicable on colour devices.
ROP2_0
public static final int ROP2_0
Binary raster op constant for zeroing out the destination.
Since:
JDE 3.6.0
ROP2_DSon
public static final int ROP2_DSon
Binary raster op constant for ( not ( source or dest ) )
Since:
JDE 3.6.0
ROP2_DSna
public static final int ROP2_DSna
Binary raster op constant for ( ( not source ) and dest )
Since:
JDE 3.6.0
ROP2_Sn
public static final int ROP2_Sn
Binary raster op constant for ( not source )
Since:
JDE 3.6.0
ROP2_SDna
public static final int ROP2_SDna
Binary raster op constant for ( ( not dest ) and source )
Since:
JDE 3.6.0
ROP2_Dn
public static final int ROP2_Dn
Binary raster op constant for invert destination.
Since:
JDE 3.6.0
ROP2_DSx
public static final int ROP2_DSx
Binary raster op constant for selective invert ( source xor dest )
Since:
JDE 3.6.0
ROP2_DSan
public static final int ROP2_DSan
Binary raster op constant for ( not ( source and dest ) )
Since:
JDE 3.6.0
ROP2_DSa
public static final int ROP2_DSa
Binary raster op constant for masking ( source and dest )
Since:
JDE 3.6.0
ROP2_DSxn
public static final int ROP2_DSxn
Binary raster op constant for ( not ( source xor dest ) )
Since:
JDE 3.6.0
ROP2_D
public static final int ROP2_D
Binary raster op constant for nop.
Since:
JDE 3.6.0
ROP2_DSno
public static final int ROP2_DSno
Binary raster op constant for ( ( not source ) or dest )
Since:
JDE 3.6.0
ROP2_S
public static final int ROP2_S
Binary raster op constant for normal source copy.
Since:
JDE 3.6.0
ROP2_SDno
public static final int ROP2_SDno
Binary raster op constant for ( source or ( not dest ) )
Since:
JDE 3.6.0
ROP2_DSo
public static final int ROP2_DSo
Binary raster op constant for ( source or dest )
Since:
JDE 3.6.0
ROP2_1
public static final int ROP2_1
Binary raster op constant for filling dest with 1 values.
Since:
JDE 3.6.0
DRAWSTYLE_AALINES
public static final int DRAWSTYLE_AALINES
Drawing style for anti-aliased rendering of lines, used by setDrawingStyle and isDrawingStyleSet.
If this style is set, lines and path outlines may be antialiased.
This style is off by default.
Since:
JDE 3.7.0
Category:
Colour: This call is only applicable on colour devices.
DRAWSTYLE_AAPOLYGONS
public static final int DRAWSTYLE_AAPOLYGONS
Drawing style for anti-aliased rendering of polygons, used by setDrawingStyle and isDrawingStyleSet.
If this style is set, filled paths and polygons may be antialiased.
This style is off by default.
Since:
JDE 3.7.0
Category:
Colour: This call is only applicable on colour devices.
DRAWSTYLE_FOCUS
public static final int DRAWSTYLE_FOCUS
This style is set by the framework when painting is being done for focus drawing.
Since:
JDE 3.7.0
Category:
Colour: This call is only applicable on colour devices.
DRAWSTYLE_SELECT
public static final int DRAWSTYLE_SELECT
This style is set by the framework when painting is being done for selection drawing.
Since:
JDE 3.7.0
Category:
Colour: This call is only applicable on colour devices.
CURVEDPATH_END_POINT
public static final byte CURVEDPATH_END_POINT
End-point type for drawing paths. A curve or line ends on this point. The value of this constant
will always be 0, so it is possible to just create a points array and set only the values of the
curves' control points.
Since:
JDE 3.6.0
CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT
public static final byte CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT
Quadratic bezier control-point type for drawing paths. The control point of a quadratic bezier is
the single point that "stretches" the curve awway from the end points. If a point is a quadratic
bezier control point, the points preceeding and succeeding it must be end points.
Since:
JDE 3.6.0
CURVEDPATH_CUBIC_BEZIER_CONTROL_POINT
public static final byte CURVEDPATH_CUBIC_BEZIER_CONTROL_POINT
Cubic bezier control-point type for drawing paths. A control point of a cubic bezier is
one of two points that "stretch" the curve awway from the end points. Cubic bezier control
points must come in sets of two, with end points coming before the first control point and
after the second.
Clears a region specified by an XYRect
object to the current background.
Use this method to clear only a region within the
entire graphics area. You specify the region to clear with
an XYRect that you pass to this method.
Parameters:
region - Rectangular region to clear.
Since:
JDE 3.7.0
copyArea
public boolean copyArea(int x,
int y,
int width,
int height,
int dx,
int dy)
Copies a region of this graphics canvas.
Use this method to copy a region of the drawing buffer. You specify
the source region by describing its extent in passed parameters. The
source region is left intact (i.e. not cleared).
To paste the copy of the region to the left of or above the drawing
anchor, specify a negative value for the dx or
dy parameters.
If a portion of the source rectangle lies outside the bounds of the
clipping region, this method does not copy the associated pixels. You can
refresh the omitted area by invoking paint on the
component.
This method fails in situations where the pixels are not
available. This can happen when a front buffer screen is obscuring this
graphics context's screen. In this case, this method returns false; you
should then prompt a full repaint by invoking
invalidate on the screen.
Parameters:
x - Left edge of the source region.
y - Top edge of the source region
width - Width of the source region.
height - Height of the source region.
dx - Horizontal distance to move the region.
dy - Vertical distance to move the region.
Returns:
True if the copyArea was successful; otherwise, false.
Since:
JDE 3.7.0
copyArea
public boolean copyArea(XYRect region,
int dx,
int dy)
Copies a region of this graphics canvas, specified by an XYRect.
Use this method to copy a region of the drawing buffer. You specify
the source region with an XYRect that you pass to this
method. The source region is left intact (i.e. not cleared).
To paste the copy of the region to the left of or above the drawing
anchor, specify a negative value for the dx and
dy parameters.
If a portion of the source region lies outside the bounds of the
clipping region, this method does not copy the associated pixels. You can
refresh the omitted area by invoking Field.paint(net.rim.device.api.ui.Graphics) on the component.
This method fails in situations where the pixels are not
available. This can happen when a front buffer screen is obscuring this
graphics context's screen. In this case, this method returns false; you
should then prompt a full repaint by invoking
invalidate on the screen.
Parameters:
region - Source region to copy.
dx - Horizontal distance to move the region.
dy - Vertical distance to move the region.
Returns:
True if the copyArea was successful; otherwise, false.
Since:
JDE 3.7.0
drawArc
public void drawArc(int x,
int y,
int width,
int height,
int startAngle,
int arcAngle)
Draws an arc through a specified rectangle.
The center of the drawn arc is the center of a
rectangle whose origin is (x,y) and whose
size is specified by the width and
height parameters.
The arc begins at startAngle and extends
for arcAngle degrees, using the current draw
color. The drawing algorithm assumes that the 0 degree
position is in the center of the right edge of the
rectangle. The direction of the arc drawn depends on the
relative values of startAngle and
arcAngle:
If (startAngle < arcAngle), this
method draws the arc in a counterclockwise direction.
If startAngle > arcAngle, this method
draws the arc in a clockwise direction.
The resulting arc covers an area
width pixels wide by
height pixels tall and end points are
one pixel outside the extent of the rectangle).
If either width or height is less than zero,
this method draws nothing.
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.
Parameters:
x - Horizontal coordinate of the arc's starting position.
y - Vertical coordinate of the arc's starting position.
width - Width of rectangle containing the arc.
height - Height of rectangle containing the arc.
startAngle - The angle position at which to commence drawing.
arcAngle - Angular extent of the arc, relative to the
start angle.
Since:
JDE 3.7.0
isRopSupported
public boolean isRopSupported(int rop)
Determines if a raster operation is supported.
Use this method to query if a particular raster operation
is supported for the Graphics object. Note that all ROP2s as
well as ROP_SRC_COPY, ROP_SRCMONOEXPAND_COPY, ROP_SRC_ALPHA
and ROP_SRCMONOEXPAND_ALPHA are always supported.
Parameters:
rop - Constant for the raster operation to query.
Since:
JDE 3.7.0
Category:
Colour: This call is only applicable on colour devices.
rop
public void rop(int rop,
int x,
int y,
int width,
int height,
Bitmap source,
int left,
int top)
Executes an area raster operation on the specified region.
Use this method to run a raster operation with or without
a source bitmap.
You must specify the extent of the region to draw to, as
well as the top left position in the (optional) source bitmap.
Parameters:
rop - Constant for the raster operation to execute.
x - Left edge of the destination region.
y - Top edge of the destination region.
width - Width of the destination region.
height - Height of the destination region.
source - Source bitmap to use (may be null for some raster operations)
left - Left edge of region within bitmap to use.
top - Top edge of region within bitmap to use.
Since:
JDE 3.7.0
tileRop
public void tileRop(int rop,
int x,
int y,
int width,
int height,
Bitmap source,
int left,
int top)
Executes an area raster operation on the specified region, tiling
the source bitmap if necessary.
Use this method to run a raster operation with or without
a source bitmap.
You must specify the extent of the region to draw to, as
well as the top left position in the (optional) source bitmap.
Parameters:
rop - Constant for the raster operation to execute.
x - Left edge of the destination region.
y - Top edge of the destination region.
width - Width of the destination region.
height - Height of the destination region.
source - Source bitmap to use (may be null for some raster operations)
left - Left edge of region within bitmap to use.
top - Top edge of region within bitmap to use.
Since:
JDE 3.7.0
drawBitmap
public void drawBitmap(XYRect dest,
Bitmap bitmap,
int left,
int top)
Draws a bitmap on a region specified by an
XYRect object.
Use this method to draw a bitmap. You specify the destination region
for the bitmap with an XYRect that you pass to this method.
You must also specify the extent of the bitmap to
draw (the top left corner of this extent defined by the
top and left parameters). If a
portion of part of the bitmap you want to draw falls
outside the size of the destination region, this method
crops to fit.
Parameters:
dest - Destination region in which to draw the
bitmap.
bitmap - Bitmap to draw.
left - Left edge of region within bitmap to draw.
top - Top edge of region within bitmap to draw.
Since:
JDE 3.7.0
drawBitmap
public void drawBitmap(int x,
int y,
int width,
int height,
Bitmap bitmap,
int left,
int top)
Draws a bitmap.
Use this method to draw a bitmap. You specify the destination region
for the bitmap by describing the extent of the region with passed
parameters.
You must also specify the extent of the bitmap to draw (the top left
corner of this extent defined by the top and
left parameters). If a portion of part of the bitmap you
want to draw falls outside the size of the destination region, this
method crops to fit.
Pixels that are "on" in the source image are drawn using the current
foreground color. Pixels that are "off" in the source image are not
drawn (i.e., they are transparent. To do a non-transparent invocation of
this method first do a fillRect(int, int, int, int) using the background color.
Parameters:
x - Left edge of the destination region.
y - Top edge of the destination region.
width - Width of the destination region.
height - Height of the destination region.
bitmap - Bitmap to draw.
left - Left edge of region within bitmap to draw.
top - Top edge of region within bitmap to draw.
Since:
JDE 3.7.0
drawImage
public void drawImage(XYRect dest,
EncodedImage image,
int frameIndex,
int left,
int top)
Draws an encoded image on a region specified by an
XYRect object.
Use this method to draw an image. You specify the destination region
for the image with an XYRect that you pass to this method.
The region to be drawn is decoded, drawn and then thrown away. Thus
if you plan to draw a full encoded image multiple times it is faster
to first decode into a Bitmap object and draw that.
You must also specify the extent of the image to
draw (the top left corner of this extent defined by the
top and left parameters). If a
portion of part of the image you want to draw falls
outside the size of the destination region, this method
crops to fit.
Parameters:
dest - Destination region in which to draw the
bitmap.
image - Encoded image to draw
frameIndex - The frame to draw
left - Left edge of region within bitmap to draw.
top - Top edge of region within bitmap to draw.
Since:
JDE 3.7.0
drawImage
public void drawImage(int x,
int y,
int width,
int height,
EncodedImage image,
int frameIndex,
int left,
int top)
Draws an encoded image.
Use this method to draw an encoded image. You specify the
destination region for the bitmap by describing the extent of
the region with passed parameters.
The region to be drawn is decoded, drawn and then thrown away. Thus
if you plan to draw a full encoded image multiple times it is faster
to first decode into a Bitmap object and draw that.
You must also specify the extent of the image to draw (the top left
corner of this extent defined by the top and
left parameters). If a portion of part of the image you
want to draw falls outside the size of the destination region, this
method crops to fit.
Pixels that are "on" in the source image are drawn using the current
foreground color. Pixels that are "off" in the source image are not
drawn (i.e., they are transparent. To do a non-transparent invocation of
this method first do a fillRect(int, int, int, int) using the background color.
Parameters:
x - Left edge of the destination region.
y - Top edge of the destination region.
width - Width of the destination region.
height - Height of the destination region.
image - Encoded image to draw.
frameIndex - The frame to draw
left - Left edge of region within bitmap to draw.
top - Top edge of region within bitmap to draw.
Since:
JDE 3.7.0
drawFilledPath
public void drawFilledPath(int[] xPts,
int[] yPts,
byte[] pointTypes,
int[] offsets)
Draws a set of filled paths.
Use this method to draw one or more filled non-intersecting paths that contain line segments or curves.
You specify the x and y coordinates and point types of the paths desired.
The offsets indicate the beginnings of each path in the data array. The data in the ith
path is defined to be the (xPts,yPts) values from offsets[i] to offsets[i+1]-1 inclusive. Thus if there are
N values in offsets, there are N-1 paths defined, where the final value is one greater than the offset where
the final point of the final path is located in the points data. If offsets is null, the xPts and yPts data
will be treated as a single path, and these arrays must have the same length.
The xPts and yPts arrays keep track of each vertex in the polygon and
each value in the xPts array must have a corresponding value at the same index
in the yPts array, and a corresponding value at the same index in the pointTypes array.
None of the edges in a path may cross any other edge in any of the paths (including itself). If edges
do cross, the drawing behaviour is undefined. A path may be fully contained within another path,
e.g. a "donut" shape.
The paths are filled by the "even-odd" rule. Thus if a ray is drawn from any point, the area
containing the point will be filled if the ray passes through an odd number of edges and will not be filled
if is passes through an even number of edges.
Note that each non-null array parameter must be a different array.
Parameters:
xPts - the ordered list of x values for each vertex in the paths
yPts - the ordered list of y values for each vertex in the paths
pointTypes - one of Graphics.CURVEDPATH_END_POINT, CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT,
or CURVEDPATH_CUBIC_BEZIER_CONTROL_POINT. There must be one of these values for each (x,y) point
defined. If pointTypes is null, all point are assumed to be of type CURVEDPATH_END_POINT.
If a point's value is CURVEDPATH_END_POINT, then a line or curve ends on this point. If a curve control
point is next to this point, a curve will have this point as an endpoint. Otherwise, straight lines are
drawn between successive end points.
If a point's value is CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT, the point is a control point for a
quadratic bezier. The control point of a quadratic bezier is the single point that "stretches" the curve
away from the end points. If a point is a quadratic bezier control point, the points preceeding and
succeeding it must be end points (CURVEDPATH_END_POINT).
If a point's value is CURVEDPATH_CUBIC_BEZIER_CONTROL_POINT, the point is a control point for a
cubic bezier. A cubic bezier has two control points that "stretch" the curve away from the end points.
Cubic bezier control points must come in sets of two, with end points (CURVEDPATH_END_POINT) coming
before the first control point and after the second.
offsets - the list defining the beginnings of each path in the xPts/yPts data
arrays, or null to indicate a single path. A path that begins at point (xPts[offsets[i]],yPts[offsets[i]])
will end at point (xPts[offsets[i+1]]-1,yPts[offsets[i+1]]-1).
Throws:
IllegalArgumentException - if the data is malformed. e.g. the values in offsets is negative or not in
increasing order, there are fewer than 2 points in a single path, the values in offsets index outside the points arrays,
the values in pointTypes are invalid, or offsets is null and xPts and yPts are not the same length.
Use this method to draw one or more filled non-intersecting paths that contain line segments and curves.
You specify the x and y coordinates and point types of the paths desired as well as the color values of each
vertex which will be blended together creating the shading effect.
The offsets indicate the beginnings of each path in the data array. The data in the ith
path is defined to be the (xPts,yPts) values from offsets[i] to offsets[i+1]-1 inclusive. Thus if there are
N values in offsets, there are N-1 paths defined, where the final value is one greater than the offset where
the final point of the final path is located in the points data. If offsets is null, the xPts and yPts data
will be treated as a single path, and these arrays must have the same length.
The xPts and yPts arrays keep track of each vertex in the polygon and
each value in the xPts array must have a corresponding value at the same index
in the yPts array, and a corresponding value at the same index in the pointTypes array.
Similarly the color array stores the RGB color of each vertex ( in 0x00RRGGBB format )
and its indices must correspond with those of both the xPts and yPts arrays.
None of the edges in a path may cross any other edge in any of the paths (including itself). If edges
do cross, the drawing behaviour is undefined. A path may be fully contained within another path,
e.g. a "donut" shape.
The paths are filled by the "even-odd" rule. Thus if a ray is drawn from any point, the area
containing the point will be filled if the ray passes through an odd number of edges and will not be filled
if is passes through an even number of edges.
Note that each non-null array parameter must be a different array.
Parameters:
xPts - the ordered list of x values for each vertex in the paths
yPts - the ordered list of y values for each vertex in the paths
pointTypes - one of Graphics.CURVEDPATH_END_POINT, CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT,
or CURVEDPATH_CUBIC_BEZIER_CONTROL_POINT. There must be one of these values for each (x,y) point
defined. If pointTypes is null, all point are assumed to be of type CURVEDPATH_END_POINT.
If a point's value is CURVEDPATH_END_POINT, then a line or curve ends on this point. If a curve control
point is next to this point, a curve will have this point as an endpoint. Otherwise, straight lines are
drawn between successive end points.
If a point's value is CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT, the point is a control point for a
quadratic bezier. The control point of a quadratic bezier is the single point that "stretches" the curve
awway from the end points. If a point is a quadratic bezier control point, the points preceeding and
succeeding it must be end points (CURVEDPATH_END_POINT).
If a point's value is CURVEDPATH_CUBIC_BEZIER_CONTROL_POINT, the point is a control point for a
cubic bezier. A cubic bezier has two control points that "stretch" the curve away from the end points.
Cubic bezier control points must come in sets of two, with end points (CURVEDPATH_END_POINT) coming
before the first control point and after the second.
colors - the ordered list of color values for each vertex ( 0x00RRGGBB format ). If null, a solid filled path
will be drawn in the current foreground color.
offsets - the list defining the beginnings of each path in the xPts/yPts data
arrays, or null to indicate a single path. A path that begins at point (xPts[offsets[i]],yPts[offsets[i]]) will end
at point (xPts[offsets[i+1]]-1,yPts[offsets[i+1]]-1).
Throws:
IllegalArgumentException - if the data is malformed. e.g. the values in offsets is negative or not in
increasing order, there are fewer than 2 points in a single path, the values in offsets index outside the points arrays,
the values in pointTypes are invalid, or offsets is null and xPts and yPts are not the same length.
Since:
JDE 3.7.0
Category:
Colour: This call is only applicable on colour devices.
Use this method to draw a set of path outlines that contains line segments and curves.
The xPts and yPts arrays keep track of each vertex in the path.
Each value in the xPts array must have corresponding values at the same index
in the yPts array and the pointTypes array.
The offsets array keeps track of the locations of each
path in the set of paths. If offsets is null, the xPts and yPts data
will be treated as a single path, and these arrays must have the same length.
Note that each non-null array parameter must be a different array.
Parameters:
xPts - the ordered list of x values for each vertex in the paths
yPts - the ordered list of y values for each vertex in the paths
pointTypes - one of Graphics.CURVEDPATH_END_POINT, CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT,
or CURVEDPATH_CUBIC_BEZIER_CONTROL_POINT. There must be one of these values for each (x,y) point
defined. If pointTypes is null, all point are assumed to be of type CURVEDPATH_END_POINT.
If a point's value is CURVEDPATH_END_POINT, then a line or curve ends on this point. If a curve control
point is next to this point, a curve will have this point as an endpoint. Otherwise, straight lines are
drawn between successive end points.
If a point's value is CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT, the point is a control point for a
quadratic bezier. The control point of a quadratic bezier is the single point that "stretches" the curve
awway from the end points. If a point is a quadratic bezier control point, the points preceeding and
succeeding it must be end points (CURVEDPATH_END_POINT).
If a point's value is CURVEDPATH_CUBIC_BEZIER_CONTROL_POINT, the point is a control point for a
cubic bezier. A cubic bezier has two control points that "stretch" the curve away from the end points.
Cubic bezier control points must come in sets of two, with end points (CURVEDPATH_END_POINT) coming
before the first control point and after the second.
offsets - the list defining the beginnings of each path in the xPts/yPts data
arrays, or null to indicate a single path. A path that begins at point (xPts[offsets[i]],yPts[offsets[i]])
will end at point (xPts[offsets[i+1]]-1,yPts[offsets[i+1]]-1).
closed - if this value is true, each path in the set will be closed by connecting the final
point in the path's data with the first point.
Throws:
IllegalArgumentException - if the data is malformed. e.g. the values in offsets is negative or not in
increasing order, there are fewer than 2 points in a single path, the values in offsets index outside the points arrays,
the values in pointTypes are invalid, or offsets is null and xPts and yPts are not the same length.
Since:
JDE 3.7.0
drawLine
public void drawLine(int x1,
int y1,
int x2,
int y2)
Draws a line.
Use this method to draw a line; you specify
coordinates for the endpoints of the line.
Parameters:
x1 - Horizontal position of the line's starting point.
y1 - Vertical position of the line's starting point.
x2 - Horizontal position of the line's ending point.
y2 - Vertical position of the line's ending point.
Since:
JDE 3.7.0
drawPoint
public void drawPoint(int x,
int y)
Draws a point.
This method draws the pixel located at a coordinate
you specify.
Parameters:
x - Horizontal position of the point to draw.
y - Vertical position of the point to draw.
Since:
JDE 3.7.0
drawRect
public void drawRect(int x,
int y,
int width,
int height)
Draws a rectangle.
Use this method to draw a rectangle. You specify the top and left
edges of the rectangle, and its width and height. This method draws the
right edge of the rectangle at (x+width-1), the bottom edge
at (y+height-1). The resulting rectangle will thus have an
area of (width * height).
If you pass in a zero or negative value for either the height or
width, this method draws nothing.
Parameters:
x - Left edge of the rectangle.
y - Top edge of the rectangle.
width - Width of the rectangle.
height - Height of the rectangle.
Since:
JDE 3.7.0
drawRoundRect
public void drawRoundRect(int x,
int y,
int width,
int height,
int arcWidth,
int arcHeight)
Draws a rectangle with rounded edges.
Use this method to draw a rectangle with rounded edges. You specify
the top and left edges of the rectangle, and its width and height. This
method draws the right edge of the rectangle at (x+width-1),
the bottom edge at (y+height-1). The resulting rectangle will
thus have an area, assuming no rounded corners, of
width * height.
If you pass in a zero or negative value for either the height or
width, this method draws nothing.
Use the arcWdith and arcHeight parameters to describe the arcs used
to round off the four corners.
Parameters:
x - Left edge of the rectangle.
y - Top edge of the rectangle.
width - Width of the rectangle.
height - Height of the rectangle.
arcWidth - Width of arc used to round the four corners.
arcHeight - Height of arc used to round the four corners.
Since:
JDE 3.7.0
drawRGB
public void drawRGB(int[] data,
int offset,
int scanLength,
int x,
int y,
int width,
int height)
Draws raw RGB data from an int array.
Parameters:
data - Color data to use, of the form 0x00RRGGBB.
offset - Offset into the data to start drawing from.
public int drawText(char character,
int x,
int y,
int flags,
int width)
Draws a text character.
Use this method to draw a text character. You specify the position of
the drawing anchor, and this method renders the character's glyph using
the default font.
If the glyph to draw is too large for the current clipping region,
this method crops to fit.
Parameters:
character - Character to draw.
x - Horizontal position of drawing anchor.
y - Vertical position of drawing anchor.
flags - Combination of constant drawing position flags.
Returns:
Actual block width of the glyph, in pixels
(including width of any clipped pixels).
Use this method to draw a string of text using the
default position values (LEFT|TOP).
If the string to draw is too large for the current
clipping region, this method crops to fit.
Parameters:
text - String to draw.
x - Horizontal position of drawing anchor.
y - Vertical position of drawing anchor.
Returns:
Actual block widths of text drawn, in pixels
(including width of any clipped text).
Since:
JDE 3.7.0
drawText
public int drawText(String text,
int x,
int y,
int flags)
Draws a text string with specified positioning.
Use this method to draw a string of text, with your
specified position values.
Parameters:
text - String to draw.
x - Horizontal position of drawing anchor.
y - Vertical position of drawing anchor.
flags - Combination of constant drawing position flags.
Returns:
Actual block width of text drawn, in pixels
(including width of any clipped text).
Since:
JDE 3.7.0
drawText
public int drawText(String text,
int x,
int y,
int flags,
int width)
Draws text within a specified width.
Use this method to draw a string of text, with your
specified position values, and within a specified drawing
region.
Parameters:
text - String to draw.
x - Horizontal position of drawing anchor.
y - Vertical position of drawing anchor.
flags - Combination of constant drawing position flags.
width - Width of region available for drawing.
Returns:
Actual block width of text drawn, in pixels. This
includes any width of text clipped by the clipping region,
but not text clipped by the width
parameter.
Since:
JDE 3.7.0
drawText
public int drawText(byte[] text,
int offset,
int len,
int x,
int y,
int flags,
int width)
Draws text contained in a byte array.
Use this method to draw a string of text, with your
specified position values, and within a specified drawing
region.
Your text string is encapsulated in a byte
array. Since the only character representation currently
supported by the system is Unicode, we assume that all the
high bytes are 0. Otherwise, you should use the
drawText method that takes a char array.
Parameters:
text - String to draw.
offset - Element of the text byte array at which to
start drawing.
len - Number of character glyphs to draw.
x - Horizontal position of drawing anchor.
y - Vertical position of drawing anchor.
flags - Combination of constant drawing position flags.
width - Width of region available for drawing.
Returns:
Actual block width of text drawn, in pixels. This
includes any width of text clipped by the clipping region,
but not text clipped by the width
parameter.
Throws:
IndexOutOfBoundsException - If your
offset+len parameters extend beyond the
length of your byte array.
Since:
JDE 3.7.0
drawText
public int drawText(char[] text,
int offset,
int len,
int x,
int y,
int flags,
int width)
Draws text contained in a char array.
Use this method to draw a string of text (encapsulate
in a char arry), with your specified position values, and
within a specified drawing region.
Parameters:
text - String to draw.
offset - Element of the text char array at which to
start drawing.
len - Number of character glyphs to draw.
x - Horizontal position of drawing anchor.
y - Vertical position of drawing anchor.
flags - Combination of constant drawing position flags.
width - Width of region available for drawing.
Returns:
Actual block width of text drawn, in pixels. This
includes any width of text clipped by the clipping region,
but not text clipped by the width
parameter.
Throws:
IndexOutOfBoundsException - If your
offset+len parameters extend beyond the
length of your char array.
Since:
JDE 3.7.0
drawText
public int drawText(String text,
int offset,
int len,
int x,
int y,
int flags,
int width)
Draws text contained in a string.
Use this method to draw a string of text with your
specified position values, and within a specified drawing
region.
Parameters:
text - String to draw.
offset - Character in the string at which to start drawing.
len - Number of character glyphs to draw.
x - Horizontal position of drawing anchor.
y - Vertical position of drawing anchor.
flags - Combination of constant drawing position flags.
width - Width of region available for drawing.
Returns:
Actual block width of text drawn, in pixels. This
includes any width of text clipped by the clipping region,
but not text clipped by the width
parameter.
public int drawText(StringBuffer text,
int offset,
int len,
int x,
int y,
int flags,
int width)
Draws text contained in a string buffer.
Use this method to draw a string of text with your
specified position values, and within a specified drawing
region.
Parameters:
text - StringBuffer to draw.
offset - Character in the string buffer at which to start drawing.
len - Number of character glyphs to draw.
x - Horizontal position of drawing anchor.
y - Vertical position of drawing anchor.
flags - Combination of constant drawing position flags.
width - Width of region available for drawing.
Returns:
Actual block width of text drawn, in pixels. This
includes any width of text clipped by the clipping region,
but not text clipped by the width
parameter.
Throws:
IndexOutOfBoundsException - If your
offset+len parameters extend beyond the
length of your string buffer.
Since:
JDE 3.7.0
fillArc
public void fillArc(int x,
int y,
int width,
int height,
int startAngle,
int arcAngle)
Fills a circular or elliptical arc covering a specified
rectangle.
The center of the filled arc is the center of a
retangle whose origin is (x,y) and whose size
is specified by the width and
height parameters.
The arc begins at startAngle and extends
for arcAngle degrees, using the current draw
color. The drawing algorithm assumes that the 0 degree
position is in the center of the right edge of the
rectangle. The direction of the arc drawn depends on the
relative values of startAngle and
arcAngle:
If (startAngle < arcAngle), this
method fills the arc in a counterclockwise direction.
If (startAngle > arcAngle), this
method fills the arc in a clockwise direction.
The resulting filled region consist of the wedge
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.
If either width or height is less than zero, this
method draws nothing.
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.
Parameters:
x - Horizontal coordinate of the arc's starting position.
y - Vertical coordinate of the arc's starting position.
width - Width of rectangle containing the filled arc.
height - Height of rectangle containing the filled arc.
startAngle - - The angle position at which to
commence drawing the edge of the arc.
arcAngle - - Angular extent of the arc, relative to
the start angle.
Since:
JDE 3.7.0
fillRect
public void fillRect(int x,
int y,
int width,
int height)
Fills a rectangle.
Use this method to fill a rectangle. You specify the
top and left edges of the rectangle, and its width and
height. This method paints the right edge of the rect at
(x+width-1), the bottom edge at
(y+height-1). The resulting rectangle will thus
have an area of width * height.
If you pass in a zero or negative value for either the height or
width, this method draws nothing.
Parameters:
x - Left edge of the rectangle.
y - Top edge of the rectangle.
width - Width of the rectangle.
height - Height of the rectangle.
Since:
JDE 3.7.0
fillRoundRect
public void fillRoundRect(int x,
int y,
int width,
int height,
int arcWidth,
int arcHeight)
Fills a rectangle with rounded edges.
Use this method to fill a rectangle with rounded
edges. You specify the top and left edges of the
rectangle, and its width and height. This method draws the
right edge of the filled rectangle at
(x+width-1), the bottom edge at
(y+height-1). The resulting rectangle will thus
have an area, assuming no rounded corners, of
width * height.
If you pass in a zero or negative value for either the height or
width, this method draws nothing.
Use the arcWidth and
arcHeight parameters to describe the arcs
used to round off the four corners.
Parameters:
x - Left edge of the rectangle.
y - Top edge of the rectangle.
width - Width of the rectangle.
height - Height of the rectangle.
arcWidth - Width of arc used to round the four corners.
arcHeight - Height of arc used to round the four corners.
Retrieves the local coordinates of current clipping
region.
The returned XYRect is owned by this
graphics object and you should not change
it. Instead, use this class's various push
and pop methods to change the extent of the
current clipping region.
This method performs a one's complement operation on
each pixel in your specified region.
Parameters:
rect - Region to invert.
Since:
JDE 3.7.0
popContext
public void popContext()
Pops a drawing context off the stack.
Use this method to pop off the context stack the
last context pushed.
pushRegion
public boolean pushRegion(int x,
int y,
int width,
int height,
int xScroll,
int yScroll)
Pushes a drawing region (and optional scroll offset) onto
the context stack.
The clipping region is updated by intersecting with
the previous clipping region. The drawing offset
is adjusted by the value of the region origin. You can also
specify an (optional) additional scroll offset with
the xScroll and yScroll
parameters.
This method is suitable for pushing
a context for drawing into a subregion.
Pushes a drawing region onto the context stack,
specified by a XYRect object.
The clipping region is updated by intersecting with
the previous clipping region. The drawing offset
is adjusted by the value of the region origin.
This method is suitable for pushing
a context for drawing into a subregion.
Parameters:
region - New drawing region rectangle in local
coordinates.
Since:
JDE 3.7.0
pushRegion
public boolean pushRegion(XYRect region,
int xScroll,
int yScroll)
Pushes a drawing region (and optional scroll offset) onto
the context stack.
This method behaves exactly like
pushRegion( XYRect ), except you can
also specify an (optional) additional scroll offset
with the xScroll and yScroll
parameters.
public boolean pushContext(XYRect clip,
int xOffset,
int yOffset)
Pushes a clipping region (and optional drawing offset) onto
the context stack.
This clipping region is updated by intersecting with
the previous clipping region. Unlike pushRegion
the drawing offset is not adjusted by the value of
the region origin. You can also specify an additional drawing
offset update by using the xOffset and
yOffset parameters.
To setup a subregion for local drawing pushRegion
should be used.
public boolean pushContext(int x,
int y,
int width,
int height,
int xOffset,
int yOffset)
Pushes a clipping region (and optional drawing offset) onto
the context stack.
This clipping region is updated by intersecting with
the previous clipping region. Unlike pushRegion
the drawing offset is not adjusted by the value of
the region origin. You can also specify an additional drawing
offset update by using the xOffset and
yOffset parameters.
To setup a subregion for local drawing pushRegion
should be used.
Apply a translation to the current drawing offset.
The drawing offset is updated by adding the x and y offsets.
Parameters:
x - The horizontal offset to add to the current x drawing offset.
y - The vertical offset to add to the current y drawing offset.
Since:
JDE 3.7.0
getTranslateX
public int getTranslateX()
Retrieves the horizontal component of the current drawing offset.
Returns:
X value of drawing offset.
Since:
JDE 3.6.0
getTranslateY
public int getTranslateY()
Retrieves the vertical component of the current drawing offset.
Returns:
Y value of drawing offset.
Since:
JDE 3.6.0
isDrawingStyleSet
public boolean isDrawingStyleSet(int drawStyle)
Determines whether the specified drawing style is turned on.
Parameters:
drawStyle - Graphics drawing style to be checked.
Returns:
True if the specified style is turned on, false otherwise.
Since:
JDE 3.7.0
Category:
Colour: This call is only applicable on colour devices.
setDrawingStyle
public void setDrawingStyle(int drawStyle,
boolean on)
Sets the current drawing style.
Parameters:
drawStyle - Graphics drawing style to turn on or off.
on - True to turn on the specified style, false to turn it off.
Since:
JDE 3.7.0
Category:
Colour: This call is only applicable on colour devices.
setColor
public void setColor(int RGB)
Sets the current color.
All subsequent rendering will be done in this color (more precisely,
rendering will be done in a displayable colour that is nearest to the
colour you specify).
Parameters:
RGB - Color to use, of the form 0x00RRGGBB.
Since:
JDE 3.7.0
setGlobalAlpha
public void setGlobalAlpha(int alpha)
Sets the current global alpha value for drawing operations.
Currently only raster operations with global alpha support
use this value, but in the future more drawing primitives may respect it.
Be sure to reset the global alpha value when appropriate.
All subsequent global alpha operations are done using the
value specified. The alpha value should be specified in the range 0-255,
where 0 is fully transparent and 255 is fully opaque.
Parameters:
alpha - Alpha value to use, in the range 0x00 to 0xff.
Since:
JDE 3.7.0
Category:
Colour: This call is only applicable on colour devices.
setStipple
public void setStipple(int mask)
Sets the current line stippling value.
All subsequent line rendering operations will be done with this
stipple value. The stipple value is a 32 bit bitmask where a 1 indicates
a pixel should be drawn and a 0 indicates the destination pixel should be
left as is. The mask is cycled through as the line is drawn.
Copyright 1999-2002 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved. Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved. Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
