org.dvb.application.inner
Class InnerApplicationContainer

java.lang.Object
  |
  +--java.awt.Component
        |
        +--org.havi.ui.HComponent
              |
              +--org.dvb.application.inner.InnerApplicationContainer
All Implemented Interfaces:
org.havi.ui.HMatteLayer, org.havi.ui.HNavigable, org.havi.ui.HNavigationInputPreferred, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, org.dvb.ui.TestOpacity
Direct Known Subclasses:
HTMLInnerApplicationContainer

public abstract class InnerApplicationContainer
extends org.havi.ui.HComponent
implements org.havi.ui.HNavigable

Represents embedding of an inner application within the user interface of a DVB-J application. The inner application shall be started when the object of this class is constructed. The behaviour of instances of this class when an inner application exits is either implementation or inner application format dependent.

When an instance of this class gains input focus,shall gain the input focus. The meaning of this is specific to the format of the inner application concerned. Inner applications are allowed to consume the events VK_UP, VK_DOWN, VK_LEFT and VK_RIGHT. While this is happening, the HNavigable focus management shall be disabled and the actions defined by setFocusTraversal shall not happen. The mechanisms by which inner applications start and stop consuming these events are specific to the content format of the inner application.

See Also:
Serialized Form

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
protected InnerApplicationContainer(InnerApplication a)
          Construct an instance of this class with a particular inner application as its content.
 
Method Summary
 void addHFocusListener(org.havi.ui.event.HFocusListener l)
          Adds the specified HFocusListener to receive HFocusEvent events sent from this HNavigable.
 void addInnerApplicationListener(InnerApplicationListener l)
          Add a listener for events when the inner application exits.
 org.havi.ui.HSound getGainFocusSound()
          Get the sound associated with the gain focus event.
 org.havi.ui.HSound getLoseFocusSound()
          Get the sound associated with the lost focus event.
 org.havi.ui.HNavigable getMove(int keyCode)
          Provides the HNavigable object that is navigated to when a particular key is pressed.
 int[] getNavigationKeys()
          Retrieve the set of key codes which this component maps to navigation targets.
 boolean isSelected()
          Indicates if this component has focus.
 void processHFocusEvent(org.havi.ui.event.HFocusEvent evt)
          Process an HFocusEvent sent to this HNavigationInputPreferred.
 void removeHFocusListener(org.havi.ui.event.HFocusListener l)
          Removes the specified HFocusListener so that it no longer receives HFocusEvent events from this HNavigable.
 void removeInnerApplicationListener(InnerApplicationListener l)
          Remove a listener for events when the inner application exits.
 void setFocusTraversal(org.havi.ui.HNavigable up, org.havi.ui.HNavigable down, org.havi.ui.HNavigable left, org.havi.ui.HNavigable right)
          Set the focus control for an HNavigable component.
 void setGainFocusSound(org.havi.ui.HSound sound)
          Associate a sound with gaining focus, i.e.
 void setLoseFocusSound(org.havi.ui.HSound sound)
          Associate a sound with losing focus, i.e.
 void setMove(int keyCode, org.havi.ui.HNavigable target)
          Defines the navigation path from the current HNavigable to another HNavigable when a particular key is pressed.
 
Methods inherited from class org.havi.ui.HComponent
getMatte, isDoubleBuffered, isEnabled, isOpaque, processEvent, setEnabled, setMatte
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addKeyListener, addMouseListener, addMouseMotionListener, addNotify, bounds, checkImage, checkImage, contains, contains, createImage, createImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, getAlignmentX, getAlignmentY, getBackground, getBounds, getColorModel, getComponentAt, getComponentAt, getCursor, getFont, getFontMetrics, getForeground, getGraphics, getLocale, getLocation, getLocationOnScreen, getMaximumSize, getMinimumSize, getName, getParent, getPeer, getPreferredSize, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hide, imageUpdate, inside, invalidate, isFocusTraversable, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paint, paintAll, paramString, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, processComponentEvent, processFocusEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, remove, removeComponentListener, removeFocusListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeNotify, repaint, repaint, repaint, repaint, requestFocus, reshape, resize, resize, setBackground, setBounds, setBounds, setCursor, setFont, setForeground, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus, update, validate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

InnerApplicationContainer

protected InnerApplicationContainer(InnerApplication a)
                             throws java.io.IOException
Construct an instance of this class with a particular inner application as its content. This shall not be used by inter-operable applications.
Parameters:
a - the inner application
Throws:
java.io.IOException - if an error occurred while reading the code or data for the inner application
Method Detail

addInnerApplicationListener

public void addInnerApplicationListener(InnerApplicationListener l)
Add a listener for events when the inner application exits.
Parameters:
l - the listener to be notified when the inner application exits

removeInnerApplicationListener

public void removeInnerApplicationListener(InnerApplicationListener l)
Remove a listener for events when the inner application exits.
Parameters:
l - the listener to be removed

setMove

public void setMove(int keyCode,
                    org.havi.ui.HNavigable target)
Defines the navigation path from the current HNavigable to another HNavigable when a particular key is pressed.

Note that setFocusTraversal is equivalent to multiple calls to setMove, where the key codes VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT are used.

Specified by:
setMove in interface org.havi.ui.HNavigable
Parameters:
keyCode - The key code of the pressed key. Any numerical keycode is allowed, but the platform may not be able to generate all keycodes. Application authors should only use keys for which HRcCapabilities.isSupported() or HKeyCapabilities.isSupported() returns true.
target - The target HNavigable object that should be navigated to. If a target is to be removed from a particular navigation path, then null should be specified.

