org.havi.ui
Class HContainer

java.lang.Object
  extended byjava.awt.Component
      extended byjava.awt.Container
          extended byorg.havi.ui.HContainer
All Implemented Interfaces:
HComponentOrdering, HMatteLayer, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, TestOpacity

public class HContainer
extends java.awt.Container
implements HMatteLayer, HComponentOrdering, TestOpacity

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

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 HContainer, 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. For example, one implementation of popToFront might be to make the specified Component become the first Component added to the parent Container by removing all Components from that Container, adding the specified Container first, and then adding the remaining Components in their current relative order to that Container.


The parameters to the constructors are as follows, in cases where parameters are not used, then the constructor should use the default values.

Default parameter values exposed in the constructors

ParameterDescriptionDefault value Set methodGet method
x x-coordinate of top left hand corner of this component in pixels, relative to its parent container (subject to layout management). --- java.awt.Component#setBounds java.awt.Component#getBounds
y y-coordinate of top left hand corner of this component in pixels, relative to its parent container (subject to layout management). --- java.awt.Component#setBounds java.awt.Component#getBounds
width width of this component in pixels (subject to layout management). --- java.awt.Component#setBounds java.awt.Component#getBounds
height height of this component in pixels (subject to layout management). --- java.awt.Component#setBounds java.awt.Component#getBounds

Default parameter values not exposed in the constructors

DescriptionDefault valueSet method Get method
Associated matte (HMatte). none (i.e. getMatte() returns null) setMatte getMatte
LayoutManager null (in contrast to java.awt.Container) java.awt.Container#setLayout java.awt.Container#getLayout

See Also:
Serialized Form

Field Summary
 
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
HContainer()
          Creates an HContainer object.
HContainer(int x, int y, int width, int height)
          Creates an HContainer object.
 
