org.dvb.application.inner

Interface DVBScene

public interface DVBScene

Represents various features which are common to the top level Container of applications whether running stand-alone or embedded in a DVB-HTML application. All integer constants used in this class are those defined in the class org.havi.ui.HScene.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	addShortcut(int keyCode, HActionable comp) Adds a shortcut key to action the specified HActionable.
void	addWindowListener(WindowListener wl) Add a listener to receive any java.awt.event.WindowEvents sent from this DVBScene.
void	enableShortcuts(boolean enable) Enables or disables all short cuts that are currently set on the Scene.
int[]	getAllShortcutKeycodes() Returns all keycodes added in the DVBScene as shortcuts.
Image	getBackgroundImage() Retrieve any image used as a background for this DVBScene.
int	getBackgroundMode() Get the background mode of this DVBScene.
Component	getFocusOwner() Returns the child component of this DVBScene which has focus if and only if this DVBScene is active.
int	getRenderMode() Get the rendering mode of any background image associated with this DVBScene.
HActionable	getShortcutComponent(int keyCode) Retrieve the HActionable associated with the specified shortcut key.
int	getShortcutKeycode(HActionable comp) Returns the keycode associated with the specified HActionable component.
boolean	isDoubleBuffered() Returns true if all the drawing done during the update and paint methods for this specific DVBScene object is automatically double buffered.
boolean	isEnableShortcuts() Returns the status of all short cuts that are currently set on the DVBScene.
boolean	isOpaque() Returns true if the entire DVBScene area, as given by the java.awt.Component#getBounds method, is fully opaque, i.e.
boolean	isVisible() Determines if the DVBScene (or more properly its added child components) is Visible.
void	removeShortcut(int keyCode) Removes the specified short-cut key.
void	removeWindowListener(WindowListener wl) Remove a listener so that it no longer receives any java.awt.event.WindowEvents.
void	setBackgroundImage(Image image) Set an image which shall be painted in the background of the DVBScene, after the background has been drawn according to the current mode set with setBackgroundMode, but before any children are drawn.
void	setBackgroundMode(int mode) Set the background mode of this DVBScene.
boolean	setRenderMode(int mode) Set the rendering mode of any background image associated with this DVBScene.

Method Detail

addWindowListener

void addWindowListener(WindowListener wl)

Add a listener to receive any java.awt.event.WindowEvents sent from this DVBScene. 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:

wl - The java.awt.event.WindowListener to be notified of any java.awt.event.WindowEvents.

enableShortcuts

void enableShortcuts(boolean enable)

Enables or disables all short cuts that are currently set on the Scene. To enable or disable a single shortcut use addShortcut or removeShortcut.

Note enableShortcuts(false) does not remove existing added DVBScene shortcuts - they are merely disabled and may be subsequently re-enabled with enableShortcuts(true).

Parameters:

enable - a value of true indicates all shortcuts are to be enabled, and a value of false indicates all shortcuts are to be disabled.

getAllShortcutKeycodes

int[] getAllShortcutKeycodes()

Returns all keycodes added in the DVBScene as shortcuts.

Returns:

all keycodes added in the DVBScene as shortcuts, there are no ordering guarantees.

getBackgroundImage

Image getBackgroundImage()

Retrieve any image used as a background for this DVBScene.

Returns:

an image used as a background, or null if no image is set. Note that depending on the current render mode any image set may not actually be rendered.

See Also:

setRenderMode(int)

getBackgroundMode

int getBackgroundMode()

Get the background mode of this DVBScene. The return value specifies whether the paint method should draw the background (i.e. a rectangle filling the bounds of the DVBScene).

Returns:

one of NO_BACKGROUND_FILL or BACKGROUND_FILL.

getFocusOwner

Component getFocusOwner()

Returns the child component of this DVBScene which has focus if and only if this DVBScene is active.

Returns:

the component with focus, or null if no children have focus assigned to them.

getRenderMode

int getRenderMode()

Get the rendering mode of any background image associated with this DVBScene.

Returns:

the rendering mode, one of IMAGE_NONE, IMAGE_STRETCH, IMAGE_CENTER or IMAGE_TILE.

getShortcutComponent

HActionable getShortcutComponent(int keyCode)

Retrieve the HActionable associated with the specified shortcut key.

Parameters:

keyCode - the shortcut key code to be queried for an associated HActionable.

Returns:

the HActionable associated with the specified key if keyCode is a valid shortcut key for this DVBScene, null otherwise.

getShortcutKeycode

int getShortcutKeycode(HActionable comp)

Returns the keycode associated with the specified HActionable component.

Parameters:

comp - the HActionable to return the keycode that it is associated with.

Returns:

the keycode associated with the specified HActionable component, if it is currently a valid shortcut "target", otherwise return java.awt.event.KeyEvent#VK_UNDEFINED.

