com.sun.dtv.ui.event
Class UserInputEventManager

java.lang.Object
  com.sun.dtv.ui.event.UserInputEventManager

public final class UserInputEventManager
extends Object

The instances of this class are the event managers handling the user input events to be handled by a widget. The aim of these managers is mainly to manage exclusively reserved events and install listeners to handle them.

The exclusive reservation itself will be done using the scarce resource mechanism. The user input events to be handled this way implement the ScarceResource interface in order to be able to be handled this way. The following is a code snippet, demonstrating how to exclusively register for an user input event.

 // MyClass implements UserInputEventListener, this way it can be used as
 // its own UserInputEventListener
 import com.sun.dtv.ui.event.*;
 
 public class MyClass implements com.sun.dtv.ui.event.UserInputEventListener {
 ...
    // implementing the interface requires to implement the 
    // userInputEventReceived method:
    public void userInputEventReceived(UserInputEvent event) {
       ...
    }
    ...
    public void myMethod(...) {
       ...
       // in this method, we exclusively register for user input events
       // first, we have to retrieve the UserInputEventManager for our
       // current screen
       UserInputEventManager manager =
            UserInputEventManager.getUserInputEventManager(currentScreen);
       // now we can exclusively register for several kind of user input 
       // events
       // first, we construct a mouse event pattern, covering all mouse events
       // we want to get notified about:
       MouseEvent anyMouseLeftClick = 
          new MouseEvent(null, // no matter which component is affected
                         MouseEvent.MOUSE_LEFT_CLICK,
                         0, // don't care about time
                         0, // no modifiers 
                         0, 0, // don't care about position
                         1, // one click associated with the event
                         false); // no popup trigger
      // now we exclusively register for this type of mouse event
      anyMouseLeftClick.reserve(true, -1, aScarceResourceListener);
      // We force the reservation, no timeout. For details about the
      // ScarceResourceListener see documentation about scarce resources.
      // Now make the exclusively reserved type of user input event handled:
      manager.addUserInputEventListener(this, anyMouseLeftClick);
      // We will now be exclusively notified about any mouse left click
      // received by our screen, i.e. nobody else - including the awt
      // event handling mechanism - will be noticed about this kind of 
      // event. This is true until we release the event type or we lose
      // the exclusive control about it by a reservation done by somebody
      // else (in this case the specified ScarceResourceListener will be
      // notified though).
      // We will now still reserve any key clicks to colored keys:
      RemoteControlEvent anyColoredKeyTyped =
         new RemoteControlEvent(null, // no matter which component is affected
               java.awt.event.KeyEvent.KEY_TYPED,
               0, // no matter when
               0, // no modifiers
               RemoteControlEvent.VK_COLORED, // any colored key
               CHAR_UNDEFINED); // no 
      anyColoredKeyTyped.reserve(true, -1, aScarceResourceListener),
      // see mouse click example above for details
      manager.addUserInputEventListener(this, anyColoreKeyTyped);
      ...
    }
    ...
 }
 

See Also:

ScarceResource, UserInputEvent, KeyEvent, MouseEvent, RemoteControlEvent

Method Summary

void	addUserInputEventListener(UserInputEventListener listener, UserInputEvent event) Add the specified listener which would like to be notified about the UserInputEvent specified.
static UserInputEventManager	getUserInputEventManager(Screen screen) Returns the unique UserInputEventManager for the specified Screen.
void	removeUserInputEventListener(UserInputEventListener listener) Remove the specified listener from the UserInputEventManager for this screen.

Methods inherited from class java.lang.Object

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

Method Detail

getUserInputEventManager

public static UserInputEventManager getUserInputEventManager(Screen screen)

Returns the unique UserInputEventManager for the specified Screen. As a consequence, this method will create the UserInputEventManager if firstly called for the specified Screen (usually this will happen out of the Screen's constructor), and return the identical instance for any subsequent call.

Parameters:

screen - the Screen we want to get the UserInputEventManager for

Returns:

the UserInputEventManager instance for the specified Screen

addUserInputEventListener

public void addUserInputEventListener(UserInputEventListener listener,
                                      UserInputEvent event)

Add the specified listener which would like to be notified about the UserInputEvent specified. Please be aware that the listener will not be notified about received UserInputEvents in the case that another application has exclusively reserved this event using the scarce resource mechanism before and this reservation is still valid. If this method is called more than once for the same listener, registering for a notification about the same user input event, after the first calls subsequent calls have no effect, i.e. a listener can only once register for one user input event. If several listeners register for the same user input event, but one has exclusively reserved this event, the other listeners won't be notified at all, even if they are still registered. If more than one listener has tried to exclusively reserve the event, this is managed following the rules of scarce resource management. IMPLEMENTATION NOTE: The implementation has to ensure that notifications about all events are processed sequentially. It has to be guaranteed that no more than one notification is handled at the same time. Any single listener shall only be notified about one event instance at one time. If a new event is generated before the notified listener method has returned from processing the previous event, the implementation SHOULD wait for the return before processing the next notification call.

Parameters:

listener - the UserInputEventListener to be added

event - the UserInputEvent the listener should listen to

See Also:

KeyEvent.reserve(boolean, long, com.sun.dtv.resources.ScarceResourceListener), MouseEvent.reserve(boolean, long, com.sun.dtv.resources.ScarceResourceListener), KeyEvent.reserve(boolean, long, com.sun.dtv.resources.ScarceResourceListener), removeUserInputEventListener(com.sun.dtv.ui.event.UserInputEventListener)

removeUserInputEventListener

public void removeUserInputEventListener(UserInputEventListener listener)

Remove the specified listener from the UserInputEventManager for this screen. If the specified UserInputEventListener has not been added before to this manager, the call to this method has no effect.

Parameters:

listener - the UserInputEventListener to be removed

See Also:

addUserInputEventListener(com.sun.dtv.ui.event.UserInputEventListener, com.sun.dtv.ui.event.UserInputEvent)