org.havi.ui
Class HGraphicsDevice

java.lang.Object
  extended by org.havi.ui.HScreenDevice
      extended by org.havi.ui.HGraphicsDevice
All Implemented Interfaces:
ResourceProxy, ResourceServer
Direct Known Subclasses:
HEmulatedGraphicsDevice

public class HGraphicsDevice
extends HScreenDevice

The HGraphicsDevice class describes the raster graphics devices that are available for a particular HScreen. Each HGraphicsDevice has one or more HGraphicsConfiguration objects associated with it. These objects specify the different configurations (settings) in which the HGraphicsDevice can be used.


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.

See Also:
HGraphicsConfiguration, HScreenDevice, HScreen

Method Summary
 HGraphicsConfiguration getBestConfiguration(HGraphicsConfigTemplate hgct)
          The getBestConfiguration method attempts to return an HGraphicsConfiguration that matches the specified HGraphicsConfigTemplate.
 HGraphicsConfiguration getBestConfiguration(HGraphicsConfigTemplate[] hgcta)
          The getBestConfiguration method attempts to return an HGraphicsConfiguration that matches the specified HGraphicsConfigTemplate objects within the specified array.
 HGraphicsConfiguration[] getConfigurations()
          Returns all of the HGraphicsConfiguration objects associated with this HGraphicsDevice.
 HGraphicsConfiguration getCurrentConfiguration()
          Returns the current HGraphicsConfiguration for this HGraphicsDevice.
 HGraphicsConfiguration getDefaultConfiguration()
          Returns the default HGraphicsConfiguration associated with this HGraphicsDevice.
 boolean setGraphicsConfiguration(HGraphicsConfiguration hgc)
          Set the graphics 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 HGraphicsConfiguration[] getConfigurations()
Returns all of the HGraphicsConfiguration objects associated with this HGraphicsDevice. 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 HGraphicsConfiguration objects that are associated with this HGraphicsDevice. The class of the objects returned can also be a class inheriting from HGraphicsConfiguration (e.g. HEmulatedGraphicsConfiguration).
See Also:
HGraphicsConfiguration

getDefaultConfiguration

public HGraphicsConfiguration getDefaultConfiguration()
Returns the default HGraphicsConfiguration associated with this HGraphicsDevice. 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 HGraphicsConfiguration of this HGraphicsDevice. The class of the object returned can also be a class inheriting from HGraphicsConfiguration (e.g. HEmulatedGraphicsConfiguration).

getBestConfiguration

public HGraphicsConfiguration getBestConfiguration(HGraphicsConfigTemplate hgct)
The getBestConfiguration method attempts to return an HGraphicsConfiguration that matches the specified HGraphicsConfigTemplate. If this is not possible it will attempt to construct an HEmulatedGraphicsConfiguration where the emulated configuration best matches this HGraphicsConfigTemplate. If this is not possible, null is returned. Note that the algorithm used for this behavior, and the extent and behavior of HEmulatedGraphicsConfiguration are platform specific.

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:
hgct - an HGraphicsConfigTemplate object used to obtain a valid HGraphicsConfiguration. If this parameter is null the default configuration for the platform shall be returned.
Returns:
an HGraphicsConfiguration that passes the criteria defined in the specified HGraphicsConfigTemplate or null if no HGraphicsConfiguration or HEmulatedGraphicsConfiguration passes the criteria.

getBestConfiguration

public HGraphicsConfiguration getBestConfiguration(HGraphicsConfigTemplate[] hgcta)
The getBestConfiguration method attempts to return an HGraphicsConfiguration that matches the specified HGraphicsConfigTemplate objects within the specified array. The HGraphicsTemplate objects should be considered for matching in priority order from 0 to (hgcta.length - 1). If this is not possible, it will attempt to construct an HEmulatedGraphicsConfiguration where the emulated configuration best matches the specified HGraphicsConfigTemplate objects. If this is not possible, null is returned.

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:
hgcta - the HGraphicsConfigTemplate array used to obtain a valid HGraphicsConfiguration.
Returns:
an HGraphicsConfiguration that passes the criteria defined in one of the HGraphicsConfigTemplate objects within the specified array. The class of the object returned can also be a class inheriting from HGraphicsConfiguration (e.g. HEmulatedGraphicsConfiguration).

getCurrentConfiguration

public HGraphicsConfiguration getCurrentConfiguration()
Returns the current HGraphicsConfiguration for this HGraphicsDevice.

Returns:
the current HGraphicsConfiguration for this HGraphicsDevice. The class of the object returned can also be a class inheriting from HGraphicsConfiguration (e.g. HEmulatedGraphicsConfiguration).
See Also:
HGraphicsConfiguration

setGraphicsConfiguration

public boolean setGraphicsConfiguration(HGraphicsConfiguration hgc)
                                 throws java.lang.SecurityException,
                                        HPermissionDeniedException,
                                        HConfigurationException
Set the graphics 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.

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. The first one will cause no changes to already running graphical applications. This means that no changes may be applied to the graphics device. Similarly the second constant will result in no changes to the video 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.

On successful change to the specified configuration, the device shall fire one or more HScreenConfigurationEvent 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 HScreenConfigurationEvent. 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:
hgc - the HGraphicsConfiguration 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:
java.lang.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.