com.sun.dtv.ui
Class Screen

java.lang.Object
  com.sun.dtv.ui.Screen

All Implemented Interfaces:

ScarceResource

public class Screen
extends Object
implements ScarceResource

This class is a representation of a TV screen. Such a screen consists on a number of planes dedicated for several purposes like video, graphics, subtitles and background. All of these will be combined together before being displayed. In case a platform supports more than one display it would handle an instance of this class for each. Audio output is also supported where needed. Also, there is a number of UserInputDevices dedicated to this Screen. These user input devices can be used to control this particular screen.

Although every plane of a screen device has it's own setup, all of them must have certain properties in common. Conflicting setups of several planes for the same screen are not supported.

This class also handles the main thread for the toolkit referenced here on as the EDT (Event Dispatch Thread) similar to the Swing EDT. This thread encapsulates the platform specific event delivery and painting semantics and enables threading features such as animations etc...

The EDT should not be blocked since paint operations and events would also be blocked in much the same way as they would be in other platforms. In order to serialize calls back into the EDT use the methods callSerially(java.lang.Runnable) & callSeriallyAndWait(java.lang.Runnable).

Notice that all LWUIT calls occur on the EDT (events, painting, animations etc...), LWUIT should normally be manipulated on the EDT as well (hence the callSerially(java.lang.Runnable) & callSeriallyAndWait(java.lang.Runnable) methods). Theoretically it should be possible to manipulate some LWUIT features from other threads but this can't be guaranteed to work for all use cases.

Method Summary

static void	addResourceTypeListener(ResourceTypeListener listener) Adds a ResourceTypeListener to the implementation.
void	addScarceResourceListener(ScarceResourceListener listener) Register a listener for events about changes in the state of the ownership of this screen.
void	callSerially(Runnable r) Causes the runnable to be invoked on the event dispatch thread.
void	callSeriallyAndWait(Runnable r) Identical to callSerially with the added benefit of waiting for the Runnable method to complete.
Plane[]	getAllPlanes() Returns a list of all planes for this screen.
static Screen[]	getAvailableScreens() Returns all Screens available in this system.
PlaneSetup	getBestSetup(PlaneSetupPattern[] patterns) Returns a PlaneSetup from an Plane which is present on this Screen that best matches at least one of the specified PlaneSetupPatterns.
PlaneSetup[]	getCoherentPlaneSetups(PlaneSetupPattern[] patterns) Return a coherent set of PlaneSetups matching a set of patterns.
static Screen	getCurrentScreen() Returns the Screen the caller is displayed on.
static Screen	getDefaultScreen() Returns the default Screen for this application.
static Screen[]	getInstances() Return the list of all existing instances of Screen, whether they are already reserved or not.
Keyboard	getKeyboard() Returns the keyboard which can be used to control this screen if any.
Mouse	getMouse() Returns the mouse which can be used to control this screen if any.
RemoteControl	getRemoteControl() Returns the TV remote control which can be used to control this screen if any.
Dimension	getScreenAspectRatio() Returns the aspect ratio of this Screen.
UserInputDevice[]	getSupportedUserInputDevices() Returns a list of UserInputDevices that are associated to this Screen.
UserInputEventManager	getUserInputEventManager() Return the UserInputEventManager of this screen.
void	invokeAndBlock(Runnable r) Invokes runnable and blocks the current thread, if the current thread is the edt it will still be blocked however a separate thread would be launched to perform the duties of the EDT while it is blocked.
boolean	isAvailable() Checks whether the given resource is currently available for reservation.
boolean	isEdt() Returns true if we are currently in the event dispatch thread.
boolean	isKeyboardSupported() Indicates whether this screen can be controlled using a keyboard.
boolean	isMouseSupported() Indicates whether this screen can be controlled using a mouse.
boolean	isRemoteControlSupported() Indicates whether this screen can be controlled using a TV remote control.
void	release() Releases this resource.
static void	removeResourceTypeListener(ResourceTypeListener listener) Removes a previously attached listener.
void	removeScarceResourceListener(ScarceResourceListener listener) Remove a listener for events about changes in the state of the ownership of this screen.
void	reserve(boolean force, long timeout, ScarceResourceListener listener) Requests reservation of the given scarce resource instance.
static Screen	reserveOne(boolean force, long timeoutms, ScarceResourceListener listener) Returns a reserved instance out of the pool of all Screen instances.
boolean	setCoherentPlaneSetups(PlaneSetup[] setups) Modify the settings for a set of Planes, based on their PlaneSetups supplied.

