waba.fx
Class Image

java.lang.Object
  |
  +--waba.fx.Image

Direct Known Subclasses:

GifImage, ImageTester, JpegImage, PngImage

public class Image

extends java.lang.Object

implements ISurface

Image is a rectangular image.

You can draw into an image and copy an image to a surface using a Graphics object. Before a image is drawn, its palette is set.

See Also:

Graphics

Field Summary

protected int	height
int[]	palRGBs Contains the palette RGBs.
int[][]	pixels On desktop, contains the pixels of this image.
protected Palette	savingPal Used on desktop only to match the colors that are being saved with the colors that are being getted when saving a bitmap
Color	transparentColor Deprecated. use transparentPixel instead, or get/setTransparentColor
int	transparentPixel Sets the transparent pixel of this image.
protected int	width

Constructor Summary

protected	Image() Used by classes that extends the Image class
	Image(byte[] fullBmpDescription) Parses an image from the given byte array.
	Image(int width, int height) Creates an image of the specified width and height.
	Image(java.lang.String path) Loads and constructs an image from a file.

Method Summary

void	applyPalette() apply the palette used by this bitmap to the display
void	changeColors(Color from, Color to) Changes all the pixels of the image from one color to the other.
int	createBmp(DataStream ds) saves this image as a Windows .bmp file format, with the same bpp of the screen using the current palette of this image, to the given DataStream.
void	free() Sets the image width and height to 0 and frees any systems resources associated with the image.
Graphics	getGraphics() Returns a new Graphics instance that can be used to drawing in this image.
int	getHeight() Returns the height of the image.
Palette	getPalette() returns the palette associated with this image.
protected void	getPixelRow(byte[] fillIn, int y) used in saveTo method. fill in the y row into the fillIn array. there must be enough space for the full line be filled.
Image	getRotatedScaledInstance(int scale, int angle, Color fill) Creates a rotated and/or scaled version of this Image.
Image	getScaledInstance(int newWidth, int newHeight) Returns the scaled instance for this picture.
Image	getTouchedUpInstance(byte brightness, byte contrast) Creates a touched-up version of this Image with the specified brightness and contrast.
Color	getTransparentColor() Gets the transparent color of this image.
int	getWidth() Returns the width of the image.
void	load(Stream inputStream) Not implemented by this class.
int	saveTo(Catalog cat, java.lang.String name) saves this image as a Windows .bmp file format to the given Catalog.
Image	scaledBy(float scaleX, float scaleY) Returns the scaled instance for this picture, given the scale arguments.
void	setPalette(Palette pal) substitutes the original palette that came with this image with the given one.
void	setTransparentColor(Color c) Sets the transparent color of this image.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

width

protected int width

height

protected int height

transparentPixel

public int transparentPixel

Sets the transparent pixel of this image. Used in many controls. Note that you can set it to -1 to make the image use the background color. Note also that this value is not used by the system, but the controls (E.g.: waba.ui.Button) use the value stored here to set the background color when going to draw a transparent image. Note: the transparentPixel is proper to the image, and doesn't require any palette examination. If one only know the transparent color of the image, then use the palette specific to this Image to find the associated color index: this is the value to be used as being the transparent pixel. Only knowing the transparent color can be ambiguous, since the Palette can have more than one index describing this color.

palRGBs

public int[] palRGBs

Contains the palette RGBs. Note that changing entries has no effect (use the changeColors method instead), and also in 16bpp this will always be null.

savingPal

protected Palette savingPal

Used on desktop only to match the colors that are being saved with the colors that are being getted when saving a bitmap

pixels

public int[][] pixels

On desktop, contains the pixels of this image. On device, holds the GrHandle structure. NEVER USE THIS MEMBER IN ANY WAY!

transparentColor

public Color transparentColor

Deprecated. use transparentPixel instead, or get/setTransparentColor

Constructor Detail

Image

protected Image()

Used by classes that extends the Image class

Image

public Image(int width,
             int height)

Creates an image of the specified width and height. The image has a color depth (number of bitplanes) and color map that matches the default drawing surface. Here is an example of use:

 Image img = new Image(100,100);
 Graphics g = img.getGraphics();
 g.setBackColor(Color.WHITE);
 g.fillRect(25,25,50,50);
 ...
 Graphics screenG = createGraphics();
 screenG.drawImage(img,CENTER,CENTER);
 

