org.havi.ui

Class HContainer

java.lang.Object

java.awt.Component

java.awt.Container

org.havi.ui.HContainer

All Implemented Interfaces:

ImageObserver, MenuContainer, Serializable, TestOpacity, HComponentOrdering, HMatteLayer

public class HContainer
extends 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

Parameter	Description	Default value	Set method	Get 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

Description	Default value	Set 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

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

Constructor and Description
HContainer() Creates an HContainer object.
HContainer(int x, int y, int width, int height) Creates an HContainer object.

Method Summary

Methods

Modifier and Type	Method and Description
Component	addAfter(Component component, Component front) Adds a java.awt.Component to this HContainer directly behind a previously added java.awt.Component.
Component	addBefore(Component component, 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.
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 HContainer.
boolean	popToFront(Component component) Brings the specified java.awt.Component to the "front" of the Z-order in this HContainer.
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 HContainer.
boolean	pushToBack(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, 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, paint, 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, isVisible, 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, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

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.

Overrides:

isDoubleBuffered in class Component

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

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 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 Component addAfter(Component component,
                 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(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(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(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(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(Component move,
                   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(Component move,
                 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()