net.rim.device.api.ui
Class Graphics

java.lang.Object
  net.rim.device.api.ui.Graphics

All Implemented Interfaces:

DrawStyle

public class Graphics
extends Object
implements DrawStyle

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 the following information about the current drawing context:

• Clipping region
• Offset position
• Foreground color
• Global alpha
• Background color
• Stippling pattern
• Draw style flags
• Stroke width
• Stroke style

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 rectangles with rounded corners
You have a variety of methods for drawing rects with rounded corners. This class identifies each logical corner with an associated static bitmask constant with a name ending in _ROUNDED_RECT_CORNER, and this class also provides pre-combined mask constants representing groups of corners (with names ending in _ROUNDED_RECT_CORNERS). Combine these constants together to pass to one of the appropriate draw methods (such as Graphics.drawGradientFilledRoundedRect(net.rim.device.api.ui.XYRect, int, int, int, int)), identifying which of the rect's corners should render as rounded, and which should render as squared off.

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.

You may further notice that since advance width can be less than the inked pixels width (e.g. 'K' in BBAlphaSans or Georgia), if we pass width returned by Font.measureText() (x advance) into the drawText method, the text drawn might get truncated. The drawText tries to align width of the inked pixels within the supplied width. For most of the cases, you may use Font.getBounds() which returns maximum of these widths.

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	ALL_ROUNDED_RECT_CORNERS All four corners of a drawn rectangle should be rounded.
static int	BLACK Black (0x00101010).
static int	BOTTOM_LEFT_ROUNDED_RECT_CORNER Bottom-left corner of a drawn rectangle should be rounded.
static int	BOTTOM_RIGHT_ROUNDED_RECT_CORNER Bottom-right corner of a drawn rectangle should be rounded.
static int	BOTTOM_ROUNDED_RECT_CORNERS Both bottom corners of a drawn rectangle should be rounded.
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 Deprecated. use DRAWSTYLE_ANTIALIASED instead
static int	DRAWSTYLE_AAPOLYGONS Deprecated. use DRAWSTYLE_ANTIALIASED instead
static int	DRAWSTYLE_ANTIALIASED Drawing style for anti-aliased rendering of lines and 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	LEFT_ROUNDED_RECT_CORNERS Both left-side corners of a drawn rectangle should be rounded.
static int	NO_ROUNDED_RECT_CORNERS No corners of a drawn rectangle should be rounded.
static int	RIGHT_ROUNDED_RECT_CORNERS Both right-side corners of a drawn rectangle should be rounded.
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 Deprecated. Use fillRect instead.
static int	ROP_SRCMONOEXPAND_ALPHA Raster operation constant for expanding a monochrome source bitmap with current foreground and background drawing colors, 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 colors.
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	TOP_LEFT_ROUNDED_RECT_CORNER Top-left corner of a drawn rectangle should be rounded.
static int	TOP_RIGHT_ROUNDED_RECT_CORNER Top-right corner of a drawn rectangle should be rounded.
static int	TOP_ROUNDED_RECT_CORNERS Both top corners of a drawn rectangle should be rounded.
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. Use the static factory method, Graphics.create(Bitmap), instead.

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	drawGradientFilledRect(int x, int y, int width, int height, int startColor, int endColor) Draws an un-bordered rectangle with a gradient fill, from a provided point.
void	drawGradientFilledRect(int x, int y, int width, int height, int startColor, int endColor, boolean drawBorder) Draws a rectangle with a gradient fill, from a provided point.
void	drawGradientFilledRect(XYRect rect, int startColor, int endColor) Draws an un-bordered rectangle with a gradient fill.
void	drawGradientFilledRect(XYRect rect, int startColor, int endColor, boolean drawBorder) Draws a rectangle with a gradient fill.
void	drawGradientFilledRoundedRect(int x, int y, int width, int height, int startColor, int endColor, boolean drawBorder, int arcWidth, int arcHeight) Draws a fully rounded rectangle with a gradient fill, from a provided point.
void	drawGradientFilledRoundedRect(int x, int y, int width, int height, int startColor, int endColor, boolean drawBorder, int roundedCorners, int arcWidth, int arcHeight) Draws a rounded rectangle with a gradient fill, from a provided point.
void	drawGradientFilledRoundedRect(int x, int y, int width, int height, int startColor, int endColor, int arcWidth, int arcHeight) Draws an un-bordered, fully rounded rectangle with a gradient fill, from a provided point.
void	drawGradientFilledRoundedRect(int x, int y, int width, int height, int startColor, int endColor, int roundedCorners, int arcWidth, int arcHeight) Draws an un-bordered rectangle with a gradient fill, from a provided point.
void	drawGradientFilledRoundedRect(XYRect rect, int startColor, int endColor, boolean drawBorder, int arcWidth, int arcHeight) Draws a fully rounded rectangle with a gradient fill.
void	drawGradientFilledRoundedRect(XYRect rect, int startColor, int endColor, boolean drawBorder, int roundedCorners, int arcWidth, int arcHeight) Draws a rounded rectangle with a gradient fill.
void	drawGradientFilledRoundedRect(XYRect rect, int startColor, int endColor, int arcWidth, int arcHeight) Draws an un-bordered, fully rounded rectangle with a gradient fill.
void	drawGradientFilledRoundedRect(XYRect rect, int startColor, int endColor, int roundedCorners, int arcWidth, int arcHeight) Draws an un-bordered, rounded rectangle with a gradient fill.
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. Use Graphics.drawOutlinedPath(int[],int[],byte[],int[],boolean).
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	drawRoundRect(int x, int y, int width, int height, int roundedCorners, int arcWidth, int arcHeight) Draws an un-bordered rounded rectangle, from a provided point.
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(char[] aText, int aOffset, int aLength, int aX, int aY, DrawTextParam aParam, TextMetrics aMetrics) Draws part of the text in a char array using the current font and clipping to the current clipping region.
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(String aText, int aOffset, int aLength, int aX, int aY, DrawTextParam aParam, TextMetrics aMetrics) Draws part of the text in a String using the current font and clipping to the current clipping region.
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.
int	drawText(StringBuffer aText, int aOffset, int aLength, int aX, int aY, DrawTextParam aParam, TextMetrics aMetrics) Draws part of the text in a StringBuffer using the current font and clipping to the current clipping region.
int	drawTextOnPath(char[] aText, int aOffset, int aLength, int aOriginX, int aOriginY, int[] aXPoints, int[] aYPoints, byte[] aPointTypes, int[] aContourStarts, DrawTextParam aParam, TextMetrics aMetrics) Draws text along a path.
int	drawTextOnPath(String aText, int aOffset, int aLength, int aOriginX, int aOriginY, int[] aXPoints, int[] aYPoints, byte[] aPointTypes, int[] aContourStarts, DrawTextParam aParam, TextMetrics aMetrics) Draws text along a path.
int	drawTextOnPath(StringBuffer aText, int aOffset, int aLength, int aOriginX, int aOriginY, int[] aXPoints, int[] aYPoints, byte[] aPointTypes, int[] aContourStarts, DrawTextParam aParam, TextMetrics aMetrics) Draws text along a path.
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

