NAME
mouse_xy - get mouse location within window
PROTOTYPE
unitptr mouse_xy( char *pcWdw, char *fmt, unitptr uHost)
ARGUMENTS
- char *pcWdw
- window to use (can specify scaling). If w=-k is negative, the k-th predecessor window that is managed by a unit in the queue of host dest will be used.
- char *fmt
- string to specify options
- unitptr uHost
- pointer to newly created unit
INTERFACE OF CREATED UNIT:
- X_in[2]
- user-specified location (x,y) for setting a marker
(in user coordinates set by options %s, %o or %a,
see below).
- Y_in[0]:
- Marker type (one of 1..8)
- Z_in[1]:
- Mode field. Note that the modes explained below
may become modified, if the mouse unit is used
in "Autoloop mode" (cf. below).
The following modes can be set:
- -1:
- (mark-only mode) exec-routine draws a marker of shape Y_in[0] at
location given by X_in[] and returns.
(i.e. no mouse actions are evalutated)
- 0:
- (wait mode [default]) exec-routine waits until mouse button
is pressed and returns values 1,2 or 4 for
button RIGTHBUTTON, MIDDLEBUTTON, LEFTBUTTON.
If %m-option was specified, a marker
(shape given by Y_in[0] is drawn
at the screen location of the mouse pointer
at the instant of the button press.
- 1:
- (nowait mode) exec-routine polls buttons and mouse locator and returns value
RIGHTBUTTON+2*MIDDLEBUTTON+4*LEFTBUTTON,
with RIGHT..LEFTBUTTON=1, if pressed, zero else.
No marker is added (neither on the screen, nor in the
internal buffer), routine does not wait.
Position coordinates of mouse locator are written to
output pins.
- CTL_in[0]:
- control field. Value=0 switches unit off.
Values >= 1 select subsets of callbacks (cf. below)
- X_out[2]:
- scaled pixel coordinates of mouse pointer
at last button press (not valid, if return value was zero).
- Y_out[2]:
- returns untransformed (x,y) coordinates
of mouse pointer
at last button press (i.e. with respect to lower left
screen corner; not valid, if return value was zero)
- Z_out[3]:
- states of buttons 1,2,3 when routine returns.
EXECUTION OF THE CREATED UNIT:
Execution of this unit returns at output fields X_out
and Y_out the position where a
mouse button press occurred. The unit either waits
for a button press to occur with mouse pointer in window
win (if Z_in[0]==0, which is the default),
or simply polls the current button state and mouse location
without waiting (.Z_in[0]!=0. If Z_in[0]=-1,
the unit may be used to draw and store markers (see below).
String fmt may be used to alter this behaviour in
several ways and to specify options for this routine
(see below).
CONTROL MODES:
The following control modes are recognized by the ctrl_unit
routine for the mouse_xy-unit:
NST_W_REDRAW redraw all markers (%m and %f options)
stored so far.
NST_W_CLEAR clear all markers stored so far.
DESCRIPTION:
This routine creates a unit with two output fields of two
pins, which return the coordinates of the mouse pointer
with respect to the lower left corner of window w
(unless automatic scaling is active, see below) and in
absolute screen coordinates.
To obtain the current coordinate values, the exec_unit - routine
must be called. If Z_in[0]==0 (the default), it will
wait until a mouse button is
pressed while the mouse pointer is within the window wid
(this condition can be relaxed by specifying the %u-option),
see below) and return the mouse coordinates at the instant of the
button press. String fmt may be used to specify options
for this routine. Each option is of the form %f1:f2:f3c,
where f1..f3 are floating point numbers (which need not
all be present) and .c
is a control character. Currently, the following control fields
are recognized:
- %a
- automatic scaling
If this option is specified,
the routine checks, whether any special coordinate system is defined
for the specified window w and if so, automatically transforms
the mouse location into these coordinates, which are then returned
at output field X_out[2]. This is, for instance, useful
for windows created by routines xyplot and write_pix.
The presence of this option overrides any other scaling option.
- %x:yb
- specify forbidden border region extending
horizontally x pixels and vertically y pixels
inwards from the window border. I.e. the region for which mouse
events are accepted is the rectangle with lower left corner
at (x,y) and upper right corner at (dx-x-1,dy-y-1)
(with both corners included and dx, dy the window
width and height in screen pixels). Default is %0:0b.
- %pB
- (deprecated, use draw_sym instead) buffer p marker points.
At p+1 - th point, clear buffer.
- %u
- unrestricted area. Normally, button presses and mouse pointer
locations are only evaluated while the pointer is inside the window.
The %u option lifts this restriction and allows
also mouse pointer events that lie outside the window area.
- %c
- (deprecated, use draw_sym instead) connect markers by lines.
- %L
- auto-loop mode: loop continuously until pointer leaves window
- %N
- nowait-callback mode: as %L, but for usage of mouse unit
as a non-blocking continuous callback (e.g., within an
input window). Behavior is like %L (i.e., all %bL callback
functions below are applicable), but the mouse unit will
be non-blocking if there are no events available or no
mouse buttons pressed.
- %bL
- auto-loop mode: loop continuously (even if pointer is not in window),
until button b is pressed (which, in the absence of the %u option,
must occur while the pointer is in the window). Then terminate loop
(any callbacks associated with button b are
executed, before loop is terminated).
NOTE: if %L autoloop mode is on, the mouse unit will always wait for
events in its window, but for %N it will return in this case.
- %!foo
- execute named unit once when loop is started in auto-loop mode.
- %!!foo
- execute named unit continuously while loop is active in auto-loop mode.
- %!!!foo
- execute named unit once when loop is ended in auto-loop mode.
- %b!foo
- execute named unit foo once each time button b becomes pressed.
- %b!!foo
- as before, but execute named unit foo continuously
while button b is down.
- %b!!!foo
- as before, but execute named unit foo
once when button b is released.
If for the above three a second argument c>0 is specified, the corresponding
option is active only while the control input field has input value c.
In this case, several instances of each option (with different c values)
can be present, which can be selected dynamically with the control field.
- %F
- draw into frontbuffer
- %G
- draw into backbuffer
- %i1:i2:i3m
- put marker of
shape Y_in[0], color i1, size i2 and line width
i3 at mouse pointer
location when middle button press occurs (the marker is not
drawn, when the right or left button is pressed).
Defaults are %2:10:1m, i.e. a red cross mark of size 10 pixels and
one-pixel wide lines.
Any drawn marker symbol is stored internally. The markers are
redrawn, if a call ctrl_unit(NST_W_REDRAW,u) is made.
The stored markers are deleted by a call ctrl_unit(NST_W_CLEAR,u).
- %a:bf
- (deprecated, use draw_sym instead)
Surround marker position by a rectangle
of width a and height b. The rectangle will be centered
at the marker position.
- %f1:f2s
- specify that a window pixel has a size of
f1 screen pixels along the horizontal direction, and of f2
screen pixels along the vertical direction (i.e. the horizontal
and vertical mouse coordinates will be scaled by factors 1/f1 and 1/f2).
- %f1:f2o
- add an offset vector (f1,f2)
to the scaled mouse coordinates. When in drawing mode, the
offset vector (f1,f2) is subtracted from the input vector X_in
to obtain the marker position (this convention ensures
that X_in = X_out always holds).
In the case of conflicting options, the rightmost option of a set of
conflicting options will prevail.
EXAMPLE:
If the options
%L %0:2L %!!foo %1!doit %2!finish
are given, this will cause the mouse unit to loop
until the pointer leaves the associated window or one of
buttons 0 or 2 is pressed (here, %0L %2L would be equivalent).
At each loop iteration, named unit foo will be executed.
In addition, at each press of button 1, named unit doit will be
executed. Finally, if button 2 is used to leave the loop, named
unit finish will be executed once at that moment.
(Deprecated: To draw markers and add them to the already stored markers, the
exec - routine can be called with Z_in[0] = -1.
This draws a marker of shape Y_in[0] at the location
specified by X_in[] (using
the same coordinate system that was specified
for X_out[] )).
FILE
/homes/jontrup/nst5/man/../o.sol2//../nstsrc/nst_plot.c