pick

Synopsis

Display the coordinates of one or more mouse or key presses.

Syntax

pick()
pick(count)
pick(count, eventmask)
pick(id)
pick(id, count)
pick(id, count, eventmask)

Description

The function arguments.

Argument	Description
count	The number of events to capture; default is 1.
eventmask	Which type of events to capture (the default is taken from the pick.mask preference setting).
id	A ChipsId structure identifying the item.

The pick command allows the user to obtain the location of the cursor when a specified event is registered. Pick may be used to approximate the location of data points in a plot or to determine the location of where to place a label, for example. When an event is registered, the coordinates are printed to standard output as an (x,y) coordinate pair.

Valid event types for the eventmask argument:

Event type	Numeric value	Description
KEY_PRESS	0x01	pressing any key
KEY_RELEASE	0x10	releasing any key
BTNS_DOWN	0x0E	clicking any mouse button
BTN1_DOWN	0x02	clicking the left mouse button
BTN2_DOWN	0x04	clicking the middle mouse button
BTN3_DOWN	0x08	clicking the right mouse button
BTNS_UP	0xE0	releasing any mouse button
BTN1_UP	0x20	releasing the left mouse button
BTN2_UP	0x40	releasing the middle mouse button
BTN3_UP	0x80	releasing the right mouse button

The default eventmask value is "KEY_PRESS|BTNS_DOWN"; this can be changed by setting the pick.mask preference. Note that when more than one entry is specified, they are joined via the | (vertical pipe) symbol.

Number of events

The number of events to capture may be set by the user via the count parameter; the default value is 1. A value of 0 indicates that the pick should continue until the user uses the escape key (<ESC>) to end the pick. A count value greater than 0 indicates that the pick should continue until the specified number of events has occurred.

To capture an array of pick points, use the get_pick command.

Examples

Example 1

chips> pick()
(4.20919,2.70993)

Use the pick command to determine the approximate location of one point within a plot.

Example 2

chips> clear()
chips> add_image("evt2.fits[sky=circle(4095,4095,500)][bin sky=1]")
chips> pick()
(239.559, 27.2719)
chips> set_xaxis(["tickformat", "%ra"])
chips> set_yaxis(["tickformat", "%dec"])
chips> pick()
(15:58:14, +27:16:17)

Here we display an image of a Chandra observation, which defaults to using decimal degrees for both axes. The first pick() call uses this format ("%g") when returning values. We then change to use sexagesimal notation for both axes and find that pick() uses this format when returning coordinates.

Example 3

chips> id = ChipsId()
chips> id.coord_sys = FRAME_NORM
chips> pick(id, 2)

Pick two locations in frame normalized coordinates, using the default eventmask.

Example 4

chips> id = ChipsId()
chips> id.coord_sys = DATA
chips> pick(id, 0, BTN3_DOWN)

Print the cursor location in data coordinates whenever the right mouse button is pressed, until the Escape key is pressed. If

chips> pick(id, 0, KEY_PRESS)

had been used instead then the location would be recorded whenever a key was pressed instead (the Escape key is not considered a key press in this context; it exits the pick call instead).

Bugs

The button event types are not processed correctly

The button-up event types - such as BTNS_UP and BTN1_UP - are not handled correctly and should not be used. The button-down evens - such as BTNS_DOWN - may also incorrectly register up events; this may mean duplicated positions are reported to the screen.

Do not use when the window display is turned off

It is possible to hang ChIPS if you use pick with a window which was created with its display attribute set to False and this attribute has remained unchanged.

See the bugs pages on the ChIPS website for an up-to-date listing of known bugs.