org.havi.ui

Class HScene

java.lang.Object

java.awt.Component

java.awt.Container

org.havi.ui.HScene

All Implemented Interfaces:

ImageObserver, MenuContainer, Serializable, HComponentOrdering

public class HScene
extends Container
implements HComponentOrdering

An HScene is a container representing the displayable area on-screen within which the application can display itself and thus interact with the user.

HScene may be regarded as a simple connection to the window management policy within the device, acting as a "screen resource reservation mechanism" denoting the area within which an application may present components.

Rendering Behavior

By default, HScene does not paint itself on-screen, only its added "child" components and hence its only immediate graphical effect is to "clip" its child components. However, it is possible to request that the entire HScene be painted in the current background color before any drawing takes place, and/or that a background image be drawn before the children are rendered.

An application which sets both of setBackgroundMode(NO_BACKGROUND_FILL) and setImageMode(IMAGE_NONE) shall be responsible for ensuring that all pixels in the HScene are filled with a value which is either opaque or transparent only to video. Such an application cannot make any assumptions about the previous contents of the graphics objects into which it is drawing. For implementations which double-buffer the display of graphics, these existing contents are implementation dependent.

Class Behavior

For all interoperable applications, the HScene is considered the top-level component of the application. No parent component to an HScene should be accessible to applications. Interoperable applications should not use the getParent method in HScene, since results are implementation dependent and valid implementations may generate a run-time error.

Although HScene is a subclass of java.awt.Container, implementations are allowed to insert extra classes in the inheritance tree between HScene and Container. It is allowed that this may result in HScene inheriting additional methods beyond those specified here. This allows platforms with only one native java.awt.Frame to use HScene as specified, whereas platforms with support for multiple java.awt.Frame or java.awt.Window classes can use an HScene class derived from the appropriate class.

HScenes follow the design pattern of the java.awt.Window class. They are not a scarce resource on the platform. On platforms which only support one HScene being visible at one time the current HScene both loses the input focus and is hidden (e.g. iconified) when another application successfully requests the input focus. Two java.awt.event.WindowEvent events, with ids WINDOW_DEACTIVATED and WINDOW_ICONIFIED, shall be generated and sent to the HScene which has lost the focus and the isShowing method for that HScene shall return false.

In terms of delegation, the HScene shall behave like a Window with a native peer implementation, in that it will not appear to delegate any functionality to any parent object. Components which do not specify default characteristics inherit default values transitively from their parent objects. Therefore, the implementation of HScene must have valid defaults defined for all characteristics, e.g. Font, foreground Color, background Color, ColorModel, Cursor and Locale.

Additional Z-order support

HScene extends the java.awt.Container class by providing additional Z-ordering capabilities, which are required since components in the HAVi user-interface are explicitly allowed to overlap each other. The Z-ordering capabilities are defined by the HComponentOrdering interface.

Note that these Z-ordering capabilities (addBefore, addAfter, pop, popInFrontOf, popToFront, push, pushBehind and pushToBack) must be implemented by (implicitly) reordering the child Components within the HScene, so that the standard AWT convention that the Z-order is defined as the order in which Components are added to a given Container is maintained. See the description for HComponentOrdering for more details.

Shortcut Keys

It is an implementation option for HAVi systems to implement shortcut keys by forwarding java.awt.KeyEvent events to the parent HScene of an application. Under these circumstances it is the responsibility of the application designer to ensure that the relevant java.awt.KeyEvent events used for "shortcut keys" are not consumed by any custom components.

Implementations of the standard HAVi UI components which process java.awt.event.KeyEvent events shall not consume any KeyEvent, thus allowing their use as a shortcut key on implementation which rely on KeyEvents being available in this way.

Event Handling

The mechanism by which input events are passed to the HScene and its component hierarchy is not specified.

Note that whether the HScene is visible or not (as determined by the isVisible method) does not guarantee that it has the input focus and is receiving events.

When the application initially gains the input focus, this is indicated by the system sending a java.awt.event.WindowEvent of type WINDOW_ACTIVATED to the HScene. The HScene should request that a child component gain the focus, if one is available. However, the mechanism by which this occurs is intentionally not specified here.

When the entire application loses the user's focus, the system shall notify the HScene that it is no longer receiving events by sending a java.awt.event.WindowEvent of type WINDOW_DEACTIVATED to the HScene.

Acquiring and Displaying HScenes

There is no public constructor for HScene, it is constructed by an HSceneFactory. Only one HScene per HGraphicsDevice can be acquired at any one time for each application.