BLACK

public static final int BLACK

Black (0x00101010).

See Also:

Constant Field Values

WHITE

public static final int WHITE

White (0x00EBEBEB).

See Also:

Constant Field Values

FULL_BLACK

public static final int FULL_BLACK

Full black (0x00000000).

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

FULL_WHITE

public static final int FULL_WHITE

Full white (0x00ffffff).

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP_SRC_COPY

public static final int ROP_SRC_COPY

Raster operation constant for normal bitmap copy.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP_SRCMONOEXPAND_COPY

public static final int ROP_SRCMONOEXPAND_COPY

Raster operation constant for expanding a monochrome source bitmap with the current foreground and background drawing colors.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP_SRC_ALPHA

public static final int ROP_SRC_ALPHA

Raster operation constant for normal bitmap copy with an alpha channel.

See Also:

Constant Field Values

Since:

BlackBerry API 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 colors, respecting the alpha channel. The behaves similar to a rubber stamp.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP_CONST_GLOBALALPHA

public static final int ROP_CONST_GLOBALALPHA

Deprecated. Use fillRect instead.

Raster operation constant for blending the constant foreground color, using a constant global alpha value with destination pixels.

Set the global alpha value using Graphics.setGlobalAlpha(int).

See Also:

Constant Field Values

Since:

BlackBerry API 3.7.0

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 Graphics.setGlobalAlpha(int).

See Also:

Constant Field Values

Since:

BlackBerry API 3.7.0

ROP_SRC_ALPHA_GLOBALALPHA

public static final 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.

Set the global alpha value using Graphics.setGlobalAlpha(int).

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

ROP2_0

public static final int ROP2_0

Binary raster op constant for zeroing out the destination.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_DSon

public static final int ROP2_DSon

Binary raster op constant for ( not ( source or dest ) ).

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_DSna

public static final int ROP2_DSna

Binary raster op constant for ( ( not source ) and dest ).

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_Sn

public static final int ROP2_Sn

Binary raster op constant for ( not source ).

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_SDna

public static final int ROP2_SDna

Binary raster op constant for ( ( not dest ) and source ).

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_Dn

public static final int ROP2_Dn

Binary raster op constant for invert destination.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_DSx

public static final int ROP2_DSx

Binary raster op constant for selective invert ( source xor dest ).

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_DSan

public static final int ROP2_DSan

Binary raster op constant for ( not ( source and dest ) ).

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_DSa

public static final int ROP2_DSa

Binary raster op constant for masking ( source and dest ).

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_DSxn

public static final int ROP2_DSxn

Binary raster op constant for ( not ( source xor dest ) ).

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_D

public static final int ROP2_D

Binary raster op constant for nop.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_DSno

public static final int ROP2_DSno

Binary raster op constant for ( ( not source ) or dest ).

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_S

public static final int ROP2_S

Binary raster op constant for normal source copy.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_SDno

public static final int ROP2_SDno

Binary raster op constant for ( source or ( not dest ) ).

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_DSo

public static final int ROP2_DSo

Binary raster op constant for ( source or dest ).

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

ROP2_1

public static final int ROP2_1

Binary raster op constant for filling dest with 1 values.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

DRAWSTYLE_AALINES

public static final int DRAWSTYLE_AALINES

Deprecated. use DRAWSTYLE_ANTIALIASED instead

Drawing style for anti-aliased rendering of lines, used by 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.

See Also:

Constant Field Values

Since:

BlackBerry API 3.7.0

DRAWSTYLE_AAPOLYGONS

public static final int DRAWSTYLE_AAPOLYGONS

Deprecated. use DRAWSTYLE_ANTIALIASED instead

Drawing style for anti-aliased rendering of polygons, used by 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.

See Also:

Constant Field Values

Since:

BlackBerry API 3.7.0

DRAWSTYLE_ANTIALIASED

public static final int DRAWSTYLE_ANTIALIASED

Drawing style for anti-aliased rendering of lines and polygons, used by Graphics.setDrawingStyle(int, boolean) and Graphics.isDrawingStyleSet(int).

If this style is set, lines, path outlines, afilled paths and polygons may be antialiased.

This style is off by default.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

DRAWSTYLE_FOCUS

public static final int DRAWSTYLE_FOCUS

This style is set by the framework when painting is being done for focus drawing.

See Also:

Constant Field Values

Since:

BlackBerry API 3.7.0

DRAWSTYLE_SELECT

public static final int DRAWSTYLE_SELECT

This style is set by the framework when painting is being done for selection drawing.

See Also:

Constant Field Values

Since:

BlackBerry API 3.7.0

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.

See Also:

Constant Field Values

Since:

BlackBerry API 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.

See Also:

Constant Field Values

Since:

BlackBerry API 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.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

NO_ROUNDED_RECT_CORNERS

public static final int NO_ROUNDED_RECT_CORNERS

No corners of a drawn rectangle should be rounded.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

TOP_LEFT_ROUNDED_RECT_CORNER

public static final int TOP_LEFT_ROUNDED_RECT_CORNER

Top-left corner of a drawn rectangle should be rounded.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

TOP_RIGHT_ROUNDED_RECT_CORNER

public static final int TOP_RIGHT_ROUNDED_RECT_CORNER

Top-right corner of a drawn rectangle should be rounded.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

BOTTOM_LEFT_ROUNDED_RECT_CORNER

public static final int BOTTOM_LEFT_ROUNDED_RECT_CORNER

Bottom-left corner of a drawn rectangle should be rounded.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

BOTTOM_RIGHT_ROUNDED_RECT_CORNER

public static final int BOTTOM_RIGHT_ROUNDED_RECT_CORNER

Bottom-right corner of a drawn rectangle should be rounded.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

TOP_ROUNDED_RECT_CORNERS

public static final int TOP_ROUNDED_RECT_CORNERS

Both top corners of a drawn rectangle should be rounded.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

BOTTOM_ROUNDED_RECT_CORNERS

public static final int BOTTOM_ROUNDED_RECT_CORNERS

Both bottom corners of a drawn rectangle should be rounded.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

LEFT_ROUNDED_RECT_CORNERS

public static final int LEFT_ROUNDED_RECT_CORNERS

Both left-side corners of a drawn rectangle should be rounded.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

