com.nokia.mid.ui
Interface DirectGraphics

public interface DirectGraphics

DirectGraphics contains some graphics extensions to MIDP Graphics: drawing triangles, drawing manipulated images (rotated, flipped) and drawing raw pixel array directly to graphics context. DirectUtils class can be used to convert standard Graphics to proprietary DirectGraphics object:

 DirectGraphics dg = DirectUtils.getDirectGraphics(g);
 

The operations to DirectGraphics reference will affect also original graphics context, for example, setting color of DirectGraphics will change current painting color of Graphics and vice versa. In fact developer can see DirectGraphics as a new way to do call to Graphics. DirectGraphics doesn't inherit standard Graphics because of API dependency reasons. ARGB values used with some methods of this interface are interpreted with the least significant eight bits giving the blue component, the next eight more significant bits giving the green component, the next eight more significant bits giving the red component and the next eight more significant bits giving the alpha component. That is to say, the color component is specified in the form of 0xAARRGGBB. This correspons to native format specified by { @link DirectGraphics#TYPE_ARGB_8888 }. Manipulation parameters to drawPixels are formed by bitwise ORring FLIP_HORIZONTAL or FLIP_VERTICAL with a degree value: ROTATE_90, ROTATE_180 or ROTATE_270. Currently only these constant defined degree values are supported when rotating images.

Copyright (c) 2001 Nokia Mobile Phones

Since:

1.0

Field Summary

static int	FLIP_HORIZONTAL Constant for horizontal image flipping.
static int	FLIP_VERTICAL Constant for vertical image flipping.
static int	FORM_CHOICE_HIGHLIGHT_BORDER_TYPE Constant for drawing the Form's Choice element highlight border type.
static int	FORM_ITEM_BORDER_TYPE Constant for drawing the Form's item border type.
static int	FORM_TEXT_FIELD_BORDER_TYPE Constant for drawing the Form's TextField border type.
static int	ROTATE_180 Constant for rotating image 180 degrees counter-clockwise.
static int	ROTATE_270 Constant for rotating image 270 degrees counter-clockwise.
static int	ROTATE_90 Constant for rotating image 90 degrees counter-clockwise.
static int	TYPE_BYTE_1_GRAY 1 bit format, 2 distinct color values (on/off), stored as a byte.
static int	TYPE_BYTE_1_GRAY_VERTICAL 1 bit format, 2 distinct color values (on/off), stored as a byte.
static int	TYPE_BYTE_2_GRAY 2 bit format, 4 gray scale colors.
static int	TYPE_BYTE_332_RGB 3 bits for red, 3 bits for green, and 2 bits for blue component in a pixel, stored as a byte.
static int	TYPE_BYTE_4_GRAY 4 bit format, 16 gray scale colors.
static int	TYPE_BYTE_8_GRAY 8 bit format, 256 gray scale colors.
static int	TYPE_INT_888_RGB 8 bits for red, green and blue component in a pixel (0x00RRGGBB).
static int	TYPE_INT_8888_ARGB 8 bits for alpha, red, green and blue component in a pixel (0xAARRGGBB).
static int	TYPE_USHORT_1555_ARGB 1 bit for alpha, 5 bits for red, green and blue component in a pixel.
static int	TYPE_USHORT_444_RGB 4 bits for red, green and blue component in a pixel, stored as a short (0x0RGB).
static int	TYPE_USHORT_4444_ARGB 4 bits for alpha, red, green and blue component in a pixel, stored as a short (0xARGB).
static int	TYPE_USHORT_555_RGB 5 bits for red, green and blue component in a pixel.
static int	TYPE_USHORT_565_RGB 5 bits for red, 6 bits for green and 5 bits for blue component in a pixel.

Method Summary

