com.sun.dtv.ui
Class DTVContainer

java.lang.Object
  com.sun.dtv.lwuit.Component
      com.sun.dtv.lwuit.Container
          com.sun.dtv.ui.DTVContainer

All Implemented Interfaces:

Animation, StyleListener, Animated, MatteEnabled

public class DTVContainer
extends Container

An DTVContainer is the top-level container in the DTV API's component hierarchy, representing the widget containing anything else viewable at on particular Plane. There is always only one DTVContainer available per Plane.

The DTVContainer itself is never subject to painting activities, its only task is the clipping of the contained Components. In respect thereof it differs from "normal" Containers, although it is subclassing this class.

The DTVContainer also adds Z-ordering capabilities in order to enable overlapping widgets within a DTVContainer to be arranged into the desired Z_ordering by an application.

Being a Component, a DTVContainer is able to receive input events and handle them by usage of attached event handlers. The visibility of a DTVContainer is no warranty that it will also receive events. For this, the associated application has to take care that the DTVContainer gains the input focus. The DTV container will then pass the input focus to one of the contained components in an implementation dependent manner. If the entire application gains or loses the input focus (and at the same time also the associated DTVContainer of course), this should be indicated by the system by sending a WINDOW_ACTIVATED or WINDOW_DEACTIVATED event to the DTVCOntainer, respectively.

A DTVContainer cannot be created by explicitly calling a constructor. The reason is that requiring a DTVCOntainer has to take into account a number of conditions, determined by the TV device's capabilities, the Screen, and the Plane the DTVContainer is requested for. Several factory methods of this class provide the ability to take all this into account and provide the optimal DTVConatiner to an application. Furthermore, an application can specify the characteristics of a desired DTVContainer and the priorities for the desired characteristics, using the DTVContainerPattern class. The getBestDTVContainer method accepts an argument of the type DTVContainerPattern and provides a DTVContainer considering the specified preferences if possible.

Field Summary

static int	BACKGROUND_FILL Constant to be used in the setBackgroundMode method.
static int	BACKGROUND_IMAGE_CENTERED Constant to be used in the setBackgroundImageRenderMode method.
static int	BACKGROUND_IMAGE_NONE Constant to be used in the setBackgroundImageRenderMode method.
static int	BACKGROUND_IMAGE_STRETCHED Constant to be used in the setBackgroundImageRenderMode method.
static int	BACKGROUND_IMAGE_TILED Constant to be used in the setBackgroundImageRenderMode method.
static int	BACKGROUND_NO_FILL Constant to be used in the setBackgroundMode method.

Fields inherited from class com.sun.dtv.lwuit.Component

BOTTOM, BRB_CENTER_OFFSET, BRB_CONSTANT_ASCENT, BRB_CONSTANT_DESCENT, BRB_OTHER, CENTER, LEFT, RIGHT, TOP

Fields inherited from interface com.sun.dtv.ui.Animated

ALTERNATING, LOOP, REPEATING

Method Summary

