The CURSOR procedure is used to read the position of the interactive graphics cursor from the current graphics device. Note that not all graphics devices have interactive cursors. CURSOR enables the graphic cursor on the device and optionally waits for the operator to position it. On devices that have a mouse, CURSOR normally waits until a mouse button is pressed (or already down). If no mouse buttons are present, CURSOR waits for a key on the keyboard to be pressed. The X and Y arguments are named variables that receive the cursor position. Normally, the position is reported in data coordinates, but the DATA, DEVICE, and NORMAL keywords can be used to explicitly specify the coordinate system.
When CURSOR returns, the button field of the system variable !MOUSE is set to the button status. Each mouse button is assigned a bit in the button field. Bit 0 is the leftmost button (value = 1), bit 1 is the middle button (value = 2), and bit 3 is the rightmost button (value = 4) for the typical three-button mouse.
Examples
Activate the graphics cursor, select a point in the graphics window, and return the position of the cursor in device coordinates. Enter:
CURSOR, X, Y, /DEVICE
Move the cursor over the graphics window and press the mouse button. The position of the cursor in device coordinates is stored in the variables X and Y. To label the location, enter:
XYOUTS, X, Y, 'X marks the spot.', /DEVICE
The following two programs demonstrate simple applications of the interactive graphics cursor and the CURSOR procedure.
The first routine is a simple drawing program. Straight lines are connected to positions marked with the left or middle mouse buttons until the right button is pressed.
PRO EX_DRAW
ERASE
CURSOR, X, Y, /NORMAL, /DOWN
WHILE (!MOUSE.button NE 4) DO BEGIN
CURSOR, X1, Y1, /NORM, /DOWN
PLOTS,[X,X1], [Y,Y1], /NORMAL
X = X1 & Y = Y1
ENDWHILE
END
The second simple procedure can be used to label plots using the cursor to position the text:
PRO LABEL, TEXT
PRINT, 'Use the mouse to mark the text position:'
CURSOR, X, Y, /NORMAL, /DOWN
XYOUTS, X, Y, TEXT, /NORMAL, /NOCLIP
END
At the command line, set TEXT equal to the string of text you want to appear in the window. For example, enter,
Text = 'My Sample Text'
Compile and run the program by entering the following at the command line, passing your text string to the procedure:
LABEL, TEXT
Next, move the pointer device to the desired spot in the window and click the locator button. Consider how you might augment the LABEL procedure to allow you to specify the size and font of the annotation text.
Avoid Using CURSOR with Draw Widgets
Note that the CURSOR procedure is only for use with IDL direct graphics windows. It should not be used with draw widgets. To obtain the cursor position and button state information from a draw widget, set the BUTTON_EVENTS and MOTION_EVENTS keywords to WIDGET_DRAW, and examine the X, Y, PRESS, and RELEASE fields in the structures returned by the draw widget in response to cursor events. See WIDGET_DRAW for more information.
Using CURSOR with the TEK Device
Note that for the CURSOR procedure to work properly with Tektronix terminals, you may need to execute the command, DEVICE, GIN_CHARS=6.
Syntax
CURSOR, X, Y [, Wait | [, /CHANGE | , /DOWN | , /NOWAIT | , /UP | , /WAIT]] [, /DATA | , /DEVICE, | , /NORMAL]
Arguments
X
A named variable to receive the cursor’s current column position.
Y
A named variable to receive the cursor’s current row position.
Wait
An integer that specifies the conditions under which CURSOR returns. This parameter can be used interchangeably with the keyword parameters listed below that specify the type of wait. The default value is 1. The table below describes each type of wait.
Note that not all modes of waiting work with all display devices.
Wait Value |
Corresponding Keyword
|
Action |
0 |
NOWAIT |
Return immediately.
|
1 |
WAIT |
Return if a button is down.
|
2 |
CHANGE |
Return if a button is pressed, released, or the pointer is moved.
|
3 |
DOWN |
Return when a button down transition is detected.
|
4 |
UP |
Return when a button up transition is detected.
|
Keywords
CHANGE
Set this keyword to wait for pointer movement or button transition within the currently selected window.
DATA
Set this keyword to return X and Y in data coordinates.
DOWN
Set this keyword to wait for a button down transition within the currently selected window.
DEVICE
Set this keyword to return X and Y in device coordinates.
NORMAL
Set this keyword to return X and Y in normalized coordinates.
NOWAIT
Set this keyword to read 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
Set this keyword to wait for a button up transition within the current window.
WAIT
Set this keyword to wait for a button to be depressed within the currently selected window. If a button is already pressed, return immediately.
Version History
See Also
RDPIX Procedure, TVCRS Procedure, CURSOR_CROSSHAIR (and other CURSOR_ keywords), WIDGET_DRAW, !MOUSE