org.havi.ui
Class HStillImageBackgroundConfiguration

java.lang.Object
  extended by org.havi.ui.HScreenConfiguration
      extended by org.havi.ui.HBackgroundConfiguration
          extended by 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

ParameterDescriptionDefault value Set methodGet method
None.

Default parameter values not exposed in the constructors

DescriptionDefault valueSet method Get method
None.


Method Summary
 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(java.awt.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
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

displayImage

public void displayImage(HBackgroundImage image)
                  throws java.io.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:
java.io.IOException - if the data for the HBackgroundImage is not loaded and loading the data is impossible or fails.
java.lang.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 java.io.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:
java.io.IOException - if the data for the HBackgroundImage is not loaded and loading the data is impossible or fails.
java.lang.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(java.awt.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.