void	addToBack(Component component) Adds a Component to this DTVContainer behind all previously added components.
void	addToFront(Component component) Adds a Component to this DTVContainer directly in front of all previously added components.
void	addWindowListener(WindowListener listener) Add a listener to receive any java.awt.event.WindowEvents sent to this DTVContainer.
void	consumeWindowEvent(WindowEvent event) Consumes a java.awt.event.WindowEvents for this DTVContainer.
void	dispose() Disposes of this DTVContainer.
Image	getBackgroundImage() Get the background image assigned to this DTVContainer if any.
int	getBackgroundImageRenderMode() Obtains the rendering mode for a background image as specified using the setBackgroundImageRenderMode method.
int	getBackgroundMode() Obtains the background mode as specified using the setBackgroundMode method.
static DTVContainer	getBestDTVContainer(DTVContainerPattern pattern) Returns a DTVContainer that best corresponds to the input DTVContainerPattern, or null if such an DTVContainer cannot be found.
static DTVContainerPattern	getBestDTVContainerPattern(DTVContainerPattern pattern) Returns an DTVContainerPattern closest to to the input DTVContainerPattern and at the same time specifying a DTVContainer which could be successfully created on the underlying platform at the time this method is called.
static DTVContainer	getCurrentDTVContainer() Returns the DTVContainer the caller is displayed within.
static DTVContainer	getDTVContainer(Plane plane) Create a DTVContainer for the specified Plane.
static DTVContainer	getDTVContainer(Plane plane, Container container) Create a DTVContainer for the specified Plane, which can be used as an Xlet container.
DTVContainerPattern	getDTVContainerPattern() Returns a DTVContainerPattern describing this DTVContainer.
Component	getFocusOwnerComponent() Obtains the Component contained by this DTVContainer which currently owns the input focus.
boolean	isDoubleBuffered() Obtains whether all drawing operations performed for this DTVContainer are automatically double buffered.
boolean	isOpaque() Obtains whether the full area of the DTVContainer as given by the Component.getBounds() method, is fully opaque.
void	paint(Graphics g) This method paints the Component on the screen, it should be overriden by subclasses to perform custom drawing or invoke the UI API's to let the PLAF perform the rendering.
void	pop(Component component) Moves the specified Component one level up in the Z-order.
void	popInFrontOf(Component move, Component behind) Moves the specified Component move directly in front of the Component behind.
void	popToFront(Component component) Brings the specified Component to the front of the Z-order in this DTVContainer.
void	push(Component component) Moves the specified Component one level down in the Z-order.
void	pushBehind(Component move, Component front) Moves the specified Component move directly behind the Component front.
void	pushToBack(Component component) Brings the specified Component to the back of the Z-order in this DTVContainer.
void	removeWindowListener(WindowListener listener) Remove a listener from this DTVContainer so that it no longer receives any java.awt.event.WindowEvents.
DTVContainerPattern	resize(DTVContainerPattern pattern) Resizes this DTVContainer so that it best corresponds to the input DTVContainerPattern, or do nothing if not necessary.
void	setBackgroundImage(Image image) Sets a background image to be painted in the background of the DTVContainer.
void	setBackgroundImageRenderMode(int mode) Set the rendering mode of a background image assigned to this DTVContainer.
void	setBackgroundMode(int mode) Set the background mode of this DTVContainer.
void	setToFront() Brings this DTVContainer to the front.

Methods inherited from class com.sun.dtv.lwuit.Container

addComponent, addComponent, addComponent, contains, doLayout, getComponentAt, getComponentAt, getComponentCount, getComponentIndex, getLayout, getLayoutHeight, getLayoutWidth, getMatte, invalidate, isScrollableX, isScrollableY, layoutContainer, pointerPressed, refreshTheme, removeAll, removeComponent, replace, revalidate, scrollComponentToVisible, setCellRenderer, setLayout, setMatte, setScrollable, setScrollableX, setScrollableY

Methods inherited from class com.sun.dtv.lwuit.Component

addFocusListener, animate, calcPreferredSize, contains, deinitialize, getAbsoluteX, getAbsoluteY, getAnimationMode, getBaseline, getBaselineResizeBehavior, getBottomGap, getBounds, getClientProperty, getComponentForm, getDelay, getHeight, getNextFocusDown, getNextFocusLeft, getNextFocusRight, getNextFocusUp, getParent, getPosition, getPreferredSize, getRepetitionMode, getScrollAnimationSpeed, getScrollX, getScrollY, getSideGap, getStyle, getUIID, getWidth, getX, getY, handlesInput, hasFocus, initialize, isEnabled, isFocusable, isFocusPainted, isInitialized, isRunning, isScrollVisible, isSmoothScrolling, isVisible, jumpTo, keyPressed, keyReleased, keyRepeated, longKeyPress, paintBackgrounds, paintComponent, paintComponent, pointerDragged, pointerReleased, putClientProperty, removeFocusListener, repaint, repaint, requestFocus, scrollRectToVisible, setAnimationMode, setDelay, setEnabled, setFocus, setFocusable, setFocusPainted, setHandlesInput, setHeight, setInitialized, setIsScrollVisible, setNextFocusDown, setNextFocusLeft, setNextFocusRight, setNextFocusUp, setPreferredSize, setRepetitionMode, setScrollAnimationSpeed, setScrollX, setScrollY, setShouldCalcPreferredSize, setSize, setSmoothScrolling, setStyle, setUIID, setVisible, setWidth, setX, setY, start, stop, styleChanged, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

BACKGROUND_IMAGE_NONE

public static final int BACKGROUND_IMAGE_NONE

Constant to be used in the setBackgroundImageRenderMode method. Causes no background image to be rendered in this DTVContainer.

See Also:

Constant Field Values