void	drawElementBorder(int x, int y, int w, int h, int borderType, boolean withFocus) Draws the specified border type at the specified coordinates.
void	drawImage(javax.microedition.lcdui.Image img, int x, int y, int anchor, int manipulation) Draws image to the graphics context.
void	drawPixels(byte[] pixels, byte[] transparencyMask, int offset, int scanlength, int x, int y, int width, int height, int manipulation, int format) Copies or draws the pixel data directly to graphics context to specific location.
void	drawPixels(int[] pixels, boolean transparency, int offset, int scanlength, int x, int y, int width, int height, int manipulation, int format) Copies or draws the pixel data directly to graphics context to specific location from the array starting from specified offset.
void	drawPixels(short[] pixels, boolean transparency, int offset, int scanlength, int x, int y, int width, int height, int manipulation, int format) Copies or draws the pixel data directly to graphics context to specific location.
void	drawPolygon(int[] xPoints, int xOffset, int[] yPoints, int yOffset, int nPoints, int argbColor) Draws a closed polygon defined by arrays of x and y coordinates.
void	drawTriangle(int x1, int y1, int x2, int y2, int x3, int y3, int argbColor) Draws closed triangle defined by coordinates.
void	fillPolygon(int[] xPoints, int xOffset, int[] yPoints, int yOffset, int nPoints, int argbColor) Fills a closed polygon defined by arrays of x and y coordinates.
void	fillTriangle(int x1, int y1, int x2, int y2, int x3, int y3, int argbColor) Fills closed triangle defined by coordinates.
int	getAlphaComponent() Gets the alpha component of the current color.
int	getNativePixelFormat() Returns the native color format used, for example, DirectGraphics#TYPE_BYTE_GRAY_1 or DirectGraphics#TYPE_USHORT_ARGB_4444.
void	getPixels(byte[] pixels, byte[] transparencyMask, int offset, int scanlength, int x, int y, int width, int height, int format) Gets the pixel (including any transparency mask) values of an image to an array of byte values from specific screen location.
void	getPixels(int[] pixels, int offset, int scanlength, int x, int y, int width, int height, int format) Gets the pixel values of an image to an array of ARGB values.
void	getPixels(short[] pixels, int offset, int scanlength, int x, int y, int width, int height, int format) Gets the pixel values of an image to an array of short values from specific screen location.
void	setARGBColor(int argbColor) Sets the current color to the specified ARGB value.

Field Detail

FLIP_HORIZONTAL

static final int FLIP_HORIZONTAL

Constant for horizontal image flipping.

Since:

1.0

See Also:

drawImage(Image img, int x, int y, int anchor, int manipulation), Constant Field Values

FLIP_VERTICAL

static final int FLIP_VERTICAL

Constant for vertical image flipping.

Since:

1.0

See Also:

drawImage(Image img, int x, int y, int anchor, int manipulation), Constant Field Values

ROTATE_90

static final int ROTATE_90

Constant for rotating image 90 degrees counter-clockwise. ROTATE_90 can be multiplied using "(ROTATE_90 + ROTATE_90)". If rotate constant is combined with flip use brackets: "(ROTATE_90 * 2) | FLIP_VERTICAL". (ROTATE_90 * 2) results 180 degree rotate.
(ROTATE_90 * 3) results 270 degree rotate.

Since:

1.0

See Also:

drawImage(Image img, int x, int y, int anchor, int manipulation), Constant Field Values

ROTATE_180

static final int ROTATE_180

Constant for rotating image 180 degrees counter-clockwise. ROTATE_180 = (2 * ROTATE_90).

Since:

1.0

See Also:

drawImage(Image img, int x, int y, int anchor, int manipulation), Constant Field Values

ROTATE_270

static final int ROTATE_270

Constant for rotating image 270 degrees counter-clockwise. ROTATE_180 = (3 * ROTATE_90).

Since:

1.0

See Also:

drawImage(Image img, int x, int y, int anchor, int manipulation), Constant Field Values

TYPE_BYTE_1_GRAY_VERTICAL

static final int TYPE_BYTE_1_GRAY_VERTICAL

1 bit format, 2 distinct color values (on/off), stored as a byte. 8 pixel values in a single byte. The pixel data is presented vertically from left to right.

  BYTE   0 1 2 3 4 5 6 7

  LSB    + +         + +
         + + +       + +
         + + + +     + +
         + + + + +   + +
         + +   + + + + +
         + +     + + + +
         + +       + + +
  MSB    + +         + +

         byte [] byteArray = new byte[8]
         byteArray[0] = 0xFF // binary 11111111
         byteArray[1] = 0xFF // binary 11111111
         byteArray[2] = 0x0E // binary 00001110
         byteArray[3] = 0x1C // binary 00011100
         byteArray[4] = 0x38 // binary 00111000
         byteArray[5] = 0x70 // binary 01110000
         byteArray[5] = 0xFF // binary 11111111
         byteArray[7] = 0xFF // binary 11111111
 

