Java DTV API 1.3
18-Nov-2009

com.sun.dtv.ui.event
Class MouseEvent

java.lang.Object
  extended by java.util.EventObject
      extended by java.awt.AWTEvent
          extended by java.awt.event.ComponentEvent
              extended by java.awt.event.InputEvent
                  extended by java.awt.event.MouseEvent
                      extended by com.sun.dtv.ui.event.MouseEvent
All Implemented Interfaces:
ScarceResource, UserInputEvent, Serializable

public class MouseEvent
extends MouseEvent
implements UserInputEvent

This class extends the MouseEvent class by implementing the UserInputEvent interface. Being just a marker interface, UserInputEvent is derived from ScarceResource interface though, therefore methods from there have to be implemented here.

See Also:
ScarceResource.reserve(boolean, long, com.sun.dtv.resources.ScarceResourceListener), ScarceResource.release(), Serialized Form

Field Summary
static int MOUSE_DRAG
          Constant used for specification of a mouse code.
static int MOUSE_ENTER
          Constant used for specification of a mouse code.
static int MOUSE_EXIT
          Constant used for specification of a mouse code.
static int MOUSE_LEFT_CLICK
          Constant used for specification of a mouse code.
static int MOUSE_LEFT_PRESS
          Constant used for specification of a mouse code.
static int MOUSE_LEFT_RELEASE
          Constant used for specification of a mouse code.
static int MOUSE_MOVE
          Constant used for specification of a mouse code.
static int MOUSE_RIGHT_CLICK
          Constant used for specification of a mouse code.
static int MOUSE_RIGHT_PRESS
          Constant used for specification of a mouse code.
static int MOUSE_RIGHT_RELEASE
          Constant used for specification of a mouse code.
 
Fields inherited from class java.awt.event.MouseEvent
BUTTON1, BUTTON2, BUTTON3, MOUSE_CLICKED, MOUSE_DRAGGED, MOUSE_ENTERED, MOUSE_EXITED, MOUSE_FIRST, MOUSE_LAST, MOUSE_MOVED, MOUSE_PRESSED, MOUSE_RELEASED, MOUSE_WHEEL, NOBUTTON
 
Fields inherited from class java.awt.event.InputEvent
ALT_DOWN_MASK, ALT_GRAPH_DOWN_MASK, ALT_GRAPH_MASK, ALT_MASK, BUTTON1_DOWN_MASK, BUTTON1_MASK, BUTTON2_DOWN_MASK, BUTTON2_MASK, BUTTON3_DOWN_MASK, BUTTON3_MASK, CTRL_DOWN_MASK, CTRL_MASK, META_DOWN_MASK, META_MASK, SHIFT_DOWN_MASK, SHIFT_MASK
 
Fields inherited from class java.awt.event.ComponentEvent
COMPONENT_FIRST, COMPONENT_HIDDEN, COMPONENT_LAST, COMPONENT_MOVED, COMPONENT_RESIZED, COMPONENT_SHOWN
 
Fields inherited from class java.awt.AWTEvent
ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, COMPONENT_EVENT_MASK, consumed, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, id, INPUT_METHOD_EVENT_MASK, INVOCATION_EVENT_MASK, ITEM_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, PAINT_EVENT_MASK, RESERVED_ID_MAX, TEXT_EVENT_MASK, WINDOW_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK
 
Fields inherited from class java.util.EventObject
source
 
Constructor Summary
MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger)
          Constructs a MouseEvent object.
MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger, int button)
          Constructs a MouseEvent object.
 
Method Summary
static void addResourceTypeListener(ResourceTypeListener listener)
          Adds a ResourceTypeListener to the implementation.
static MouseEvent[] getInstances()
          Return the list of all existing instances of MouseEvent, whether they are already reserved or not.
 boolean isAvailable()
          Checks whether the given resource is currently available for reservation.
 void release()
          Releases this resource.
static void removeResourceTypeListener(ResourceTypeListener listener)
          Removes a previously attached listener.
 void reserve(boolean force, long timeout, ScarceResourceListener listener)
          Requests reservation of the given scarce resource instance.
static MouseEvent reserveOne(boolean force, long timeoutms, ScarceResourceListener listener, int id)
          Returns a reserved instance out of the pool of all MouseEvent instances.
 
Methods inherited from class java.awt.event.MouseEvent
getButton, getClickCount, getMouseModifiersText, getPoint, getX, getY, isPopupTrigger, paramString, translatePoint
 
