Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

Event Library
[AES Function Reference]

wait for user response More...

Functions

short mt_evnt_button (short Clicks, short WhichButton, short WhichState, short *Mx, short *My, short *ButtonState, short *KeyState, short *global_aes)
short mt_evnt_dclick (short ToSet, short SetGet, short *global_aes)
short mt_evnt_keybd (short *global_aes)
short mt_evnt_mesag (short MesagBuf[], short *global_aes)
short mt_evnt_mouse (short EnterExit, short InX, short InY, short InW, short InH, short *OutX, short *OutY, short *ButtonState, short *KeyState, short *global_aes)
short mt_evnt_multi (short Type, short Clicks, short WhichButton, short WhichState, short EnterExit1, short In1X, short In1Y, short In1W, short In1H, short EnterExit2, short In2X, short In2Y, short In2W, short In2H, short MesagBuf[], unsigned long Interval, short *OutX, short *OutY, short *ButtonState, short *KeyState, short *Key, short *ReturnCount, short *global_aes)
short mt_evnt_multi_fast (const EVMULT_IN *em_i, short MesagBuf[], EVMULT_OUT *em_o, short *global_aes)
short mt_evnt_timer (unsigned long Interval, short *global_aes)
void mt_EVNT_multi (short evtypes, short nclicks, short bmask, short bstate, const MOBLK *m1, const MOBLK *m2, unsigned long ms, EVNT *event, short *global_aes)

Detailed Description

wait for user response

The Event Library consists of a group of system calls which are used to monitor system messages including mouse clicks, keyboard usage, menu bar interaction, timer calls, and mouse tracking.


Function Documentation

short mt_evnt_button short  clicks,
short  mask,
short  state,
short mx,
short my,
short mbutton,
short kmeta,
short global_aes
 

releases control to the operating system until the specified mouse button event has occurred.

Parameters:
clicks specifies the number of mouse-clicks that must occur before returning
mask specifies the mouse buttons to wait for as follows:
  • 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).
  • (unamed) (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:
  • 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.
[option CHECK_NULLPTR] mx may be NULL
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.
[option CHECK_NULLPTR] my may be NULL
mbutton is a pointer to a WORD which upon return will contain the mouse button state as defined in state.
[option CHECK_NULLPTR] mbutton may be NULL
kmeta 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: [option CHECK_NULLPTR] kmeta may be NULL
global_aes global AES array
Returns:
a WORD indicating the number of times the mouse button state matched state.
Since:
All AES versions.
See also:
mt_evnt_multi(), Kbshift(), vq_mouse()
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 mt_evnt_multi() as well.

short mt_evnt_dclick short  value,
short  sflag,
short global_aes
 

sets the mouse double-click response rate. This call is global, and thus, affects all applications.

Parameters:
value specifies the double-click rate as follows:
  • 0 Slowest
  • 1
  • 2
  • 3
  • 4 Fastest
sflag If sflag is EDC_INQUIRE then value is ignored and the current double-click rate is returned. If sflag is EDC_SET then the value is used to set a new double-click rate value.
global_aes global AES array
Returns:
the newly set or current double-click rate based on sflag.
Since:
All AES versions.
Because this setting is global for all applications, Atari has strongly recommended that developers use this call only where appropriate (such as in a configuration CPX like the General Setup CPX included with XCONTROL).

short mt_evnt_keybd short global_aes  ) 
 

relinquishes program control to the operating system until a valid keypress is available in the applications' message pipe.

Parameters:
global_aes global AES array
Returns:
16-bit value containing the ASCII code of the key entered in the lower eight bits and the scan code in the upper 8-bits.
Since:
All AES versions.
See also:
mt_evnt_multi()
TOS versions released at or above 2.06 and 3.06 disabled reception of keys 1 through 9 on the numeric keypad when used in conjunction with the alternate key. Users may now enter the full range of ASCII values by holding down alt, typing in the decimal ASCII code, and then releasing the alt key. These keys, therefore, should not be used by applications. The standard numeric keypad is still available.

Note:
The return value of this funtion is often named kreturn if it is used in the other mt_evnt functions.

short mt_evnt_mesag short  msg[],
short global_aes
 

releases control to the operating system until a valid system message is available in the applications' message pipe.

Parameters:
msg A pointer to an array of 8 WORD's to be used as a message buffer. This array contains:
  • msg[0] is the message type.
  • msg[1] is the AES application identifier of the sender
  • msg[2] contains the length of the message beyond 16 bytes (use mt_appl_read() to read the excess) Currently all system messages return 0 in this slot. Only user-defined messages utilize a higher value
  • other fields depend on the type of message.
global_aes global AES array
Returns:
Currently reserved by Atari and currently is defined as a value of 1.
Since:
All AES versions.
See also:
mt_evnt_multi()
Here is a list of system messages. You may refer to their documentation for more details about the content of the msg[] buffer.

short mt_evnt_mouse short  flag,
short  x,
short  y,
short  w,
short  h,
short mx,
short my,
short mbutton,
short kmeta,
short global_aes
 

releases control to the operating system until the mouse enters or leaves a specified area of the screen.

Parameters:
flag specifies the event to wait for as follows:
  • MO_ENTER Wait for mouse to enter rectangle
  • MO_LEAVE Wait for mouse to leave rectangle