Methods inherited from class java.lang.Object

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

Method Detail

getAvailableScreens

public static Screen[] getAvailableScreens()

Returns all Screens available in this system.

Returns:

an array of Screens representing all Screens available in this system.

getDefaultScreen

public static Screen getDefaultScreen()

Returns the default Screen for this application.

Returns:

the default Screen for this application.

getAllPlanes

public Plane[] getAllPlanes()

Returns a list of all planes for this screen.

Returns:

an array of Plane objects or null if none exist.

getCoherentPlaneSetups

public PlaneSetup[] getCoherentPlaneSetups(PlaneSetupPattern[] patterns)
                                    throws IllegalArgumentException

Return a coherent set of PlaneSetups matching a set of patterns. One PlaneSetup will be returned for each PlaneSetupPattern provided as input.

Coherent means that all the required properties are respected in all of the patterns provided and that a setup can be returned for each pattern provided.

Conflicts between patterns are resolved as discussed in the description of PlaneSetupPattern.

Parameters:

patterns - an array of objects describing desired setups.

Returns:

an array of non-null objects describing a coherent set of screen plane setups or null if no such coherent set is possible.

Throws:

IllegalArgumentException - if a zero-length array is passed as an argument

See Also:

setCoherentPlaneSetups(com.sun.dtv.ui.PlaneSetup[])

setCoherentPlaneSetups

public boolean setCoherentPlaneSetups(PlaneSetup[] setups)
                               throws SecurityException,
                                      IllegalArgumentException,
                                      SetupException

Modify the settings for a set of Planes, based on their PlaneSetups supplied.

Parameters:

setups - the array of setups that should be applied (where possible).

Returns:

A boolean indicating whether all PlaneSetups could be applied successfully. Even if none of the PlaneSetups could be applied successfully, the setup after this method may not match the setup of the planes prior to this method being called: there is no warranty that the implementation has not changed setups of the screen in order to better meet the requirements (even if not all requirements could be fulfilled). Applications should therefore investigate whether a partial change of settings has been made for each plane even in this case.

Throws:

IllegalArgumentException - if the parameter array is empty.

SecurityException - if the application does not have sufficient rights to set the PlaneSetup for any of the planes.

SetupException - if an element of the specified PlaneSetup array is not valid for any of the planes.

See Also:

getCoherentPlaneSetups(com.sun.dtv.ui.PlaneSetupPattern[])

getBestSetup

public PlaneSetup getBestSetup(PlaneSetupPattern[] patterns)

Returns a PlaneSetup from an Plane which is present on this Screen that best matches at least one of the specified PlaneSetupPatterns. If this is not possible, null is returned.

Best in the sense of this method means that the setups satisfy a number as high as possible of preferences with priorities PREFERRED and PREFERRED_NOT as well as all preferences with priorities REQUIRED and REQUIRED_NOT. Setups are chosen by applying the following algorithm, based on the priorities as supplied to setPreference. The setup of choice:

• MUST satisfy all the preferences whose priority was REQUIRED
• MUST NOT satisfy any of the preferences whose priority was REQUIRED_NOT
• SHOULD satisfy as many as possible of the preferences whose priority was PREFERRED.
• SHOULD satisfy as few as possible of the preferences whose priority was PREFERRED_NOT.

Preferences whose priority was DONT_CARE are ignored.

This method returns null if no setup exists that satisfies all REQUIRED and REQUIRED_NOT priorities.

Parameters:

patterns - the array of PlaneSetupPattern objects to choose from.

Returns:

an PlaneSetup object that is the best matching possible setup, or null if none can be found.

getScreenAspectRatio

public Dimension getScreenAspectRatio()

Returns the aspect ratio of this Screen.

Returns:

the aspect ratio of this Screen

addScarceResourceListener

public void addScarceResourceListener(ScarceResourceListener listener)

Register a listener for events about changes in the state of the ownership of this screen. If this listener has already been added before, further calls will add further references to the listener. As a consequence, these references will receive multiple copies of one single event.

Parameters:

listener - the object to be informed of state changes.

See Also:

removeScarceResourceListener(com.sun.dtv.resources.ScarceResourceListener)

removeScarceResourceListener

public void removeScarceResourceListener(ScarceResourceListener listener)