Since:

1.0

See Also:

Constant Field Values

TYPE_BYTE_1_GRAY

static final int TYPE_BYTE_1_GRAY

1 bit format, 2 distinct color values (on/off), stored as a byte. 8 pixel values in a single byte. The pixel data is presented horizontally from left to right.

Since:

1.0

See Also:

Constant Field Values

TYPE_BYTE_2_GRAY

static final int TYPE_BYTE_2_GRAY

2 bit format, 4 gray scale colors. Stored as a byte, 4 pixel values in a single byte. The pixel data is presented horizontally from left to right.

Since:

1.0

See Also:

Constant Field Values

TYPE_BYTE_4_GRAY

static final int TYPE_BYTE_4_GRAY

4 bit format, 16 gray scale colors. Stored as a byte, 2 pixel values in a single byte. The pixel data is presented horizontally from left to right.

Since:

1.0

See Also:

Constant Field Values

TYPE_BYTE_8_GRAY

static final int TYPE_BYTE_8_GRAY

8 bit format, 256 gray scale colors. Stored as a byte, 1 pixel value in a single byte. The pixel data is presented horizontally from left to right.

Since:

1.0

See Also:

Constant Field Values

TYPE_BYTE_332_RGB

static final int TYPE_BYTE_332_RGB

3 bits for red, 3 bits for green, and 2 bits for blue component in a pixel, stored as a byte. The pixel data is presented horizontally from left to right.

Since:

1.0

See Also:

Constant Field Values

TYPE_USHORT_4444_ARGB

static final int TYPE_USHORT_4444_ARGB

4 bits for alpha, red, green and blue component in a pixel, stored as a short (0xARGB).

Since:

1.0

See Also:

Constant Field Values

TYPE_USHORT_444_RGB

static final int TYPE_USHORT_444_RGB

4 bits for red, green and blue component in a pixel, stored as a short (0x0RGB).

Since:

1.0

See Also:

Constant Field Values

TYPE_USHORT_555_RGB

static final int TYPE_USHORT_555_RGB

5 bits for red, green and blue component in a pixel.

Since:

1.0

See Also:

Constant Field Values

TYPE_USHORT_1555_ARGB

static final int TYPE_USHORT_1555_ARGB

1 bit for alpha, 5 bits for red, green and blue component in a pixel.

Since:

1.0

See Also:

Constant Field Values

TYPE_USHORT_565_RGB

static final int TYPE_USHORT_565_RGB

5 bits for red, 6 bits for green and 5 bits for blue component in a pixel.

Since:

1.0

See Also:

Constant Field Values

TYPE_INT_888_RGB

static final int TYPE_INT_888_RGB

8 bits for red, green and blue component in a pixel (0x00RRGGBB). The high order byte (alpha) is ignored by the implementation.

Since:

1.0

See Also:

Constant Field Values

TYPE_INT_8888_ARGB

static final int TYPE_INT_8888_ARGB

8 bits for alpha, red, green and blue component in a pixel (0xAARRGGBB).

Since:

1.0

See Also:

Constant Field Values

FORM_ITEM_BORDER_TYPE

static final int FORM_ITEM_BORDER_TYPE

Constant for drawing the Form's item border type.

See Also:

Constant Field Values

FORM_TEXT_FIELD_BORDER_TYPE

static final int FORM_TEXT_FIELD_BORDER_TYPE

Constant for drawing the Form's TextField border type.

See Also:

Constant Field Values

FORM_CHOICE_HIGHLIGHT_BORDER_TYPE

static final int FORM_CHOICE_HIGHLIGHT_BORDER_TYPE

Constant for drawing the Form's Choice element highlight border type.

See Also:

Constant Field Values

Method Detail

getAlphaComponent

int getAlphaComponent()

Gets the alpha component of the current color.

Returns:

integer value in range 0-255

Since:

1.0

setARGBColor

void setARGBColor(int argbColor)

Sets the current color to the specified ARGB value. All subsequent rendering operations will use this specified color.

Parameters:

argbColor - the color being set

Since:

1.0

drawImage

