Java DTV API 1.3
18-Nov-2009

com.sun.dtv.ui
Class DTVContainer

java.lang.Object
  extended by com.sun.dtv.lwuit.Component
      extended by com.sun.dtv.lwuit.Container
          extended by 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: .

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

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

Java DTV API 1.3
18-Nov-2009

Copyright © 2008-2009 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved.

U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Sun, Sun Microsystems, the Sun logo and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.Products covered by and information contained in this service manual are controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited.

DOCUMENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Use of this document is subject to license terms.