Remove a listener for events about changes in the state of the ownership of this screen. This method has no effect if the specified listener has not been registered before.

Parameters:

listener - the object which is no longer interested.

See Also:

addScarceResourceListener(com.sun.dtv.resources.ScarceResourceListener)

reserve

public void reserve(boolean force,
                    long timeout,
                    ScarceResourceListener listener)
             throws IllegalArgumentException,
                    TimeoutException

Requests reservation of the given scarce resource instance. The method will block until this instance is available. The method returns normally only if the reservation succeeded. All other cases are handled by exceptions.

First, if there is a security manager, its checkPermission method is called with the permission ScarceResourcePermission(name, "reserve"). If force is moreover set to true, then the permission is also checked on ScarceResourcePermission(name, "force").

During the reservation process, if that resource instance is already allocated, the implementation must notify the current owner of that resource about the reservation request via the ScarceResourceListener interface:

• either by ScarceResourceListener.releaseRequested() if force is false,
• or by ScarceResourceListener.releaseForced() in the other case.

The listener will be used for such notification only until this resource is released. After releasing, the implementation must not call any of the listener's interface methods.

After that first event, the implementation will proceed accordingly and release (or not) the requested resource. In case the implementation releases the resource, it will trigger a ScarceResourceListener.released() event to the original listening owner of the resource to inform him that the resource does not belong to him anymore.

The application may control the time to wait for such a resource to be available by setting timeoutms. In case the duration of the reservation exceeds the time expressed in timeoutms, a TimeoutException is thrown.

Under normal operation, resources are released using the release method. However, in the case where the application does not release resources when requested or the application is terminated, the implementation must release all resources allocated to the application to allow other applications to be notified of changes in resource allocation and to be able to reserve them. See the Resource Cleanup section of the application lifecycle.

Specified by:

reserve in interface ScarceResource

Parameters:

force - If true, this method will withdraw the resource from the current owner. If false, the implementation will block and wait until the resource is made available (using release()) or until timeoutms.

timeout - A positive amount of time in millisecond until which this method will wait for the resource to be released by its current owner. The value of -1 indicates that the implementation will wait forever.

listener - The listener to be attached to receive notification about the status of the resource.

Throws:

IllegalArgumentException - If listener is null or if the value specified in timeoutms is not valid i.e. not either a positive integer or -1.

TimeoutException - If the time specified in timeoutms is over and the resource could not be reserved.

reserveOne

public static Screen reserveOne(boolean force,
                                long timeoutms,
                                ScarceResourceListener listener)
                         throws IllegalArgumentException,
                                TimeoutException

Returns a reserved instance out of the pool of all Screen instances. This method either returns with the instance or throws an exception according to the situation.

This method behaves exactly as the reserve() method.

Parameters:

force - If true, this method is allowed to withdraw any given resource from its current owner. If false, the implementation will block and wait until a resource of the given type is made available (using release()) or until timeoutms milliseconds.

timeoutms - A positive amount of time in millisecond until which this method will wait for any resource to be released by its current owner. The value of -1 indicates that the implementation will wait forever.

listener - The listener to be attached to receive notification about the status of the resource.

Returns:

The instance of type Screen that has been reserved.

Throws:

IllegalArgumentException - If listener is null or if the value specified in timeoutms is not valid i.e. not either a positive integer or -1.

TimeoutException - If the time specified in timeoutms is over and the resource could not be reserved.

See Also:

reserve(boolean, long, com.sun.dtv.resources.ScarceResourceListener)

release

public void release()

Releases this resource.

The resource will be made available to another application across the platform. After calling this method, it is no more possible to interact with the given resource: calls to critical methods of that scarce resource must be ignored and may throw IllegalStateException. This assertion is valid and the behavior required for any class implementing the ScarceResource interface. In order to interact again with the given resource, the application must call the reserve() method and become the owner again.

The implementation may dispose any system resources that this object is using. After the implementation must not call any of the methods of the listener that was attached at reservation time.

If the resource was already available (i.e. not reserved), this method does nothing.

Specified by:

release in interface ScarceResource

isAvailable

public boolean isAvailable()

Checks whether the given resource is currently available for reservation. The returned value gives the current situation and does not guarantee that the resource will still be available at a later moment e.g. at reservation time: another application may have taken that resource in the meantime.

Specified by:

isAvailable in interface ScarceResource

Returns:

A boolean set to true if the given resource is currently available for reservation.

getSupportedUserInputDevices