void drawImage(javax.microedition.lcdui.Image img,
               int x,
               int y,
               int anchor,
               int manipulation)

Draws image to the graphics context. Does common image manipulations during drawing of an image. Manipulation can be 0 if no manipulation is done. Draws the specified image by using the anchor point - the anchor point is applied after the manipulation. The image can be drawn in different positions relative to the anchor point by passing the appropriate position constants.

Parameters:

img - the specified image to be drawn

x - the x coordinate of the anchor point

y - the y coordinate of the anchor point

anchor - the anchor point for positioning the image

manipulation - flip or rotate value or a combination of values, 0 if none

Throws:

java.lang.IllegalArgumentException - if anchor is not a legal value or manipulation is not supported

java.lang.NullPointerException - if img is null

Since:

1.0

See Also:

Image, FLIP_VERTICAL, FLIP_HORIZONTAL, ROTATE_90

drawTriangle

void drawTriangle(int x1,
                  int y1,
                  int x2,
                  int y2,
                  int x3,
                  int y3,
                  int argbColor)

Draws closed triangle defined by coordinates. Note that the method uses the color passed as a parameter for drawing the triangle and not the current active color of graphics context. This is due to efficiency reasons as it is expected that the method may be called several times in each repaint cycle, thus separate calls to setColor would create unnecessary overhead. The call won't change the current active drawing color of graphics context.

Parameters:

x1 - the x coordinate of first vertex

y1 - the y coordinate of first vertex

x2 - the x coordinate of second vertex

y2 - the y coordinate of second vertex

x3 - the x coordinate of third vertex

y3 - the y coordinate of third vertex

argbColor - the ARGB color value used painting the triangle

Since:

1.0

fillTriangle

void fillTriangle(int x1,
                  int y1,
                  int x2,
                  int y2,
                  int x3,
                  int y3,
                  int argbColor)

Fills closed triangle defined by coordinates. Note that the method uses the color passed as a parameter for drawing the triangle and not the current active color of graphics context. This is due to efficiency reasons as it is expected that the method may be called several times in each repaint cycle, thus separate calls to setColor would create unnecessary overhead. The call won't change the current active drawing color of graphics context.

Parameters:

x1 - the x coordinate of first vertex

y1 - the y coordinate of first vertex

x2 - the x coordinate of second vertex

y2 - the y coordinate of second vertex

x3 - the x coordinate of third vertex

y3 - the y coordinate of third vertex

argbColor - the ARGB color value used painting the triangle

Since:

1.0

drawPolygon

void drawPolygon(int[] xPoints,
                 int xOffset,
                 int[] yPoints,
                 int yOffset,
                 int nPoints,
                 int argbColor)

Draws a closed polygon defined by arrays of x and y coordinates. Each pair of (x, y) coordinates defines a point. This method draws the polygon defined by nPoint line segments, where the first nPoint - 1 line segments are line segments from (xPoints[xOffset + i - 1], yPoints[yOffset + i - 1]) to (xPoints[xOffset + i], yPoints[yOffset + i]), for 1 <= i <= nPoints. The figure is automatically closed by drawing a line connecting the final point to the first point, if those points are different.

Parameters:

xPoints - an array of x coordinates

xOffset - an offset to first x point in xPoints

yPoints - an array of y coordinates

yOffset - an offset to first y point in yPoints

nPoints - the total number of points

argbColor - the ARGB color value used painting the polygon

Since:

1.0

fillPolygon

void fillPolygon(int[] xPoints,
                 int xOffset,
                 int[] yPoints,
                 int yOffset,
                 int nPoints,
                 int argbColor)

Fills a closed polygon defined by arrays of x and y coordinates. This method draws the polygon defined by nPoint line segments, where the first nPoint - 1 line segments are line segments from (xPoints[xOffset + i - 1], yPoints[yOffset + i - 1]) to (xPoints[xOffset + i], yPoints[yOffset + i]), for 1 <= i <= nPoints. The figure is automatically closed by drawing a line connecting the final point to the first point, if those points are different. The area inside the polygon is defined using an even-odd fill rule, also known as the alternating rule.

Parameters:

xPoints - an array of x coordinates

xOffset - an offset to first x point in xPoints

yPoints - an array of y coordinates

yOffset - an offset to first y point in yPoints