isDoubleBuffered

boolean isDoubleBuffered()

Returns true if all the drawing done during the update and paint methods for this specific DVBScene object is automatically double buffered.

Returns:

true if all the drawing done during the update and paint methods for this specific DVBScene object is automatically double buffered, or false if drawing is not double buffered. The default value for the double buffering setting is platform-specific.

isEnableShortcuts

boolean isEnableShortcuts()

Returns the status of all short cuts that are currently set on the DVBScene.

Returns:

true if shortcuts are enabled, false otherwise.

See Also:

enableShortcuts(boolean)

isOpaque

boolean isOpaque()

Returns true if the entire DVBScene area, as given by the java.awt.Component#getBounds method, is fully opaque, i.e. its paint method (or surrogate methods) guarantee that all pixels are painted in an opaque Color.

By default, the return value depends on the value of the current background mode, as set by the setBackgroundMode method. The return value should be overridden by subclasses that can guarantee full opacity. The consequences of an invalid overridden value are implementation specific.

Returns:

true if all the pixels within the area given by the java.awt.Component#getBounds method are fully opaque, i.e. its paint method (or surrogate methods) guarantee that all pixels are painted in an opaque Color, otherwise false.

isVisible

boolean isVisible()

Determines if the DVBScene (or more properly its added child components) is Visible. Initially an DVBScene is invisible.

Returns:

true if the DVBScene is visible; false otherwise.

removeShortcut

void removeShortcut(int keyCode)

Removes the specified short-cut key. if the specified short-cut key is not registered, the method has no effect

Parameters:

keyCode - The keycode that represents the short cut

removeWindowListener

void removeWindowListener(WindowListener wl)

Remove a listener so that it no longer receives any java.awt.event.WindowEvents. 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:

wl - The java.awt.event.WindowListener to be removed from notification of any java.awt.event.WindowEvents.

setBackgroundImage

void setBackgroundImage(Image image)

Set an image which shall be painted in the background of the DVBScene, after the background has been drawn according to the current mode set with setBackgroundMode, but before any children are drawn. The image is rendered according to the current render mode set with setRenderMode.

Note that the use of a background image in this way may affect the return value of the isOpaque method, depending on the image and the current rendering mode.

Parameters:

image - the image to be used as a background. If this parameter is null any current image is removed. Note that depending on the current render mode any image set may not actually be rendered.

See Also:

setRenderMode(int)

setBackgroundMode

void setBackgroundMode(int mode)

Set the background mode of this DVBScene. The value specifies whether the paint method should draw the background (i.e. a rectangle filling the bounds of the DVBScene).

Note that the background mode will affect the return value of the isOpaque method, depending on the value of the mode parameter. A fill mode of BACKGROUND_FILL implies that isOpaque must return true.

Parameters:

mode - one of NO_BACKGROUND_FILL or BACKGROUND_FILL. If mode is not a valid value, an IllegalArgumentException will be thrown.

setRenderMode

boolean setRenderMode(int mode)

Set the rendering mode of any background image associated with this DVBScene.

Note that the minimum requirement is to support only the IMAGE_NONE mode. Support of the other modes is platform and implementation specific.

Parameters:

mode - the rendering mode, one of IMAGE_NONE, IMAGE_STRETCH, IMAGE_CENTER or IMAGE_TILE.

Returns:

true if the mode was set successfully, false if the mode is not supported by the platform.

addShortcut

boolean addShortcut(int keyCode,
                  HActionable comp)

Adds a shortcut key to action the specified HActionable. Generating the defined java.awt.KeyEvent or HRcEvent keycode causes the specified component to become actioned --- potentially any keyCode may have a shortcut associated with it. The shortcut will only be added if the HActionable component is a child component in the container hierarchy of which the HScene is the root container. If this is not the case this method shall return false.

Note that a maximum of one HActionable may be associated with a given keyCode. An HActionable can have at most one associated shortcut keycode. Calling addShortcut repeatedly with the same HActionable will result in the previous short cut being removed. A short cut can be set on an invisible HActionable and therefore it is possible to provide short-cuts that have no user representation.

If the relevant keyCode is received by the HScene, then the HActionable will be actioned by the HScene sending it an ACTION_PERFORMED. Note that it is the responsibility of the application to ensure that the keyCode used is included in the set registered with the setKeyEvents method and is one which the platform can generate, i.e. where the method HRcCapabilities.isSupported() returns true.

Parameters:

keyCode - the keycode that represents the short cut. If keycode is java.awt.event.KeyEvent#VK_UNDEFINED, then the shortcut will not be added, any existing shortcut for this component will not be changed and this method shall return false.

comp - The actionable component that will be actioned.

Returns:

true if the shortcut was added, false otherwise.