HScene

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 HScene

    java.lang.Object
      java.awt.Component
          java.awt.Container
              org.havi.ui.HScene

All Implemented Interfaces:
  ImageObserver, 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

Field Summary
`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`

Method Summary
`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`.
`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, areFocusTraversalKeysSet, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getInsets, getLayout, getMaximumSize, getMinimumSize, getPreferredSize, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicySet, list, list, paintComponents, print, printComponents, remove, remove, removeAll, removeContainerListener, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setFont, setLayout, transferFocusBackward, transferFocusDownCycle, update, validate`

Methods inherited from class java.awt.Component
`addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addNotify, addPropertyChangeListener, checkImage, checkImage, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, dispatchEvent, enableInputMethods, getBackground, getBounds, getBounds, getColorModel, getComponentListeners, getCursor, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, hasFocus, imageUpdate, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isShowing, isValid, list, list, list, paintAll, prepareImage, prepareImage, printAll, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removeNotify, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocusInWindow, setBackground, setBounds, setBounds, setCursor, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, toString, transferFocus, transferFocusUpCycle`

Methods inherited from class java.lang.Object
`equals, 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

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.
  See Also:
    `Component.setVisible(boolean)`

### 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.
  See Also:
    `Component.update(Graphics)`

### 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`.
  See Also:
    `Component.isLightweight()`

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

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

  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

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

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