The application may request that it be made visible by calling the the show method. This method should ensure that the HScene is completely visible to the user, e.g. by expanding an icon, or changing the stacking order between competing overlapping applications.

Making the HScene visible shall not automatically cause it to receive or even request input focus. Input focus can be requested by the application by calling the requestFocus method at any time.

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
Visibility of the HScene	false	setVisible	isVisible
Activity of associated shortcuts	Shortcuts are active	enableShortcuts	isEnableShortcuts
Associated layout manager	null	java.awt.Container#setLayout	java.awt.Container#getLayout
Background image mode	IMAGE_NONE	setRenderMode	getRenderMode

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

Fields

Modifier and Type	Field and Description
static int	BACKGROUND_FILL A constant for use with the setBackgroundMode method which indicates that the HScene should fill its bounding rectangle with its current background color before painting any background image and children.
static int	IMAGE_CENTER A constant for use with setRenderMode which specifies that any background image rendered in this HScene should be centered in the extents of the HScene.
static int	IMAGE_NONE A constant for use with setRenderMode which specifies that a background image should not be rendered in this HScene.
static int	IMAGE_STRETCH A constant for use with setRenderMode which specifies that any background image rendered in this HScene should be stretched to fill the extents of the HScene.
static int	IMAGE_TILE A constant for use with setRenderMode which specifies that any background image rendered in this HScene should be tiled starting from the top left origin of the HScene.
static int	NO_BACKGROUND_FILL A constant for use with the setBackgroundMode method which indicates that the HScene should not fill its bounding rectangle with any color before painting any background image and children.

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	HScene() It is not intended that applications should directly construct HScene objects.

Method Summary

Methods

Modifier and Type	Method and Description
Component	addAfter(Component component, Component front) Adds a java.awt.Component to this HScene directly behind a previously added java.awt.Component.
Component	addBefore(Component component, Component behind) Adds a java.awt.Component to this HScene directly in front of a previously added java.awt.Component.
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 HScene.
void	dispose() Disposes of this HScene.
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 HScene as shortcuts.
Image	getBackgroundImage() Retrieve any image used as a background for this HScene.
int	getBackgroundMode() Get the background mode of this HScene.
Component	getFocusOwner() Returns the child component of this HScene which has focus if and only if this HScene is active.
HEventGroup	getKeyEvents() Return the key codes which this HScene is interested in receiving when it has input focus.
HScreenRectangle	getPixelCoordinatesHScreenRectangle(Rectangle r) Returns an HScreenRectangle which corresponds to the graphics (AWT) pixel area specified by the parameter in this HScene.
int	getRenderMode() Get the rendering mode of any background image associated with this HScene.
HSceneTemplate	getSceneTemplate() Return an HSceneTemplate describing this HScene.
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 HScene object is automatically double buffered.
boolean	isEnableShortcuts() Returns the status of all short cuts that are currently set on the HScene.
boolean	isOpaque() Returns true if the entire HScene area, as given by the java.awt.Component#getBounds method, is fully opaque, i.e.
boolean	isVisible() Determines if the HScene (or more properly its added child components) is Visible.
void	paint(Graphics g) HScene objects override the paint method (defined in java.awt.Component) to paint the added "child" components on top of an optional background color or image.
boolean	pop(Component component) Moves the specified java.awt.Component one component nearer in the Z-order, i.e.
boolean	popInFrontOf(Component move, Component behind) Puts the specified java.awt.Component in front of another java.awt.Component in the Z-order of this HScene.
boolean	popToFront(Component component) Brings the specified java.awt.Component to the "front" of the Z-order in this HScene.
protected void	processWindowEvent(WindowEvent we) Process a java.awt.event.WindowEvent for this HScene.
boolean	push(Component component) Moves the specified java.awt.Component one component further away in the Z-order, i.e.
boolean	pushBehind(Component move, Component front) Puts the specified java.awt.Component behind another java.awt.Component in the Z-order of this HScene.
boolean	pushToBack(Component component) Place the specified java.awt.Component at the "back" of the Z-order in this HScene.
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	setActive(boolean focus) Set whether the HScene is prepared to accept focus.
void	setBackgroundImage(Image image) Set an image which shall be painted in the background of the HScene, 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 HScene.
void	setKeyEvents(HEventGroup keyCodes) Define the key codes which this HScene is interested in receiving when it has input focus.
boolean	setRenderMode(int mode) Set the rendering mode of any background image associated with this HScene.
void	setVisible(boolean visible) Shows or hides this HScene depending on the value of the input parameter visible.
void	show() Shows this HScene, and brings it to the front.

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addNotify, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getInsets, getLayout, getListeners, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, isValidateRoot, layout, list, list, locate, minimumSize, paintComponents, paramString, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, removeNotify, setComponentZOrder, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, setLayout, transferFocusDownCycle, update, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAccessibleContext, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, revalidate, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Field Detail

