ewe.fx
Class mImage

java.lang.Object
  ewe.fx.mImage

All Implemented Interfaces:

ByteEncodable, IImage, OnScreenImage

Direct Known Subclasses:

AniImage, DisabledIcon, DrawnIcon

public class mImage

extends Object

implements OnScreenImage, ByteEncodable

An mImage is a versatile implementation of IImage. One of its major uses is to display Images with transparent or partially transparent areas. This is needed because the Graphics class does not draw transparent images unless the DRAW_ALPHA mode is specified or unless one of the special drawImage() methods are used that use an image mask (itself an image) or a transparent color to display certain areas of the image as being transparent.

You can also inherit from mImage and override the doDraw() method to custom draw your Image.

Field Summary

static int	AlwaysOnTop A property bit - The image is always on top.
Color	backgroundColor
Mask	bitmask A bitmask used for the image.
static int	CompletelyIn A property bit - Another image must be completely within this image to be considered "within" this image.
IImage	drawable If this is set, then the mImage will draw itself using this other IImage.
int	drawMode
static int	HasBorder A property bit - The image has a border.
static int	HasChanged A property bit - The image has changed, this is normally set and cleared automatically.
static int	HasMoved A property bit - The image has moved, this is normally set and cleared automatically.
Area	hotArea This Area must update itself as the image moves.
Polygon	hotPolygon This polygon must be relative to the top-left of the image.
Image	image The base image for the mImage.
protected boolean	imageMayChange
static int	InUse A property bit - Used by MosaicPanel
static int	IsAnimated A property bit - indicates that this image will be animated and so the ImageRefresher should be set if it is being placed into a Control.
static int	IsEmpty A property bit - The image is empty.
static int	IsInvisible A property bit - The image is invisible
static int	IsLocked A property bit - The image is locked - not used yet.
static int	IsMoveable A property bit - The image is moveable (draggable).
static int	IsNotHot A property bit - The image has no hot area.
static int	IsNotStill A property bit - The image is not still, it is animated.
static int	IsPrepared A property bit - The image is fully prepared.
static int	IsPreparing A property bit - The image is being prepared.
static int	KeepOnScreen A property bit - When refreshing this image, the associated Mosaic will scroll itself to keep the image fully visible (if possible).
Rect	lastDrawn
Rect	location
Image	mask An image mask used for the image.
static int	MouseMustBeOver A property bit - In order for a "drag over" event to be recognized, the mouse pointer must be over the image.
int	properties This is used for setting properties of the mImage.
static int	RelativeToOrigin A property bit - The image stays on the same spot on the screen, even if the mosaic scrolls.
protected Image	sourceImage
protected Image	sourceMask
Color	transparentColor

Fields inherited from interface ewe.fx.IImage

DISABLED, OUTLINED

Constructor Summary

mImage()
Create a new mImage().

mImage(IImage drawable)
Create a new mImage() for a specified IImage.

mImage(IImage drawable, int drawMode)
Create a new mImage() for the specified IImage.

mImage(Image image, int drawMode, boolean imageMayChange)

mImage(String mi)
Create a new mImage() with the named image.

mImage(String mi, Color trans)
Create a new mImage() with the named image and specified transparent color.

mImage(String mi, String mm)
Create a new mImage() with the named image and mask.

Method Summary