RIGHT_ROUNDED_RECT_CORNERS

public static final int RIGHT_ROUNDED_RECT_CORNERS

Both right-side corners of a drawn rectangle should be rounded.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

ALL_ROUNDED_RECT_CORNERS

public static final int ALL_ROUNDED_RECT_CORNERS

All four corners of a drawn rectangle should be rounded.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

SCREEN_HAS_BORDER

public static final boolean SCREEN_HAS_BORDER

Does the screen have a lit border around the drawable area of the screen? Currently, this is false only for 7100-series and 8700-series devices.

Since:

BlackBerry API 4.0.2

Constructor Detail

Graphics

public Graphics(Bitmap bitmap)

Deprecated. Use the static factory method, Graphics.create(Bitmap), instead.

Constructs a Graphics object for drawing directly to a bitmap.

Parameters:

bitmap - Writeable bitmap to draw into; must not be null.

Throws:

IllegalArgumentException - If your provided bitmap is not writeable or too large to fit into the drawing cache.

Method Detail

create

public static Graphics create(Bitmap bitmap)

Constructs a Graphics object for drawing to a bitmap.

Parameters:

bitmap - Writeable bitmap to draw into. Must not be null and must be the default bitmap type for the device.

Returns:

Graphics object created from the provided bitmap.

Throws:

IllegalArgumentException - If your provided bitmap is not writeable or too large to fit into the drawing chache.

Since:

BlackBerry API 4.7.0

clear

public void clear()

Clears the entire graphics area to the current background color. Note that global alpha is not applied in this case. If the background color contains alpha and the target surface contains alpha, the pixels are overwritten with the background color and include alpha; the old target surface content is ignored.

clear

public void clear(int x,
                  int y,
                  int width,
                  int height)

Clears a region to the current background color. Note that global alpha is not applied in this case. If the background color contains alpha and the target surface contains alpha, the pixels are overwritten with the background color and include alpha; the old target surface content is ignored.

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.

Parameters:

x - Left edge of the region.

y - Top edge of the region.

width - Width of the region.

height - Height of the region.

clear

public void clear(XYRect region)

Clears a region specified by an XYRect object to the current background color. Note that global alpha is not applied in this case. If the background color contains alpha and the target surface contains alpha, the pixels are overwritten with the background color and include alpha; the old target surface content is ignored.

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.

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.

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.

drawARGB

public 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.

Parameters:

data -

offset -

scanLength -

x -

y -

width -

height -

Since:

BlackBerry API 4.2.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. ATTENTION: This method doesn't support transformations specified in the setTransformation method.

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.

drawEllipse

public void drawEllipse(int cx,
                        int cy,
                        int px,
                        int py,
                        int qx,
                        int qy,
                        int startAngle,
                        int arcAngle)

Draws an ellipse.

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.

Parameters:

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.

Since:

BlackBerry API 4.2.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 Graphics.ROP_SRC_COPY, Graphics.ROP_SRCMONOEXPAND_COPY, Graphics.ROP_SRC_ALPHA and Graphics.ROP_SRCMONOEXPAND_ALPHA are always supported.

Parameters:

rop - Constant for the raster operation to query.

Returns:

If true, specified raster operation is supported; otherwise, false.

Since:

BlackBerry API 3.7.0

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:

BlackBerry API 3.6.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:

BlackBerry API 3.6.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.

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 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.

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.

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:

BlackBerry API 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 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.

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:

BlackBerry API 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 i^th 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 - 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).

Throws:

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.

Since:

BlackBerry API 3.6.0

drawShadedFilledPath

public void drawShadedFilledPath(int[] xPts,
                                 int[] yPts,
                                 byte[] pointTypes,
                                 int[] colors,
                                 int[] offsets)

Draws a set of shaded filled paths.

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 i^th 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.

Parameters:

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).

Throws:

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.

Since:

BlackBerry API 3.7.0

drawPathOutline

public void drawPathOutline(int[] xPts,
                            int[] yPts,
                            byte[] pointTypes,
                            int[] offsets,
                            boolean closed)

Deprecated. Use Graphics.drawOutlinedPath(int[],int[],byte[],int[],boolean).

Draw a set of path outlines.

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 - 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.

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:

BlackBerry API 3.6.0

drawOutlinedPath

public void drawOutlinedPath(int[] xPts,
                             int[] yPts,
                             byte[] pointTypes,
                             int[] offsets,
                             boolean closed)

Draw a set of path outlines.

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 - 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.

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:

BlackBerry API 5.0.0

drawTexturedPath

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)

Draws a set of texture-filled paths.

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.

Specifying the positions of the vertices. 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.