Methods inherited from class java.awt.event.InputEvent
consume, getModifiers, getModifiersEx, getModifiersExText, getWhen, isAltDown, isAltGraphDown, isConsumed, isControlDown, isMetaDown, isShiftDown
 
Methods inherited from class java.awt.event.ComponentEvent
getComponent
 
Methods inherited from class java.awt.AWTEvent
getID, toString
 
Methods inherited from class java.util.EventObject
getSource
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MOUSE_LEFT_CLICK

public static int MOUSE_LEFT_CLICK
Constant used for specification of a mouse code. Means that the left mouse button is clicked. Value 521.


MOUSE_RIGHT_CLICK

public static int MOUSE_RIGHT_CLICK
Constant used for specification of a mouse code. Means that the right mouse button is clicked. Value 522.


MOUSE_LEFT_PRESS

public static int MOUSE_LEFT_PRESS
Constant used for specification of a mouse code. Means that the left mouse button is pressed. Value 523.


MOUSE_RIGHT_PRESS

public static int MOUSE_RIGHT_PRESS
Constant used for specification of a mouse code. Means that the right mouse button is pressed. Value 524.


MOUSE_LEFT_RELEASE

public static int MOUSE_LEFT_RELEASE
Constant used for specification of a mouse code. Means that the left mouse button is released. Value 525.


MOUSE_RIGHT_RELEASE

public static int MOUSE_RIGHT_RELEASE
Constant used for specification of a mouse code. Means that the right mouse button is released. Value 526.


MOUSE_MOVE

public static int MOUSE_MOVE
Constant used for specification of a mouse code. Means that the mouse is moved. Value 527.


MOUSE_DRAG

public static int MOUSE_DRAG
Constant used for specification of a mouse code. Means that the mouse is dragged. Value 528.


MOUSE_ENTER

public static int MOUSE_ENTER
Constant used for specification of a mouse code. Means that the mouse cursor enters the visible area of the screen controlled by this mouse. Value 529.


MOUSE_EXIT

public static int MOUSE_EXIT
Constant used for specification of a mouse code. Means that the mouse cursor exits the visible area of the screen controlled by this mouse. Value 530.

Constructor Detail

MouseEvent

public MouseEvent(Component source,
                  int id,
                  long when,
                  int modifiers,
                  int x,
                  int y,
                  int clickCount,
                  boolean popupTrigger)
Constructs a MouseEvent object.

Parameters:
source - the Component that originated the event
id - the integer that identifies the event
when - a long int that gives the time the event occurred
modifiers - the modifier keys down during event (e.g. shift, ctrl, alt, meta) Either extended _DOWN_MASK or old _MASK modifiers should be used, but both models should not be mixed in one event. Use of the extended modifiers is preferred.
x - the horizontal x coordinate for the mouse location
y - the vertical y coordinate for the mouse location
clickCount - the number of mouse clicks associated with event
popupTrigger - a boolean, true if this event is a trigger for a popup menu
See Also:
MouseEvent

MouseEvent

public MouseEvent(Component source,
                  int id,
                  long when,
                  int modifiers,
                  int x,
                  int y,
                  int clickCount,
                  boolean popupTrigger,
                  int button)
Constructs a MouseEvent object.

Parameters:
source - the Component that originated the event
id - the integer that identifies the event
when - a long int that gives the time the event occurred
modifiers - the modifier keys down during event (e.g. shift, ctrl, alt, meta) Either extended _DOWN_MASK or old _MASK modifiers should be used, but both models should not be mixed in one event. Use of the extended modifiers is preferred.
x - the horizontal x coordinate for the mouse location
y - the vertical y coordinate for the mouse location
clickCount - the number of mouse clicks associated with event
popupTrigger - a boolean, true if this event is a trigger for a popup menu
button - which of the mouse buttons has changed state. NOBUTTON, BUTTON1, BUTTON2 or BUTTON3 (as defined in java.awt.event.MouseEvent.
See Also:
MouseEvent
Method Detail

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:

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 MouseEvent reserveOne(boolean force,
                                    long timeoutms,
                                    ScarceResourceListener listener,
                                    int id)
                             throws IllegalArgumentException,
                                    TimeoutException
Returns a reserved instance out of the pool of all MouseEvent 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.
id - the integer that identifies the event
Returns:
The instance of type MouseEvent with the specified identifier 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.

getInstances

public static MouseEvent[] getInstances()
Return the list of all existing instances of MouseEvent, whether they are already reserved or not.

Returns:
list of all existing instances of MouseEvent.

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)

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.