CURSOR Procedure

Reads the position of the interactive graphics cursor from the current graphics device.

CURSOR, x, y [, wait]

wait (optional) An integer specifying when CURSOR returns. This parameter may be used interchangeably with the keywords listed below that specify the type of wait.

---

UNIX and OpenVMS Users: Not all wait modes work with all display devices. Many devices, such as Tektronix terminals, do not have the ability to return immediately, and so always wait. In addition, not all types of waiting are available for devices that do not have the ability to sense transitions or states.

---

x A named variable to receive the cursor's current column.

y A named variable to receive the cursor's current row.

Change Waits for pointer movement or button down within the currently selected window.

Data If present and nonzero, causes the values placed into x and y to be in data coordinates (the default).

Device If present and nonzero, causes the values placed into x and y to be in device coordinates.

Down Waits for a button down transition within the currently selected window.

Normal If present and nonzero, causes the values placed into x and y to be in normalized coordinates.

Nowait Reads the pointer position and button status and return immediately. If the pointer is not within the currently selected window, the device coordinates -1, -1 are returned.

Up Waits for a button up transition within the current window.

Wait Waits for a button to be depressed within the currently selected window. If a button is already pressed, returns immediately.

CURSOR enables the graphic cursor on the device and waits for the operator to position it. On devices that have a mouse, CURSOR normally waits until a mouse button is pressed. If no mouse is present, CURSOR waits for a key on the keyboard to be pressed.

The system variable !Err is set to the button status; if no mouse is present, it is set to the ASCII code of the key. Each mouse button is assigned a bit in !Errbit 0 is the left-most button, bit 1 the next, and so on.

Thus, for a three-button mouse, !Err will contain the values 1 - 7, depending upon which button or combination of buttons was pushed. For example, the left button produces a value of 1, the middle button 2, and the right button 4, while pressing the left and right buttons together produce the value 5.

The system variable !Mouse contains the X and Y position of the mouse, the mouse button status, and a date/time stamp. The mouse position is given in device coordinates. The button status appears as 1 - 7; these values are contained in the !Err system variable. The date/time stamp may not be available on all systems.

Since the values returned are, by default, in data coordinates, if no data coordinate system has been previously established, then calling CURSOR without specifying either the Normal or Device keywords will result in an error and procedural execution will be halted.

WINDOW, XSize=512, YSize=512
CURSOR, x, y, /Normal

; This returns the normalized coordinates of the point selected in 
; the graphics window when a button is pressed. The button press
; is the default event activation, and not overtly specified.

In this example, PLOTS and CURSOR are used interactively in a loop to build a sketch pad. While the cursor is in the graphics window and a button is held down, CURSOR returns the device coordinates of the cursor. The PLOTS procedure draws a line segment between the previously returned cursor position and the current cursor position.

PRO sketch
false = 0
true = 1
window, 0
XYOUTS, 2, 2, "QUIT", Size = 2, /Device

; Create a quit button in the window.

PLOTS, [0, 48, 48], [20, 20, 0], /Device
first = true
REPEAT BEGIN

CURSOR, xnew, ynew, /Device

; Get cursor position, placing the x-coordinate in xnew, and 
; the y-coordinate in ynew.

IF (xnew LE 48) AND (ynew LE 20) THEN STOP

; If cursor position is within the QUIT button, then stop.

IF first THEN BEGIN

xold = xnew
yold = ynew
first = false

ENDIF

; First time through loop, set xold and yold to be the same
; as xnew and ynew.

PLOTS, [xold, xnew], [yold, ynew], /Device

; Plot a line segment from (xold, yold) to (xnew, ynew).

xold = xnew
yold = ynew

ENDREP UNTIL FALSE
END

!Err, !Mouse, TVCRS