MIDP3.0

javax.microedition.lcdui
Class ScalableImage

java.lang.Object
  extended by javax.microedition.lcdui.Image
      extended by javax.microedition.lcdui.ScalableImage

public class ScalableImage
extends Image

A ScalableImage object encapsulates vector graphics content. The enclosed vector content can be used directly in high-level LCDUI components, and can also be used (in a rasterized, bitmap form) as an Image of variable dimensions in low-level graphics APIs.

Vector graphics content has a viewport to define the area within its own coordinate system that should be rendered. Typically, the viewport region is defined by the content author (e.g. using the viewBox attribute in SVG) and is sized to contain all of its drawing operations. If a viewport is not explicitly defined in the content, the implementation may examine the drawing operations to determine a suitable viewport; if such an examination is unfeasible or not supported by the implementation, a default viewport of (0, 0, 100, 100) may be used instead. The viewport dimensions may be obtained using the getViewportWidth() and getViewportHeight() methods.

As a subclass of Image, a ScalableImage also has a pixel-based width and height, as reported by the getWidth() and getHeight() methods. For a ScalableImage, these values indicate its rasterized size when used as a pixel-based Image in low-level graphics API's, and they are initially set to match the content's viewport dimensions. The pixel dimensions of the image may be subsequently modified using the setWidth() and setHeight() methods, thus changing the size of the rasterized Image that it represents; however, it is important to note that such changes do not alter the viewport of the content itself. The initial frame of the content is rasterized if the content includes animations.

When used with high-level UI components, the implementation SHOULD use the vector-based content directly and render it at a size that is appropriate for the given component. The size may be determined based on the content's viewport size and the preferred image dimensions for the Display. Support for animation is OPTIONAL and interactive functionality MAY be disabled. The pixel-based dimensions of a ScalableImage may be ignored when it is used in this manner.

Creating ScalableImages

A ScalableImage instance can be created by calling one of the following factory methods in the Image class with valid vector graphics content (e.g. SVG Tiny 1.1):

All ScalableImage objects are immutable and cannot be drawn on with a Graphics object; calls to isMutable() will return false and an attempt to obtain a Graphics object will result in an IllegalStateException being thrown. The LCDUI does not provide any capabilities to modify the content of the ScalableImage. Any modifications to the vector-based content are done through an auxiliary vector graphics API like M2G, if the ScalableImage has been created using the bind(Object) method.

Creating Pixel-Based Images From ScalableImages

As stated above, a ScalableImage itself can be used directly as a regular pixel-based Image for low-level graphics APIs. However, it is also possible create a pixel-based Image instance from a ScalableImage by using it as the source for the following factory methods in Image:

Use of ScalableImage with Sprite and TiledLayer

A ScalableImage may be used with the Sprite and TiledLayer class in the Game API. However, since these APIs assume fixed image dimensions, the implementation must behave as if a fixed-size, bitmapped snapshot of the ScalableImage is taken when the relevant method is invoked. That is, the following code:


 new Sprite(myScalableImage);
 

must behave as:


 new Sprite(Image.createImage(myScalableImage));
 

Thus, subsequent changes to the dimensions or content of the ScalableImage do not effect the size or appearance of the Sprite or TiledLayer.

Since:
MIDP 3.0

Method Summary
static ScalableImage bind(java.lang.Object extScalableImage)
          Binds a ScalableImage instance to a more advanced scalable image object from an external graphics API.
 int getViewportHeight()
          Gets the height of the content's viewport.
 int getViewportWidth()
          Gets the width of the content's viewport.
 void setHeight(int height, boolean matchAspectRatio)
          Sets the pixel-based height of the ScalableImage, as returned by getHeight.
 void setWidth(int width, boolean matchAspectRatio)
          Sets the pixel-based width of the ScalableImage, as returned by getWidth.
 void unbind()
          Unbinds this ScalableImage instance from an external scalable image object.
 
Methods inherited from class javax.microedition.lcdui.Image
createImage, createImage, createImage, createImage, createImage, createImage, createImage, createImage, createRGBImage, getARGB16, getGraphics, getHeight, getRGB, getRGB16, getWidth, hasAlpha, isAnimated, isMutable, isScalable
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getViewportWidth

public int getViewportWidth()
Gets the width of the content's viewport.

Returns:
the viewport width

getViewportHeight

public int getViewportHeight()
Gets the height of the content's viewport.

Returns:
the viewport height

bind

public static ScalableImage bind(java.lang.Object extScalableImage)

Binds a ScalableImage instance to a more advanced scalable image object from an external graphics API. This method creates and returns a new scalable image instance that can be used for drawing within LCDUI. If this method is called again for the same target, it MUST return the same ScalableImage instance that was returned from the initial call to this method.

For example, M2G has the javax.microedition.m2g.ScalableImage class. This method allows to get a javax.microedition.lcdui.ScalableImage representation out of javax.microedition.m2g.ScalableImage.

As long as the binding is in effect (i.e. the unbind method has not been called), modifications to extScalableImage MUST be visible directly in the ScalableImage object returned from the method.

Parameters:
extScalableImage - the external scalable image object to bind to
Returns:
ScalableImage instance bound to external API scalable image object
Throws:
java.lang.NullPointerException - if target is null
java.lang.IllegalArgumentException - if target is invalid

unbind

public void unbind()

Unbinds this ScalableImage instance from an external scalable image object. From the point unbind() is called, modifications to the previously bound external scalable image will no longer be reflected in this ScalableImage instance. The data and attributes of the ScalableImage reflect the state of the external scalable image at the point unbind() was called. If the instance is not bound to an external object, this method does nothing.

See Also:
bind(java.lang.Object)

setWidth

public void setWidth(int width,
                     boolean matchAspectRatio)

Sets the pixel-based width of the ScalableImage, as returned by getWidth. This dimension only applies when the image is used as a pixel-based Image in low-level graphics APIs such as drawImage.

If matchAspectRatio is true, the pixel-based height is automatically changed to match the aspect ratio of the content's viewport given the new width. Mathematically:

     height = (getViewportHeight() * width) / getViewportWidth()
 

Parameters:
width - The new pixel-based width of the image, in pixels
matchAspectRatio - true if the height should be changed to match the content's aspect ratio
Throws:
java.lang.IllegalArgumentException - if width is not a positive value

setHeight

public void setHeight(int height,
                      boolean matchAspectRatio)

Sets the pixel-based height of the ScalableImage, as returned by getHeight. This dimension only applies when the image is used as a pixel-based Image in low-level graphics APIs such as drawImage.

If matchAspectRatio is true, the pixel-based width is automatically changed to match the aspect ratio of the content's viewport given the new height. Mathematically:

     width = (viewport_width * height) / viewport_height
 

Parameters:
height - The new pixel-based height of the image, in pixels
matchAspectRatio - true if the width should be changed to match the content's aspect ratio
Throws:
java.lang.IllegalArgumentException - if height is not a positive value

MIDP3.0

Send a comment or suggestionVersion 3.0 of Mobile Information Device Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-2009 Motorola Inc. Portions copyright 1993-2002 Sun Microsystems, Inc. and Motorola, Inc. All Rights Reserved.