org.havi.ui.HContainer Maven / Gradle / Ivy
package org.havi.ui;
/*
* Copyright 2000-2003 by HAVi, Inc. Java is a trademark of Sun
* Microsystems, Inc. All rights reserved.
*/
import java.awt.Color;
import java.awt.Image;
/**
The {@link org.havi.ui.HContainer HContainer} class extends the
java.awt.Container class by implementing the {@link
org.havi.ui.HMatteLayer 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 {@link org.havi.ui.HContainer
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 ({@link org.havi.ui.HMatte HMatte}).
none (i.e. getMatte() returns null)
{@link org.havi.ui.HComponent#setMatte setMatte}
{@link org.havi.ui.HComponent#getMatte getMatte}
LayoutManager
null (in contrast to java.awt.Container)java.awt.Container#setLayout
java.awt.Container#getLayout
*/
public class HContainer
extends java.awt.Container
implements HMatteLayer, HComponentOrdering, org.dvb.ui.TestOpacity
{
/**
* Creates an HContainer object. See the class description for
* details of constructor parameters and default values.
*/
public HContainer()
{
}
/**
* Creates an HContainer object. See the class description for
* details of constructor parameters and default values.
*/
public HContainer(int x, int y, int width, int height)
{
}
/**
* Applies an {@link org.havi.ui.HMatte 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.
*
* @param m The {@link org.havi.ui.HMatte 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 {@link
* org.havi.ui.HFlatMatte HFlatMatte} associated with it (i.e an
* HFlatMatte with the default value of 1.0.)
* @exception HMatteException if the {@link org.havi.ui.HMatte
* 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
* {@link org.havi.ui.HFlatEffectMatte HFlatEffectMatte} or {@link
* org.havi.ui.HImageEffectMatte HImageEffectMatte}. The exception
* is thrown even if m is null.
*
* @see HMatte
*/
public void setMatte(HMatte m) throws HMatteException
{
return;
}
/**
* Get any {@link org.havi.ui.HMatte HMatte} currently associated
* with this component.
*
* @return the {@link org.havi.ui.HMatte HMatte} currently
* associated with this component or null if there is no
* associated matte.
*/
public HMatte getMatte()
{
return(null);
}
/**
* Returns true if all the drawing done during the update and
* paint methods for this specific {@link org.havi.ui.HContainer
* HContainer} object is automatically double buffered.
*
* @return true if all the drawing done during the
* update and paint methods for this specific {@link
* org.havi.ui.HComponent 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.
*/
public boolean isDoubleBuffered()
{
return(false);
}
/**
* Returns true if the entire {@link org.havi.ui.HContainer
* 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.
*
* @return 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.
*/
public boolean isOpaque()
{
return (false);
}
/**
* Adds a java.awt.Component to this {@link
* org.havi.ui.HContainer 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 {@link
* org.havi.ui.HContainer HContainer}, and may also implicitly
* change the numeric ordering of those children.
*
* @param component is the java.awt.Component to be
* added to the {@link org.havi.ui.HContainer HContainer}
* @param 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
* @return 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 {@link
* org.havi.ui.HContainer HContainer}, then null will
* be returned.
This method must be implemented in a thread
* safe manner.
*/
public java.awt.Component addBefore(java.awt.Component component, java.awt.Component behind)
{
return(null);
}
/**
* Adds a java.awt.Component to this {@link
* org.havi.ui.HContainer 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 {@link
* org.havi.ui.HContainer HContainer}, and may also implicitly
* change the numeric ordering of those children.
*
* @param component is the java.awt.Component to be
* added to the {@link org.havi.ui.HContainer HContainer}
* @param 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
* @return 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 {@link org.havi.ui.HContainer HContainer}, then
* null will be returned.
*
* This method must be implemented in a thread safe manner.
*/
public java.awt.Component addAfter(java.awt.Component component, java.awt.Component front)
{
return(null);
}
/**
* Brings the specified java.awt.Component to the
* "front" of the Z-order in this {@link
* org.havi.ui.HContainer HContainer}.
*
* If component is already at the front of the
* Z-order, the order is unchanged and popToFront
* returns true.
*
* @param component The java.awt.Component to bring to the
* "front" of the Z-order of this {@link org.havi.ui.HContainer
* HContainer}.
*
* @return returns true on success,
* false on failure, for example when the
* java.awt.Component has yet to be added to the
* {@link org.havi.ui.HContainer HContainer}. If this method
* fails, the Z-order is unchanged.
*/
public boolean popToFront(java.awt.Component component)
{
return(true);
}
/**
* Place the specified java.awt.Component at the
* "back" of the Z-order in this {@link
* org.havi.ui.HContainer HContainer}.
*
* If component is already at the back the Z-order is
* unchanged and pushToBack returns true.
*
* @param component The java.awt.Component to place
* at the "back" of the Z-order of this {@link org.havi.ui.HContainer
* HContainer}.
* @return returns true on success,
* false on failure, for example when the
* java.awt.Component has yet to be added to the
* {@link org.havi.ui.HContainer HContainer}. If the component was
* not added to the container pushToBack does not change the
* Z-order.
*/
public boolean pushToBack(java.awt.Component component)
{
return(true);
}
/**
* 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.
*
* @param component The java.awt.Component to be moved.
* @return returns true on success, false on failure, for example
* if the java.awt.Component has yet to be added to
* the {@link org.havi.ui.HContainer HContainer}.
*/
public boolean pop(java.awt.Component component)
{
return(true);
}
/**
* 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.
*
* @param component The java.awt.Component to be
* moved.
* @return returns true on success,
* false on failure, for example if the
* java.awt.Component has yet to be added to the
* {@link org.havi.ui.HContainer HContainer}.
*/
public boolean push(java.awt.Component component)
{
return(true);
}
/**
* Puts the specified java.awt.Component in front of
* another java.awt.Component in the Z-order of this
* {@link org.havi.ui.HContainer 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.
*
* @param move The java.awt.Component to be moved
* directly in front of the "behind" Component in the
* Z-order of this {@link org.havi.ui.HContainer HContainer}.
* @param behind The java.awt.Component which the
* "move" Component should be placed directly in front
* of.
* @return returns true on success,
* false on failure, for example when either
* java.awt.Component has yet to be added to the
* {@link org.havi.ui.HContainer HContainer}. If this method
* fails, the Z-order is unchanged.
*/
public boolean popInFrontOf(java.awt.Component move, java.awt.Component behind)
{
return(true);
}
/**
* Puts the specified java.awt.Component behind
* another java.awt.Component in the Z-order of this
* {@link org.havi.ui.HContainer 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.
*
* @param move The java.awt.Component to be moved
* directly behind the "front" Component in the Z-order
* of this {@link org.havi.ui.HContainer HContainer}.
* @param front The java.awt.Component which the
* "move" Component should be placed directly behind.
* @return returns true on success,
* false on failure, for example when either
* java.awt.Component has yet to be added to the
* {@link org.havi.ui.HContainer HContainer}.
*/
public boolean pushBehind(java.awt.Component move, java.awt.Component front)
{
return(true);
}
/**
* Groups the HContainer and its components. If the container is
* already grouped this method has no effect
*
* @see org.havi.ui.HContainer#ungroup
* @see org.havi.ui.HContainer#isGrouped
*/
public void group()
{
}
/**
* Ungroups the HContainer and its components. If the container is
* already ungrouped, this method has no effect.
*
* @see org.havi.ui.HContainer#group
* @see org.havi.ui.HContainer#isGrouped
*/
public void ungroup()
{
}
/**
* Tests whether the HContainer and its components are grouped.
* By default the container is not grouped with its components.
*
* @return returns true if the HContainer and its
* components are grouped, false otherwise.
*
* @see org.havi.ui.HContainer#group
* @see org.havi.ui.HContainer#ungroup
*/
public boolean isGrouped()
{
return (false);
}
}