Method Summary
 java.awt.Component addAfter(java.awt.Component component, java.awt.Component front)
          Adds a java.awt.Component to this HContainer directly behind a previously added java.awt.Component.
 java.awt.Component addBefore(java.awt.Component component, java.awt.Component behind)
          Adds a java.awt.Component to this HContainer directly in front of a previously added java.awt.Component.
 HMatte getMatte()
          Get any HMatte currently associated with this component.
 void group()
          Groups the HContainer and its components.
 boolean isDoubleBuffered()
          Returns true if all the drawing done during the update and paint methods for this specific HContainer object is automatically double buffered.
 boolean isGrouped()
          Tests whether the HContainer and its components are grouped.
 boolean isOpaque()
          Returns true if the entire HContainer 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.
 boolean pop(java.awt.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.
 boolean popInFrontOf(java.awt.Component move, java.awt.Component behind)
          Puts the specified java.awt.Component in front of another java.awt.Component in the Z-order of this HContainer.
 boolean popToFront(java.awt.Component component)
          Brings the specified java.awt.Component to the "front" of the Z-order in this HContainer.
 boolean push(java.awt.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.
 boolean pushBehind(java.awt.Component move, java.awt.Component front)
          Puts the specified java.awt.Component behind another java.awt.Component in the Z-order of this HContainer.
 boolean pushToBack(java.awt.Component component)
          Place the specified java.awt.Component at the "back" of the Z-order in this HContainer.
 void setMatte(HMatte m)
          Applies an HMatte to this component, for matte compositing.
 void ungroup()
          Ungroups the HContainer and its components.
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addNotify, countComponents, deliverEvent, doLayout, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getInsets, getLayout, getMaximumSize, getMinimumSize, getPreferredSize, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paint, paintComponents, paramString, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, removeNotify, setCursor, setLayout, update, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addKeyListener, addMouseListener, addMouseMotionListener, bounds, checkImage, checkImage, contains, contains, createImage, createImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, getBackground, getBounds, getColorModel, getCursor, getFont, getFontMetrics, getForeground, getGraphics, getLocale, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hide, imageUpdate, inside, isEnabled, isFocusTraversable, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, remove, removeComponentListener, removeFocusListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, repaint, repaint, repaint, repaint, requestFocus, reshape, resize, resize, setBackground, setBounds, setBounds, setEnabled, setFont, setForeground, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

HContainer

public HContainer()
Creates an HContainer object. See the class description for details of constructor parameters and default values.


HContainer

public HContainer(int x,
                  int y,
                  int width,
                  int height)
Creates an HContainer object. See the class description for details of constructor parameters and default values.

Method Detail

setMatte

public void setMatte(HMatte m)
              throws HMatteException
Applies an HMatte to this component, for matte compositing. Any existing animated matte must be stopped before this method is called or an HMatteException will be thrown.

Specified by:
setMatte in interface HMatteLayer
Parameters:
m - The HMatte to be applied to this component -- note that only one matte may be associated with the component, thus any previous matte will be replaced. If m is null, then any matte associated with the component is removed and further calls to getMatte() shall return null. The component shall behave as if it had a fully opaque HFlatMatte associated with it (i.e an HFlatMatte with the default value of 1.0.)
Throws:
HMatteException - if the HMatte cannot be associated with the component. This can occur:
  • if the specific matte type is not supported
  • if the platform does not support any matte type
  • if the component is associated with an already running HFlatEffectMatte or HImageEffectMatte. The exception is thrown even if m is null.
See Also:
HMatte

getMatte

public HMatte getMatte()
Get any HMatte currently associated with this component.

Specified by:
getMatte in interface HMatteLayer
Returns:
the HMatte currently associated with this component or null if there is no associated matte.

isDoubleBuffered

public boolean isDoubleBuffered()
Returns true if all the drawing done during the update and paint methods for this specific HContainer object is automatically double buffered.

Returns:
true if all the drawing done during the update and paint methods for this specific HComponent 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 HContainer 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 is false. The return value should be overridden by subclasses that can guarantee full opacity. The consequences of an invalid overridden value are implementation specific.

Specified by:
isOpaque in interface TestOpacity
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 java.awt.Component addBefore(java.awt.Component component,
                                    java.awt.Component behind)
Adds a java.awt.Component to this HContainer 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 HContainer, 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 HContainer
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 HContainer, then null will be returned.

This method must be implemented in a thread safe manner.


addAfter

public java.awt.Component addAfter(java.awt.Component component,
                                   java.awt.Component front)
Adds a java.awt.Component to this HContainer 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 HContainer, 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 HContainer
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 HContainer, then null will be returned.

This method must be implemented in a thread safe manner.


popToFront

public boolean popToFront(java.awt.Component component)
Brings the specified java.awt.Component to the "front" of the Z-order in this HContainer.

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 HContainer.
Returns:
returns true on success, false on failure, for example when the java.awt.Component has yet to be added to the HContainer. If this method fails, the Z-order is unchanged.

pushToBack

public boolean pushToBack(java.awt.Component component)
Place the specified java.awt.Component at the "back" of the Z-order in this HContainer.

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 HContainer.
Returns:
returns true on success, false on failure, for example when the java.awt.Component has yet to be added to the HContainer. If the component was not added to the container pushToBack does not change the Z-order.

pop

public boolean pop(java.awt.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 HContainer.

push

public boolean push(java.awt.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 HContainer.

popInFrontOf

public boolean popInFrontOf(java.awt.Component move,
                            java.awt.Component behind)
Puts the specified java.awt.Component in front of another java.awt.Component in the Z-order of this HContainer.

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 HContainer.
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 HContainer. If this method fails, the Z-order is unchanged.

pushBehind

public boolean pushBehind(java.awt.Component move,
                          java.awt.Component front)
Puts the specified java.awt.Component behind another java.awt.Component in the Z-order of this HContainer.

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

group

public void group()
Groups the HContainer and its components. If the container is already grouped this method has no effect

See Also:
ungroup(), isGrouped()

ungroup

public void ungroup()
Ungroups the HContainer and its components. If the container is already ungrouped, this method has no effect.

See Also:
group(), isGrouped()

isGrouped

public boolean isGrouped()
Tests whether the HContainer and its components are grouped. By default the container is not grouped with its components.

Returns:
returns true if the HContainer and its components are grouped, false otherwise.
See Also:
group(), ungroup()