Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-Fileevnt_multi()
Kbshift()
vq_mouse()
Event Library
evnt_button()                                                           AES

Syntax

WORD evnt_button( clicks, mask, state, mx, my, button, kstate )
WORD clicks, mask, state;
WORD *mx, *my, *button, *kstate;

Function       evnt_button() releases control to the operating system until
               the specified mouse button event has occurred.

Opcode         21 (0x15)

Availability   All AES versions.

Parameters     clicks specifies the number of mouse-clicks that must occur
               before returning.
               mask specifies the mouse buttons to wait for as follows:

               Name             mask     Meaning

               LEFT_BUTTON      0x01     Left mouse button

               RIGHT_BUTTON     0x02     Right mouse button

               MIDDLE_BUTTON    0x04     Middle button (this button would be
                                         the first button to the left of the
                                         rightmost button on the device).

               -                0x08     Other buttons (0x08 is the mask for
                                .        the button to the immediate left of
                                .        the middle button. Masks continue
                                         leftwards).

               state specifies the button state that must occur before
               returning as follows:

               mask   Meaning

               0x00   All buttons released

               0x01   Left button depressed

               0x02   Right button depressed

               0x04   Middle button depressed

               0x08   etc...
                .
                .

               mx is a pointer to a WORD which upon return will contain the
               x-position of the mouse pointer at the time of the event.
               my is a pointer to a WORD which upon return will contain the
               y-position of the mouse pointer at the time of the event.
               button is a pointer to a WORD which upon return will contain
               the mouse button state as defined in state.
               kstate is a pointer to a WORD which upon return will contain
               the current status of the keyboard shift keys. The value is
               a bit-mask defined as follows:

               Name             Mask     Key

               K_RSHIFT         0x01     Right Shift

               K_LSHIFT         0x02     Left Shift

               K_CTRL           0x04     Control

               K_ALT            0x08     Alternate

Binding        intin[0] = clicks;
               intin[1] = mask;
               intin[2] = state;

               crys_if(0x15);

               *mx = intout[1];
               *my = intout[2];
               *button = intout[3];
               *kstate = intout[4];

               return intout[0];

Return Value   Upon exit, evnt_button() returns a WORD indicating the number
               of times the mouse button state matched state.

Comments       A previously undocumented feature of this call is accessed by
               logically OR'ing the clicks parameter with 0x100 or 0x200.
               0x100 causes the call to return when independent buttons are
               depressed except combination of both and 0x200 for any
               combination. For example, a mask value of 0x03 will return
               when both the left and right mouse buttons are depressed.
               A clicks value of 0x202 will cause the call to return when
               either button is depressed.

               The values 0x103, 1, 3 are for the clicks, mask and state
               are the best. Other combinations may generate too many
               messages what could cause problems especially in
               Multitasking operating systems.

               This method works with evnt_multi() as well.

See Also       evnt_multi(), Kbshift(), vq_mouse()

Group          Event Library