Images

Images are bit-mapped pictures drawn on the device screen.

The image tag defines a bit-mapped picture to draw on a device screen and includes a rich set of property elements to customize how that bit-mapped picture is drawn. See image. The URL of the file containing the picture to draw is specified with a url property element. See url. The URL can refer to a local file or to a network resource downloaded from a server at run time. See Media Files, Resources.

Figure 1. An image displayed by the visualelements.ujml sample.

File types

Different devices support different bitmap file types. You can determine available and preferred file types at run time. See Determining Device Context, Image Support.

The easiest way to support multiple devices is to supply the same bitmap in different file formats. You can then call the _image_url() function to append the file extension for the device's preferred file format to the file name. See _image_url() function . For example calling '_image_url("http://myserver/app/startupimage")' on a device where the preferred extension is '.png' will return 'http://myserver/app/startupimage.png'.

Alpha opacity

On some devices the x-alpha property element allows you to specify how opaque the image is, using an int value of 0 (completely transparent) to 255 (completely opaque). See x-alpha. This value works exactly like the alpha opacity portion of a UJML color. See UJML Colors. A partially opaque picture shows the background as if the entire picture was washed over it.

Not all devices support alpha opacity. See Determining Device Context, Color Support.

Transparency

Many bitmap file types support transparency allowing you to specify some portion of the image as transparent and let the background show completely through in those places only.

When a bitmap file type does not support transparency you can fill any parts of the image that you wish to be transparent with the color fuchsia (Red 255, Green 0, Blue 255). UJML will automatically make those areas transparent.

Not all devices support transparency. See Determining Device Context, Image Support.

Figure 2. Example of a picture with transparency indicated using a fuchsia fill.

Using segments of a picture

UJML supports drawing only selected portions of a picture. To do this you specify the area of the image to draw using the src-x and src-y property elements to specify the upper-left corner of the area on the picture. See src-x and src-y. This picture segment is then drawn onto the device screen for the dimensions specified by the image element's bounding area. If the picture segment is larger than the bounding area, it is cropped to fit. If the picture segment is smaller than the bounding area the additional space is drawn as transparent.

You can use this feature to reduce download times for multiple images by downloading a single image containing all the required images and drawing segments of the composite image as needed. This reduces the network traffic to a single transaction.

Another common use of this feature is for animation. Rather than using a separate file for each frame of an animation, you would create a single picture file containing all of the frames and only show the portion of the picture that contains the current frame.

Figure 3. Example of a picture containing multiple frames of an animation.

Scaling

Some devices support scaling pictures using the x-src-width and x-src-height property elements. See x-src-width and x-src-height. These specify a bounding area in a picture segment that is stretched or compressed to fit into the bounding area of the image element.

Not all devices support scaling. See Determining Device Context, Image Support.

Example

The following example shows how to display a picture with alpha opacity. It is part of the visualelements.ujml sample.

Copy Code

<image>
    <url><eval>mImageURL</eval></url>
    <x><eval>mRectX + (mRectWidth / 2) - (&IMAGE_WIDTH; / 2)</eval></x>
    <y><eval>mRectY + (mRectHeight / 2) - (&IMAGE_HEIGHT; / 2)</eval></y>
    <width>&IMAGE_WIDTH;</width>
    <height>&IMAGE_HEIGHT;</height>
    <x-alpha><eval>mOpacity</eval></x-alpha>
</image>

The following example shows how to display a segment of a picture. It is part of the lunarlander.ujml sample.

Copy Code

<image>
    <url><eval>mLanderImageURL</eval></url>
    <src-x><eval>&LANDER_WIDTH; * &LANDER_LEFT1;</eval></src-x>
    <src-y>0</src-y>
    <x><eval>ScreenPane.screenX(mPosX)</eval></x>
    <y><eval>ScreenPane.screenY(mPosY)</eval></y>
    <width>&LANDER_WIDTH;</width>
    <height>&LANDER_HEIGHT;</height>
</image>