boolean	changeRefresher(ImageRefresher newRefresher, ImageRefresher oldRefresher) Change the ImageRefresher for the Image only if the old Refresher is the same as the one specified.
int	compareTo(Object other)
void	copyFrom(Object other)
int	decodeBytes(byte[] source, int offset, int length)
void	doDraw(Graphics g, int options) Bottom level draw.
void	draw(Graphics g) Draws itself on the graphic g at the point specified by the variable "location".
void	draw(Graphics g, int x, int y, int options) Draws itself on the graphic g at a specfied co-ordinate.
void	drawBorder(Graphics g, int x, int y, int options) Draws the border of the image.
void	drawn(Rect where)
int	encodeBytes(ByteArray dest) This requests the Object to encode itself as a stream of bytes which is appended to the destination ByteArray.
protected void	fixColors()
void	free() This frees system resources associated with the Image.
protected void	freeIfNotOriginal()
void	freeSource() This will free the source image IF it is not being directly used by the mImage.
Color	getBackground() This returns a background color if one is set for the image.
static IImage	getBrokenImage()
Object	getCopy()
protected IImage	getDefaultImage()
Rect	getDim(Rect dest)
mImage	getFullCopy() This gets a copy which has copies of the image resources of this one.
int	getHeight() This returns the height of the image.
Area	getHotArea() The area returned here is not relative to the top left of the image.
Point	getLocation(Point dest) Get the X,Y location of the mImage.
Object	getNew()
int[]	getPixels(int[] dest, int offset, int x, int y, int width, int height, int options) Retrieve the pixels from the Image in encoded ARGB values.
ImageRefresher	getRefresher() Retrieve the ImageRefresher for the image which is weakly referenced by the OnScreenImage.
Dimension	getSize(Dimension dest) Get the width and height of the mImage.
static IImage	getUnknownImage()
protected Color	getUnusedColor()
int	getWidth() This returns the width of the image.
void	imageSet()
Area	makeOpaqueHotArea(mImage template) This sets the hot area to be within the image and include only the opaque portions of the image.
boolean	onHotArea(int x, int y) Returns if the point is on the hot area of the image.
protected void	refresh(ImageRefresher on)
mImage	scale(int newWidth, int newHeight, Rect area, int imageAndScaleOptions) Produce a new mImage that is a scaled version of a section of this one.
void	setHotAreaInImage(Area inImage)
void	setImage(IImage im)
void	setImage(Image im) Set the Image for the mImage.
void	setImage(Image im, Color transparent)
void	setImage(Image im, Image msk) This sets the mask image for the mImage.
void	setImage(Image im, int drawMode)
void	setImage(Image im, int drawMode, boolean imageMayChange)
void	setImage(Image im, Mask mask)
void	setMImage(mImage other)
void	setRefresher(ImageRefresher refresher) Weakly set the ImageRefresher for the Image.
Image	toAlphaImage(Rect area, int imageCreationOptions) Convert the mImage to a single Image with an alpha channel.
Object	toCursor(Point hotSpot) This transforms the image into a mouse cursor suitable for use on the current platform.
String	toString() Return a String representation of this object.
boolean	usesAlpha() Returns whether the image uses the Alpha channel.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode

Field Detail

image

public Image image

The base image for the mImage.

mask

public Image mask

An image mask used for the image. Don't set this directly, instead use setImage(Image image,Image mask) - using setMask() will create the appropriate Image mask for use when drawing.

bitmask

public Mask bitmask

A bitmask used for the image. Don't set this directly, instead use setImage(Image image,Mask mask) - using setMask() will create the appropriate Image mask for use when drawing.

drawable

public IImage drawable

If this is set, then the mImage will draw itself using this other IImage.

properties

public int properties

This is used for setting properties of the mImage. Properties should ORed together and stored in this variable.

transparentColor

public Color transparentColor

backgroundColor

public Color backgroundColor

IsPreparing

public static final int IsPreparing

A property bit - The image is being prepared.

See Also:

Constant Field Values

IsPrepared

public static final int IsPrepared

A property bit - The image is fully prepared.

See Also:

Constant Field Values

IsInvisible

public static final int IsInvisible

A property bit - The image is invisible

See Also:

Constant Field Values

HasBorder

public static final int HasBorder

A property bit - The image has a border.

See Also:

Constant Field Values

IsEmpty

public static final int IsEmpty

A property bit - The image is empty.

See Also:

Constant Field Values

AlwaysOnTop

public static final int AlwaysOnTop

A property bit - The image is always on top.

See Also:

Constant Field Values

InUse

public static final int InUse

A property bit - Used by MosaicPanel

