5.12 Cursor Control and Location - SWT: The Standard Widget Toolkit

5.12 Cursor Control and Location

Displays provide API to identify the control that has the cursor and get and set the location of the cursor. Because there is only one cursor on the desktop, it is shared by all applications. Moving the cursor on the display will move the cursor for every application on the desktop.

5.12.1 Getting the Cursor Control

At any time, the cursor can be over a control or the desktop. Although it is possible to write code that gets the list of shells and recursively queries the bounds of their children to find the child that is under the cursor, this is inefficient and can be problematic. When the user clicks or moves the mouse, the operating system determines where the mouse operation occurred. This process is called hit testing. Normally, mouse events are delivered to the deepest child in the hierarchy^[9] but this is not always the case. For example, a control that is disabled does not receive mouse clicks, even though it may contain the cursor. This prevents the control from acting on a mouse click while it is disabled.

^[9] In this case, we are talking about the containment hierarchy made up of controls and their children, so that the control that is returned would be the one that is under the cursor that does not have children that are also under the cursor.

To match the rules for operating system hit testing, you should use the getCursorControl() method when you need to hit test your controls.

getCursorControl() Returns the control that would receive the SWT .MouseDown event if the mouse were clicked at the current cursor position or null if the event would not be sent to a control on this display.

The following example code uses getCursorControl() to detect when the mouse enters and exits the area covered by each control. Note that there are already events to do this for controls (see SWT.MouseEnter and SWT.MouseExit in the chapter The Mouse), so this code does not have practical value beyond demonstrating the API.

public static void main(String[] args) {

    final Display display = new Display();

    final Control[] last = new Control[1];

    display.timerExec(100, new Runnable() {

        public void run() {

            Control control = display.getCursorControl();

            if (control != last[0]) {

                if (last[0] != null

                    && !last[0].isDisposed()) {

                    System.out.println("Exit:" + last[0]);

                }

                if (control != null

                    && !control.isDisposed()) {

                    System.out.println("Enter:" + control);

                }

            }

            last[0] = control;

            display.timerExec(100, this);

        }

    });

    Shell shell = new Shell(display);

    shell.pack();

    shell.open();

    while (!shell.isDisposed()) {

        if (!display.readAndDispatch()) display.sleep();

    }

    display.dispose();

}

The example checks the cursor control every 100 milliseconds; if it has changed, the previous focus control and the new one are printed.

5.12.2 Setting and Getting the Cursor Location

An application program can determine the location of the cursor using the Display method.

getCursorLocation() Returns the location of the cursor in coordinates that are relative to the display.

Note that the coordinates returned by getCursorLocation() differ from the coordinates reported in a mouse down event. The coordinates reported in mouse down events are relative to the control that received the event. In addition, because the mouse may have moved since the last mouse event was processed, the actual mouse location can be different. The getCursorLocation() method always returns the actual mouse location at the time it was called.

The following line of code queries the cursor location.

Point location = display.getCursorLocation();

Setting the location of the cursor is also supported using the following Display methods.

setCursorLocation(int x, int y) Moves the cursor to the location (x, y) relative to the origin of the display.

setCursorLocation(Point p) Equivalent to setCursorLocation(p.x, p.y).

It is considered bad user interface design to move the cursor using these methods because the user expects to be in control of the cursor location. If your application changes the location of the cursor programmatically, this expectation is broken. In fact, some windowing systems, such as GTK, do not support setting the cursor location. For both of these reasons, you should avoid calling setCursorLocation() unless it is absolutely necessary for your application.