Image

public Image(java.lang.String path)

Loads and constructs an image from a file. The path given is the path to the image file. The file must be in 2, 16 or 256 color uncompressed BMP bitmap format. If the image cannot be loaded, the image constructed will have a width and height of 0.

Important optimization trick: if your image has large parts of white pixels, it will load faster (in other words, use white as background when possible).

For color devices, it is strongly recommended that your images have all the same palette (the web-safe, from SuperWabaSDK/samples/WebSafePalette), non-compressed bmps, because the load time is cut by 100 times!

Throws:

ImageError - Starting in SuperWaba version 5.8, an ImageError can be thrown when the file was not found if Settings.useExceptions is true.

Image

public Image(byte[] fullBmpDescription)

Parses an image from the given byte array. Note that the byte array must specify the full bitmap, with headers, palette and the data. The bitmap can be in compressed rle4 or rle8. Here is a code example:

 // create the image and fill it with something
 Image img = new Image(160,160);
 Graphics g = img.getGraphics();
 for (int i =0; i < 16; i++)
 {
    g.setBackColor(new Color(10*i,10*i,10*i));
    g.fillRect(i*10,0,10,160);
 }
 // save the bmp in a byte stream
 ByteArrayStream bas = new ByteArrayStream(4096);
 DataStream ds = new DataStream(bas);
 int totalBytesWritten = img.createBmp(ds);
 // parse the saved bmp
 Image im = new Image(bas.getBuffer()); // Caution! the buffer may be greater than totalBytesWritten, but when parsing theres no problem.
 if (im.getWidth() > 0) // successfully parsed?
 {
    createGraphics().drawImage(im,CENTER,CENTER);
    Vm.sleep(2000);
 }
 

Throws:

ImageError - Starting in SuperWaba version 5.8, an ImageError can be thrown when something was wrong with the image if Settings.useExceptions is true.

Method Detail

load

public void load(Stream inputStream)

Not implemented by this class. Just a placeholder for the Gif/Png/Jpg classes.

free

public void free()

Sets the image width and height to 0 and frees any systems resources associated with the image. The image will be no longer valid and will be GC'd.

getHeight

public int getHeight()

Returns the height of the image. You can check if the image is ok comparing this with zero.

getWidth

public int getWidth()

Returns the width of the image. You can check if the image is ok comparing this with zero.

getGraphics

public Graphics getGraphics()

Returns a new Graphics instance that can be used to drawing in this image.

setTransparentColor

public void setTransparentColor(Color c)

Sets the transparent color of this image. Used in many controls. Note that you can set it to null to make the image use the background color. Note also that this value is not used by the system, but the controls (E.g.: waba.ui.Button) use the value stored here to set the background color when going to draw a transparent image. Important!: If your image doesnt use the web safe palette, you must call myImage.applyPalette before calling setTransparentColor (or before the first time the image is drawn), otherwise the color may not be found in the active palette.

getTransparentColor

public Color getTransparentColor()

Gets the transparent color of this image.

changeColors

public void changeColors(Color from,
                         Color to)

Changes all the pixels of the image from one color to the other. Note that the current value of the transparent color is not changed. When you load a mono bmp (consumes less memory), it is stored internally as grayScale (or color). Using this routine, you can change the colors to any other you want.

getPalette

public Palette getPalette()

returns the palette associated with this image. If this method return null, the default SystemPalette is used.

setPalette

public void setPalette(Palette pal)

substitutes the original palette that came with this image with the given one.

saveTo

public int saveTo(Catalog cat,
                  java.lang.String name)

saves this image as a Windows .bmp file format to the given Catalog. Important note: the catalog can save multiple images, but the record must be in the SuperWaba warp record format (the image name comes before the data) and must be sorted. This method finds the exact place where to insert the bmp and put it there. If you want to create a bmp to be transfered by a stream to serial or socket then you must use the method createBmp instead. Important: when creating the catalog, the type must be 'SWAX' (SuperWAba eXtension library); if not, the library will not be found by the VM. The catalog name can not be the same name of the image. EG: you can have a catalog named "images" and containing lots of images, one with each name. if a record with this name already exists, it will be replaced. The name is always converted to lowercase and the method makes sure that .bmp is appended to it. To get the list of images in a Catalog, just do a readString at the beginning of each record.