x 
y 
w 
h The rectangle to watch
mx 
my WORD pointers which will be filled in with the final position of the mouse.
[option CHECK_NULLPTR] mx and my may be NULL
mbutton is a WORD pointer which will be filled in upon return with the final state of the mouse button as defined in mt_evnt_button().
[option CHECK_NULLPTR] mbutton may be NULL
kmeta is a WORD pointer which will be filled in upon return with the final state of the keyboard shift keys as defined in mt_evnt_button().
[option CHECK_NULLPTR] kmeta may be NULL
global_aes global AES array
Returns:
should be reserved (and should always be 1). Actually it depends on OS you are running, so it is not reserved any more.
Since:
All AES versions.
See also:
mt_evnt_multi()
The mt_evnt_multi() function can be used to watch two mouse/rectangle events as opposed to one.

void mt_EVNT_multi short  evtypes,
short  nclicks,
short  bmask,
short  bstate,
const MOBLK m1,
const MOBLK m2,
unsigned long  ms,
EVNT event,
short global_aes
 

see mt_evnt_multi().

Parameters:
evtypes see mt_evnt_multi()
nclicks see mt_evnt_multi()
bmask see mt_evnt_multi()
bstate see mt_evnt_multi()
m1 see mt_evnt_multi()
m2 see mt_evnt_multi()
ms see mt_evnt_multi()
event see mt_evnt_multi()
global_aes global AES array
Returns:
see mt_evnt_multi()
Since:
see mt_evnt_multi()

short mt_evnt_multi short  events,
short  bclicks,
short  bmask,
short  bstate,
short  m1_leave,
short  m1_x,
short  m1_y,
short  m1_w,
short  m1_h,
short  m2_leave,
short  m2_x,
short  m2_y,
short  m2_w,
short  m2_h,
short  msg[],
unsigned long  interval,
short mx,
short my,
short mbutton,
short kmeta,
short kreturn,
short mbclicks,
short global_aes
 

suspends the application until a valid message that the application is interested in occurs.

Parameters:
events is a bit mask which tells the function which events your application is interested in. You should logically 'OR' any of the following values together:
  • MU_KEYBD Wait for a user keypress.
  • MU_BUTTON Wait for the specified mouse button state.
  • MU_M1 Wait for a mouse/rectangle event as specified.
  • MU_M2 Wait for a mouse/rectangle event as specified.
  • MU_MESAG Wait for a message.
  • MU_TIMER Wait the specified amount of time.
bclicks see mt_evnt_button()
bmask see mt_evnt_button()
bstate see mt_evnt_button()
m1_leave see mt_evnt_mouse()
m1_x see mt_evnt_mouse()
m1_y see mt_evnt_mouse()
m1_w see mt_evnt_mouse()
m1_h see mt_evnt_mouse()
m2_leave see mt_evnt_mouse()
m2_x see mt_evnt_mouse()
m2_y see mt_evnt_mouse()
m2_w see mt_evnt_mouse()
m2_h see mt_evnt_mouse()
msg see mt_evnt_mesag()
interval see mt_evnt_timer()
mx see mt_evnt_button()
[option CHECK_NULLPTR] mx may be NULL
my see mt_evnt_button()
[option CHECK_NULLPTR] my may be NULL
mbutton see mt_evnt_button()
[option CHECK_NULLPTR] mbutton may be NULL
kmeta see mt_evnt_button()
[option CHECK_NULLPTR] kmeta may be NULL
kreturn the return value of the mt_evnt_keybd()
[option CHECK_NULLPTR] kreturn may be NULL
mbclicks see mt_evnt_button()
[option CHECK_NULLPTR] mbclicks may be NULL
global_aes global AES array
Returns:
a bit mask of which events actually happened as in events. This may be one or more events and your application should be prepared to handle each.
Since:
All AES versions. Under TOS 1.0, calling this function from a desk accessory with the MU_TIMER mask and interval being equal to 0 could hang the system.
See also:
mt_evnt_button(), mt_evnt_keybd(), mt_evnt_mesag(), mt_evnt_mouse(), mt_evnt_timer()
This call combines the functionality of mt_evnt_button(), mt_evnt_keybd(), mt_evnt_mesag(), mt_evnt_mouse(), and mt_evnt_timer() into one call. This call is usually the cornerstone of all GEM applications that must process system events.

short mt_evnt_multi_fast const EVMULT_IN em_in,
short  msg[],
EVMULT_OUT em_out,
short global_aes
 

suspends the application until a valid message that the application is interested in occurs.

Parameters:
em_in see the input arguments of mt_evnt_multi()
msg see mt_evnt_mesag()
em_out see the output arguments of mt_evnt_multi()
global_aes global AES array
Returns:
a bit mask of which events actually happened as in events. This may be one or more events and your application should be prepared to handle each.
Since:
All AES versions.
See also:
mt_evnt_multi()
For detailed description consult the mt_evnt_multi() documentation.

short mt_evnt_timer unsigned long  interval,
short global_aes
 

releases control to the operating system until a specified amount of time has passed.

Parameters:
interval time value specified in milliseconds.
global_aes global AES array
Returns:
reserved and is currently always 1.
Since:
All AES versions. Under TOS 1.0, calling this function from a desk accessory with interval having a value of 0 will hang the system.
See also:
mt_evnt_multi()
This function should not be relyed on as an accurate clock. The time specified is used as a minimum time value only and the function will return at some point after that duration has passed.


Generated on Wed Nov 3 22:42:20 2004 for GEMLIB by  doxygen 1.3.9.1