org.havi.ui

Class HStillImageBackgroundConfiguration

java.lang.Object

org.havi.ui.HScreenConfiguration

org.havi.ui.HBackgroundConfiguration

org.havi.ui.HStillImageBackgroundConfiguration

public class HStillImageBackgroundConfiguration
extends HBackgroundConfiguration

This class represents a background configuration which supports the installation of still images. The platform using the HAVi user-interface specification must specify which image formats are supported. The java.awt.Image class is intentionally not used in order to allow the support of image formats which carry sufficient restrictions that expressing them through the API of that class would require extensive use of runtime errors. One specific example of this is MPEG I-frames. The parameters to the constructors are as follows, in cases where parameters are not used, then the constructor should use the default values.

Default parameter values exposed in the constructors

Parameter	Description	Default value	Set method	Get method
None.

Default parameter values not exposed in the constructors

Description	Default value	Set method	Get method
None.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	HStillImageBackgroundConfiguration() An interoperable application shall not subclass the HStillImageBackgroundConfiguration class.

Method Summary

Methods

Modifier and Type	Method and Description
void	displayImage(HBackgroundImage image) Display an image.
void	displayImage(HBackgroundImage image, HScreenRectangle r) Display an image to cover a particular area of the screen.
void	setColor(Color color) Set the current color of this background.

Methods inherited from class org.havi.ui.HBackgroundConfiguration

getColor, getConfigTemplate, getDevice

Methods inherited from class org.havi.ui.HScreenConfiguration

convertTo, getFlickerFilter, getInterlaced, getOffset, getPixelAspectRatio, getPixelResolution, getScreenArea

Methods inherited from class java.lang.Object

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

Constructor Detail

HStillImageBackgroundConfiguration

protected HStillImageBackgroundConfiguration()

An interoperable application shall not subclass the HStillImageBackgroundConfiguration class.

Creates an HStillImageBackgroundConfiguration object. See the class description for details of constructor parameters and default values.

Method Detail

displayImage

public void displayImage(HBackgroundImage image)
                  throws IOException,
                         HPermissionDeniedException,
                         HConfigurationException

Display an image. If the data for the image has not been loaded then this method will block while the data is loaded. It is platform dependent whether this image is scaled to fit or whether it is cropped (where too large) or repeated (where too small). The position of the image is platform-dependent. If the platform does not scale the image to fit, the previous color set using setColor is shown in the areas where no image is displayed. If no color has been set what is shown in this area is platform dependent. What is displayed while the image is loading is implementation specific.

Note that the image may be removed by calling the setColor method.

If the image parameter is null a java.lang.NullPointerException is thrown.

Parameters:

image - the image to display.

Throws:

IOException - if the data for the HBackgroundImage is not loaded and loading the data is impossible or fails.

IllegalArgumentException - if the HBackgroundImage does not contain an image in a supported image encoding format

HPermissionDeniedException - if the HBackgroundDevice concerned is not reserved.

HConfigurationException - if the HStillImageBackgroundConfiguration is not the currently set configuration for its HBackgroundDevice.

displayImage

public void displayImage(HBackgroundImage image,
                HScreenRectangle r)
                  throws IOException,
                         HPermissionDeniedException,
                         HConfigurationException

Display an image to cover a particular area of the screen. If the data for the image has not been loaded then this method will block while the data is loaded. It is platform dependent whether this image is scaled to fit or whether it is cropped (where too large) or repeated (where too small). The position of the image within the rectangle is platform-dependent. If the platform does not scale the image to fit, or the rectangle does not cover the entire display area, the previous color set using setColor is shown in the areas where no image is displayed. If no color has been set what is shown in this area is platform dependent.

Note that the image may be removed by calling the setColor method.

If either or both parameters are null a java.lang.NullPointerException is thrown.

Parameters:

image - the image to display

r - the area of the screen to cover with the image

Throws:

IOException - if the data for the HBackgroundImage is not loaded and loading the data is impossible or fails.

IllegalArgumentException - if the HBackgroundImage does not contain an image in a supported image encoding format

HPermissionDeniedException - if the HBackgroundDevice concerned is not reserved.

HConfigurationException - if the HStillImageBackgroundConfiguration is not the currently set configuration for its HBackgroundDevice.

setColor

public void setColor(Color color)
              throws HPermissionDeniedException,
                     HConfigurationException

Set the current color of this background. On platforms where there is a sub-class of java.awt.Color supporting transparency of any kind, passing an object representing a non-opaque color is illegal. Platforms with a limited color resolution for backgrounds may approximate this value to the nearest available. The getColor method will return the actual value used.

Note that calling this method will clear any image currently displayed by the HBackgroundDevice.

Overrides:

setColor in class HBackgroundConfiguration

Parameters:

color - the color to be used for the background

Throws:

HPermissionDeniedException - if this HBackgroundDevice does not have the right to control the background

HConfigurationException - if the color specified is illegal for this platform.