BACKGROUND_IMAGE_STRETCHED

public static final int BACKGROUND_IMAGE_STRETCHED

Constant to be used in the setBackgroundImageRenderMode method. Causes a rendered background image to be stretched in order to fill out the DTVContainer.

See Also:

Constant Field Values

BACKGROUND_IMAGE_CENTERED

public static final int BACKGROUND_IMAGE_CENTERED

Constant to be used in the setBackgroundImageRenderMode method. Causes a rendered background image to be centered within the borders of the DTVContainer.

See Also:

Constant Field Values

BACKGROUND_IMAGE_TILED

public static final int BACKGROUND_IMAGE_TILED

Constant to be used in the setBackgroundImageRenderMode method. Causes a rendered background image to be tiled within the borders of the DTVContainer.

See Also:

Constant Field Values

BACKGROUND_NO_FILL

public static final int BACKGROUND_NO_FILL

Constant to be used in the setBackgroundMode method. Causes that the DTVContainer will not be filled (with a color) before a background image or components are painted.

See Also:

Constant Field Values

BACKGROUND_FILL

public static final int BACKGROUND_FILL

Constant to be used in the setBackgroundMode method. Causes that the DTVContainer will be filled (with the current background color) before a background image or components are painted.

See Also:

Constant Field Values

Method Detail

paint

public void paint(Graphics g)

This method paints the Component on the screen, it should be overriden by subclasses to perform custom drawing or invoke the UI API's to let the PLAF perform the rendering.

If the current background mode is BACKGROUND_FILL, the whole area of the DTVContainer is filled with the current background color first. If a background image has been set using the setBackgroundImage method, the specified image is painted unless the current background image rendering mode is BACKGROUND_IMAGE_NONE. In all other cases the image will be scaled or tiled as specified by call of the setBackgroundImageRenderMode(int) method. Then, all contained components are painted taking into account the specified Z-order.

Specified by:

paint in interface Animation

Overrides:

paint in class Container

Parameters:

g - the component graphics

getBackgroundMode

public int getBackgroundMode()

Obtains the background mode as specified using the setBackgroundMode method.

Returns:

one of BACKGROUND_NO_FILL or BACKGROUND_FILL.

See Also:

setBackgroundMode(int)

setBackgroundMode

public void setBackgroundMode(int mode)
                       throws IllegalArgumentException

Set the background mode of this DTVContainer.

If the background mode is set to BACKGROUND_FILL, this will automatically cause the isOpaque method to return true.

Parameters:

mode - one of BACKGROUND_NO_FILL or BACKGROUND_FILL

Throws:

IllegalArgumentException - if the mode parameter has not a valid value

See Also:

getBackgroundMode()

getBackgroundImageRenderMode

public int getBackgroundImageRenderMode()

Obtains the rendering mode for a background image as specified using the setBackgroundImageRenderMode method.

Returns:

one of BACKGROUND_IMAGE_NONE, BACKGROUND_IMAGE_STRETCHED, BACKGROUND_IMAGE_CENTERED or BACKGROUND_IMAGE_TILED.

See Also:

setBackgroundImageRenderMode(int)

setBackgroundImageRenderMode

public void setBackgroundImageRenderMode(int mode)

Set the rendering mode of a background image assigned to this DTVContainer.

Parameters:

mode - one of BACKGROUND_IMAGE_NONE, BACKGROUND_IMAGE_STRETCHED, BACKGROUND_IMAGE_CENTERED or BACKGROUND_IMAGE_TILED.

See Also:

getBackgroundImageRenderMode()

getBackgroundImage

public Image getBackgroundImage()

Get the background image assigned to this DTVContainer if any. Please consider that even if an image is assigned it will be possibly not rendered, depending on the background image render mode.

Returns:

the background image assigned to this DTVContainer, or null if no image is assigned.

See Also:

setBackgroundImage(com.sun.dtv.lwuit.Image), setBackgroundImageRenderMode(int)

setBackgroundImage

public void setBackgroundImage(Image image)

Sets a background image to be painted in the background of the DTVContainer. How the image will be rendered depends on the currently valid render mode as set using the setBackgroundImageRenderMode method. Please consider that an assigned background may not be rendered, depending on the currently valid background image render mode.

Parameters:

image - the background image to be assigned to this DTVContainer. A value of null causes a currently assigned image to be removed.

See Also:

getBackgroundImage(), setBackgroundImageRenderMode(int)

isDoubleBuffered

public boolean isDoubleBuffered()

Obtains whether all drawing operations performed for this DTVContainer are automatically double buffered.

Returns:

true if all drawing operations are double-buffered, false otherwise.

isOpaque

public boolean isOpaque()

Obtains whether the full area of the DTVContainer as given by the Component.getBounds() method, is fully opaque.

Returns:

true if all pixels within the area given by the Component.getBounds() method are painted in an opaque color, otherwise false.

addToFront

public void addToFront(Component component)

Adds a Component to this DTVContainer directly in front of all previously added components.

Parameters:

component - the Component to be added to this DTVContainer

addToBack

public void addToBack(Component component)

Adds a Component to this DTVContainer behind all previously added components.

Parameters:

component - the Component to be added to this DTVContainer

popToFront

public void popToFront(Component component)
                throws IllegalArgumentException

Brings the specified Component to the front of the Z-order in this DTVContainer. If the component is already at the front of the Z-order, or is the only component in this DTVContainer, the method call has no effect.

Parameters:

component - The Component to be brought to the front of the Z-order of this DTVContainer.

Throws:

IllegalArgumentException - if the specified component is not contained in this DTVContainer

pushToBack

public void pushToBack(Component component)
                throws IllegalArgumentException

Brings the specified Component to the back of the Z-order in this DTVContainer. If the component is already at the back of the Z-order, or is the only component in this DTVContainer, the method call has no effect.

Parameters:

component - The Component to be brought to the back of the Z-order of this DTVContainer.

Throws:

IllegalArgumentException - if the specified component is not contained in this DTVContainer

pop

public void pop(Component component)
         throws IllegalArgumentException

Moves the specified Component one level up in the Z-order. This causes the Component being directly in front of the specified component to be moved one level down. If the component is the only component in this DTVContainer, the method call has no effect. If the component is already at the front of the Z-order, the order is unchanged and the method call has no effect.

Parameters:

component - The Component to be moved.

Throws:

IllegalArgumentException - if the specified component is not contained in this DTVContainer

push

public void push(Component component)
          throws IllegalArgumentException

Moves the specified Component one level down in the Z-order. This causes the Component being directly behind the specified component to be moved one level up. If the component is the only component in this DTVContainer, the method call has no effect. If the component is already at the back of the Z-order, the order is unchanged and the method call has no effect.

Parameters:

component - The Component to be moved.

Throws:

IllegalArgumentException - if the specified component is not contained in this DTVContainer

popInFrontOf

public void popInFrontOf(Component move,
                         Component behind)
                  throws IllegalArgumentException

Moves the specified Component move directly in front of the Component behind. This causes the Component behind to be moved one level down in the Z-order.

Parameters:

move - The Component to be moved.

behind - The Component component should be set in front of

Throws:

IllegalArgumentException - if one of the specified components is not contained in this DTVContainer

pushBehind

public void pushBehind(Component move,
                       Component front)
                throws IllegalArgumentException

Moves the specified Component move directly behind the Component front.

Parameters:

move - The Component to be moved.

front - The Component component should be set behind

Throws:

IllegalArgumentException - if one of the specified components is not contained in this DTVContainer

addWindowListener

public void addWindowListener(WindowListener listener)

Add a listener to receive any java.awt.event.WindowEvents sent to this DTVContainer. If the specified listener has already been added further calls will add further references to the listener, which will then receive multiple copies of the same event.

Parameters:

listener - The java.awt.event.WindowListener to be notified about any java.awt.event.WindowEvent.

See Also:

removeWindowListener(java.awt.event.WindowListener)

removeWindowListener

public void removeWindowListener(WindowListener listener)

Remove a listener from this DTVContainer so that it no longer receives any java.awt.event.WindowEvents. If the specified listener has not been previously registered, the call to this method has no effect. If multiple references to a single listener have been registered before the call to this method will cause the removal of exactly one reference only.

Parameters:

listener - The java.awt.event.WindowListener to be removed

See Also:

addWindowListener(java.awt.event.WindowListener)

consumeWindowEvent

public void consumeWindowEvent(WindowEvent event)

Consumes a java.awt.event.WindowEvents for this DTVContainer.

Parameters:

event - the java.awt.event.WindowEvents to be consumed.

getFocusOwnerComponent

public Component getFocusOwnerComponent()

