CURSOR Procedure

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

Usage

CURSOR, x, y[, wait]

Input Parameters

wait—(optional) An integer specifying when CURSOR returns. This parameter may be used interchangeably with the five keywords listed in Five Keywords Specifying Wait Type that specify the type of wait.

Five Keywords Specifying Wait Type
Value	Keyword	Action
0	Nowait	Return immediately.
1	Wait	Return if button pressed (the default value).
2	Change	Return if button pressed, changed, or pointer moved.
3	Down	Return when button down transition is detected.
4	Up	Return when button up transition is detected.

Note: 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.

Output Parameters

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

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

Keywords

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.

Discussion

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.

Note: Not all graphics devices have interactive cursors.

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 !Err—bit 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.

Example 1

This returns 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.

WINDOW, XSize=512, YSize=512
PRINT, 'Select a point in the window.'
CURSOR, x, y, /Normal
PRINT, 'Normalized coordinates of selected point: ', $
   STRTRIM(x,2), '  ', STRTRIM(y,2)

Example 2

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 cursor_ex2
   WINDOW, 0
   ; Create a quit button in the window.
   XYOUTS, 5, 5, "QUIT", Size=2, /Device
   PLOTS, [0, 75, 75], [35, 35, 0], /Device
   end_loop = 0
   ; Get cursor position, placing x-coordinate in xnew, 
   ; and the y-coordinate in ynew.
   CURSOR, xnew, ynew, /Device
   IF (xnew GT 75) OR (ynew GT 35) THEN BEGIN
      xold = xnew
      yold = ynew
      WHILE (end_loop EQ 0) DO BEGIN
         ; Get cursor position, placing x-coordinate in xnew, 
         ; and the y-coordinate in ynew.
         CURSOR, xnew, ynew, /Device
         ; If cursor position is within the QUIT button,
         ; then stop.
         IF (xnew GT 75) OR (ynew GT 35) THEN BEGIN
            ; Plot a line segment from (xold, yold)
            ; to (xnew, ynew).
            PLOTS, [xold, xnew], [yold, ynew], /Device
           xold = xnew
           yold = ynew
         ENDIF ELSE end_loop = 1
      ENDWHILE
   ENDIF
END