wait for user response More...

Macros
#define	evnt_button(a, b, c, d, e, f, g) mt_evnt_button(a,b,c,d,e,f,g,aes_global)

#define	evnt_dclick(a, b) mt_evnt_dclick(a,b,aes_global)

#define	evnt_keybd() mt_evnt_keybd(aes_global)

#define	evnt_mesag(a) mt_evnt_mesag(a,aes_global)

#define	evnt_mouse(a, b, c, d, e, f, g, h, i) mt_event_mouse(a,b,c,d,e,f,g,h,i,aes_global)

#define	evnt_multi(a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v) mt_evnt_multi(a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,aes_global)

#define	evnt_multi_fast(a, b, c) mt_evnt_multi_fast(a,b,c,aes_global)

#define	evnt_timer(a) mt_evnt_timer(a,aes_global)

#define	EVNT_multi(a, b, c, d, e, f, g, h) mt_EVNT_multi(a,b,c,d,e,f,g,h,aes_global)

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.

Macro Definition Documentation

#define evnt_button	(	a,
		b,
		c,
		d,
		e,
		f,
		g
	)	mt_evnt_button(a,b,c,d,e,f,g,aes_global)

single-thread version of mt_evnt_button()

#define evnt_dclick	(	a,
		b
	)	mt_evnt_dclick(a,b,aes_global)

single-thread version of mt_evnt_dclick()

#define evnt_keybd ( ) mt_evnt_keybd(aes_global)

single-thread version of mt_evnt_keybd()

#define evnt_mesag ( a ) mt_evnt_mesag(a,aes_global)

single-thread version of mt_evnt_mesag()

#define evnt_mouse	(	a,
		b,
		c,
		d,
		e,
		f,
		g,
		h,
		i
	)	mt_event_mouse(a,b,c,d,e,f,g,h,i,aes_global)

single-thread version of mt_event_mouse()

#define EVNT_multi	(	a,
		b,
		c,
		d,
		e,
		f,
		g,
		h
	)	mt_EVNT_multi(a,b,c,d,e,f,g,h,aes_global)

single-thread version of mt_EVNT_multi()

#define evnt_multi	(	a,
		b,
		c,
		d,
		e,
		f,
		g,
		h,
		i,
		j,
		k,
		l,
		m,
		n,
		o,
		p,
		q,
		r,
		s,
		t,
		u,
		v
	)	mt_evnt_multi(a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,aes_global)

single-thread version of mt_evnt_multi()

#define evnt_multi_fast	(	a,
		b,
		c
	)	mt_evnt_multi_fast(a,b,c,aes_global)

single-thread version of mt_evnt_multi_fast()

#define evnt_timer ( a ) mt_evnt_timer(a,aes_global)

single-thread version of mt_evnt_timer()

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: `K_RSHIFT` (0x01) Right Shift `K_LSHIFT` (0x02) Left Shift `K_CTRL` (0x04) Control `K_ALT` (0x08) Alternate [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()

References EVNT::msg, MU_M1, and MU_M2.

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.

References EVMULT_OUT::emo_events.

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.

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation