NAME

PROTOTYPE

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:

CONTROL MODES:

   NST_W_REDRAW redraw all markers (%m and %f options)
                    stored so far.
   NST_W_CLEAR clear all markers stored so far.

DESCRIPTION:

%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.

%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).

EXAMPLE:

     %L %0:2L %!!foo %1!doit %2!finish

FILE