|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.ui.Graphics
public class Graphics
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).
Drawing text
The Graphics class provides a variety of drawText
methods to
render text on the drawing surface. There are several versions of
drawText, taking single characters and various text classes. The most general
take a drawing anchor (x and y coordinates of the start of the text),
drawing position flags made up from bit flags specified as constants in
the DrawStyle
interface, and a width into which the text is drawn.
The drawing position flags specify both the baseline and the horizontal alignment. You combine them using the OR operator: e.g., BASELINE | HCENTER.
Baseline values:
The TOP baseline value draws the text below the drawing anchor.
The BOTTOM baseline value draws the text above the drawing anchor.
The BASELINE baseline value draws the text with its alphabetic baseline on the drawing anchor.
The VCENTER baseline value centers the text vertically on the drawing anchor.
Horizontal alignment values, used if a width greater than 0 is specified (a width of -1 forces left alignment; other values less than or equal to zero cause no text to be drawn):
The LEFT alignment value draws the text left-aligned to the paintable region. The paintable region is the area of the screen on which text can be drawn.
The HCENTER alignment value centers the text horizontally in the supplied width.
The RIGHT alignment value draws the text right-aligned to the paintable region. The paintable region is the area of the screen on which text can be drawn.
The HFULL (full justification) alignment value is not implemented by this interface, and is treated as identical to HCENTER.
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.
Using DrawTextParam and TextMetrics
Some versions of drawText
allow more detailed control over the
way the text is drawn, and can return full text metrics. See the
DrawTextParam
and Graphics.WrappedTextMetrics
classes for details.
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 use the width
of the whole text to be drawn.
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 (usually three dots, like this: ...).
If the ellipsis glyph itself would be clipped by the text width
parameter, then no ellipsis character is drawn.
You can use the TRUNCATE_BEGINNING
constant to truncate the
text at the start, not at the end, if it is wider than the supplied width. It
can be combined with ELLIPSIS
to put an ellipsis at the start
if truncation occurs.
Width of text rendered
All of the drawText
methods return the linear advance, in pixels, of
the text drawn. That is the amount by which the drawing position
is moved along the baseline by drawing the text. If you want to draw some more
text so that it joins with the text you have just drawn, the correct new
x anchor position is the old x anchor position plus this advance value
(assuming that you are drawing on a left-to-right baseline)
but see also AdvancedDrawTextParam.iAllowStartOverlap
.
You should also note that the advance 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.
Italics and kerning
Parts of italic characters often protrude beyond - before or after - the
horizontal bounds defined by the anchor position and the advance width. This
can also happen when two adjacent characters, like 'T' and 'o', are
automatically moved closer together, which is called kerning. If you need
to take account of kerning outside the advance width, you should either
use the ARTIC text layout system (see the ArticInterface
class),
or use Font.measureText
to obtain the full metrics.
Field Summary | ||
---|---|---|
static int |
BLACK
Black (0x00101010). |
|
static byte |
CURVEDPATH_CUBIC_BEZIER_CONTROL_POINT
Cubic bezier control-point type for drawing paths. |
|
static byte |
CURVEDPATH_END_POINT
End-point type for drawing paths. |
|
static byte |
CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT
Quadratic bezier control-point type for drawing paths. |
|
static int |
DRAWSTYLE_AALINES
Drawing style for anti-aliased rendering of lines, used by Graphics.setDrawingStyle(int, boolean) and Graphics.isDrawingStyleSet(int) . |
|
static int |
DRAWSTYLE_AAPOLYGONS
Drawing style for anti-aliased rendering of polygons, used by Graphics.setDrawingStyle(int, boolean) and Graphics.isDrawingStyleSet(int) . |
|
static int |
DRAWSTYLE_FOCUS
This style is set by the framework when painting is being done for focus drawing. |
|
static int |
DRAWSTYLE_SELECT
This style is set by the framework when painting is being done for selection drawing. |
|
static int |
FULL_BLACK
Full black (0x00000000). |
|
static int |
FULL_WHITE
Full white (0x00ffffff). |
|
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. |
|
static int |
ROP2_D
Binary raster op constant for nop. |
|
static int |
ROP2_DSa
Binary raster op constant for masking ( source and dest ). |
|
static int |
ROP2_DSan
Binary raster op constant for ( not ( source and dest ) ). |
|
static int |
ROP2_DSna
Binary raster op constant for ( ( not source ) and dest ). |
|
static int |
ROP2_DSno
Binary raster op constant for ( ( not source ) or dest ). |
|
static int |
ROP2_DSo
Binary raster op constant for ( source or dest ). |
|
static int |
ROP2_DSon
Binary raster op constant for ( not ( source or dest ) ). |
|
static int |
ROP2_DSx
Binary raster op constant for selective invert ( source xor dest ). |
|
static int |
ROP2_DSxn
Binary raster op constant for ( not ( source xor dest ) ). |
|
static int |
ROP2_Dn
Binary raster op constant for invert destination. |
|
static int |
ROP2_S
Binary raster op constant for normal source copy. |
|
static int |
ROP2_SDna
Binary raster op constant for ( ( not dest ) and source ). |
|
static int |
ROP2_SDno
Binary raster op constant for ( source or ( not dest ) ). |
|
static int |
ROP2_Sn
Binary raster op constant for ( not source ). |
|
static int |
ROP_CONST_GLOBALALPHA
Raster operation constant for blending the constant foreground colour, 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 |
ROP_SRC_ALPHA
Raster operation constant for normal bitmap copy with an alpha channel. |
|
static int |
ROP_SRC_ALPHA_GLOBALALPHA
Raster operation constant for blending a source bitmap with an alpha channel and a constant global alpha value with destination pixels. |
|
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 boolean |
SCREEN_HAS_BORDER
Does the screen have a lit border around the drawable area of the screen? |
|
static int |
WHITE
White (0x00EBEBEB). |
Fields inherited from interface net.rim.device.api.ui.DrawStyle |
---|
BASELINE, BOTTOM, ELLIPSIS, HALIGN_MASK, HCENTER, HDEFAULT, HFULL, LEADING, LEFT, RIGHT, TOP, TRAILING, TRUNCATE_BEGINNING, VALIGN_MASK, VCENTER, VDEFAULT, VFULL |
Constructor Summary | ||
---|---|---|
Graphics(Bitmap bitmap)
Deprecated. Instead use Graphics.create( Bitmap ) |
Method Summary | ||
---|---|---|
void |
clear()
Clears the entire graphics area to the current background color. |
|
void |
clear(int x,
int y,
int width,
int height)
Clears a region to the current background color. |
|
void |
clear(XYRect region)
Clears a region specified by an XYRect object to the current background color. |
|
boolean |
copyArea(int x,
int y,
int width,
int height,
int dx,
int dy)
Copies a region of this graphics canvas. |
|
boolean |
copyArea(XYRect region,
int dx,
int dy)
Copies a region of this graphics canvas, specified by an XYRect . |
|
static Graphics |
create(Bitmap bitmap)
Constructs a Graphics object for drawing to a bitmap. |
|
void |
drawARGB(int[] data,
int offset,
int scanLength,
int x,
int y,
int width,
int height)
Similar to drawRGB, but source data also contains alpha. |
|
void |
drawArc(int x,
int y,
int width,
int height,
int startAngle,
int arcAngle)
Draws an arc through a specified rectangle. |
|
void |
drawBitmap(int x,
int y,
int width,
int height,
Bitmap bitmap,
int left,
int top)
Draws a bitmap. |
|
void |
drawBitmap(XYRect dest,
Bitmap bitmap,
int left,
int top)
Draws a bitmap on a region specified by an XYRect object. |
|
void |
drawEllipse(int cx,
int cy,
int px,
int py,
int qx,
int qy,
int startAngle,
int arcAngle)
Draws an ellipse. |
|
void |
drawFilledPath(int[] xPts,
int[] yPts,
byte[] pointTypes,
int[] offsets)
Draws a set of filled paths. |
|
void |
drawImage(int x,
int y,
int width,
int height,
EncodedImage image,
int frameIndex,
int left,
int top)
Draws an encoded image. |
|
void |
drawImage(XYRect dest,
EncodedImage image,
int frameIndex,
int left,
int top)
Draws an encoded image on a region specified by an XYRect object. |
|
void |
drawLine(int x1,
int y1,
int x2,
int y2)
Draws a line. |
|
void |
drawOutlinedPath(int[] xPts,
int[] yPts,
byte[] pointTypes,
int[] offsets,
boolean closed)
Draw a set of path outlines. |
|
void |
drawPathOutline(int[] xPts,
int[] yPts,
byte[] pointTypes,
int[] offsets,
boolean closed)
Deprecated. |
|
void |
drawPoint(int x,
int y)
Draws a point. |
|
void |
drawRGB(int[] data,
int offset,
int scanLength,
int x,
int y,
int width,
int height)
Draws raw RGB data from an int array. |
|
void |
drawRect(int x,
int y,
int width,
int height)
Draws a rectangle. |
|
void |
drawRoundRect(int x,
int y,
int width,
int height,
int arcWidth,
int arcHeight)
Draws a rectangle with rounded edges. |
|
void |
drawShadedFilledPath(int[] xPts,
int[] yPts,
byte[] pointTypes,
int[] colors,
int[] offsets)
Draws a set of shaded filled paths. |
|
int |
drawText(byte[] aText,
int aOffset,
int aLength,
int aX,
int aY,
int aFlags,
int aWidth)
Draws part of the contents of a byte array using the current font, clipping to the current clipping region, and using the baseline and alignment specified by aFlags and aWidth. |
|
int |
drawText(char aChar,
int aX,
int aY,
int aFlags,
int aWidth)
Draws a character using the current font and clipping to the current clipping region. |
|
int |
drawText(char[] aText,
int aOffset,
int aLength,
int aX,
int aY,
int aFlags,
int aWidth)
Draws part of the contents of a char array using the current font, clipping to the current clipping region, and using the baseline and alignment specified by aFlags and aWidth. |
|
int |
drawText(String aText,
int aX,
int aY)
Draws the text in a string using the current font, clipping to the current clipping region and using the TOP baseline and LEFT alignment. |
|
int |
drawText(String aText,
int aX,
int aY,
int aFlags)
Draws the text in a string using the current font, clipping to the current clipping region and using the baseline specified by aFlags. |
|
int |
drawText(String aText,
int aX,
int aY,
int aFlags,
int aWidth)
Draws the text in a string using the current font, clipping to the current clipping region, and using the baseline and alignment specified by aFlags and aWidth. |
|
int |
drawText(String aText,
int aOffset,
int aLength,
int aX,
int aY,
int aFlags,
int aWidth)
Draws part of the text in a String using the current font, clipping to the current clipping region, and using the baseline and alignment specified by aFlags and aWidth. |
|
int |
drawText(StringBuffer aText,
int aOffset,
int aLength,
int aX,
int aY,
int aFlags,
int aWidth)
Draws part of the text in a StringBuffer using the current font, clipping to the current clipping region, and using the baseline and alignment specified by aFlags and aWidth. |
|
void |
drawTexturedPath(int[] xPts,
int[] yPts,
byte[] pointTypes,
int[] offsets,
int xOrigin,
int yOrigin,
int dux,
int dvx,
int duy,
int dvy,
Bitmap textureData)
Draws a set of texture-filled paths. |
|
void |
fillArc(int x,
int y,
int width,
int height,
int startAngle,
int arcAngle)
Fills a circular or elliptical arc covering a specified rectangle. |
|
void |
fillEllipse(int cx,
int cy,
int px,
int py,
int qx,
int qy,
int startAngle,
int arcAngle)
Fills an ellipse. |
|
void |
fillRect(int x,
int y,
int width,
int height)
Fills a rectangle. |
|
void |
fillRoundRect(int x,
int y,
int width,
int height,
int arcWidth,
int arcHeight)
Fills a rectangle with rounded edges. |
|
void |
getAbsoluteClippingRect(XYRect clip)
Retreives the absolute coordinates of current clipping region. |
|
int |
getBackgroundColor()
Retrieves the current background color. |
|
XYRect |
getClippingRect()
Retrieves the local coordinates of current clipping region. |
|
int |
getColor()
Retrieves the current foreground drawing color. |
|
int |
getContextStackSize()
Retrieves the size of the stack of drawing contexts. |
|
void |
getDrawingOffset(XYPoint offset)
Retrieves the absolute coordinates for the current drawing offset. |
|
Font |
getFont()
Retrieves the current font for the current graphics context. |
|
int |
getGlobalAlpha()
Retrieves the current global alpha value. |
|
int |
getNearestColor(int color)
Gets the color that will be used if the specified color is requested. |
|
static int |
getNumColors()
Deprecated. Use Display.getNumColors(); |
|
static int |
getScreenHeight()
Deprecated. Use Display.getHeight() |
|
static int |
getScreenHorizontalResolution()
Deprecated. Use Display.getHorizontalResolution() |
|
static int |
getScreenVerticalResolution()
Deprecated. Use Display.getVerticalResolution() |
|
static int |
getScreenWidth()
Deprecated. Use Display.getWidth() |
|
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()
Deprecated. Use Display.isColor(). |
|
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. |
|
void |
setBackgroundColor(int RGB)
Sets the current background color. |
|
void |
setColor(int RGB)
Sets the current color. |
|
void |
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. |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int BLACK
public static final int WHITE
public static final int FULL_BLACK
public static final int FULL_WHITE
public static final int ROP_SRC_COPY
public static final int ROP_SRCMONOEXPAND_COPY
public static final int ROP_SRC_ALPHA
public static final int ROP_SRCMONOEXPAND_ALPHA
public static final int ROP_CONST_GLOBALALPHA
Set the global alpha value using Graphics.setGlobalAlpha(int)
.
public static final int ROP_SRC_GLOBALALPHA
Set the global alpha value using Graphics.setGlobalAlpha(int)
.
public static final int ROP_SRC_ALPHA_GLOBALALPHA
Set the global alpha value using Graphics.setGlobalAlpha(int)
.
public static final int ROP2_0
public static final int ROP2_DSon
public static final int ROP2_DSna
public static final int ROP2_Sn
public static final int ROP2_SDna
public static final int ROP2_Dn
public static final int ROP2_DSx
public static final int ROP2_DSan
public static final int ROP2_DSa
public static final int ROP2_DSxn
public static final int ROP2_D
public static final int ROP2_DSno
public static final int ROP2_S
public static final int ROP2_SDno
public static final int ROP2_DSo
public static final int ROP2_1
public static final int DRAWSTYLE_AALINES
Graphics.setDrawingStyle(int, boolean)
and Graphics.isDrawingStyleSet(int)
.
If this style is set, lines and path outlines may be antialiased.
This style is off by default.
public static final int DRAWSTYLE_AAPOLYGONS
Graphics.setDrawingStyle(int, boolean)
and Graphics.isDrawingStyleSet(int)
.
If this style is set, filled paths and polygons may be antialiased.
This style is off by default.
public static final int DRAWSTYLE_FOCUS
public static final int DRAWSTYLE_SELECT
public static final byte CURVEDPATH_END_POINT
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.
public static final byte CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT
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.
public static final byte CURVEDPATH_CUBIC_BEZIER_CONTROL_POINT
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.
public static final boolean SCREEN_HAS_BORDER
Constructor Detail |
---|
public Graphics(Bitmap bitmap)
bitmap
- Bitmap to draw into. Must be the default type of the device.
IllegalArgumentException
- If the type of 'bitmap' is not
supported, or the bitmap is readonly.Method Detail |
---|
public static Graphics create(Bitmap bitmap)
bitmap
- Bitmap to draw into. Must be the default type of the device.
public void clear()
public void clear(int x, int y, int width, int height)
Use this method to clear only a region within the entire graphics area. You specify the region to clear by describing its extent in passed parameters.
x
- Left edge of the region.y
- Top edge of the region.width
- Width of the region.height
- Height of the region.public void clear(XYRect region)
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.
region
- Rectangular region to clear.public boolean copyArea(int x, int y, int width, int height, int dx, int dy)
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.
x
- Left edge of the source region.y
- Top edge of the source regionwidth
- 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.
public boolean copyArea(XYRect region, int dx, int dy)
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.
region
- Source region to copy.dx
- Horizontal distance to move the region.dy
- Vertical distance to move the region.
public void drawARGB(int[] data, int offset, int scanLength, int x, int y, int width, int height)
data
- offset
- scanLength
- x
- y
- width
- height
- public void drawArc(int x, int y, int width, int height, int startAngle, int arcAngle)
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
:
(startAngle < arcAngle)
, this method draws the arc
in a counterclockwise direction.
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. ATTENTION: This method doesn't support transformations specified in the setTransformation method.
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.public void drawEllipse(int cx, int cy, int px, int py, int qx, int qy, int startAngle, int arcAngle)
Draws an ellipse with the specified endpoints P = (px, py) and Q = (qx, qy) of two conjugate diameters of the ellipse. The endpoints are specified as absolute coordinates.
This example shows an ellipse with the aligned p and q points.
This example shows how the p and q points can be used to draw a non-aligned ellipse.
cx
- X-ordinate of the ellipse centre. cx is one of the coordinates of the center point of the ellipse.cy
- Y-ordinate of the ellipse centre.px
- X-ordinate of the point P. P is one of the coordinates of the tangents of a parallelogram
that bounds the ellipse. By convention, if the ellipse is aligned with the screen axes,
the p point defines the x-axis radius.py
- Y-ordinate of the point P. P is one of the coordinates of the tangents of a parallelogram
that bounds the ellipse. By convention, if the ellipse is aligned with the screen axes,
the p point defines the x-axis radius.qx
- X-ordinate of the point Q. Q is one of the coordinates of the tangents of a parallelogram
that bounds the ellipse. By convention, if the ellipse is aligned with the screen axes,
the q point defines the y-axis radius.qy
- Y-ordinate of the point Q. Q is one of the coordinates of the tangents of a parallelogram
that bounds the ellipse. By convention, if the ellipse is aligned with the screen axes,
the q point defines the y-axis radius.startAngle
- Arc start angle. Drawing starts at the angular position defined by the start angle
(clockwise with zero degrees being the x-axis and x left, y down) and ends at an angular position
equal to the start angle plus the arc angle. For example, if you set the start angle to 90 degrees
and the arc angle to 90 degrees, the ¼ ellipse starts at the y axis and continues to the x axis.arcAngle
- Angular extent of the arc, relative to the start angle.public boolean isRopSupported(int rop)
Use this method to query if a particular raster operation is
supported for the Graphics object. Note that all ROP2s as well as
Graphics.ROP_SRC_COPY
, Graphics.ROP_SRCMONOEXPAND_COPY
,
Graphics.ROP_SRC_ALPHA
and Graphics.ROP_SRCMONOEXPAND_ALPHA
are always
supported.
rop
- Constant for the raster operation to query.
public void rop(int rop, int x, int y, int width, int height, Bitmap source, int left, int top)
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.
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.public void tileRop(int rop, int x, int y, int width, int height, Bitmap source, int left, int top)
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.
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.public void drawBitmap(XYRect dest, Bitmap bitmap, int left, int top)
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.
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.public void drawBitmap(int x, int y, int width, int height, Bitmap bitmap, int left, int top)
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 are drawn exactly as in the Bitmap, with no color transformations.
To have a monochrome image act like a rubber stamp, use Graphics.rop(int, int, int, int, int, net.rim.device.api.system.Bitmap, int, int)
with
Graphics.ROP_SRCMONOEXPAND_COPY
or Graphics.ROP_SRCMONOEXPAND_ALPHA
.
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.public void drawImage(XYRect dest, EncodedImage image, int frameIndex, int left, int top)
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.
dest
- Destination region in which to draw the bitmap.image
- Encoded image to drawframeIndex
- The frame to drawleft
- Left edge of region within bitmap to draw.top
- Top edge of region within bitmap to draw.public void drawImage(int x, int y, int width, int height, EncodedImage image, int frameIndex, int left, int top)
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 are drawn exactly as in the Bitmap, with no color transformations.
To have a monochrome image act like a rubber stamp, use Graphics.rop(int, int, int, int, int, net.rim.device.api.system.Bitmap, int, int)
with
Graphics.ROP_SRCMONOEXPAND_COPY
or Graphics.ROP_SRCMONOEXPAND_ALPHA
.
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 drawleft
- Left edge of region within bitmap to draw.top
- Top edge of region within bitmap to draw.public void drawFilledPath(int[] xPts, int[] yPts, byte[] pointTypes, int[] offsets)
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.
xPts
- Ordered list of x values for each vertex in the paths.yPts
- Ordered list of y values for each vertex in the paths.pointTypes
- One of Graphics.CURVEDPATH_END_POINT
,
Graphics.CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT
,
or Graphics.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 Graphics.CURVEDPATH_END_POINT
.
If a point's value is Graphics.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 Graphics.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
(Graphics.CURVEDPATH_END_POINT
).
If a point's value is Graphics.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
(Graphics.CURVEDPATH_END_POINT
) coming before the first control point and
after the second.
offsets
- 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).
IllegalArgumentException
- If the data is malformed. For example,
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.public void drawShadedFilledPath(int[] xPts, int[] yPts, byte[] pointTypes, int[] colors, int[] offsets)
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, for example, 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.
xPts
- Ordered list of x values for each vertex in the paths.yPts
- Ordered list of y values for each vertex in the paths.pointTypes
- One of Graphics.CURVEDPATH_END_POINT
,
Graphics.CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT
,
or Graphics.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 Graphics.CURVEDPATH_END_POINT
.
If a point's value is Graphics.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
Graphics.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 (Graphics.CURVEDPATH_END_POINT
).
If a point's value is Graphics.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
(Graphics.CURVEDPATH_END_POINT
) coming before the first control point and after
the second.
colors
- 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
- 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).
IllegalArgumentException
- If the data is malformed. For example,
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.public void drawPathOutline(int[] xPts, int[] yPts, byte[] pointTypes, int[] offsets, boolean closed)
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.
xPts
- Ordered list of x values for each vertex in the paths.yPts
- Ordered list of y values for each vertex in the paths.pointTypes
- One of Graphics.Graphics.CURVEDPATH_END_POINT
,
Graphics.CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT
,
or Graphics.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 Graphics.CURVEDPATH_END_POINT
.
If a point's value is Graphics.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 Graphics.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
(Graphics.CURVEDPATH_END_POINT
).
If a point's value is Graphics.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
(Graphics.CURVEDPATH_END_POINT
) coming before the first control point and after
the second.
offsets
- 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.
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.Graphics.drawOutlinedPath(int[],int[],byte[],int[],boolean)
public void drawOutlinedPath(int[] xPts, int[] yPts, byte[] pointTypes, int[] offsets, boolean closed)
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.
xPts
- Ordered list of x values for each vertex in the paths.yPts
- Ordered list of y values for each vertex in the paths.pointTypes
- One of Graphics.Graphics.CURVEDPATH_END_POINT
,
Graphics.CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT
,
or Graphics.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 Graphics.CURVEDPATH_END_POINT
.
If a point's value is Graphics.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 Graphics.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
(Graphics.CURVEDPATH_END_POINT
).
If a point's value is Graphics.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
(Graphics.CURVEDPATH_END_POINT
) coming before the first control point and after
the second.
offsets
- 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.
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.public void drawTexturedPath(int[] xPts, int[] yPts, byte[] pointTypes, int[] offsets, int xOrigin, int yOrigin, int dux, int dvx, int duy, int dvy, Bitmap textureData)
Use this method to draw one or more texture-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.
The texture used to fill the path is specified as a Bitmap. Starting
from the texture origin (as specified in local coordinates by
xOrigin
and yOrigin
), the texture is mapped
into the path, being tiled as necessary to fill the region. The scale and
angle used to map the texture are specified by the two walk vectors
(dux
, dvx
) and (duy
,
dvy
) (u and v are taken to correspond to x and y, but in
texture space rather than in screen space). dux
and
dvx
indicate how many u and v coordinates to skip in the
texture per x coordinate on the screen. Likewise, duy
and
dvy
indicate how texture coordinates to skip per y
coordinate on the screen. These four values are represented in 15.16
fixed point, allowing for eight bits of decimal precision. Using these
walk vectors it is possible to achieve arbitrary rotation, scaling, and
skewing on a given texture.
Note that each non-null array parameter must be a different array.
xPts
- Ordered list of x values for each vertex in the paths.yPts
- Ordered list of y values for each vertex in the paths.pointTypes
- One of Graphics.CURVEDPATH_END_POINT
,
Graphics.CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT
,
or Graphics.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 Graphics.CURVEDPATH_END_POINT
.
If a point's value is Graphics.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 Graphics.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
(Graphics.CURVEDPATH_END_POINT
).
If a point's value is Graphics.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
(Graphics.CURVEDPATH_END_POINT
) coming before the first control point and
after the second.
offsets
- 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).xOrigin
- X component of the texture origin in local screen
coordinates.yOrigin
- Y component of the texture origin in local screen
coordinates.dux
- Number of u points to skip in the texture per x point on
screen (15.16 fixed point).dvx
- Number of v points to skip in the texture per x point on
screen (15.16 fixed point).duy
- Number of u points to skip in the texture per y point on
screen (15.16 fixed point).dvy
- Number of v points to skip in the texture per y point on
screen (15.16 fixed point).textureData
- Non-null bitmap to be used as a texture.
IllegalArgumentException
- If the data is malformed. For example,
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.
IllegalArgumentException
- If texture bitmap is null.
IllegalArgumentException
- If texture bitmap is empty, i.e. width or height is zero.public void drawLine(int x1, int y1, int x2, int y2)
Use this method to draw a line; you specify coordinates for the endpoints of the line.
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.public void drawPoint(int x, int y)
This method draws the pixel located at a coordinate you specify.
x
- Horizontal position of the point to draw.y
- Vertical position of the point to draw.public void drawRect(int x, int y, int width, int height)
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.
x
- Left edge of the rectangle.y
- Top edge of the rectangle.width
- Width of the rectangle.height
- Height of the rectangle.public void drawRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight)
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.
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.public void drawRGB(int[] data, int offset, int scanLength, int x, int y, int width, int height)
data
- Color data to use, of the form 0x00RRGGBB.offset
- Offset into the data to start drawing from.scanLength
- Width of a scanline within the data.x
- Left edge of rectangle.y
- Top edge of the rectangle.width
- Width of the rectangle.height
- Height of the rectangle.
NullPointerException
- If 'data' is null.
ArrayIndexOutOfBoundsException
- If the data parameters are invalid.public int drawText(char aChar, int aX, int aY, int aFlags, int aWidth)
aChar
- The character to draw.aX
- The horizontal position of the drawing anchor in pixels.aY
- The vertical position of drawing anchor in pixels.aFlags
- A combination of constant drawing position flags.aWidth
- The width in pixels. The text is aligned within this
width, and truncated if it is wider than aWidth. The value -1
causes the actual width of the text to be used, and forces left alignment.
public int drawText(String aText, int aX, int aY)
aText
- The text to draw.aX
- The horizontal position of the drawing anchor in pixels.aY
- The vertical position of drawing anchor in pixels.
public int drawText(String aText, int aX, int aY, int aFlags)
aText
- The text to draw.aX
- The horizontal position of the drawing anchor in pixels.aY
- The vertical position of drawing anchor in pixels.aFlags
- A combination of constant drawing position flags.
public int drawText(String aText, int aX, int aY, int aFlags, int aWidth)
aText
- The text to draw.aX
- The horizontal position of the drawing anchor in pixels.aY
- The vertical position of drawing anchor in pixels.aFlags
- A combination of constant drawing position flags.aWidth
- The width in pixels. The text is aligned within this
width, and truncated if it is wider than aWidth. The value -1
causes the actual width of the text to be used, and forces left alignment.
public int drawText(byte[] aText, int aOffset, int aLength, int aX, int aY, int aFlags, int aWidth)
Each byte is a single Unicode code point in the range 0...255. This method does not support UTF8 or any other encoding. To draw characters outside this range use a drawText method that accepts a char array or a String.
aText
- The text to draw.aOffset
- The start index of the text.aLength
- The length of the text (number of elements in the array) to draw.aX
- The horizontal position of the drawing anchor in pixels.aY
- The vertical position of drawing anchor in pixels.aFlags
- A combination of constant drawing position flags.aWidth
- The width in pixels. The text is aligned within this
width, and truncated if it is wider than aWidth. The value -1
causes the actual width of the text to be used, and forces left alignment.
IndexOutOfBoundsException
- If the values of aOffset and aLength
cause an element outside the array aText to be accessed.public int drawText(char[] aText, int aOffset, int aLength, int aX, int aY, int aFlags, int aWidth)
aText
- The text to draw.aOffset
- The start index of the text.aLength
- The length of the text (number of elements in the array) to draw.aX
- The horizontal position of the drawing anchor in pixels.aY
- The vertical position of drawing anchor in pixels.aFlags
- A combination of constant drawing position flags.aWidth
- The width in pixels. The text is aligned within this
width, and truncated if it is wider than aWidth. The value -1
causes the actual width of the text to be used, and forces left alignment.
IndexOutOfBoundsException
- If the values of aOffset and aLength
cause an element outside the array aText to be accessed.public int drawText(String aText, int aOffset, int aLength, int aX, int aY, int aFlags, int aWidth)
aText
- The text to draw.aOffset
- The start index of the text.aLength
- The number of characters to draw.aX
- The horizontal position of the drawing anchor in pixels.aY
- The vertical position of drawing anchor in pixels.aFlags
- A combination of constant drawing position flags.aWidth
- The width in pixels. The text is aligned within this
width, and truncated if it is wider than aWidth. The value -1
causes the actual width of the text to be used, and forces left alignment.
IndexOutOfBoundsException
- If the values of aOffset and aLength
cause an element outside the array aText to be accessed.public int drawText(StringBuffer aText, int aOffset, int aLength, int aX, int aY, int aFlags, int aWidth)
aText
- The text to draw.aOffset
- The start index of the text.aLength
- The number of characters to draw.aX
- The horizontal position of the drawing anchor in pixels.aY
- The vertical position of drawing anchor in pixels.aFlags
- A combination of constant drawing position flags.aWidth
- The width in pixels. The text is aligned within this
width, and truncated if it is wider than aWidth. The value -1
causes the actual width of the text to be used, and forces left alignment.
IndexOutOfBoundsException
- If the values of aOffset and aLength
cause an element outside the array aText to be accessed.public void fillArc(int x, int y, int width, int height, int startAngle, int arcAngle)
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
:
(startAngle < arcAngle)
, this method fills the
arc in a counterclockwise direction.
(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. ATTENTION: This method doesn't support transformations specified in the setTransformation method.
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
- Angle position at which to commence drawing the edge of
the arc.arcAngle
- Angular extent of the arc, relative to the start angle.public void fillEllipse(int cx, int cy, int px, int py, int qx, int qy, int startAngle, int arcAngle)
Fills an ellipse with the specified endpoints P = (px, py) and Q = (qx, qy) of two conjugate diameters of the ellipse. The endpoints are specified as absolute coordinates.
This example shows an ellipse with the aligned p and q points.
This example shows how the p and q points can be used to draw a non-aligned ellipse.
cx
- X-ordinate of the ellipse centre. cx is one of the coordinates of the center point of the ellipse.cy
- Y-ordinate of the ellipse centre. cy is one of the coordinates of the center point of the ellipse.px
- X-ordinate of the point P. P is one of the coordinates of the tangents of a parallelogram
that bounds the ellipse. By convention, if the ellipse is aligned with the screen axes,
the p point defines the x-axis radius.py
- Y-ordinate of the point P. P is one of the coordinates of the tangents of a parallelogram
that bounds the ellipse. By convention, if the ellipse is aligned with the screen axes,
the p point defines the x-axis radius.qx
- X-ordinate of the point Q. Q is one of the coordinates of the tangents of a parallelogram
that bounds the ellipse. By convention, if the ellipse is aligned with the screen axes,
the q point defines the y-axis radius.qy
- Y-ordinate of the point Q. Q is one of the coordinates of the tangents of a parallelogram
that bounds the ellipse. By convention, if the ellipse is aligned with the screen axes,
the q point defines the y-axis radius.startAngle
- Arc start angle. Drawing starts at the angular position defined by the start angle
(clockwise with zero degrees being the x-axis and x left, y down) and ends at an angular position
equal to the start angle plus the arc angle. For example, if you set the start angle to 90 degrees
and the arc angle to 90 degrees, the ¼ ellipse starts at the y axis and continues to the x axis.arcAngle
- Angular extent of the arc, relative to the start angle.public void fillRect(int x, int y, int width, int height)
Note that if global alpha is set or if the fill color includes alpha then the rectangle color will be blended onto the content on the target surface.
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.
x
- Left edge of the rectangle.y
- Top edge of the rectangle.width
- Width of the rectangle.height
- Height of the rectangle.public void fillRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight)
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.
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.public void getAbsoluteClippingRect(XYRect clip)
Use this method to retrieve, into a provided XYRect object, the absolute coordinates of the current clipping region.
Since the out parameter contains only a copy of the clipping region, altering its contents has no effect on the current clipping region.
clip
- Clipping region is returned in this parameter.public int getBackgroundColor()
public XYRect getClippingRect()
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.
public int getContextStackSize()
public int getColor()
public void getDrawingOffset(XYPoint offset)
The drawing offset is the point, offset from the top left corner of the screen, which drawing operations use as their origin point.
offset
- Drawing offset is returned in this paramater.public int getGlobalAlpha()
public int getNearestColor(int color)
color
- the desired color (in 0x00RRGGBB format, the high-order byte is ignored)
public static int getNumColors()
public int getStipple()
public Font getFont()
public static int getScreenHeight()
public static int getScreenHorizontalResolution()
public static int getScreenVerticalResolution()
public static int getScreenWidth()
public void invert(int x, int y, int width, int height)
This method performs a one's complement operation on each pixel in your specified region.
x
- Left edge of the region.y
- Top edge of the region.width
- Width of the region.height
- Height of the region.public void invert(XYRect rect)
This method performs a one's complement operation on each pixel in your specified region.
rect
- Region to invert.public void popContext()
Use this method to pop off the context stack the last context pushed.
public boolean pushRegion(int x, int y, int width, int height, int xScroll, int yScroll)
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.
x
- Left edge of the region.y
- Top edge of the region.width
- Width of the region.height
- Height of the region.xScroll
- Optional, additional scroll offset.yScroll
- Optional, additional scroll offset.public boolean pushRegion(XYRect region)
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.
region
- New drawing region rectangle in local coordinates.public boolean pushRegion(XYRect region, int xScroll, int yScroll)
This method behaves exactly like Graphics.pushRegion(XYRect)
, except
you can also specify an (optional) additional scroll offset with the
xScroll
and yScroll
parameters.
region
- New drawing region in local coordinates.xScroll
- Optional, additional horizontal scroll offset.yScroll
- Optional, additional vertical scroll offset.public boolean pushContext(XYRect clip, int xOffset, int yOffset)
This clipping region is updated by intersecting with the previous
clipping region. Unlike Graphics.pushRegion(int, int, int, int, int, int)
, 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.
clip
- New clipping region in local coordinates.xOffset
- Optional, additional horizontal scroll offset.yOffset
- Optional, additional vertical scroll offset.public boolean pushContext(int x, int y, int width, int height, int xOffset, int yOffset)
This clipping region is updated by intersecting with the previous
clipping region. Unlike Graphics.pushRegion(int, int, int, int, int, int)
, 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, Graphics.pushRegion(int, int, int, int, int, int)
should be
used.
x
- Left edge of clipping region.y
- Top edge of clipping region.width
- Width in pixels of clipping region.height
- Height in pixels of clipping region.xOffset
- Optional, additional horizontal scroll offset.yOffset
- Optional, additional vertical scroll offset.public void translate(int x, int y)
The drawing offset is updated by adding the x and y offsets.
x
- Horizontal offset to add to the current x drawing offset.y
- Vertical offset to add to the current y drawing offset.public int getTranslateX()
public int getTranslateY()
public boolean isDrawingStyleSet(int drawStyle)
drawStyle
- Graphics drawing style to be checked.
public void setDrawingStyle(int drawStyle, boolean on)
drawStyle
- Graphics drawing style to turn on or off.on
- True to turn on the specified style, false to turn it off.public void setColor(int RGB)
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).
RGB
- Color to use, of the form 0x00RRGGBB.public void setGlobalAlpha(int alpha)
Be sure to reset the global alpha value when appropriate since all subsequent operations are done using the value specified. Global alpha is stored on the stack so popContext will restore it to the previous value.
Note that alpha
will be clamped to the range 0-255.
alpha
- Alpha value to use, from 0 (fully transparent) to 255 (fully opaque).public void setStipple(int mask)
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.
mask
- The stipple mask to use for line drawing.public void setBackgroundColor(int RGB)
RGB
- Color to use, of the form 0x00RRGGBB.public void setFont(Font font)
Subsequent text rendering uses this font.
font
- New font.
NullPointerException
- If font is null.public static boolean isColor()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.