Reference Guide > C Routines > CURSOR Procedure
  

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.
 
Table 4-2: 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
ChangeWaits for pointer movement or button down within the currently selected window.
DataIf present and nonzero, causes the values placed into x and y to be in data coordinates (the default).
DeviceIf present and nonzero, causes the values placed into x and y to be in device coordinates.
DownWaits for a button down transition within the currently selected window.
NormalIf 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.
UpWaits 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 !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.
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
See Also
!Err,   !Mouse,  TVCRS

Version 2017.0
Copyright © 2017, Rogue Wave Software, Inc. All Rights Reserved.