Specifying the type of each vertex. The pointTypes array encodes the type of each point along the textured path: for example, the third element in the pointTypes array describes the function of the vertex at the position described by the third element in each of the xPts and yPts arrays. The values in the pointTypes array match static constants in this class, and should be equal to Graphics.CURVEDPATH_END_POINT, Graphics.CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT, or Graphics.CURVEDPATH_CUBIC_BEZIER_CONTROL_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. This is the default value for points (and if the pointTypes array is null, all points are assumed to be 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.

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 coming before the first control point and after the second.

Specifying the paths between vertices. The array of offset values indicates the beginnings of each path in the data array. The data in the i^th 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.

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.

Specifying the texture to draw with. You provide a bitmap to indicate the texture to draw with, in the textureData parameter. Starting from the texture origin (as specified in local coordinates by xOrigin and yOrigin), this method maps the texture into the path, tiling as necessary to fill the region.

You use two walk vectors (dux, dvx) and (duy, dvy) to describe the scale and angle the method should use to map the texture: 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 many 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: Each non-null array parameter must be a different array.

Parameters:

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 - Ordered list of point types corresponding to the list.

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.

Throws:

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.

Since:

BlackBerry API 4.2.0

drawTextOnPath

public int drawTextOnPath(StringBuffer aText,
                          int aOffset,
                          int aLength,
                          int aOriginX,
                          int aOriginY,
                          int[] aXPoints,
                          int[] aYPoints,
                          byte[] aPointTypes,
                          int[] aContourStarts,
                          DrawTextParam aParam,
                          TextMetrics aMetrics)

Draws text along a path.

This method draws the text along a path made up of straight line segments and curves. The curves are quadratic or cubic Bezier splines. A path is made up of one or more separate contours.

Note that each non-null array parameter must be a different array.

The coordinates of the path are pixels, relative to a specified origin. To use absolute path coordinates supply an origin of (0,0).

Parameters:

aText - The text to draw.

aOffset - The start index of the text.

aLength - The number of characters to draw.

aOriginX - The x part of the origin of the path coordinate system.

aOriginY - The y part of the origin of the path coordinate system.

aXPoints - An array of x coordinates for the path.

aYPoints - An array of y coordinates for the path.

aPointTypes - If non-null, an array of point types. If it is null, or if it contains fewer values than the points arrays, missing values are taken to be on-curve points. Each point type must be either Graphics.CURVEDPATH_END_POINT, Graphics.CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT, or Graphics.CURVEDPATH_CUBIC_BEZIER_CONTROL_POINT.

aContourStarts - If non-null, an array of indexes of contour (sub-path) starts. Each contour contains all the points from aContourStarts[N] to aContourStarts[N+1]-1, except for the last contour, which contains all remaining points.

aParam - Text drawing parameters. If null, use default parameters.

aMetrics - If not null, this parameter receives the metrics of the text drawn.

Returns:

The length of the text drawn along the path, in pixels.

Throws:

IllegalArgumentException - or NullPointerException.

Since:

BlackBerry API 6.0.0

drawTextOnPath

public int drawTextOnPath(String aText,
                          int aOffset,
                          int aLength,
                          int aOriginX,
                          int aOriginY,
                          int[] aXPoints,
                          int[] aYPoints,
                          byte[] aPointTypes,
                          int[] aContourStarts,
                          DrawTextParam aParam,
                          TextMetrics aMetrics)

Draws text along a path.

This method draws the text along a path made up of straight line segments and curves. The curves are quadratic or cubic Bezier splines. A path is made up of one or more separate contours.

Note that each non-null array parameter must be a different array.

The coordinates of the path are pixels, relative to a specified origin. To use absolute path coordinates supply an origin of (0,0).

Parameters:

aText - The text to draw.

aOffset - The start index of the text.

aLength - The number of characters to draw.

aOriginX - The x part of the origin of the path coordinate system.

aOriginY - The y part of the origin of the path coordinate system.

aXPoints - An array of x coordinates for the path.

aYPoints - An array of y coordinates for the path.

aPointTypes - If non-null, an array of point types. If it is null, or if it contains fewer values than the points arrays, missing values are taken to be on-curve points. Each point type must be either Graphics.CURVEDPATH_END_POINT, Graphics.CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT, or Graphics.CURVEDPATH_CUBIC_BEZIER_CONTROL_POINT

aContourStarts - If non-null, an array of indexes of contour (sub-path) starts. Each contour contains all the points from aContourStarts[N] to aContourStarts[N + 1] - 1, except for the last contour, which contains all remaining points.

aParam - Text drawing parameters. If null, use default parameters.

aMetrics - If non-null, this parameter receives the metrics of the text drawn.

Returns:

The length of the text drawn along the path, in pixels.

Throws:

IllegalArgumentException - or NullPointerException.

Since:

BlackBerry API 6.0.0

drawTextOnPath

public int drawTextOnPath(char[] aText,
                          int aOffset,
                          int aLength,
                          int aOriginX,
                          int aOriginY,
                          int[] aXPoints,
                          int[] aYPoints,
                          byte[] aPointTypes,
                          int[] aContourStarts,
                          DrawTextParam aParam,
                          TextMetrics aMetrics)

Draws text along a path.

This method draws the text along a path made up of straight line segments and curves. The curves are quadratic or cubic Bezier splines. A path is made up of one or more separate contours.

Note that each non-null array parameter must be a different array.

The coordinates of the path are pixels, relative to a specified origin. To use absolute path coordinates supply an origin of (0,0).

Parameters:

aText - The text to draw.

aOffset - The start index of the text.

aLength - The number of characters to draw.

aOriginX - The x part of the origin of the path coordinate system.

aOriginY - The y part of the origin of the path coordinate system.

aXPoints - An array of x coordinates for the path.

aYPoints - An array of y coordinates for the path.

aPointTypes - If non-null, an array of point types. If it is null, or if it contains fewer values than the points arrays, missing values are taken to be on-curve points. Each point type must be either Graphics.CURVEDPATH_END_POINT, Graphics.CURVEDPATH_QUADRATIC_BEZIER_CONTROL_POINT, or Graphics.CURVEDPATH_CUBIC_BEZIER_CONTROL_POINT

aContourStarts - If non-null, an array of indexes of contour (sub-path) starts. Each contour contains all the points from aContourStarts[N] to aContourStarts[N + 1] - 1, except for the last contour, which contains all remaining points.

aParam - Text drawing parameters. If null, use default parameters.

aMetrics - If non-null, this parameter receives the metrics of the text drawn.

Returns:

The length of the text drawn along the path, in pixels.

Throws:

IllegalArgumentException - or NullPointerException.

Since:

BlackBerry API 6.0.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.

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.

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.

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.

To apply anti-aliasing to the rounded corners, enable the drawing style Graphics.DRAWSTYLE_AALINES (see @setDrawingStyle)

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.

drawRoundRect

public void drawRoundRect(int x,
                          int y,
                          int width,
                          int height,
                          int roundedCorners,
                          int arcWidth,
                          int arcHeight)

Draws an un-bordered rounded rectangle, from a provided point.

The home corner coordinates you provide locate the top left corner of the rectangle you want to draw.

If you want to use anti-aliasing for drawing, use Graphics.setDrawingStyle(int, boolean) with Graphics.DRAWSTYLE_ANTIALIASED.

You specify the curvature for rounded corners by giving the height and width of an ellipical curve's quadrant (the quadrant of the ellipse chosen is the associated quadrant of the rectangle to draw--thus the top right quadrant of the ellipse gets used as the template for the curve of the top right quadrant of the rectangle to draw). If you want the rectangle's corner to be evenly rounded, you specify an ellipse with equal height and width (i.e. you describe a circle as the curvature template).

Parameters:

x - Distance from left edge of the rectangle's home corner.

y - Distance from top edge of the rectangle's home corner.

width - Horizontal size of the rectangle; must be greater than one.

height - Vertical size of the rectangle; must be greater than one.

roundedCorners - Rounded corners bitmask value indicating which corners to round (mask of the various *_ROUNDED_RECT_CORNER constants).

arcWidth - Width of the ellipse providing the arc segments used to round the corners; must be greater than zero and less than the rectangle's total width.

arcHeight - Height of the ellipse providing the arc segments used to round the corners; must be greater than zero, and less than the rectangle's total height.

Throws:

IllegalArgumentException - Thrown if you provide a width or height less than one, or if the provided arc specifications are malformed (height or width less than zero or greater than the rect's associated dimension).

Since:

BlackBerry API 7.0.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.

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.

Throws:

NullPointerException - If 'data' is null.

ArrayIndexOutOfBoundsException - If the data parameters are invalid.

Since:

BlackBerry API 3.6.0

drawText

public 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.

Parameters:

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 its inked pixels bounds or x advance exceed aWidth. The value -1 causes the actual width of the text to be used, and forces left alignment.

Returns:

The linear advance width in pixels of the text drawn, including characters falling outside the graphic clip region, but not those truncated by aWidth. Note: This can be less than the inked pixels width.

drawText

public 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.

Parameters:

aText - The text to draw.

aX - The horizontal position of the drawing anchor in pixels.

aY - The vertical position of drawing anchor in pixels.

Returns:

The linear advance width in pixels of the text drawn, including characters falling outside the graphic clip region, but not those truncated by aWidth. Note: This can be less than the inked pixels width.

drawText

public 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.

Parameters:

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.

Returns:

The linear advance width in pixels of the text drawn, including characters falling outside the graphic clip region, but not those truncated by aWidth. Note: This can be less than the inked pixels width.

drawText

public 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.

Parameters:

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 its inked pixels bounds or x advance exceed aWidth. The value -1 causes the actual width of the text to be used, and forces left alignment.

Returns:

The linear advance width in pixels of the text drawn, including characters falling outside the graphic clip region, but not those truncated by aWidth. Note: This can be less than the inked pixels width.

drawText

public 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.

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.

Parameters:

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 its inked pixels bounds or x advance exceed aWidth. The value -1 causes the actual width of the text to be used, and forces left alignment.

Returns:

The linear advance width in pixels of the text drawn, including characters falling outside the graphic clip region, but not those truncated by aWidth. Note: This can be less than the inked pixels width.

Throws:

IndexOutOfBoundsException - If the values of aOffset and aLength cause an element outside the array aText to be accessed.

drawText

public 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.

Parameters:

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 its inked pixels bounds or x advance exceed aWidth. The value -1 causes the actual width of the text to be used, and forces left alignment.

Returns:

The linear advance width in pixels of the text drawn, including characters falling outside the graphic clip region, but not those truncated by aWidth. Note: This can be less than the inked pixels width.

Throws:

IndexOutOfBoundsException - If the values of aOffset and aLength cause an element outside the array aText to be accessed.

drawText

public 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.

Parameters:

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 its inked pixels bounds or x advance exceed aWidth. The value -1 causes the actual width of the text to be used, and forces left alignment.

Returns:

The linear advance width in pixels of the text drawn, including characters falling outside the graphic clip region, but not those truncated by aWidth. Note: This can be less than the inked pixels width.

Throws:

IndexOutOfBoundsException - If the values of aOffset and aLength cause an element outside the array aText to be accessed.

drawText

public 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.

Parameters:

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 its inked pixels bounds or x advance exceed aWidth. The value -1 causes the actual width of the text to be used, and forces left alignment.

Returns:

The linear advance width in pixels of the text drawn, including characters falling outside the graphic clip region, but not those truncated by aWidth. Note: This can be less than the inked pixels width.

Throws:

IndexOutOfBoundsException - If the values of aOffset and aLength cause an element outside the array aText to be accessed.

drawText

public int drawText(String aText,
                    int aOffset,
                    int aLength,
                    int aX,
                    int aY,
                    DrawTextParam aParam,
                    TextMetrics aMetrics)

Draws part of the text in a String using the current font and clipping to the current clipping region. Optionally uses parameters supplied in aParam and returns metrics in aMetrics.

Parameters:

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.

aParam - Text drawing parameters. If null, use default parameters.

aMetrics - If non-null, this parameter receives the metrics of the text drawn.

Returns:

The linear advance width in pixels of the text drawn, including characters falling outside the graphic clip region, but not those truncated by aWidth. Note: This can be less than the inked pixels width.

Throws:

IndexOutOfBoundsException - If the values of aOffset and aLength cause an element outside the array aText to be accessed.

Since:

BlackBerry API 6.0.0

drawText

public int drawText(StringBuffer aText,
                    int aOffset,
                    int aLength,
                    int aX,
                    int aY,
                    DrawTextParam aParam,
                    TextMetrics aMetrics)

Draws part of the text in a StringBuffer using the current font and clipping to the current clipping region. Optionally uses parameters supplied in aParam and returns metrics in aMetrics.

Parameters:

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.

aParam - Text drawing parameters. If null, use default parameters.

aMetrics - If non-null, this parameter receives the metrics of the text drawn.

Returns:

The linear advance width in pixels of the text drawn, including characters falling outside the graphic clip region, but not those truncated by aWidth. Note: This can be less than the inked pixels width.

Throws:

IndexOutOfBoundsException - If the values of aOffset and aLength cause an element outside the array aText to be accessed.

Since:

BlackBerry API 6.0.0

drawText

public int drawText(char[] aText,
                    int aOffset,
                    int aLength,
                    int aX,
                    int aY,
                    DrawTextParam aParam,
                    TextMetrics aMetrics)

Draws part of the text in a char array using the current font and clipping to the current clipping region. Optionally uses parameters supplied in aParam and returns metrics in aMetrics.

Parameters:

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.

aParam - Text drawing parameters. If null, use default parameters.

aMetrics - If non-null, this parameter receives the metrics of the text drawn.

Returns:

The linear advance width in pixels of the text drawn, including characters falling outside the graphic clip region, but not those truncated by aWidth. Note: This can be less than the inked pixels width.

Throws:

IndexOutOfBoundsException - If the values of aOffset and aLength cause an element outside the array aText to be accessed.

Since:

BlackBerry API 6.0.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. ATTENTION: This method doesn't support transformations specified in the setTransformation method.

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 - Angle position at which to commence drawing the edge of the arc.

arcAngle - Angular extent of the arc, relative to the start angle.

fillEllipse

public void fillEllipse(int cx,
                        int cy,
                        int px,
                        int py,
                        int qx,
                        int qy,
                        int startAngle,
                        int arcAngle)

Fills an ellipse.

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.

Parameters:

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.

Since:

BlackBerry API 4.2.0

fillRect

public void fillRect(int x,
                     int y,
                     int width,
                     int height)

Fills a rectangle.

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.

Parameters:

x - Left edge of the rectangle.

y - Top edge of the rectangle.

width - Width of the rectangle.

height - Height of the rectangle.

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.

getAbsoluteClippingRect

public void getAbsoluteClippingRect(XYRect clip)

Retreives the absolute coordinates of current clipping region.

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.

Parameters:

clip - Clipping region is returned in this parameter.

getBackgroundColor

public int getBackgroundColor()

Retrieves the current background color.

Returns:

Current color in the form 0x00RRGGBB.

getClippingRect

public XYRect getClippingRect()

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.

Returns:

Current clipping rect.

getContextStackSize

public int getContextStackSize()

Retrieves the size of the stack of drawing contexts.

Returns:

Number of elements on the context stack.

Since:

BlackBerry API 4.1.0

getColor

public int getColor()

Retrieves the current foreground drawing color.

Returns:

Current color in the form 0x00RRGGBB.

getDrawingOffset

public void getDrawingOffset(XYPoint offset)

Retrieves the absolute coordinates for the current drawing offset.

The drawing offset is the point, offset from the top left corner of the screen, which drawing operations use as their origin point.

Parameters:

offset - Drawing offset is returned in this paramater.

getGlobalAlpha

public int getGlobalAlpha()

Retrieves the current global alpha value.

Returns:

Current alpha value in the range 0x00 to 0xff.

Since:

BlackBerry API 3.7.0

getNearestColor

public int getNearestColor(int color)

Gets the color that will be used if the specified color is requested. For example, in RGB565 or grayscale color space, some information will be lost.

Parameters:

color - the desired color (in 0x00RRGGBB format, the high-order byte is ignored)

Returns:

the corresponding color that will be written to this graphics context (in 0x00RRGGBB format)

Since:

BlackBerry API 5.0.0

getNumColors

public static int getNumColors()

Deprecated. Use Display.getNumColors();

Retrieve the number of colors that the display supports.

Returns:

Number of colors the screen can display.

Since:

BlackBerry API 3.7.0

getStipple

public int getStipple()

Retrieves the current line stippling value.

Returns:

Current stipple mask.

getFont

public Font getFont()

Retrieves the current font for the current graphics context.

Returns:

Current font used for text drawing operations.

getScreenHeight

public static int getScreenHeight()

Deprecated. Use Display.getHeight()

Retrieves total drawing height of the screen.

Returns:

Height in pixels of the display's drawable area.

getScreenHorizontalResolution

public static int getScreenHorizontalResolution()

Deprecated. Use Display.getHorizontalResolution()

Retrieve screen's horizontal resolution in pixels per meter (PPM).

Returns:

Horizontal resolution (PPM) of screen.

getScreenVerticalResolution

public static int getScreenVerticalResolution()

Deprecated. Use Display.getVerticalResolution()

Retrieve screen's vertical resolution in pixels per meter (PPM).

Returns:

Vertical resolution (PPM) of screen.

getScreenWidth

public static int getScreenWidth()

Deprecated. Use Display.getWidth()

Retrieves total drawing width of the screen.

Returns:

Width in pixels of the display's drawable area.

invert

public void invert(int x,
                   int y,
                   int width,
                   int height)

Inverts a region.

This method performs a one's complement operation on each pixel in your specified region.

Parameters:

x - Left edge of the region.

y - Top edge of the region.

width - Width of the region.

height - Height of the region.

invert

public void invert(XYRect rect)

Inverts a region specified by an XYRect object.

This method performs a one's complement operation on each pixel in your specified region.

Parameters:

rect - Region to invert.

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.

Parameters:

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.

pushRegion

public boolean pushRegion(XYRect region)

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.

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 Graphics.pushRegion(XYRect), except you can also specify an (optional) additional scroll offset with the xScroll and yScroll parameters.

Parameters:

region - New drawing region in local coordinates.

xScroll - Optional, additional horizontal scroll offset.

yScroll - Optional, additional vertical scroll offset.

pushContext

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 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.

Parameters:

clip - New clipping region in local coordinates.

xOffset - Optional, additional horizontal scroll offset.

yOffset - Optional, additional vertical scroll offset.

pushContext

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 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.

Parameters:

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.

translate

public void translate(int x,
                      int y)

Apply a translation to the current drawing offset.

The drawing offset is updated by adding the x and y offsets.

Parameters:

x - Horizontal offset to add to the current x drawing offset.

y - Vertical offset to add to the current y drawing offset.

Since:

BlackBerry API 3.6.0

getTranslateX

public int getTranslateX()

Retrieves the horizontal component of the current drawing offset.

Returns:

X value of drawing offset.

Since:

BlackBerry API 3.6.0

getTranslateY

public int getTranslateY()

Retrieves the vertical component of the current drawing offset.

Returns:

Y value of drawing offset.

Since:

BlackBerry API 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; otherwise, false.

Since:

BlackBerry API 3.7.0

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:

BlackBerry API 3.7.0

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 color that is nearest to the color you specify).

Parameters:

RGB - Color to use, of the form 0x00RRGGBB.

setGlobalAlpha

public void setGlobalAlpha(int alpha)

Sets the current global alpha value for drawing operations. It ranges from 0 (fully transparent) to 255 (fully opaque).

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.

Parameters:

alpha - Alpha value to use, from 0 (fully transparent) to 255 (fully opaque).

Since:

BlackBerry API 3.7.0

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.

Parameters:

mask - The stipple mask to use for line drawing.

setBackgroundColor

public void setBackgroundColor(int RGB)

Sets the current background color.

Parameters:

RGB - Color to use, of the form 0x00RRGGBB.

setFont

public void setFont(Font font)

Sets the current font for the current graphics context.

Subsequent text rendering uses this font.

Parameters:

font - New font.

Throws:

NullPointerException - If font is null.

isColor

public static boolean isColor()

Deprecated. Use Display.isColor().

Determines if the display supports color.

Returns:

True if the the display supports color; otherwise, false.

Since:

BlackBerry API 3.7.0

drawGradientFilledRect

public void drawGradientFilledRect(XYRect rect,
                                   int startColor,
                                   int endColor)

Draws an un-bordered rectangle with a gradient fill.

This is a convenience method wrapping drawGradientFill(rect,startColor,endColor,false).

Parameters:

rect - Rectangle to draw; must not be null and must have dimensions greater than zero.

startColor - Color to start with.

endColor - Color to end with.

Throws:

IllegalArgumentException - Thrown if the provided rect is malformed (either null, or with a height or width of zero or less).

Since:

BlackBerry API 7.0.0

drawGradientFilledRect

public void drawGradientFilledRect(XYRect rect,
                                   int startColor,
                                   int endColor,
                                   boolean drawBorder)

Draws a rectangle with a gradient fill.

The gradient fill is a linear gradient from the top edge of the rectangle to the bottom edge.

If you want to use dithered shading, use Graphics.setDrawingStyle(int, boolean) with Graphics.DRAWSTYLE_DITHERED_SHADING.

Parameters:

rect - Dimensions and placement of the rectangle to draw; must not be null and must have dimensions greater than zero.

startColor - Color to start with, at the top edge of the rectangle.

endColor - Color to transform into, at the bottom edge of the rectangle.

drawBorder - True to draw a bordered rectangle; false to draw the rect with no border. The border stroke is one pixel wide; the border color is the default foreground color set with Graphics.setColor(int).

Throws:

IllegalArgumentException - Thrown if the provided rect is malformed (either null, or with a height or width of zero or less).

Since:

BlackBerry API 7.0.0

drawGradientFilledRect

public void drawGradientFilledRect(int x,
                                   int y,
                                   int width,
                                   int height,
                                   int startColor,
                                   int endColor)

Draws an un-bordered rectangle with a gradient fill, from a provided point.

This is a convenience method wrapping drawGradientFilledRect(x,y,width,height,startColor,endColor,false).

Parameters:

x - Distance from left edge of the rectangle's home corner.

y - Distance from the top edge of the rectangle's home corner.

width - Horizontal size of the rectangle; must be greater than zero.

height - Vertical size of the rectangle; must be greater than zero.

startColor - Color to start with.

endColor - Color to end with.

Throws:

IllegalArgumentException - Thrown if you provide a width or height of zero or less.

Since:

BlackBerry API 7.0.0

drawGradientFilledRect

public void drawGradientFilledRect(int x,
                                   int y,
                                   int width,
                                   int height,
                                   int startColor,
                                   int endColor,
                                   boolean drawBorder)

Draws a rectangle with a gradient fill, from a provided point.

The home corner coordinates you provide locate the top left corner of the rectangle you want to draw.

The gradient fill is a linear gradient from the top edge of the rectangle to the bottom edge.

If you want to use dithered shading, use Graphics.setDrawingStyle(int, boolean) with Graphics.DRAWSTYLE_DITHERED_SHADING.

Parameters:

x - Distance from left edge of the rectangle's home corner.

y - Distance from top edge of the rectangle's home corner.

width - Horizontal size of the rectangle; must be greater than zero.

height - Vertical size of the rectangle; must be greater than zero.

startColor - Color to start with, at the top edge of the rectangle.

endColor - Color to transform into, at the bottom edge of the rectangle.

drawBorder - True to draw a bordered rectangle; false to draw the rect with no border. The border stroke is one pixel wide; the border color is the default foreground color set with Graphics.setColor(int).

Throws:

IllegalArgumentException - Thrown if you provide a width or height of zero or less.

Since:

BlackBerry API 7.0.0

drawGradientFilledRoundedRect

public void drawGradientFilledRoundedRect(XYRect rect,
                                          int startColor,
                                          int endColor,
                                          int arcWidth,
                                          int arcHeight)

Draws an un-bordered, fully rounded rectangle with a gradient fill.

This is a convenience method wrapping drawGradientFilledRoundedRec(rect,startColor,endColor,false,ALL_ROUNDED_RECT_CORNERS,arcWidth,arcHeight).

Parameters:

rect - Rectangle to draw; must not be null and must have dimensions greater than zero.

startColor - Color to start with.

endColor - Color to end with.

arcWidth - Width of ellipse for rounding; must be between zero and the rect width (inclusive).

arcHeight - Height of ellipse for rounding; must be between zero and the rect height (inclusive).

Throws:

IllegalArgumentException - Thrown if the provided rect is malformed (either null, or with a height or width of zero or less), or if the provided arc specifications are malformed (height or width less than zero, or greater than the rect's associated dimension).

Since:

BlackBerry API 7.0.0

drawGradientFilledRoundedRect

public void drawGradientFilledRoundedRect(XYRect rect,
                                          int startColor,
                                          int endColor,
                                          boolean drawBorder,
                                          int arcWidth,
                                          int arcHeight)

Draws a fully rounded rectangle with a gradient fill.

This is a convenience method wrapping drawGradientFilledRoundedRec(rect,startColor,endColor,drawBorder,ALL_ROUNDED_RECT_CORNERS,arcWidth,arcHeight).

Parameters:

rect - Rectangle to draw; must not be null and must have dimensions greater than zero.

startColor - Color to start with.

endColor - Color to end with.

drawBorder - True to draw a border; false to draw the rect without a border.

arcWidth - Width of ellipse for rounding; must be between zero and the rect width (inclusive).

arcHeight - Height of ellipse for rounding; must be between zero and the rect height (inclusive).

Throws:

IllegalArgumentException - Thrown if the provided rect is malformed (either null, or with a height or width of zero or less), or if the provided arc specifications are malformed (height or width less than zero or greater than the rect's associated dimension).

Since:

BlackBerry API 7.0.0

drawGradientFilledRoundedRect

public void drawGradientFilledRoundedRect(XYRect rect,
                                          int startColor,
                                          int endColor,
                                          int roundedCorners,
                                          int arcWidth,
                                          int arcHeight)

Draws an un-bordered, rounded rectangle with a gradient fill.

This is a convenience method wrapping drawGradientFilledRoundedRec(rect,startColor,endColor,false,roundedCorners,arcWidth,arcHeight).

Parameters:

rect - Rectangle to draw; must not be null and must have dimensions greater than zero.

startColor - Color to start with.

endColor - Color to end with.

roundedCorners - Mask of *_ROUNDED_RECT_CORNER constants to mark corners to round.

arcWidth - Width of ellipse for rounding; must be between zero and the rect width (inclusive).

arcHeight - Height of ellipse for rounding; must be between zero and the rect height (inclusive).

Throws:

IllegalArgumentException - Thrown if the provided rect is malformed (either null, or with a height or width of zero or less), or if the provided arc specifications are malformed (height or width of less than zero or greater than the rect's associated dimension).

Since:

BlackBerry API 7.0.0

drawGradientFilledRoundedRect

public void drawGradientFilledRoundedRect(XYRect rect,
                                          int startColor,
                                          int endColor,
                                          boolean drawBorder,
                                          int roundedCorners,
                                          int arcWidth,
                                          int arcHeight)

Draws a rounded rectangle with a gradient fill.

The gradient fill is a linear gradient from the top edge of the rectangle to the bottom edge. If you want to use dithered shading, use Graphics.setDrawingStyle(int, boolean) with Graphics.DRAWSTYLE_DITHERED_SHADING.

You specify the curvature for rounded corners by giving the height and width of an elliptical curve's quadrant (the quadrant of the ellipse chosen is the associated quadrant of the rectangle to draw--thus the top right quadrant of the ellipse gets used as the template for the curve of the top right quadrant of the rectangle to draw). If you want the rectangle's corner to be evenly rounded, you specify an ellipse with equal height and width (i.e. you describe a circle as the curvature template).

Parameters:

rect - Dimensions and placement of the rectangle to draw; must not be null and must have dimensions greater than zero.

startColor - Color to start with, at the top edge of the rectangle.

endColor - Color to transform into, at the bottom edge of the rectangle.

drawBorder - True to draw a bordered rectangle; false to draw the rect with no border. The border stroke is one pixel wide; the border color is the default foreground color set with Graphics.setColor(int).

roundedCorners - Rounded corners bitmask value indicating which corners to round (mask of the various *_ROUNDED_RECT_CORNER constants).

arcWidth - Width of the ellipse providing the arc segments used to round the corners; must be between zero and the rectangle's total width (inclusive).

arcHeight - Height of the ellipse providing the arc segments used to round the corners; must be between zero and the rectangle's total height (inclusive).

Throws:

IllegalArgumentException - Thrown if the provided rect is malformed (either null, or with a height or width of zero or less), or if the provided arc specifications are malformed (height or width less than zero, or greater than the rect's associated dimension).

Since:

BlackBerry API 7.0.0

drawGradientFilledRoundedRect

public void drawGradientFilledRoundedRect(int x,
                                          int y,
                                          int width,
                                          int height,
                                          int startColor,
                                          int endColor,
                                          int arcWidth,
                                          int arcHeight)

Draws an un-bordered, fully rounded rectangle with a gradient fill, from a provided point.

This is a convenience method wrapping drawGradientFilledRoundedRec(x,y,width,height,startColor,endColor,false,ALL_ROUNDED_RECT_CORNERS,arcWidth,arcHeight).

Parameters:

x - Distance from left edge of the rectangle's home corner.

y - Distance from top edge of the rectangle's home corner.

width - Horizontal size of the rectangle; must be greater than zero.

height - Vertical size of the rectangle; must be greater than zero.

startColor - Color to start with.

endColor - Color to end with.

arcWidth - Width of ellipse for rounding; must be between zero and the rect width (inclusive).

arcHeight - Height of ellipse for rounding; must be between zero and the rect height (inclusive).

Throws:

IllegalArgumentException - Thrown if you provide a width or height of zero or less, or if the provided arc specifications are malformed (height or width less than zero, or greater than the rect's associated dimension).

Since:

BlackBerry API 7.0.0

drawGradientFilledRoundedRect

public void drawGradientFilledRoundedRect(int x,
                                          int y,
                                          int width,
                                          int height,
                                          int startColor,
                                          int endColor,
                                          boolean drawBorder,
                                          int arcWidth,
                                          int arcHeight)

Draws a fully rounded rectangle with a gradient fill, from a provided point.

This is a convenience method wrapping drawGradientFilledRoundedRec(x,y,width,height,startColor,endColor,drawBorder,ALL_ROUNDED_RECT_CORNERS,arcWidth,arcHeight).

Parameters:

x - Distance from left edge of the rectangle's home corner.

y - Distance from top edge of the rectangle's home corner.

width - Horizontal size of the rectangle; must be greater than zero.

height - Vertical size of the rectangle; must be greater than zero.

startColor - Color to start with.

endColor - Color to end with.

drawBorder - True to draw a border; false to draw the rect without a border.

arcWidth - Width of ellipse for rounding; must be between zero and the rect width (inclusive).

arcHeight - Height of ellipse for rounding; must be between zero and the rect height (inclusive).

Throws:

IllegalArgumentException - Thrown if you provide a width or height of zero or less, or if the provided arc specifications are malformed (height or width less than zero, or greater than the rect's associated dimension).

Since:

BlackBerry API 7.0.0

drawGradientFilledRoundedRect

public void drawGradientFilledRoundedRect(int x,
                                          int y,
                                          int width,
                                          int height,
                                          int startColor,
                                          int endColor,
                                          int roundedCorners,
                                          int arcWidth,
                                          int arcHeight)

Draws an un-bordered rectangle with a gradient fill, from a provided point.

This is a convenience method wrapping drawGradientFilledRoundedRec(x,y,width,height,startColor,endColor,false,roundedCorners,arcWidth,arcHeight).

Parameters:

x - Distance from left edge of the rectangle's home corner.

y - Distance from top edge of the rectangle's home corner.

width - Horizontal size of the rectangle; must be greater than zero.

height - Vertical size of the rectangle; must be greater than zero.

startColor - Color to start with.

endColor - Color to end with.

roundedCorners - Mask of *_ROUNDED_RECT_CORNER constants to mark corners to round.

arcWidth - Width of ellipse for rounding; must be between zero and the rect width (inclusive).

arcHeight - Height of ellipse for rounding; must be between zero and the rect height (inclusive).

Throws:

IllegalArgumentException - Thrown if you provide a width or height of zero or less, or if the provided arc specifications are malformed (height or width less than zero, or greater than the rect's associated dimension).

Since:

BlackBerry API 7.0.0

drawGradientFilledRoundedRect

public void drawGradientFilledRoundedRect(int x,
                                          int y,
                                          int width,
                                          int height,
                                          int startColor,
                                          int endColor,
                                          boolean drawBorder,
                                          int roundedCorners,
                                          int arcWidth,
                                          int arcHeight)

Draws a rounded rectangle with a gradient fill, from a provided point.

The home corner coordinates you provide locate the top left corner of the rectnagle you want to draw.

The gradient fill is a linear gradient from the top edge of the rectangle to the bottom edge. If you want to use dithered shading, use Graphics.setDrawingStyle(int, boolean) with Graphics.DRAWSTYLE_DITHERED_SHADING.

You specify the curvature for rounded corners by giving the height and width of an elliptical curve's quadrant (the quadrant of the ellipse chosen is the associated quadrant of the rectangle to draw--thus the top right quadrant of the ellipse gets used as the template for the curve of the top right quadrant of the rectangle to draw). If you want the rectangle's corner to be evenly rounded, you specify an ellipse with equal height and width (i.e. you describe a circle as the curvature template).

Parameters:

x - Distance from left edge of the rectangle's home corner.

y - Distance from top edge of the rectangle's home corner.

width - Horizontal size of the rectangle; must be greater than zero.

height - Vertical size of the rectangle; must be greater than zero.

startColor - Color to start with, at the top edge of the rectangle.

endColor - Color to transform into, at the bottom edge of the rectangle.

drawBorder - True to draw a bordered rectangle; false to draw the rect with no border. The border stroke is one pixel wide; the border color is the default foreground color set with Graphics.setColor(int).

roundedCorners - Rounded corners bitmask value indicating which corners to round (mask of the various *_ROUNDED_RECT_CORNER constants).

arcWidth - Width of the ellipse providing the arc segments used to round the corners; must be between zero and the rectangle's total width (inclusive).

arcHeight - Height of the ellipse providing the arc segments used to round the corners; must be between zero and the rectangle's total height (inclusive).

Throws:

IllegalArgumentException - Thrown if you provide a width or height of zero or less, or if the provided arc specifications are malformed (height or width less than zero, or greater than the rect's associated dimension).

Since:

BlackBerry API 7.0.0