sofia.graphics
Class Image

java.lang.Object
  extended by sofia.graphics.Image
Direct Known Subclasses:
GreenfootImage

public class Image
extends java.lang.Object

Represents a single bitmapped image, such as one loaded from a file.

Images retrieved by name or class are searched for using a robust and flexible search scheme.

This class cannot be a subclass of Bitmap, since Bitmap is a final class.

Version:
$Date: 2012/08/04 16:32 $
Author:
Stephen Edwards, Last changed by $Author: edwards $

Constructor Summary
Image(android.graphics.Bitmap bitmap)
          Create an image from a bitmap.
Image(java.lang.Class<?> klass)
          Create an image from a class.
Image(Image other)
          Create an image that is a duplicate of another image (a copy constructor).
Image(java.lang.String fileName)
          Create an image from a file.
 
Method Summary
 android.graphics.Bitmap asBitmap()
          Access the contents of this image in the form of an Android Bitmap.
static Image getDefault()
          Get a new Image object that renders as the default Sofia image.
 int getHeight()
          Return the height of this bitmap.
 sofia.graphics.Color getPixel(int x, int y)
          Returns the Color at the specified location.
 sofia.graphics.Color[] getPixels()
          Returns an array containing all of the Color of each pixel in the image, arranged in row-major order.
 boolean getScaleForDpi()
          Get whether this image will be automatically scaled up or down based on the current device's pixel density when it is loaded.
 int getWidth()
          Return the width of this bitmap.
 void resolveAgainstContext(android.content.Context context)
          Provide an Android resource context to use for loading this image (this must be called before any class/id/file name image will be available).
 void setPixel(int x, int y, sofia.graphics.Color color)
          Write the specified Color into the bitmap at the x,y coordinate.
 void setPixels(sofia.graphics.Color[] pixels)
          Replace pixels in the bitmap with the colors in the array.
 void setScaleForDpi(boolean willScaleForDpi)
          Determine whether this image will be automatically scaled up or down based on the current device's pixel density when it is loaded.
 void setUseDefaultIfNotFound(boolean useDefault)
          Determine whether this image should use the default Sofia image/icon, if no image corresponding to the search criteria (e.g., a class name, or a file name) is found.
 boolean useDefaultIfNotFound()
          Says whether this object will use the default Sofia image/icon, if no image corresponding to the search criteria specified in its constructor call (e.g., a class name, or a file name) is found.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Image

public Image(android.graphics.Bitmap bitmap)
Create an image from a bitmap.

Parameters:
bitmap - The bitmap forming this image's contents.

Image

public Image(java.lang.Class<?> klass)
Create an image from a class. The image used will be found based on the name of the class.

Parameters:
klass - The Java class after which the file is named.

Image

public Image(java.lang.String fileName)
Create an image from a file. The image will be found by searching for an appropriate match.

Parameters:
fileName - The name of the image file, optionally including an extension.

Image

public Image(Image other)
Create an image that is a duplicate of another image (a copy constructor).

Parameters:
other - The image to copy.
Method Detail

getDefault

public static Image getDefault()
Get a new Image object that renders as the default Sofia image.

Returns:
a new Image object that renders as the default image.

asBitmap

public android.graphics.Bitmap asBitmap()
Access the contents of this image in the form of an Android Bitmap.

Returns:
A Bitmap with this image's contents.

setUseDefaultIfNotFound

public void setUseDefaultIfNotFound(boolean useDefault)
Determine whether this image should use the default Sofia image/icon, if no image corresponding to the search criteria (e.g., a class name, or a file name) is found. The default is true.

Parameters:
useDefault - True if this image should render as the Sofia default image if no corresponding resource is found. If false, and no image is found, then asBitmap() will return null.

useDefaultIfNotFound

public boolean useDefaultIfNotFound()
Says whether this object will use the default Sofia image/icon, if no image corresponding to the search criteria specified in its constructor call (e.g., a class name, or a file name) is found. If it returns false, and no image file is found, then asBitmap() will return null. The default is true.

Returns:
True if this image should render as the Sofia default image when no corresponding resource is found.

setScaleForDpi

public void setScaleForDpi(boolean willScaleForDpi)
Determine whether this image will be automatically scaled up or down based on the current device's pixel density when it is loaded. The default is true. This setting is only useful before the image is resolved (loaded), since scaling happens at that time.

Parameters:
willScaleForDpi - True if this image should be scaled for the current device's pixel density.
See Also:
resolveAgainstContext(Context)

getScaleForDpi

public boolean getScaleForDpi()
Get whether this image will be automatically scaled up or down based on the current device's pixel density when it is loaded. The default is true. This setting is only useful before the image is resolved (loaded), since scaling happens at that time.

Returns:
True if this image will be scaled for the current device's pixel density when it is loaded.
See Also:
resolveAgainstContext(Context)

resolveAgainstContext

public void resolveAgainstContext(android.content.Context context)
Provide an Android resource context to use for loading this image (this must be called before any class/id/file name image will be available).

Parameters:
context - The context to resolve this image against.

getWidth

public int getWidth()
Return the width of this bitmap.

Before calling this method, the bitmap must be resolved (that is, loaded from a resource).

Returns:
The width of this bitmap, in pixels.
Throws:
java.lang.IllegalStateException - If the bitmap has not yet been resolved.

getHeight

public int getHeight()
Return the height of this bitmap.

Before calling this method, the bitmap must be resolved (that is, loaded from a resource).

Returns:
The height of this bitmap, in pixels.
Throws:
java.lang.IllegalStateException - If the bitmap has not yet been resolved.

getPixel

public sofia.graphics.Color getPixel(int x,
                                     int y)
Returns the Color at the specified location. Throws an exception if x or y are out of bounds (negative or >= to the width or height respectively).

Parameters:
x - The x coordinate (0...width-1) of the pixel to return.
y - The y coordinate (0...height-1) of the pixel to return.
Returns:
The Color at the specified coordinate
Throws:
java.lang.IllegalArgumentException - If x or y exceed the bitmap's bounds.
java.lang.IllegalStateException - If the bitmap has not yet been resolved.

getPixels

public sofia.graphics.Color[] getPixels()
Returns an array containing all of the Color of each pixel in the image, arranged in row-major order. All of the pixels in row 0 appear in the array first, followed by the pixels in row 1, row 2, and so on. The array is Width x Height in size.

Returns:
An array representing all of the pixels in the image.
Throws:
java.lang.IllegalStateException - If the bitmap has not yet been resolved.

setPixel

public void setPixel(int x,
                     int y,
                     sofia.graphics.Color color)
Write the specified Color into the bitmap at the x,y coordinate.

Parameters:
x - The x coordinate of the pixel to replace (0...width-1).
y - The y coordinate of the pixel to replace (0...height-1).
color - The Color to write into the bitmap.
Throws:
java.lang.IllegalArgumentException - If x, y are outside of the bitmap's bounds.
java.lang.IllegalStateException - If the bitmap has not yet been resolved.

setPixels

public void setPixels(sofia.graphics.Color[] pixels)
Replace pixels in the bitmap with the colors in the array.

Parameters:
pixels - The colors to write to the bitmap.
Throws:
java.lang.IllegalStateException - If the bitmap has not yet been resolved.
java.lang.IllegalArgumentException - If the pixels array is the wrong size, or null.


Greenfoot homepage