See Also:

Constant Field Values

IsNotHot

public static final int IsNotHot

A property bit - The image has no hot area.

See Also:

Constant Field Values

IsMoveable

public static final int IsMoveable

A property bit - The image is moveable (draggable).

See Also:

Constant Field Values

IsLocked

public static final int IsLocked

A property bit - The image is locked - not used yet.

See Also:

Constant Field Values

CompletelyIn

public static final int CompletelyIn

A property bit - Another image must be completely within this image to be considered "within" this image.

See Also:

Constant Field Values

HasMoved

public static final int HasMoved

A property bit - The image has moved, this is normally set and cleared automatically.

See Also:

Constant Field Values

HasChanged

public static final int HasChanged

A property bit - The image has changed, this is normally set and cleared automatically.

See Also:

Constant Field Values

IsNotStill

public static final int IsNotStill

A property bit - The image is not still, it is animated.

See Also:

Constant Field Values

RelativeToOrigin

public static final int RelativeToOrigin

A property bit - The image stays on the same spot on the screen, even if the mosaic scrolls.

See Also:

Constant Field Values

MouseMustBeOver

public static final int MouseMustBeOver

A property bit - In order for a "drag over" event to be recognized, the mouse pointer must be over the image. That is to say, if you are dragging another image over this one, the mouse pointer itself must be over this image for it to be considered dragged over.

See Also:

Constant Field Values

KeepOnScreen

public static final int KeepOnScreen

A property bit - When refreshing this image, the associated Mosaic will scroll itself to keep the image fully visible (if possible). In order for this to work the virtualSize of the Mosaic must be set.

See Also:

Constant Field Values

IsAnimated

public static final int IsAnimated

A property bit - indicates that this image will be animated and so the ImageRefresher should be set if it is being placed into a Control.

See Also:

Constant Field Values

location

public Rect location

lastDrawn

public Rect lastDrawn

drawMode

public int drawMode

sourceImage

protected Image sourceImage

sourceMask

protected Image sourceMask

imageMayChange

protected boolean imageMayChange

hotArea

public Area hotArea

This Area must update itself as the image moves.

hotPolygon

public Polygon hotPolygon

This polygon must be relative to the top-left of the image. It will be automatically updated as the image moves so you can set it to be a static polygon.

Constructor Detail

mImage

public mImage()

Create a new mImage(). Use one of the setImage() methods after creation to specify the display image.

mImage

public mImage(String mi,
              String mm)
       throws IllegalArgumentException

Create a new mImage() with the named image and mask.

Parameters:

mi - The name of the image.

mm - The name of the mask - which can be null.

Throws:

IllegalArgumentException - if the image named by mi or mm is invalid.

mImage

public mImage(String mi,
              Color trans)
       throws IllegalArgumentException

Create a new mImage() with the named image and specified transparent color.

Parameters:

mi - The name of the image.

trans - The transparent color.

Throws:

IllegalArgumentException - if the image named by mi is invalid.

mImage

public mImage(String mi)
       throws IllegalArgumentException

Create a new mImage() with the named image.

Parameters:

mi - The name of the image.

Throws:

IllegalArgumentException - if the image named by mi is invalid.

mImage

public mImage(IImage drawable)

Create a new mImage() for a specified IImage.

Parameters:

drawable - The drawable

mImage

public mImage(IImage drawable,
              int drawMode)

Create a new mImage() for the specified IImage.

Parameters:

drawable - The drawable.

drawMode - The draw mode for drawing. If this is Graphics.DRAW_ALPHA and the drawable has an alpha channel, then alpha blending will be used for drawing - if supported by the underlying system.

mImage

public mImage(Image image,
              int drawMode,
              boolean imageMayChange)

Method Detail

getLocation

public Point getLocation(Point dest)

Get the X,Y location of the mImage.

Parameters:

dest - An optional destination Point object.

Returns:

The dest object or a new Point if dest is null.

getSize

public Dimension getSize(Dimension dest)