IMAGE_NONE

public static final int IMAGE_NONE

A constant for use with setRenderMode which specifies that a background image should not be rendered in this HScene.

See Also:

Constant Field Values

IMAGE_STRETCH

public static final int IMAGE_STRETCH

A constant for use with setRenderMode which specifies that any background image rendered in this HScene should be stretched to fill the extents of the HScene.

See Also:

Constant Field Values

IMAGE_CENTER

public static final int IMAGE_CENTER

A constant for use with setRenderMode which specifies that any background image rendered in this HScene should be centered in the extents of the HScene. No tiling or scaling of the image shall be performed.

See Also:

Constant Field Values

IMAGE_TILE

public static final int IMAGE_TILE

A constant for use with setRenderMode which specifies that any background image rendered in this HScene should be tiled starting from the top left origin of the HScene. No scaling of the image shall be performed.

See Also:

Constant Field Values

NO_BACKGROUND_FILL

public static final int NO_BACKGROUND_FILL

A constant for use with the setBackgroundMode method which indicates that the HScene should not fill its bounding rectangle with any color before painting any background image and children.

See Also:

Constant Field Values

BACKGROUND_FILL

public static final int BACKGROUND_FILL

A constant for use with the setBackgroundMode method which indicates that the HScene should fill its bounding rectangle with its current background color before painting any background image and children.

See Also:

Constant Field Values

Constructor Detail

HScene

protected HScene()

It is not intended that applications should directly construct HScene objects. HScene objects should be constructed via the HSceneFactory classes factory methods.

Creates an HScene object. See the class description for details of constructor parameters and default values.

See Also:

HSceneFactory

Method Detail

setVisible

public void setVisible(boolean visible)

Shows or hides this HScene depending on the value of the input parameter visible. An HScene is initially not visible, a call to setVisible should be used to make it visible. This method does not cause the HScene to request the input focus.

Overrides:

setVisible in class Component

Parameters:

visible - If true, makes this HScene visible; otherwise, hides this HScene.

See Also:

show()

isVisible

public boolean isVisible()

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

Overrides:

isVisible in class Component

Returns:

true if the HScene is visible; false otherwise.

paint

public void paint(Graphics g)

HScene objects override the paint method (defined in java.awt.Component) to paint the added "child" components on top of an optional background color or image. The paint behavior is as follows:

1. If the current background mode is BACKGROUND_FILL, the entire HScene is first filled using the current background color.
2. If a background image has been set using the setBackgroundImage method, and the current image rendering mode as set using setRenderMode is not IMAGE_NONE, the specified image is painted. Scaling and tiling are performed according to the render mode set.
3. Finally any children of the HScene are rendered in z-order.

Overrides:

paint in class Container

Parameters:

g - the graphics context to use for painting.

getBackgroundMode

public int getBackgroundMode()

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

Returns:

one of NO_BACKGROUND_FILL or BACKGROUND_FILL.

setBackgroundMode

public void setBackgroundMode(int mode)

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

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.

setBackgroundImage

public void setBackgroundImage(Image image)

Set an image which shall be painted in the background of the HScene, 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)

getBackgroundImage

public Image getBackgroundImage()

Retrieve any image used as a background for this HScene.

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)

setRenderMode

public boolean setRenderMode(int mode)

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

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.

getRenderMode

public int getRenderMode()

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

Returns:

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

isDoubleBuffered

public boolean isDoubleBuffered()

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

Overrides:

isDoubleBuffered in class Component

Returns:

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

isOpaque

public boolean isOpaque()

Returns true if the entire HScene 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.

Overrides:

isOpaque in class Component

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.

addBefore

public Component addBefore(Component component,
                  Component behind)

Adds a java.awt.Component to this HScene directly in front of a previously added java.awt.Component.

If component has already been added to this container, then addBefore moves component in front of behind. If behind and component are the same component which was already added to this container, addBefore does not change the ordering of the components and returns component.

This method affects the Z-order of the java.awt.Component children within the HScene, and may also implicitly change the numeric ordering of those children.

Specified by:

addBefore in interface HComponentOrdering

Parameters:

component - is the java.awt.Component to be added to the HScene