Obtains the Component contained by this DTVContainer which currently owns the input focus.

Returns:

the Component owning the focus, or null if the DTVContainer does not have the input focus at all.

setToFront

public void setToFront()

Brings this DTVContainer to the front.

If this DTVContainer is not visible, the call to this method has no effect.

dispose

public void dispose()

Disposes of this DTVContainer. This method must be called by an application before it exits in order to release resources used for the DTVContainer.

getDTVContainerPattern

public DTVContainerPattern getDTVContainerPattern()

Returns a DTVContainerPattern describing this DTVContainer.

Returns:

a DTVContainerPattern describing this DTVContainer.

getBestDTVContainerPattern

public static DTVContainerPattern getBestDTVContainerPattern(DTVContainerPattern pattern)

Returns an DTVContainerPattern closest to to the input DTVContainerPattern and at the same time specifying a DTVContainer which could be successfully created on the underlying platform at the time this method is called.

Subsequent calls to this method with the same argument may cause different return values. Note that conflicts may occur between properties in the specified DTVContainerPattern and a PlaneSetupPattern describing an currently active PlaneSetup, associated with a graphics enabled plane. In case this conflicts can not be solved, this method shall fail and return null.

Parameters:

pattern - The DTVContainerPattern providing the properties that the DTVContainer should satisfy.

Returns:

a DTVContainerPattern that corresponds best to the input argument, or null if a non-solvable conflict with a currently active PlaneSetup occurs

getBestDTVContainer

public static DTVContainer getBestDTVContainer(DTVContainerPattern pattern)

Returns a DTVContainer that best corresponds to the input DTVContainerPattern, or null if such an DTVContainer cannot be found.

Note that conflicts may occur between properties in the specified DTVContainerPattern and a PlaneSetupPattern describing an currently active PlaneSetup, associated with a graphics enabled plane. In case this conflicts can not be solved, this method shall fail and return null.

Parameters:

pattern - the DTVContainerPattern specifying the properties to be taken into account

Returns:

the DTVContainer that matches the properties as specified best, or null if they cannot be satisfied, or if no further DTVContainer are available for this application.

resize

public DTVContainerPattern resize(DTVContainerPattern pattern)
                           throws IllegalStateException

Resizes this DTVContainer so that it best corresponds to the input DTVContainerPattern, or do nothing if not necessary.

Parameters:

pattern - the DTVContainerPattern which denotes the new size and location. Of course only size and location options in the DTVContainerPattern will be considered.

Returns:

an DTVContainerPattern indicating the DTVContainer properties (after possible resizing).

Throws:

IllegalStateException - if the DTVContainer had previously been disposed.

getDTVContainer

public static DTVContainer getDTVContainer(Plane plane)
                                    throws IllegalArgumentException

Create a DTVContainer for the specified Plane. A plane appropriate to host a DTVContainer must be associated with a Capabilities object for which a call to at least one of the following methods will return true:

• Capabilities.isWidgetRenderingSupported()
• Capabilities.isGraphicsRenderingSupported()

.

Parameters:

plane - the Plane for which the DTVContainer should be returned.

Returns:

the DTVContainer for the specified Plane.

Throws:

IllegalArgumentException - if the specified plane is not an appropriate one in order to host a DTVContainer (@see com.sun.dtv.ui.Capabilities)

getDTVContainer

public static DTVContainer getDTVContainer(Plane plane,
                                           Container container)
                                    throws IllegalArgumentException

Create a DTVContainer for the specified Plane, which can be used as an Xlet container. For this, the java.awt.Container provided by the XLet context, has to be passed as second parameter. A plane appropriate to host a DTVContainer must be associated with a Capabilities object for which a call to at least one of the following methods will return true:

• Capabilities.isWidgetRenderingSupported()
• Capabilities.isGraphicsRenderingSupported()

.

Parameters:

plane - the Plane for which the DTVContainer should be returned.

container - the java.awt.Container provided by calling the method getContainer() of javax.microedition.xlet.XletContext.

Returns:

the DTVContainer for the specified Plane.

Throws:

IllegalArgumentException - if the specified plane is not an appropriate one in order to host a DTVContainer (@see com.sun.dtv.ui.Capabilities)

getCurrentDTVContainer

public static DTVContainer getCurrentDTVContainer()

Returns the DTVContainer the caller is displayed within.

Returns:

the current screen