net.rim.device.api.system
Class Bitmap

java.lang.Object
  |
  +--net.rim.device.api.system.Bitmap

public final class Bitmap

extends Object

Encapsulates a Bitmap graphic usable for display on the device.

When constructing a bitmap object, you have the option to specify the type of encoding used.

Inner Class Summary

static class

Bitmap.PNGInfo Provides additional information relevant for PNG bitmap graphics.

Field Summary

static int	COLUMNWISE_MONOCHROME Columnwise, monochrome bitmap type.
static int	EXCLAMATION Predefined bitmap used for alert dialogs.
static int	HOURGLASS Predefined bitmap used for busy cursors.
static int	INFORMATION Predefined bitmap used for information dialogs.
static int	QUESTION Predefined bitmap used for query dialogs.
static int	TRUE_BLACK
static int	TRUE_WHITE

Constructor Summary

Bitmap(int width, int height)
Constructs a blank bitmap object.

Bitmap(int type, int width, int height)
Constructs a blank bitmap object of a specific type.

Bitmap(int type, int width, int height, byte[] data)
Constructs a new bitmap of a specific type from existing data.

Method Summary

static Bitmap	createBitmapFromBytes(byte[] bytes, int offset, int length, int scale) Creates a bitmap from image data.
static Bitmap	createBitmapFromPNG(byte[] png, int offset, int length) Creates a bitmap from provided PNG format data.
boolean	equals(Object obj) Tests if provided bitmap is equal to this bitmap.
static Bitmap	getBitmapResource(String name) Creates a bitmap from provided name resource.
static Bitmap	getBitmapResource(String module, String name) Creates a bitmap from provided named resource found in module.
static int	getDefaultType() Query the default Bitmap type for the device.
int	getHeight() Retrieves this bitmap's height.
static Bitmap	getPredefinedBitmap(int predefinedBitmap) Retrieves one of the predefined system bitmaps.
int	getType() Retrieves this bitmap's type.
int	getWidth() Retrieves this bitmap's width.
boolean	hasAlpha() Tests whether there is an alpha map associated with this Bitmap.
boolean	isWritable() Indicates whether the Bitmap object is read-only.

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INFORMATION

public static final int INFORMATION

Predefined bitmap used for information dialogs.

QUESTION

public static final int QUESTION

Predefined bitmap used for query dialogs.

EXCLAMATION

public static final int EXCLAMATION

Predefined bitmap used for alert dialogs.

HOURGLASS

public static final int HOURGLASS

Predefined bitmap used for busy cursors.

COLUMNWISE_MONOCHROME

public static final int COLUMNWISE_MONOCHROME

Columnwise, monochrome bitmap type.

This bitmap type indicates data is stored in pixel wide columns in successive bytes. Each bit in a byte is a pixel value, 0 is off and 1 is on. Uppermost pixels are in the less significant bits within a byte, and lower numbered bytes contain the uppermost pixels within a column.

TRUE_WHITE

public static final int TRUE_WHITE

TRUE_BLACK

public static final int TRUE_BLACK

Constructor Detail

Bitmap

public Bitmap(int width,
              int height)

Constructs a blank bitmap object.

Parameters:

width - Width of this bitmap.

height - Height of this bitmap.

Throws:

IllegalArgumentException - Thrown if width or height parameters are invalid.

Bitmap

public Bitmap(int type,
              int width,
              int height)

Constructs a blank bitmap object of a specific type.

Parameters:

width - Width of this bitmap.

height - Height of this bitmap.

type - Type of this bitmap.

Throws:

IllegalArgumentException - Thrown if the width, height, or the type is invalid.

Bitmap

public Bitmap(int type,
              int width,
              int height,
              byte[] data)

Constructs a new bitmap of a specific type from existing data.

Note that this method makes a copy of your provided bitmap data.

Parameters:

type - Type of this bitmap.

width - Width of this bitmap.

height - Height of this bitmap.

data - Data from which to build this bitmap.

Throws:

IllegalArgumentException - Thrown if the length of the data array is incorrect, the width or height are invalid, or the type is invalid.

Method Detail

getDefaultType

public static int getDefaultType()

Query the default Bitmap type for the device.

Returns:

The type of the natural device Bitmap.

getType

public int getType()

Retrieves this bitmap's type.

Returns:

Type of this bitmap.

getWidth

public int getWidth()

Retrieves this bitmap's width.

Returns:

Width of this bitmap in pixels.

getHeight

public int getHeight()

Retrieves this bitmap's height.

Returns:

Height of this bitmap in pixels.

isWritable

public boolean isWritable()

Indicates whether the Bitmap object is read-only.

Readonly bitmaps cannot be drawn to by attaching a Graphics object.

Returns:

True if the Bitmap object is writable, false if it is read-only.

createBitmapFromPNG

public static Bitmap createBitmapFromPNG(byte[] png,
                                         int offset,
                                         int length)

Creates a bitmap from provided PNG format data.

Parameters:

png - PNG data.

offset - Start of PNG data in the passed byte array.

length - Length of PNG data in the passed byte array: -1 means to the end of the data array.

Returns:

New Bitmap object.

Throws:

OutOfMemoryError - Thrown if insufficient memory to process the PNG data into a bitmap.

NullPointerException - Thrown if the png parameter is null.

IllegalArgumentException - Thrown if the png parameter is invalid, or offset or length are invalid.

Since:

JDE 3.6

createBitmapFromBytes

public static Bitmap createBitmapFromBytes(byte[] bytes,
                                           int offset,
                                           int length,
                                           int scale)

Creates a bitmap from image data. See EncodedImage.getSupportedMIMETypes to determine what image formats are supported.

The image can be optionally downscaled during decoding by an integer scale factor.

Parameters:

bytes - Image data.

offset - Start of image data in the passed byte array.

length - Length of image data in the passed byte array: -1 means to the end of the data array.

scale - Integer downscale factor: 1 means no scaling.

Returns:

New bitmap.

Throws:

OutOfMemoryError - If insufficient memory to process the image data into a bitmap.

NullPointerException - If the bytes parameter is null.

IllegalArgumentException - If the bytes parameter is invalid, offset or length are invalid, or scale is invalid.

Since:

JDE 3.6

equals

public boolean equals(Object obj)

Tests if provided bitmap is equal to this bitmap.

A bitmap is equal to another if the types are the same, the dimensions are the same, and the data is the same.

Overrides:

equals in class Object

Parameters:

obj - The object to compare to this bitmap.

Returns:

True if your obj parameter is equivalent to this bitmap; otherwise, false.

Since:

JDE 3.6

hasAlpha

public boolean hasAlpha()

Tests whether there is an alpha map associated with this Bitmap.

Returns:

True if this Bitmap has transparency information.

getBitmapResource

public static Bitmap getBitmapResource(String module,
                                       String name)

Creates a bitmap from provided named resource found in module.

Parameters:

module - Name of the module containing the bitmap resource. If not specified, the name of the calling module is used.

name - Name of the bitmap resource.

Returns:

New Bitmap object, or null if this method couldn't find your named resource.

Throws:

NullPointerException - If the name parameter is null.

Since:

JDE 3.6

getBitmapResource

public static Bitmap getBitmapResource(String name)

Creates a bitmap from provided name resource.

This method looks for the resource in the cod file that launched this process.

Parameters:

name - Name of the bitmap resource.

Returns:

New Bitmap object, or null if this method couldn't find your named resource.

Throws:

NullPointerException - If the name parameter is null.

Since:

JDE 3.6

getPredefinedBitmap

public static Bitmap getPredefinedBitmap(int predefinedBitmap)

Retrieves one of the predefined system bitmaps.

Parameters:

predefinedBitmap - System graphic to retrieve. If you specify a value not currently assigned to a standard system bitmap, this method returns the INFORMATION bitmap.

Returns:

New Bitmap object equivalent to the system graphic you specify.

Since:

JDE 3.6