HBackgroundDevice

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 HBackgroundDevice

    java.lang.Object
      org.havi.ui.HScreenDevice
          org.havi.ui.HBackgroundDevice

All Implemented Interfaces:
  ResourceProxy, ResourceServer

    public class HBackgroundDevice

extends HScreenDevice

This class represents the ultimate background of a screen. The background is the very back of the video / graphics composition stack. It can potentially cover the entire area of a screen. Where a device supports multiple applications on screen at the same time (or even a window manager), the background is not constrained by any particular application or window. The right to control the background of a screen is a scarce resource and managed as such.

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
`HBackgroundConfiguration` | `getBestConfiguration(HBackgroundConfigTemplate hbc)` Returns the "best" configuration possible that passes the criteria defined in this `HBackgroundConfigTemplate` or null.
`HBackgroundConfiguration` | `getBestConfiguration(HBackgroundConfigTemplate[] hbcta)` Returns the "best" configuration possible that passes the criteria defined in one of the `HBackgroundConfigTemplate` objects within the specified array or null.
`HBackgroundConfiguration[]` | `getConfigurations()` Returns all of the `HBackgroundConfiguration` objects associated with this `HBackgroundDevice`.
`HBackgroundConfiguration` | `getCurrentConfiguration()` Returns the current `HBackgroundConfiguration` for this `HBackgroundDevice`.
`HBackgroundConfiguration` | `getDefaultConfiguration()` Returns the default `HBackgroundConfiguration` associated with this `HBackgroundDevice` .
`boolean` | `setBackgroundConfiguration(HBackgroundConfiguration hbc)` Set the background configuration for the device.

Methods inherited from class org.havi.ui.HScreenDevice
`addResourceStatusEventListener, addScreenConfigurationListener, addScreenConfigurationListener, getClient, getIDstring, getScreenAspectRatio, releaseDevice, removeResourceStatusEventListener, removeScreenConfigurationListener, reserveDevice`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### getConfigurations

    public HBackgroundConfiguration[] getConfigurations()

  Returns all of the `HBackgroundConfiguration` objects associated with this `HBackgroundDevice`. The set of configurations returned may include ones which are only valid for the device at particular times or when the device is in a particular mode.

  Returns:
    an array of `HBackgroundConfiguration` objects
  See Also:
    `HBackgroundConfiguration`

### getDefaultConfiguration

    public HBackgroundConfiguration getDefaultConfiguration()

  Returns the default `HBackgroundConfiguration` associated with this `HBackgroundDevice` . This (single) default configuration should correspond to some well-behaved settings for the device, such as, a minimal configuration or factory preset settings.

  Returns:
    the default `HBackgroundConfiguration` of this `HBackgroundDevice`
  See Also:
    `HBackgroundConfiguration`

### getBestConfiguration

    public HBackgroundConfiguration getBestConfiguration(HBackgroundConfigTemplate hbc)

  Returns the "best" configuration possible that passes the criteria defined in this `HBackgroundConfigTemplate` or null.

  Equally best in this sense means that the configurations satisfy an equal number of preferences with priorities `PREFERRED` and `PREFERRED_NOT` and all preferences with priorities `REQUIRED` and `REQUIRED_NOT`. If there are such equally best configurations, the one which is returned by this method is an implementation dependent selection from among those which are equally best.

  Configurations are chosen according to the following algorithm, based on the priority as supplied to `setPreference`. Configurations must:

  1. satisfy ALL the preferences whose priority was `REQUIRED`
  2. satisfy NONE of the preferences whose priority was `REQUIRED_NOT`
  3. satisfy as many as possible of the preferences whose priority was `PREFERRED`.
  4. satisfy as few as possible of the preferences whose priority was `PREFERRED_NOT`.
  Preferences whose priority was `DONT_CARE` are ignored.

  This method returns null if no configuration exists that satisfies all `REQUIRED` and `REQUIRED_NOT` priorities.

  Parameters:
    `hbc` - - an `HBackgroundConfigTemplate` object used to obtain a valid `HBackgroundConfiguration`. If this parameter is null the default configuration for the platform shall be returned.
  Returns:
    an `HBackgroundConfiguration` object that passes the criteria defined in the specified `HGraphicsConfigTemplate` or null if no HBackgroundConfiguration passes the criteria.

