CURSOR Procedure

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

   ; Start with a blank screen:

   ERASE

   ; Get the initial point in normalized coordinates:

   CURSOR, X, Y, /NORMAL, /DOWN

   ; Repeat until right button is pressed. Get the second point.

   ; Draw the line. Make the current second point be the new first.

   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:

; Text is the string to be written on the screen:

PRO LABEL, TEXT

   ; Ask the user to mark the position:

   PRINT, 'Use the mouse to mark the text position:'

   ; Get the cursor position after pressing any button:

   CURSOR, X, Y, /NORMAL, /DOWN

   ; Write the text at the specified position.

   ; The NOCLIP keyword is used to ensure that

   ; the text will appear even if it is outside

   ; the plotting region.

   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

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

Original

Introduced