behind - is the java.awt.Component, which component will be placed in front of, i.e. behind will be directly behind the added java.awt.Component

Returns:

If the java.awt.Component is successfully added or was already present, then it will be returned from this call. If the java.awt.Component is not successfully added, e.g. behind is not a java.awt.Component currently added to the HScene, then null will be returned.

This method must be implemented in a thread safe manner.

addAfter

public Component addAfter(Component component,
                 Component front)

Adds a java.awt.Component to this HScene directly behind a previously added java.awt.Component.

If component has already been added to this container, then addAfter moves component behind front. If front and component are the same component which was already added to this container, addAfter does not change the ordering of the components and returns component.

This method affects the Z-order of the java.awt.Component children within the HScene, and may also implicitly change the numeric ordering of those children.

Specified by:

addAfter in interface HComponentOrdering

Parameters:

component - is the java.awt.Component to be added to the HScene

front - is the java.awt.Component, which component will be placed behind, i.e. front will be directly in front of the added java.awt.Component

Returns:

If the java.awt.Component is successfully added or was already present, then it will be returned from this call. If the java.awt.Component is not successfully added, e.g. front is not a java.awt.Component currently added to the HScene, then null will be returned.

This method must be implemented in a thread safe manner.

popToFront

public boolean popToFront(Component component)

Brings the specified java.awt.Component to the "front" of the Z-order in this HScene.

If component is already at the front of the Z-order, the order is unchanged and popToFront returns true.

Specified by:

popToFront in interface HComponentOrdering

Parameters:

component - The java.awt.Component to bring to the "front" of the Z-order of this HScene.

Returns:

returns true on success, false on failure, for example when the java.awt.Component has yet to be added to the HScene. If this method fails, the Z-order is unchanged.

pushToBack

public boolean pushToBack(Component component)

Place the specified java.awt.Component at the "back" of the Z-order in this HScene.

If component is already at the back the Z-order is unchanged and pushToBack returns true.

Specified by:

pushToBack in interface HComponentOrdering

Parameters:

component - The java.awt.Component to place at the "back" of the Z-order of this HScene.

Returns:

returns true on success, false on failure, for example when the java.awt.Component has yet to be added to the HScene. If the component was not added to the container pushToBack does not change the Z-order.

pop

public boolean pop(Component component)

Moves the specified java.awt.Component one component nearer in the Z-order, i.e. swapping it with the java.awt.Component that was directly in front of it.

If component is already at the front of the Z-order, the order is unchanged and pop returns true.

Specified by:

pop in interface HComponentOrdering

Parameters:

component - The java.awt.Component to be moved.

Returns:

returns true on success, false on failure, for example if the java.awt.Component has yet to be added to the HScene.

push

public boolean push(Component component)

Moves the specified java.awt.Component one component further away in the Z-order, i.e. swapping it with the java.awt.Component that was directly behind it.

If component is already at the back of the Z-order, the order is unchanged and push returns true.

Specified by:

push in interface HComponentOrdering

Parameters:

component - The java.awt.Component to be moved.

Returns:

returns true on success, false on failure, for example if the java.awt.Component has yet to be added to the HScene.

popInFrontOf

public boolean popInFrontOf(Component move,
                   Component behind)

Puts the specified java.awt.Component in front of another java.awt.Component in the Z-order of this HScene.

If move and behind are the same component which has been added to the container popInFront does not change the Z-order and returns true.

Specified by:

popInFrontOf in interface HComponentOrdering

Parameters:

move - The java.awt.Component to be moved directly in front of the "behind" Component in the Z-order of this HScene.

behind - The java.awt.Component which the "move" Component should be placed directly in front of.

Returns:

returns true on success, false on failure, for example when either java.awt.Component has yet to be added to the HScene. If this method fails, the Z-order is unchanged.

pushBehind

public boolean pushBehind(Component move,
                 Component front)

Puts the specified java.awt.Component behind another java.awt.Component in the Z-order of this HScene.

If move and front are the same component which has been added to the container pushBehind does not change the Z-order and returns true.

Specified by:

pushBehind in interface HComponentOrdering

Parameters:

move - The java.awt.Component to be moved directly behind the "front" Component in the Z-order of this HScene.

front - The java.awt.Component which the "move" Component should be placed directly behind.

Returns:

returns true on success, false on failure, for example when either java.awt.Component has yet to be added to the HScene.

addWindowListener

public void addWindowListener(WindowListener wl)

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

removeWindowListener

public 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.

processWindowEvent

