HScreenDevice

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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
`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
`equals, 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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD