org.havi.ui

Class HScreenDevice

java.lang.Object

org.havi.ui.HScreenDevice

All Implemented Interfaces:

ResourceProxy, ResourceServer

Direct Known Subclasses:

HBackgroundDevice, HGraphicsDevice, HVideoDevice

public class HScreenDevice
extends Object
implements ResourceProxy, ResourceServer

An instance of the HScreen class represents a single independent video output signal from a device. Devices with multiple independent video output signals should support multiple instances of this class. A video output signal is created by adding together the contributions from the devices represented by a number of objects inheriting from the HScreenDevice class. These can be HGraphicsDevice objects, HVideoDevice objects and HBackgroundDevice objects. A given HScreen may support any number of any of these objects as far as the API is concerned however some form of profiling may restrict this. In reality right now, one instance of each is all that may reasonably expected to be present.

Each HScreenDevice can have multiple settings (HScreenConfigurations) but only one "setting" (HScreenConfiguration) can be active at any point in time. The current configuration can be determined on the HScreenDevice subclasses using their specific getCurrentConfiguration methods. The current configuration can be modified on the HScreenDevice subclasses using their specific setCurrentConfiguration methods (assuming sufficient rights, etc.).

Applications may select the best of these configurations for them by creating an instance of HScreenConfigTemplate and populating that with a number preferences each with a priority. The implementation then matches this template against the range of possible configurations and attempts to find one which matches the template provided. Priorities REQUIRED and REQUIRED_NOT must be respected. If they cannot be respected then the method call shall fail and not return any configuration. Priorities PREFERRED and PREFERRED_NOT should be respected as much as possible.

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.

Method Summary

Methods

Modifier and Type	Method and Description
void	addResourceStatusEventListener(ResourceStatusListener listener) Register a listener for events about changes in the state of the ownership of this device.
void	addScreenConfigurationListener(HScreenConfigurationListener hscl) Add an HScreenConfigurationListener to this device, which is notified whenever the device's configuration is modified.
void	addScreenConfigurationListener(HScreenConfigurationListener hscl, HScreenConfigTemplate hsct) Add an HScreenConfigurationListener to this device, which is notified when the device's configuration is further modified so that it is no longer compatible with the specified HScreenConfigTemplate.
ResourceClient	getClient() Return the last ResourceClient passed to the last successful call to the reserveDevice method of this instance of HScreenDevice, or null if this method has not been called on this instance.
String	getIDstring() Returns the identification string associated with this HScreenDevice.
Dimension	getScreenAspectRatio() Return the aspect ratio of the screen as far as is known.
void	releaseDevice() Release the right to control of this device.
void	removeResourceStatusEventListener(ResourceStatusListener listener) Remove a listener for events about changes in the state of the ownership of this device.
void	removeScreenConfigurationListener(HScreenConfigurationListener hscl) Remove an HScreenConfigurationListener from this device.
boolean	reserveDevice(ResourceClient client) Requests the right to call any method which may otherwise throw an HPermissionDeniedException.

Methods inherited from class java.lang.Object

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

Method Detail

getIDstring

public String getIDstring()

Returns the identification string associated with this HScreenDevice.

Returns:

an identification string

addScreenConfigurationListener

public void addScreenConfigurationListener(HScreenConfigurationListener hscl)

Add an HScreenConfigurationListener to this device, which is notified whenever the device's configuration is modified. If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.

Parameters:

hscl - the HScreenConfigurationListener to be added to this device.

addScreenConfigurationListener

public void addScreenConfigurationListener(HScreenConfigurationListener hscl,
                                  HScreenConfigTemplate hsct)

Add an HScreenConfigurationListener to this device, which is notified when the device's configuration is further modified so that it is no longer compatible with the specified HScreenConfigTemplate. If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.

Note that if the device configuration does not match the specified template, then the listener should be added and a HScreenConfigurationEvent immediately generated for the specified HScreenConfigurationListener.

Parameters:

hscl - the HScreenConfigurationListener to be added to this device.

hsct - the HScreenConfigTemplate which is to be used to determine compatibility with the device configuration.

removeScreenConfigurationListener

public void removeScreenConfigurationListener(HScreenConfigurationListener hscl)

Remove an HScreenConfigurationListener from this device. if the specified listener is not registered, the method has no effect. If multiple references to a single listener have been registered it should be noted that this method will only remove one reference per call.

Parameters:

hscl - the HScreenConfigurationListener to be removed from this device.

getScreenAspectRatio

public Dimension getScreenAspectRatio()

Return the aspect ratio of the screen as far as is known. i.e. 4:3, 16:9, etc.

This Dimension may be used to determine the pixel aspect ratio for given HScreenConfigurations.

Returns:

a Dimension object specifying the aspect ratio of the screen

reserveDevice

public boolean reserveDevice(ResourceClient client)

Requests the right to call any method which may otherwise throw an HPermissionDeniedException. If this method returns true this exception will never be thrown until this right is revoked as notified by methods on ResourceClient. The policy by which the platform decides whether or not to grant this right is not defined in this specification.

Note that the word "right" in this context has nothing to do with security. See the description of HPermissionDeniedException.

Once the right to control this device has been granted and not removed in the intervening period further calls to this method re-using the current resource client shall have no effect and return true.

Parameters:

client - a representation of the intended owner of the resource

Returns:

true if the right is granted, otherwise false

releaseDevice

public void releaseDevice()

Release the right to control of this device. If this application doesn't have this right then this method has no effect. It is not specified whether any device configuration set by this application will be removed from display immediately or whether it will remain on display until a subsequent application obtains the device and sets its own configuration. Applications wishing to ensure a configuration they have installed is removed must actively remove it before calling this method.

getClient

public ResourceClient getClient()

Return the last ResourceClient passed to the last successful call to the reserveDevice method of this instance of HScreenDevice, or null if this method has not been called on this instance.

Specified by:

getClient in interface ResourceProxy

Returns:

a representation of the intended owner of the resource or null if none has been set.

addResourceStatusEventListener

public void addResourceStatusEventListener(ResourceStatusListener listener)

Register a listener for events about changes in the state of the ownership of this device. If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.

Specified by:

addResourceStatusEventListener in interface ResourceServer

Parameters:

listener - the object to be informed of state changes

See Also:

HScreenDeviceReleasedEvent, HScreenDeviceReservedEvent

removeResourceStatusEventListener

public void removeResourceStatusEventListener(ResourceStatusListener listener)

Remove a listener for events about changes in the state of the ownership of this device. This method has no effect if the listener specified is not registered.

Specified by:

removeResourceStatusEventListener in interface ResourceServer

Parameters:

listener - the object which is no longer interested

See Also:

HScreenDeviceReleasedEvent, HScreenDeviceReservedEvent