nPoints - the total number of points

argbColor - the ARGB color value used painting the polygon

Since:

1.0

drawPixels

void drawPixels(int[] pixels,
                boolean transparency,
                int offset,
                int scanlength,
                int x,
                int y,
                int width,
                int height,
                int manipulation,
                int format)

Copies or draws the pixel data directly to graphics context to specific location from the array starting from specified offset. Integers in array object are passed as ARGB values. Implementation does any necessary color conversions if the color model of the graphics context does not match the TYPE_INT_ARGB_8888. The boolean value transparency will indicate whether the pixel's transparency value will be checked. If the transparency argument is false the pixels are set to the graphics context without comparing the transparency values. If transparency argument is true pixel's transparency value is checked and it will affect the drawing of a pixel.

Parameters:

pixels - an array of pixel values (0xAARRGGBB)

transparency - true if the pixel's transparency value will be checked

offset - the index of the first pixel value

scanlength - the relative array offset between the corresponding pixels in consecutive rows

x - the horizontal rendering location on graphics context

y - the vertical rendering location on graphics context

width - the width of the region to the rendered

height - the height of the region to the rendered

manipulation - the manipulation done to the image before the draw, 0 means none.

format - the display format used

Throws:

java.lang.NullPointerException - if pixels is null

java.lang.ArrayIndexOutOfBoundsException - if requested to access

java.lang.IllegalArgumentException - if foramt is not supported pixels beyond the length of array or with negative index

Since:

1.0

getPixels

void getPixels(int[] pixels,
               int offset,
               int scanlength,
               int x,
               int y,
               int width,
               int height,
               int format)

Gets the pixel values of an image to an array of ARGB values. Getting the pixels will result a conversion if the color model of graphics context doesn't match the TYPE_INT_ARGB_8888. Throws ArrayIndexOutOfBoundsException if array size is too small for image pixels.

Parameters:

pixels - an array in which the image pixel information will be stored

offset - the index into the array where the first pixel value will be stored

scanlength - the relative offset in the array between corresponding pixels in consecutive rows

x - the x-coordinate of the upper left corner of the region

y - the y-coordinate of the upper left corner of the region

width - the width of the region

height - the height of the region

format - the display format used

Throws:

java.lang.NullPointerException - if pixels is null

java.lang.ArrayIndexOutOfBoundsException - if array size is too small

java.lang.IllegalArgumentException - if foramt is not supported for the image pixels or negative index access is attempted, contents of the array remain unchanged

Since:

1.0

getPixels

void getPixels(byte[] pixels,
               byte[] transparencyMask,
               int offset,
               int scanlength,
               int x,
               int y,
               int width,
               int height,
               int format)

Gets the pixel (including any transparency mask) values of an image to an array of byte values from specific screen location. Throws ArrayIndexOutOfBoundsException if array size is too small for image pixels or transparency mask. The argument transparencyMask can be null if caller is not interested in getting the mask. This method is used getting pixel data from the graphics context in native formats. Pixels are returned in format defined by getNativePixelFormat() method. If the native format is not byte based then this method converts the pixel data to TYPE_BYTE_GRAY_1 format and returns that.

Parameters:

pixels - an array in which the image pixel information will be stored

transparencyMask - an array in which the transparency mask will be stored

offset - the index into the array where the first pixel and mask value will be stored

scanlength - the relative offset in the array between corresponding pixels and mask value in consecutive rows

x - the x-coordinate of the upper left corner of the region

y - the y-coordinate of the upper left corner of the region

width - the width of the region

height - the height of the region

format - the display format used

Throws:

java.lang.NullPointerException - if pixels is null

java.lang.ArrayIndexOutOfBoundsException - if array size is too small

java.lang.IllegalArgumentException - if foramt is not supported for the image pixels or negative index access is attempted, contents of the array remain unchanged

Since:

1.0

getPixels

void getPixels(short[] pixels,
               int offset,
               int scanlength,
               int x,
               int y,
               int width,
               int height,
               int format)

Gets the pixel values of an image to an array of short values from specific screen location. Throws ArrayIndexOutOfBoundsException if array size is too small for image pixels. This method is used getting pixel data from the graphics context in native formats. Pixels are returned in format defined by getNativePixelFormat() method. If the native format is not short based then this method converts the pixel data to TYPE_USHORT_ARGB_4444 format and returns that.

