Structural Informatics Group (SIG) logo
Home | Projects | Demos | Downloads | Publications | Local Info | About Us | New site
Go to the first, previous, next, last section, table of contents.

:READ-MOUSE-STATE

source files: [xc]cmr.[ch]

SYNTAX

(SEND <cmr> :READ-MOUSE-STATE
  [ :BLOCK-UNTIL-INPUT-ARRIVES NIL ]
)

DESCRIPTION

This message is normally sent once per frame, to read the current state of the mouse and store it in XG.3D-MOUSE-ROW, XG.3D-MOUSE-COL and XG.3D-MOUSE-STATE. The the resulting XG.3D-MOUSE-STATE value is: :DOWNCLICK if a mouse button-press event was read, and :UPCLICK if a mouse button-release event was read. If no mouse button-press events are available, and if this is the first time :READ-MOUSE-STATE has been invoked this frame (that is, since the last :NEXT-FRAME message), then XG.3D-MOUSE-STATE is set to :DRAG if the last real mouse event was a :DOWNCLICK, and to :SELECT if the last real mouse event was an :UPCLICK. In all other cases, XG.3D-MOUSE-STATE is set to NIL.

(This message also sets XG.3D-MOUSE-PRESSURE to 1024 if the button is pressed, else 0. This is not terribly useful per se, but provides some minimal compatability with the Wacom pressure stylus driver in xbtp/c/xbtp.c, which returns useful pressure information via this global variable.)

Unless the optional

:BLOCK-UNTIL-INPUT-ARRIVES NIL

is supplied, this call will wait until a mouseclick or keyboard char arrives, in order to keep the application from wasting CPU cycles by busywaiting. Many graphics programs are expected to continuously update the screen even in the absence of graphics input, of course: these should set the option to NIL.

In all cases (including XG.3D-MOUSE-STATE set to NIL) XG.3D-MOUSE-ROW/COL are set to the pixel location of the mouse within the current window, origin being (0,0) at lower-left pixel. If the actual mouse location is not within the window, ROW/COL are set to the nearest pixel which *is* within the window.

While checking for mouse keyclick events, the :READ-MOUSE-STATE call may encounter keyboard characters or REDRAWs in the event queue. If so, and if the appropriate hook is bound to a non-nil value, the XG.3D-KEYBOARD-CHAR-HOOK fn(s) are called with XG.3D-KEYBOARD-CHAR bound to the character read, or else the XG.3D-REDRAW-HOOK fn(s) are called.

The return value is NIL unless events were read from the event queue. Note that the return value is non-NIL if *any* events were read, not just if mouse events were read! This is a feature, not a bug.

The :READ-MOUSE-STATE and :RUN-WIDGETS messages are designed to work nicely together, typically in a loop very like

(loop
  (let ((events-read (send (car list-of-all-cameras) :READ-MOUSE-STATE)))
    (dolist (cmr list-of-all-cameras)   (send cmr :RUN-WIDGETS))
    (unless events-read (return))))

The example assumes that list-of-all-cameras is bound to a list of all cameras currently being drawn in the window.

The :READ-MOUSE-STATE message could easily have been combined with the :RUN-WIDGETS message. The reason for not combining them (and for keeping the :READ-MOUSE-STATE semantics as simple as possible) is to make it easy for the application programmer to substitute another device for the standard system mouse, if so desired: she need only set XG.3D-MOUSE-STATE, XG.3D-MOUSE-ROW and XG.3D-MOUSE-COL by hand once each frame, and then call :RUN-WIDGETS.


Go to the first, previous, next, last section, table of contents.