protected void processWindowEvent(WindowEvent we)

Process a java.awt.event.WindowEvent for this HScene.

Parameters:

we - the java.awt.event.WindowEvent to be processed.

getFocusOwner

public Component getFocusOwner()

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

Returns:

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

show

public void show()

Shows this HScene, and brings it to the front.

If this HScene is not yet visible, show makes it visible. If this HScene is already visible, then this method brings it to the front. This method does not cause the HScene to request the input focus.

Overrides:

show in class Component

See Also:

setVisible(boolean)

dispose

public void dispose()

Disposes of this HScene. This method must be called at application exit to release the resources that are used for the HScene. Calling this method will be equivalent to calling HSceneFactory.dispose. Calling this method on an HScene that was already disposed will have no effect.

addShortcut

public 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.

removeShortcut

public 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

getShortcutComponent

public 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 HScene, null otherwise.

enableShortcuts

public 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 HScene 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.

isEnableShortcuts

public boolean isEnableShortcuts()

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

Returns:

true if shortcuts are enabled, false otherwise.

See Also:

enableShortcuts(boolean)

getShortcutKeycode

public 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.

getAllShortcutKeycodes

public int[] getAllShortcutKeycodes()

Returns all keycodes added in the HScene as shortcuts.

Returns:

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

getPixelCoordinatesHScreenRectangle

public HScreenRectangle getPixelCoordinatesHScreenRectangle(Rectangle r)

Returns an HScreenRectangle which corresponds to the graphics (AWT) pixel area specified by the parameter in this HScene. (i.e. within the HScene's coordinate space).

Parameters:

r - the AWT pixel area within this HScene (i.e. within the HScene's coordinate space), specified as an java.awt.Rectangle.

Returns:

an HScreenRectangle which corresponds to the graphics (AWT) pixel area specified by the parameter in this HScene (i.e. within the HScene's coordinate space).

getSceneTemplate

public HSceneTemplate getSceneTemplate()

Return an HSceneTemplate describing this HScene. This template can be queried in order to obtain the size & position of the HScene in screen coordinates and the display device used for the HScene, etc.

Returns:

an HSceneTemplate describing of the HScene.

setActive

public void setActive(boolean focus)

Set whether the HScene is prepared to accept focus. Changing this from false to true shall not imply requesting focus for the HScene. Changing this from true to false shall result in an HScene with focus losing it. If focus is lost in this way, it shall be notified by sending a java.awt.event.WindowEvent of type WINDOW_DEACTIVATED to the HScene. Calling the requestFocus method on an HScene where the last value passed to setActive was false shall have no effect. HScenes where this method has never been called are always prepared to accept focus and hence applications which are always prepared to accept focus never need call this method.

Parameters:

focus - true if the HScene can accept focus otherwise false

setKeyEvents

public void setKeyEvents(HEventGroup keyCodes)

Define the key codes which this HScene is interested in receiving when it has input focus. The key codes shall be defined in terms of the key code constants for HRcEvent and its parent classes. Applications which omit a key code known to be supported by a particular platform make that key code available to other applications but all other mechanisms and semantics involved in this are outside the scope of this specification. For example, an application omitting the number keys from the set which it is interested in, would make those available to other applications, for instance a television channel surfing application.

Applications may not receive all the keys in which they have declared an interest for a number of reasons.

• Because the system is incapable of generating the key concerned
• Because the key concerned is never available to applications due to some platform policy.
• Because another application has the successfully obtained the right to exclusively receive a particular key via some mechanism outside the scope of this specification.

The default set of key codes is a subset of the key codes for which HRcCapabilities.isSupported(keyCode) returns true as modified by platform policy. It represents the maximum set of key codes which an application can receive. Hence applications which never wish to receive fewer keys than this need not use this method.

Defining a key code in this method shall not result in a "virtual" keyboard being displayed. It is implementation dependent whether this method has an effect on key events generated from virtual keyboards where implementations provide these.

Listing a key code more than once in the input to this method shall have the same effect as listing it once. Unknown key codes shall be ignored and shall not cause an error condition. Applications may still receive key codes in which they have not declared an interest however this is platform dependent.

Parameters:

keyCodes - the key codes which this HScene is interested in receiving

getKeyEvents

public HEventGroup getKeyEvents()

Return the key codes which this HScene is interested in receiving when it has input focus. If the method setKeyEvents has been previously called for this HScene instance then the return value of this method shall be the last input to that method. Otherwise the return value shall be the default set of key codes.

Returns:

the key codes which this HScene is interested in receiving