### getBestConfiguration

    public HBackgroundConfiguration getBestConfiguration(HBackgroundConfigTemplate[] hbcta)

  Returns the "best" configuration possible that passes the criteria defined in one of the `HBackgroundConfigTemplate` objects within the specified array or null. The HBackgroundTemplate objects should be considered for matching in priority order from 0 to (hbcta.length - 1).

  Equally best in this sense means that the configurations satisfy an equal number of preferences with priorities `PREFERRED` and `PREFERRED_NOT` and all preferences with priorities `REQUIRED` and `REQUIRED_NOT`. If there are such equally best configurations, the one which is returned by this method is an implementation dependent selection from among those which are equally best.

  Configurations are chosen according to the following algorithm, based on the priority as supplied to `setPreference`. Configurations must:

  1. satisfy ALL the preferences whose priority was `REQUIRED`
  2. satisfy NONE of the preferences whose priority was `REQUIRED_NOT`
  3. satisfy as many as possible of the preferences whose priority was `PREFERRED`.
  4. satisfy as few as possible of the preferences whose priority was `PREFERRED_NOT`.
  Preferences whose priority was `DONT_CARE` are ignored.

  This method returns null if no configuration exists that satisfies all `REQUIRED` and `REQUIRED_NOT` priorities.

  Parameters:
    `hbcta` - the `HBackgroundConfigTemplate` array used to obtain a valid `HBackgroundConfiguration`.
  Returns:
    an `HBackgroundConfiguration` that passes the criteria defined in one of the `HBackgroundConfigTemplate` objects within the specified array

### getCurrentConfiguration

    public HBackgroundConfiguration getCurrentConfiguration()

  Returns the current `HBackgroundConfiguration` for this `HBackgroundDevice`.

  Returns:
    the current `HBackgroundConfiguration` for this `HBackgroundDevice`.
  See Also:
    `HBackgroundConfiguration`

### setBackgroundConfiguration

    public boolean setBackgroundConfiguration(HBackgroundConfiguration hbc)
                                       throws SecurityException,
                                              HPermissionDeniedException,
                                              HConfigurationException

  Set the background configuration for the device.

  An application is only allowed to call this method after it reserved the device explicitly and subject to the security policy of the platform. Subject to this, the following rules determine whether this method can succeed.

  - If an application tries to select a configuration which is not valid for that device at that time or when the device is in a particular mode then an HConfigurationException shall be thrown.
  - If the application selects a configuration that is not conflicting with the configurations of all the other devices on the same `HScreen` then that configuration is selected.
  - If an application tries to select a configuration that conflicts with a configuration of another device on this `HScreen` which this application cannot control due to platform security policy then this method shall fail with a `SecurityException`.
  - If an application tries to select a configuration that conflicts with a configuration of another device on this `HScreen` which this application cannot control due to another application owning the right to control that device and the platform not giving that right to this application then this method shall fail with an `HPermissionDeniedException`.
  - If an application tries to select a configuration that conflicts with a configuration of another device which this application can control due to either this or no application having reserved the device, then the configuration of the other device is automatically changed. There is no change in the resource ownership of the other device.
  Any modifications made to the configurations of other devices shall be reflected by the API for the devices concerned. The `getCurrentConfiguration` method for those devices shall return the new configuration.

  Applications can prevent or limit changes to configurations of other, not intended, devices by using constants `HScreenConfigTemplate.ZERO_GRAPHICS_IMPACT`, `HScreenConfigTemplate.ZERO_VIDEO_IMPACT` and `HScreenConfigTemplate.ZERO_BACKGROUND_IMPACT` in their configuration templates.

  On successful change to the specified configuration, the device shall fire one or more `HScreenConfigurationEvents` for all listeners that are currently registered (if the criteria for receiving such an event has been satisfied). If the new configuration differs by more than one characteristic from the previous configuration then the device may fire one or more `HScreenConfigurationEvents`. This behavior is implementation specific.

  If an attempt is made to set the identical configuration to that which is current, then no such event(s) shall be fired.

  Parameters:
    `hbc` - the `HBackgroundConfiguration` to which this device should be set.
  Returns:
    A boolean indicating whether the configuration could be applied successfully. If the configuration could not be applied successfully, the configuration after this method may not match the configuration of the device prior to this method being called --- applications should take steps to determine whether a partial change of settings has been made.
  Throws:
    `SecurityException` - if the application does not have sufficient rights to set the configuration for this device.
    `HPermissionDeniedException` - if the application does not currently have the right to set the configuration for this device.
    `HConfigurationException` - if the specified configuration is not valid for this device, or if it conflicts with other devices whose configuration(s) cannot be changed by this application.

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

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