Parameters:

pixels - an array in which the image pixel information will be stored

offset - the index into the array where the first pixel value will be stored

scanlength - the relative offset in the array between corresponding pixels in consecutive rows

x - the x-coordinate of the upper left corner of the region

y - the y-coordinate of the upper left corner of the region

width - the width of the region

height - the height of the region

format - the display format used

Throws:

java.lang.NullPointerException - if pixels is null

java.lang.ArrayIndexOutOfBoundsException - if array size is too small

java.lang.IllegalArgumentException - if foramt is not supported for the image pixels or negative index access is attempted, contents of the array remain unchanged

Since:

1.0

drawPixels

void drawPixels(byte[] pixels,
                byte[] transparencyMask,
                int offset,
                int scanlength,
                int x,
                int y,
                int width,
                int height,
                int manipulation,
                int format)

Copies or draws the pixel data directly to graphics context to specific location. Bytes in pixels and transparencyMask arrays will be passed in native format defined by getNativePixelFormat() method. If native format is not byte based then the implementation expects TYPE_BYTE_GRAY_1 format and does necessary conversions to actual native format. The transparencyMask can be null.

Parameters:

pixels - an array of pixel values

transparencyMask - an array defining transparency mask

offset - the index of the first pixel and mask value

scanlength - the relative array offset between the corresponding pixels and mask value in consecutive rows

x - the horizontal rendering location on graphics context

y - the vertical rendering location on graphics context

width - the width of the region to the rendered

height - the height of the region to the rendered

manipulation - the manipulation done to the image before the draw, 0 means none.

format - the display format used

Throws:

java.lang.NullPointerException - if pixels is null

java.lang.ArrayIndexOutOfBoundsException - if requested to access

java.lang.IllegalArgumentException - if foramt is not supported beyond the length of array or with negative index

Since:

1.0

drawPixels

void drawPixels(short[] pixels,
                boolean transparency,
                int offset,
                int scanlength,
                int x,
                int y,
                int width,
                int height,
                int manipulation,
                int format)

Copies or draws the pixel data directly to graphics context to specific location. Shorts in array object are passed in native format defined by getNativePixelFormat() method. If native format is not short based then the implementation expects TYPE_USHORT_ARGB_4444 format and does necessary conversions to actual native format. The boolean value transparency will indicate whether the pixel's transparency value will be checked if any. If the transparency argument is false the pixels are set to the graphics context without comparing the transparency values. If transparency argument is true pixel's transparency value is checked and it will affect the drawing of a pixel.

Parameters:

pixels - an array of pixel values

transparency - true if the pixel's transparency value will be checked

offset - the index of the first pixel value

scanlength - the relative array offset between the corresponding pixels in consecutive rows

x - the horizontal rendering location on graphics context

y - the vertical rendering location on graphics context

width - the width of the region to the rendered

height - the height of the region to the rendered

manipulation - the manipulation done to the image before the draw, 0 means none.

format - the display format used

Throws:

java.lang.NullPointerException - if pixels is null

java.lang.ArrayIndexOutOfBoundsException - if requested to access

java.lang.IllegalArgumentException - if foramt is not supported beyond the length of array or with negative index

Since:

1.0

getNativePixelFormat

int getNativePixelFormat()

Returns the native color format used, for example, DirectGraphics#TYPE_BYTE_GRAY_1 or DirectGraphics#TYPE_USHORT_ARGB_4444. Application can check the expected by drawPixels and returned from getPixels methods of this interface.

Returns:

the native format used in drawPixels and getPixels array methods.

Since:

1.0

drawElementBorder

void drawElementBorder(int x,
                       int y,
                       int w,
                       int h,
                       int borderType,
                       boolean withFocus)

Draws the specified border type at the specified coordinates. It will draw a border area in the colour and style determined by the specified border type corroborated with the current theme. For some UI style, this API may be a blank implementation.

Parameters:

x - the x coordinate of the border to be drawn

y - the y coordinate of the border to be drawn

w - the width of the border to be drawn

h - the height of the border to be drawn

borderType - the border type to draw.

Throws:

java.lang.IllegalArgumentException - if the specified border type is invalid.

Since:

1.0