Get the width and height of the mImage.

Parameters:

dest - An optional destination Dimension object.

Returns:

The dest object or a new Dimension if dest is null.

getHeight

public int getHeight()

Description copied from interface: IImage

This returns the height of the image.

Specified by:

getHeight in interface IImage

getWidth

public int getWidth()

Description copied from interface: IImage

This returns the width of the image.

Specified by:

getWidth in interface IImage

freeSource

public void freeSource()

This will free the source image IF it is not being directly used by the mImage. Sometimes, when you create an mImage OR if you use setImage(), the mImage does not use the actual provided image, but may use a modified version of it. If this is the case then this tells the mImage to free the original image.

You would normally call this after creating the mImage, if you are sure the source Image is not to be used again.

freeIfNotOriginal

protected void freeIfNotOriginal()

getNew

public Object getNew()

getCopy

public Object getCopy()

drawn

public void drawn(Rect where)

setImage

public void setImage(Image im,
                     Mask mask)

setImage

public void setImage(Image im,
                     Color transparent)

setImage

public void setImage(IImage im)

setImage

public void setImage(Image im,
                     Image msk)

This sets the mask image for the mImage. The actual value of the "mask" field may not be the provided mask. The actual mask is frequently the inversion of this mask.

Parameters:

msk - The user image mask with black pixels for opaque and white pixels for transparent.

setImage

public void setImage(Image im,
                     int drawMode)

setImage

public void setImage(Image im,
                     int drawMode,
                     boolean imageMayChange)

setImage

public void setImage(Image im)

Set the Image for the mImage.

Parameters:

im - The image to set.

getBackground

public Color getBackground()

Description copied from interface: IImage

This returns a background color if one is set for the image.

Specified by:

getBackground in interface IImage

setMImage

public void setMImage(mImage other)

imageSet

public void imageSet()

copyFrom

public void copyFrom(Object other)

drawBorder

public void drawBorder(Graphics g,
                       int x,
                       int y,
                       int options)

Draws the border of the image. If the image has a border it will be drawn.

doDraw

public void doDraw(Graphics g,
                   int options)

Bottom level draw. Override to change how the image is drawn. Will still allow borders to be drawn and allow invisible to have effect.

draw

public void draw(Graphics g,
                 int x,
                 int y,
                 int options)

Draws itself on the graphic g at a specfied co-ordinate. If the image has a border it will be drawn.

Specified by:

draw in interface IImage

draw

public void draw(Graphics g)

Draws itself on the graphic g at the point specified by the variable "location". If the image has a border it will be drawn.

setHotAreaInImage

public void setHotAreaInImage(Area inImage)

makeOpaqueHotArea

public Area makeOpaqueHotArea(mImage template)

This sets the hot area to be within the image and include only the opaque portions of the image.

getHotArea

public Area getHotArea()

The area returned here is not relative to the top left of the image. It is an absolute area, regardless of the location of the image. If you have an area that is hard to translate (e.g. a Polygon) then call convertRelativeArea()

onHotArea

public boolean onHotArea(int x,
                         int y)

Returns if the point is on the hot area of the image.

getDim

public Rect getDim(Rect dest)

compareTo

public int compareTo(Object other)

toCursor

public Object toCursor(Point hotSpot)

This transforms the image into a mouse cursor suitable for use on the current platform. Will return null if the cursor could not be created. The return value should then be passed to ewe.sys.Vm.createCursor(Object cursor).
In order for this to work there are a few conditions:
1. The mImage must be a mono (black & white) image.
2. There must be a mask for the image which must be the same size as the image.

The rules for the image and mask are as normal. The mask image should be black where you want the image to be opaque and should be white where you want the image to be transparent. The areas which are white (transparent) in the mask should also be white in the image.
The image will be scaled if necessary to get it to be the size of cursors on the system (for Win32 this is 32x32).

This will free this mImage!

free

public void free()

Description copied from interface: IImage

This frees system resources associated with the Image.

Specified by:

free in interface IImage

getFullCopy

public mImage getFullCopy()

This gets a copy which has copies of the image resources of this one.

usesAlpha

public boolean usesAlpha()

Description copied from interface: IImage

Returns whether the image uses the Alpha channel.

Specified by:

usesAlpha in interface IImage

getUnusedColor

protected Color getUnusedColor()

getPixels

public int[] getPixels(int[] dest,
                       int offset,
                       int x,
                       int y,
                       int width,
                       int height,
                       int options)

Description copied from interface: IImage

Retrieve the pixels from the Image in encoded ARGB values. If the usesAlpha() method returns false, then the A component of each pixel value (the top 8 bits) should be ignored.

Specified by:

getPixels in interface IImage

Parameters:

dest - The destination int array. If this is null then a new array should be created.

offset - The offset into the array to start placing pixels.

x - the x co-ordinate within the image.

y - the y co-ordinate within the image.

width - the width of the pixel block to get.

height - the height of the pixel block to get.

options - options for retrieving pixels - currently unused.

Returns:

The array containing the pixels, or null if getting pixels is not supported.

toAlphaImage

public Image toAlphaImage(Rect area,
                          int imageCreationOptions)
                   throws IllegalArgumentException

Convert the mImage to a single Image with an alpha channel.

Parameters:

area - an area within the image to convert. If this is null it will use the entire image.

imageCreationOptions - options to use when creating the new Image.

Returns:

a new Image or null if this mImage cannot be converted to an Image.

Throws:

IllegalArgumentException

scale

public mImage scale(int newWidth,
                    int newHeight,
                    Rect area,
                    int imageAndScaleOptions)
             throws IllegalArgumentException

Produce a new mImage that is a scaled version of a section of this one.

Parameters:

newWidth -

newHeight -

area - An area within the image to scale - or null to scale the entire image.

Returns:

a new mImage() or null if the mImage could not be scaled.

Throws:

IllegalArgumentException - if the area is out of bounds, or if the new size has negative values.

fixColors

protected void fixColors()

getUnknownImage

public static IImage getUnknownImage()

getBrokenImage

public static IImage getBrokenImage()

getDefaultImage

protected IImage getDefaultImage()

encodeBytes

public int encodeBytes(ByteArray dest)

Description copied from interface: ByteEncodable

This requests the Object to encode itself as a stream of bytes which is appended to the destination ByteArray. If the destination ByteArray is null, then the object should report how many bytes would be used if the object was encoded.

Specified by:

encodeBytes in interface ByteEncodable

Parameters:

dest - The destination ByteArray, or null to determine the number of bytes needed to encode.

Returns:

The number of bytes appended to the ByteArray or the number of bytes needed to encode.

decodeBytes

public int decodeBytes(byte[] source,
                       int offset,
                       int length)

toString

public String toString()

Description copied from class: Object

Return a String representation of this object.

Overrides:

toString in class Object

Returns:

a String representing this object.

setRefresher

public void setRefresher(ImageRefresher refresher)

Description copied from interface: OnScreenImage

Weakly set the ImageRefresher for the Image.

Specified by:

setRefresher in interface OnScreenImage

changeRefresher

public boolean changeRefresher(ImageRefresher newRefresher,
                               ImageRefresher oldRefresher)

Description copied from interface: OnScreenImage

Change the ImageRefresher for the Image only if the old Refresher is the same as the one specified.

Specified by:

changeRefresher in interface OnScreenImage

Parameters:

newRefresher - The new ImageRefresher for the image.

oldRefresher - What the old ImageRefresher was expected to be.

Returns:

true if the refresher was changed, false if it was not changed because the old Refresher was not the same as that specified in the parameter.

getRefresher

public ImageRefresher getRefresher()

Description copied from interface: OnScreenImage

Retrieve the ImageRefresher for the image which is weakly referenced by the OnScreenImage.

Specified by:

getRefresher in interface OnScreenImage

refresh

protected void refresh(ImageRefresher on)