public UserInputDevice[] getSupportedUserInputDevices()

Returns a list of UserInputDevices that are associated to this Screen.

Returns:

a list of UserInputDevices that are associated to this Screen

isKeyboardSupported

public boolean isKeyboardSupported()

Indicates whether this screen can be controlled using a keyboard.

Returns:

true if a keyboard is supported, false otherwise.

getKeyboard

public Keyboard getKeyboard()

Returns the keyboard which can be used to control this screen if any.

Returns:

the Keyboard object representing the keyboard which can be used to control this screen, null if there is none.

isRemoteControlSupported

public boolean isRemoteControlSupported()

Indicates whether this screen can be controlled using a TV remote control.

Returns:

true if TV remote control is supported, false otherwise.

getRemoteControl

public RemoteControl getRemoteControl()

Returns the TV remote control which can be used to control this screen if any.

Returns:

the RemoteControl object representing the TV remote control which can be used to control this screen, null if there is none.

isMouseSupported

public boolean isMouseSupported()

Indicates whether this screen can be controlled using a mouse.

Returns:

true if a mouse is supported, false otherwise.

getMouse

public Mouse getMouse()

Returns the mouse which can be used to control this screen if any.

Returns:

the Mouse object representing the mouse which can be used to control this screen, null if there is none.

getUserInputEventManager

public UserInputEventManager getUserInputEventManager()

Return the UserInputEventManager of this screen. Any screen owns a fixed instance of UserInputEventManager in order to be able to handle user input events coming from several applications. The UserInputEventManager is created together with the screen, it cannot be set or changed. Applications should use this method in order to gain access to the manager in order to apply for exclusive or non-exclusive access to UserInputEvents.

Returns:

the UserInputEventManager of this screen.

getCurrentScreen

public static Screen getCurrentScreen()

Returns the Screen the caller is displayed on.

Returns:

the current screen.

getInstances

public static Screen[] getInstances()

Return the list of all existing instances of Screen, whether they are already reserved or not.

Returns:

list of all existing instances of Screen.

addResourceTypeListener

public static void addResourceTypeListener(ResourceTypeListener listener)
                                    throws NullPointerException

Adds a ResourceTypeListener to the implementation. Whenever a reserve() or a release() is called on any resources of the same type, the implementation will call the listener's corresponding methods.

Parameters:

listener - The listener that is triggered for events on resources of the same type.

Throws:

NullPointerException - If listener is null.

See Also:

removeResourceTypeListener(com.sun.dtv.resources.ResourceTypeListener)

removeResourceTypeListener

public static void removeResourceTypeListener(ResourceTypeListener listener)
                                       throws NullPointerException

Removes a previously attached listener. If the listener was not attached before, this method does nothing.

Parameters:

listener - The listener that is triggered for events on resources of the same type.

Throws:

NullPointerException - If listener is null.

See Also:

addResourceTypeListener(com.sun.dtv.resources.ResourceTypeListener)

isEdt

public boolean isEdt()

Returns true if we are currently in the event dispatch thread. This is useful for generic code that can be used both with the EDT and outside of it.

Returns:

true if we are currently in the event dispatch thread; otherwise false

callSerially

public void callSerially(Runnable r)

Causes the runnable to be invoked on the event dispatch thread. This method returns immediately and will not wait for the serial call to occur

Parameters:

r - runnable (NOT A THREAD!) that will be invoked on the EDT serial to the paint and key handling events

Throws:

IllegalStateException - if this method is invoked on the event dispatch thread (e.g. during paint or event handling).

callSeriallyAndWait

public void callSeriallyAndWait(Runnable r)

Identical to callSerially with the added benefit of waiting for the Runnable method to complete.

Parameters:

r - runnable (NOT A THREAD!) that will be invoked on the EDT serial to the paint and key handling events

Throws:

IllegalStateException - if this method is invoked on the event dispatch thread (e.g. during paint or event handling).

invokeAndBlock

public void invokeAndBlock(Runnable r)

Invokes runnable and blocks the current thread, if the current thread is the edt it will still be blocked however a separate thread would be launched to perform the duties of the EDT while it is blocked. Once blocking is finished the EDT would be restored to its original position. This is very similar to the "foxtrot" Swing toolkit and allows coding "simpler" logic that requires blocking code in the middle of event sensitive areas.

Parameters:

r - runnable (NOT A THREAD!) that will be invoked synchronously by this method