getMove

public org.havi.ui.HNavigable getMove(int keyCode)
Provides the HNavigable object that is navigated to when a particular key is pressed.
Specified by:
getMove in interface org.havi.ui.HNavigable
Parameters:
keyCode - The key code of the pressed key.
Returns:
Returns the HNavigable object, or if no HNavigable is associated with the keyCode then returns null.

setFocusTraversal

public void setFocusTraversal(org.havi.ui.HNavigable up,
                              org.havi.ui.HNavigable down,
                              org.havi.ui.HNavigable left,
                              org.havi.ui.HNavigable right)
Set the focus control for an HNavigable component. Note setFocusTraversal is a convenience function for application programmers where a standard up, down, left and right focus traversal between components is required.

Note setFocusTraversal is equivalent to multiple calls to setMove, where the key codes VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT are used.

Note that this API does not prevent the creation of "isolated" HNavigable components --- authors should endeavor to avoid confusing the user.

Specified by:
setFocusTraversal in interface org.havi.ui.HNavigable
Parameters:
up - The HNavigable component to move to, when the user generates a VK_UP KeyEvent. If there is no HNavigable component to move "up" to, then null should be specified.
down - The HNavigable component to move to, when the user generates a VK_DOWN KeyEvent. If there is no HNavigable component to move "down" to, then null should be specified.
left - The HNavigable component to move to, when the user generates a VK_LEFT KeyEvent. If there is no HNavigable component to move "left" to, then null should be specified.
right - The HNavigable component to move to, when the user generates a VK_RIGHT KeyEvent. If there is no HNavigable component to move "right" to, then null should be specified.

isSelected

public boolean isSelected()
Indicates if this component has focus.
Specified by:
isSelected in interface org.havi.ui.HNavigable
Returns:
true if the component has focus, otherwise returns false.

setGainFocusSound

public void setGainFocusSound(org.havi.ui.HSound sound)
Associate a sound with gaining focus, i.e. when the HNavigable receives a java.awt.event.FocusEvent event of type FOCUS_GAINED. This sound will start to be played when an object implementing this interface gains focus. It is not guaranteed to be played to completion. If the object implementing this interface loses focus before the audio completes playing, the audio will be truncated. Applications wishing to ensure the audio is always played to completion must implement special logic to slow down the focus transitions.

By default, an HNavigable object does not have any gain focus sound associated with it.

Note that the ordering of playing sounds is dependent on the order of the focus lost, gained events.

Specified by:
setGainFocusSound in interface org.havi.ui.HNavigable
Parameters:
sound - the sound to be played, when the component gains focus. If sound content is already set, the original content is replaced. To remove the sound specify a null HSound.

setLoseFocusSound

public void setLoseFocusSound(org.havi.ui.HSound sound)
Associate a sound with losing focus, i.e. when the HNavigable receives a java.awt.event.FocusEvent event of type FOCUS_LOST. This sound will start to be played when an object implementing this interface loses focus. It is not guaranteed to be played to completion. It is implementation dependent whether and when this sound will be truncated by any gain focus sound played by the next object to gain focus.

By default, an HNavigable object does not have any lose focus sound associated with it.

Note that the ordering of playing sounds is dependent on the order of the focus lost, gained events.

Specified by:
setLoseFocusSound in interface org.havi.ui.HNavigable
Parameters:
sound - the sound to be played, when the component loses focus. If sound content is already set, the original content is replaced. To remove the sound specify a null HSound.

getGainFocusSound

public org.havi.ui.HSound getGainFocusSound()
Get the sound associated with the gain focus event.
Specified by:
getGainFocusSound in interface org.havi.ui.HNavigable
Returns:
The sound played when the component gains focus. If no sound is associated with gaining focus, then null shall be returned.

getLoseFocusSound

public org.havi.ui.HSound getLoseFocusSound()
Get the sound associated with the lost focus event.
Specified by:
getLoseFocusSound in interface org.havi.ui.HNavigable
Returns:
The sound played when the component loses focus. If no sound is associated with losing focus, then null shall be returned.

getNavigationKeys

public int[] getNavigationKeys()
Retrieve the set of key codes which this component maps to navigation targets.
Specified by:
getNavigationKeys in interface org.havi.ui.HNavigationInputPreferred
Returns:
an array of key codes, or null if no navigation targets are set on this component.

processHFocusEvent

public void processHFocusEvent(org.havi.ui.event.HFocusEvent evt)
Process an HFocusEvent sent to this HNavigationInputPreferred.
Specified by:
processHFocusEvent in interface org.havi.ui.HNavigationInputPreferred
Parameters:
evt - the HFocusEvent to process.

addHFocusListener

public void addHFocusListener(org.havi.ui.event.HFocusListener l)
Adds the specified HFocusListener to receive HFocusEvent events sent from this HNavigable. 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.
Specified by:
addHFocusListener in interface org.havi.ui.HNavigable
Parameters:
l - the HFocusListener to add

removeHFocusListener

public void removeHFocusListener(org.havi.ui.event.HFocusListener l)
Removes the specified HFocusListener so that it no longer receives HFocusEvent events from this HNavigable. 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.
Specified by:
removeHFocusListener in interface org.havi.ui.HNavigable
Parameters:
l - the HFocusListener to remove