SUGGESTED FIX
Name: rpR10076 Date: 07/21/2003
Here're the new APIs being implemented for this RFE.
New class added to java.awt package:
/**
* A class that describes the pointer position.
* It provides the <code>GraphicsDevice</code> where the
* pointer is and the <code>Point</code> that represents
* the coordinates of the pointer.
* <p>
* Instances of this class should be obtained via
* {@link MouseInfo#getPointerInfo}.
* The <code>PointerInfo</code> instance is not updated dynamically
* as the mouse moves. To get the updated location, you must call
* {@link MouseInfo#getPointerInfo} again.
*
* @see MouseInfo#getDefaultMouseInfo
* @see MouseInfo#getPointerInfo
*/
public class java.awt.PointerInfo {
/**
* Returns the <code>GraphicsDevice</code> where the mouse pointer
* was at the moment this <code>PointerInfo</code> was created.
*
* @return <code>GraphicsDevice</code> corresponding to the pointer
* @since 1.5
*/
public GraphicsDevice getDevice();
/**
* Returns the <code>Point</code> that represents the coordinates
* of the pointer on the screen. See {@link MouseInfo#getPointerInfo}
* for more information about coordinate calculation for multiscreen
* systems.
*
* @see MouseInfo
* @see MouseInfo#getPointerInfo
* @return coordinates of mouse pointer
* @since 1.5
*/
public Point getLocation();
}
New class added to java.awt package:
/**
* <code>MouseInfo</code> provides methods for getting information about the mouse,
* such as mouse pointer location and the number of mouse buttons.
*/
public class MouseInfo {
/**
* Returns a <code>PointerInfo</code> instance that represents the current
* location of the mouse pointer.
* The <code>GraphicsDevice</code> stored in this <code>PointerInfo</code>
* contains the mouse pointer. The coordinate system used for the mouse position
* depends on whether the <code>GraphicsDevice</code> is part of a virtual
* screen device.
* For virtual screen devices, the coordinates are given in the virtual
* coordinate system, otherwise they are returned in the coordinate system
* of the <code>GraphicsDevice</code>. See {@link GraphicsConfiguration} for
* more information about the virtual screen devices.
* On the systems without a mouse, returns <code>null</code>.
* <p>
* If there is a security manager, its <code>checkPermission</code> method
* is called with an <code>AWTPermission("watchMousePointer")</code>
* permission before creating and returning a <code>PointerInfo</code>
* object. This may result in a <code>SecurityException</code>.
*
* @exception HeadlessException if GraphicsEnvironment.isHeadless() returns true
* @exception SecurityException if a security manager exists and its
* <code>checkPermission</code> method doesn't allow the operation
* @see GraphicsConfiguration
* @see SecurityManager#checkPermission
* @see java.awt.AWTPermission
* @return location of the mouse pointer
* @since 1.5
*/
public static PointerInfo getPointerInfo() throws HeadlessException;
/**
* Returns the number of buttons on the mouse.
* On systems without a mouse, returns <code>-1</code>.
*
* @exception HeadlessException if GraphicsEnvironment.isHeadless() returns true
* @return number of buttons on the mouse
* @since 1.5
*/
public static int getNumberOfButtons() throws HeadlessException;
}
New method added to java.awt.Component:
/**
* Returns the position of the mouse pointer in this <code>Component</code>'s
* coordinate space if the <code>Component</code> is directly under the mouse
* pointer, otherwise returns <code>null</code>.
* If the <code>Component</code> is not showing on the screen, this method
* returns <code>null</code> even if the mouse pointer is above the area
* where the <code>Component</code> would be displayed.
* If the <code>Component</code> is partially or fully obscured by other
* <code>Component</code>s or native windows, this method returns a non-null
* value only if the mouse pointer is located above the unobscured part of the
* <code>Component</code>.
* <p>
* For <code>Container</code>s it returns a non-null value only if the mouse
* is above the <code>Container</code> itself or above any of its children.
* Use {@link Container#getMousePosition(boolean)} if you need to exclude children.
* <p>
* Sometimes the exact mouse coordinates are not important, and the only thing
* that matters is whether a specific <code>Component</code> is under the mouse
* pointer. If the return value of this method is <code>null</code>, mouse
* pointer is not directly above the <code>Component</code>.
*
* @exception HeadlessException if GraphicsEnvironment.isHeadless() returns true
* @see #isShowing
* @see Container#getMousePosition
* @return mouse coordinates relative to this <code>Component</code>, or null
* @since 1.5
*/
public Point getMousePosition() throws HeadlessException;
New method added to java.awt.Container:
/**
* Returns the position of the mouse pointer in this <code>Container</code>'s
* coordinate space if the <code>Container</code> is under the mouse pointer,
* otherwise returns <code>null</code>.
* This method is similar to {@link Component#getMousePosition()} with the exception
* that it can take the <code>Container</code>'s children into account.
* If <code>allowChildren</code> is <code>false</code>, this method will return
* a non-null value only if the mouse pointer is above the <code>Container</code>
* directly, not above the part obscured by children.
* If <code>allowChildren</code> is <code>true</code>, this method returns
* a non-null value if the mouse pointer is above <code>Container</code> or any
* of its descendants.
*
* @exception HeadlessException if GraphicsEnvironment.isHeadless() returns true
* @param allowChildren true if children should be taken into account
* @see Component#getMousePosition
* @return mouse coordinates relative to this <code>Component</code>, or null
* @since 1.5
*/
public Point getMousePosition(boolean allowChildren) throws HeadlessException;
======================================================================
|
Java