Here is an usage example:

 // create the image and paint over it
 Image img = new Image(100,100);
 Graphics g = img.getGraphics();
 g.setBackColor(Color.getColor(100,150,200));
 g.fillRect(25,25,50,50);
 g.setForeColor(Color.WHITE);
 g.drawCircle(50,50,20);
 // create the catalog to save the image. You must change CRTR to match your apps creator ID
 Catalog cat = new Catalog("images.CRTR.SWAX", Catalog.CREATE);
 img.saveTo(cat, "boxcircle.bmp");
 cat.close();
 // load the previously created image
 if (Vm.attachLibrary("images.CRTR")) // must add the creator so it can be used in desktop. The type is always SWAX
 {
    Image im = new Image("boxcircle.bmp");
    if (im.getWidth() > 0) // successfully loaded?
       createGraphics().drawImage(im,CENTER,CENTER);
 }
 

Returns:

the numbers of bytes written.

See Also:

createBmp(waba.io.DataStream)

createBmp

public int createBmp(DataStream ds)

saves this image as a Windows .bmp file format, with the same bpp of the screen using the current palette of this image, to the given DataStream. If you're sending the bmp through a stream but not saving to a catalog, you can use this method. If you're goind to save it to a catalog, then you must use the saveTo method. Note: if you're saving an image over a previously loaded one, the palette will be preserved only if the device is color. Otherwise, the colors will be converted to the current System palette or to the device's palette.

Returns:

the number of bytes written.

See Also:

saveTo(waba.io.Catalog, java.lang.String)

getPixelRow

protected void getPixelRow(byte[] fillIn,
                           int y)

used in saveTo method. fill in the y row into the fillIn array. there must be enough space for the full line be filled.

applyPalette

public void applyPalette()

apply the palette used by this bitmap to the display

getScaledInstance

public Image getScaledInstance(int newWidth,
                               int newHeight)

Returns the scaled instance for this picture. The algorithm used is the replicate scale, not good quality, but fast. Note: if the image has a different palette, you must apply the palette in the device in a way like this:

 if (Settings.isColor)
 {
    Palette pal = scaledImg.getPalette();
    createGraphics().applyPalette(pal,0,pal.size()-1); // apply the colors of the new image.
 }
 

Since:

SuperWaba 3.5

scaledBy

public Image scaledBy(float scaleX,
                      float scaleY)

Returns the scaled instance for this picture, given the scale arguments. The algorithm used is the replicate scale, not good quality, but fast. Given values must not be <= 0. Note: if the image has a different palette, you must apply the palette in the device in a way like this:

 if (Settings.isColor)
 {
    Palette pal = scaledImg.getPalette();
    createGraphics().applyPalette(pal,0,pal.size()-1); // apply the colors of the new image.
 }
 

Since:

SuperWaba 4.1

getRotatedScaledInstance

public Image getRotatedScaledInstance(int scale,
                                      int angle,
                                      Color fill)

Creates a rotated and/or scaled version of this Image.

IMPORTANT: This method does not work on Palm OS; the same image is returned.

A new Image object is returned which will render the image at the specified scale ratio and rotation angle. After rotation, the empty parts of the rectangular area of the resulting image are filled with the fill color. If color is null, then the fill color is the transparent color, or white if none.

Notes
- the new image will probably have a different size of this image.
- if you want just to scale, use the getScaledInstance or scaleBy instead, because they are faster.

Parameters:

scale - a number greater than or equal to 0 stating the percentage of scaling to be performed. 100 is not scaling, 200 doubles the size, 50 shrinks the image by 2

angle - the rotation angle, expressed in trigonometric degrees

fill - the fill color. null indicates the transparent color of this image or Color.WHITE if the transparentPixel was not set.

getTouchedUpInstance

public Image getTouchedUpInstance(byte brightness,
                                  byte contrast)

Creates a touched-up version of this Image with the specified brightness and contrast.

IMPORTANT: This method does not work on Palm OS; the same image is returned.

A new Image object is returned which will render the image at the specified brigthnessand the specified contrast.

Parameters:

brightness - a number between -128 and 127 stating the desired level of brightness. 127 is the highest brightness level (white image), -128 is no brightness (darkest image).

contrast - a number between -128 and 127 stating the desired level of contrast. 127 is the highest contrast level, -128 is no contrast.