AES Function Reference

appl_read()

WORD appl_read( ap_id, length, message )

WORD ap_id, length;

VOIDP message;

	appl_read() is designed to facilitate inter-process communication between processes running under the AES. The call will halt the application until a message of sufficient length is available (see version notes below).
Opcode	11 (0x0B)
Availability	All AES versions.
Parameters	ap_id is your application identifier as returned by appl_init(). length is the length (in bytes) of the message to read. message is a pointer to a memory buffer where the incoming message should be copied to.
Binding	intin[0] = ap_id; intin[1] = length; addrin[0] = message; return crys_if(0x0B);
Return Value	appl_read() returns 0 if an error occurred or non-zero otherwise.
Version Notes	If the AES version is 4.0 or higher and appl_getinfo() indicates that this feature is supported, ap_id takes on an additional meaning. If APR_NOWAIT (-1) is passed instead of ap_id, appl_read() will return immediately if no message is currently waiting.
Comments	Normally this call is not used. evnt_multi() or evnt_mesag() is used instead for standard message reception. appl_read() is required for reading messages that are long and/or of variable length. It is recommended that message lengths in multiples of 16 bytes be used.
See Also	appl_write()

appl_search()

WORD appl_search( mode, fname, type, ap_id )

WORD mode;

CHAR *fname;

WORD *type,*ap_id;

	appl_search() provides a method of identifying all of the currently running processes.
Opcode	18 (0x12)
Availability	Available only in AES versions 4.0 and above when appl_getinfo() indicates its presence.
Parameters	mode specifies the search mode as follows:
		Name		mode	Meaning
		APP_FIRST		0	Return the filename of the first process
		APP_NEXT		1	Return the filename of subsequent processes
	fname should point to a memory location at least 9 bytes long to hold the 8 character process filename found and the NULL byte. type is a pointer to a WORD into which will be placed the process type as follows:
			Name			type	Meaning
			APP_SYSTEM			0x01	System process
			APP_APPLICATION			0x02	Application
			APP_ACCESSORY			0x04	Accessory
			APP_SHELL			0x08
	The type parameter is actually a bit mask so it is possible that a process containing more than one characteristic will appear. The currently running shell process (usually the desktop) will return a value of APP_APPLICATION | APP_SHELL (0x0A). ap_id is a pointer to a word into which will be placed the processes' application identifier.
Binding	intin[0] = mode; addrin[0] = fname; addrin[1] = type; addrin[2] = ap_id; return crys_if(0x12);
Return Value	appl_search() returns 0 if no more applications exist or 1 when more processes exist that meet the search criteria.

appl_tplay()

WORD appl_tplay( mem, num, scale )

VOIDP mem;

WORD num, scale;

	appl_tplay() plays back events originally recorded with appl_trecord().
Opcode	14 (0x0E)
Availability	All AES versions.
Parameters	mem is a pointer to an array of EVNTREC structures (see appl_trecord()). num indicates the number of EVNTREC's to play back. scale indicates on a scale of 1 to 10000 how fast the AES will attempt to play back your recording. A value of 100 will play it back at recorded speed. A value of 200 will play the events back at twice the recorded speed, and 50 will play back the events at half of the recorded speed. Other values will respond accordingly.
Binding	intin[0] = num; intin[1] = scale; addrin[0] = mem; return crys_if(0x0E);
Return Value	appl_tplay() always returns 1 meaning no error occurred.
Caveats	This function does not work correctly on AES versions less than 1.40 without a patch program available from Atari Corp.
See Also	appl_trecord()

appl_trecord()

WORD appl_trecord( mem, num )

VOIDP mem;

WORD num;

	appl_trecord() records AES events for later playback.
Opcode	15 (0x0F)
Availability	All AES versions.
Parameters	mem points to an array of num EVNTREC structures into which the AES will record events as indicated here: typedef struct pEvntrec { WORD ap_event; LONG ap_value; } EVNTREC;ap_event defines the required interpretation of ap_value as follows:
	Name	ap_event	Event	ap_value
	APPEVNT_TIMER	0	Timer	Elapsed Time (in milliseconds)
	APPEVNT_BUTTON	1	Button	low word = state (1 = down) high word = # of clicks
	APPEVNT_MOUSE	2	Mouse	low word = X pos high word = Y pos
	APPEVNT_KEYBOARD	3	Keyboard	bits 0-7: ASCII code bits 8-15: scan code bits 16-31: shift key state
Binding	intin[0] = num; addrin[0] = mem; return crys_if(0x0F);
Return Value	appl_trecord() returns the number of events actually recorded.
Caveats	This function does not work correctly on AES versions less than 1.40 without a patch program available from Atari Corp.
See Also	appl_tplay()

appl_write()

WORD appl_write( ap_id, length, msg )

WORD ap_id, length;

VOIDP msg;

	appl_write() can be used to send a message to a valid message pipe.
Opcode	12 (0x0C)
Availability	All AES versions.
Parameters	ap_id is the application identifier of the process to which you wish to send the message. length specifies the number of bytes present in the message. msg is a pointer to a memory buffer with at least length bytes available.
Binding	intin[0] = ap_id; intin[1] = length; addrin[0] = msg; return crys_if(0x0C);
Return Value	appl_write() returns 0 if an error occurred or greater than 0 if the message was sent successfully.
Version Notes	As of AES version 1.40, desk accessories may send MN_SELECTED messages to the desktop to trigger desktop functions. As of AES version 4.00 you can use shel_write(7,...) to 'broadcast' a message to all processes running with the exception of the AES itself, the desktop, and your own application. See shel_write() for details.
Comments	It is recommended that you always send messages in 16 byte blocks using a WORD array of 8 elements as the AES does.
See Also	appl_read(), shel_write()

Event Library

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. The library consists of the following calls:

evnt_button()

evnt_dclick()

evnt_keybd()

evnt_mesag()

evnt_mouse()

evnt_multi()

evnt_timer()

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

WORD clicks, mask, state;

WORD *mx, *my, *button, *kstate;

	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 mask parameter with 0x100. This causes the call to return when independent buttons are depressed. For example, a mask value of 0x03 will return when both the left and right mouse buttons are depressed. A mask value of 0x103 will cause the call to return when either button is depressed.
See Also	evnt_multi()

evnt_dclick()

WORD evnt_dclick( new, flag )

WORD new, flag;

	evnt_dclick() sets the mouse double-click response rate. This call is global, and thus, affects all applications.
Opcode	26 (0x1A)
Availability	All AES versions.
Parameters	If flag is EDC_INQUIRE (0), new is ignored and the current double-click rate is returned. If flag is EDC_SET (1), new specifies the new double-click rate as follows:
		flag	Response
		0 1 2 3 4	Slowest Fastest
Binding	intin[0] = new; intin[1] = flag; return crys_if(0x1A);
Return Value	evnt_dclick() returns the newly set or current double-click rate based on flag.
Comments	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).

evnt_keybd()

WORD evnt_keybd( VOID )

	evnt_keybd() relinquishes program control to the operating system until a valid keypress is available in the applications' message pipe.
Opcode	20 (0x14)
Availability	All AES versions.
Parameters	None
Binding	return crys_if(0x14);
Return Value	evnt_keybd() returns a 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.
Version Notes	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.
See Also	evnt_multi()

evnt_mesag()

WORD evnt_mesag( msg )

WORD *msg;

	evnt_mesag() releases control to the operating system until a valid system message is available in the applications' message pipe.
Opcode	23 (0x17)
Availability	All AES versions.
Parameters	msg is a pointer to an array of 8 WORD's to be used as a message buffer.
Binding	addrin[0] = msg return crys_if(0x17);
Return Value	The return value is currently reserved by Atari and currently is defined as 1. The array msg is filed in with the following values:
	Index	Description		Possible Values	#
	msg[0]	Message Type		MN_SELECTED WM_REDRAW WM_TOPPED WM_CLOSED WM_FULLED WM_ARROWED WM_HSLID WM_VSLID WM_SIZED WM_MOVED WM_UNTOPPED WM_ONTOP WM_BOTTOM WM_ICONIFY WM_UNICONIFY WM_ALLICONIFY WM_TOOLBAR AC_OPEN AC_CLOSE AP_TERM AP_TFAIL AP_RESCHG SHUT_COMPLETED RESCH_COMPLETED AP_DRAGDROP SH_WDRAW CH_EXIT	10 20 21 22 23 24 25 26 27 28 30 31 33 34 35 36 37 40 41 50 51 57 60 61 63 72 90
	msg[1]	The application identifier of the sending application.		Any valid ap_id.
	msg[2]	The length of the message beyond 16 bytes (use appl_read() to read the excess).		Currently all system messages return 0 in this slot. Only user-defined messages utilize a higher value.
	Each system message can be interpreted as follows:
	Message		Extended Information
	MN_SELECTED		A menu item has been selected by the user. msg[3] contains the object number of the menu title and msg[4] contains the object number of the menu item. As of AES version 3.30 (and when indicated by appl_getinfo() ), msg[5] and msg[6] contain the high and low word, respectively, of the object tree of the menu item. msg[7] contains the parent object index of the menu item.
	WM_REDRAW		This message alerts an application that a portion of the screen needs to be redrawn. msg[3] contains the handle of the window to redraw. msg[4-7] are the x, y, w, and h respectively of the 'dirtied' area. When the message is received the window contents should be drawn (or a representative icon if the window is iconified).
	WM_TOPPED		This message is sent when an application window which is currently not the top window is clicked on by the user. msg[3] contains the handle of the window. You should use wind_set( msg[3], WF_TOP, 0, 0, 0, 0) to actually cause the window to be topped.
	WM_CLOSED		This message is sent when the user clicks on a windows' close box. msg[3] contains the handle of the window to close. You should react to this message with wind_close().
	WM_FULLED		This message is sent when the user clicks on a windows' full box. If the window is not at full size, the window should be resized using wind_set(handle, WF_CURRXYWH,... to occupy the entire screen minus the menu bar (see wind_get()). If the window was previously 'fulled' and has not been resized since, the application should return the window to its previous size.
	WM_ARROWED		This message is sent to inform an application that one of its slider gadgets has been clicked on. A row or column message is sent when a slider arrow is selected. A 'page' message is sent when a darkened area of the scroll bar is clicked. This usually indicates that the application should adjust the window's contents by a larger amount than with the row or column messages. msg[3] indicates which action was actually selected as follows: Name Value Meaning WA_UPPAGE 0 Page Up WA_DNPAGE 1 Page Down WA_UPLINE 2 Row Up WA_DNLINE 3 Row Down WA_LFPAGE 4 Page Left WA_RTPAGE 5 Page Right WA_LFLINE 6 Column Left WA_RTLINE 7 Column Right
	WM_HSLID		This message indicates that the horizontal slider has been moved. msg[3] contains the new slider position ranging from 0 to 1000. Note: Slider position is relative and not related to slider size.
	WM_VSLID		This message indicates that the vertical slider has been moved. msg[3] contains the new slider position ranging from 0 to 1000. Note: Slider position is relative and not related to slider size.
	WM_SIZED		This message occurs when the user drags the window sizing gadget. msg[3] contains the window handle. msg[4-7] indicate the x, y, w, and h respectively of the new window location. Use wind_set(handle, WF_CURRXYWH,... to actually size the window. WM_SIZED and WM_MOVED usually share common handling code.
	WM_MOVED		This message occurs when the user moves the window by dragging the windows' title bar. msg[3] contains the handle of the window being moved. msg[4-7] indicate the x, y, w, and h respectively of the new window location. Use wind_set(handle, WF_CURRXYWH,... ) to actually move the window. WM_MOVED and WM_SIZED usually share common handling code.
	WM_UNTOPPED		This message is sent when the current window is sent behind one or more windows as the result of another window being topped. msg[3] contains the handle of the window being untopped. The application need take no action. The message is for informational use only.
	WM_ONTOP		This message is sent when an applications' window is brought to the front on a multitasking AES. msg[3] is the handle of the window being brought to the front. This message requires no action, it is for informational purposes only.
	WM_BOTTOMED		This message is sent when the user shift-clicks on the window's (specified in msg[3]) mover bar to indicate that the window should be sent to the bottom of the window stack by using wind_set() with a parameter of WF_BOTTOM.
	WM_ICONIFY		This message is sent when the user clicks on the SMALLER window gadget. msg[3] indicates the handle of the window to be iconified. msg[4-7] indicate the x, y, w, and h of the iconified window. If the iconified window represents a single window this message should be responded to by using wind_set() with a parameter of WF_ICONIFY.
	WM_UNICONIFY		This message is sent when the user double-clicks on an iconified window. msg[3] indicates the handle of the window to be iconified. msg[4-7] indicate the x, y, w, and h of the original window. This message should be responded to by using wind_set() with a parameter of WF_UNICONIFY.
	WM_ALLICONIFY		This message is sent when the user ctrl-clicks on the SMALLER window gadget. msg[3] indicates which window's gadget was clicked. msg[4-7] indicates the position at which the new iconified window should be placed. The application should respond to this message by closing all open windows and opening a new iconified window at the position indicated which represents the application.
	WM_TOOLBAR		This message is sent when a toolbar object is clicked. msg[3] contains the handle of the window containing the toolbar. msg[4] contains the object index of the object clicked. msg[5] contains the number of clicks. msg[6] contains the state of the keyboard shift keys at the time of the click (as in evnt_keybd() ).
	AC_OPEN		This message is sent when the user has selected a desk accessory to open. msg[4] contains the application identifier (as returned by appl_init()) of the accessory to open.
	AC_CLOSE		This message is sent to a desk accessory when the accessory should be closed. msg[3] is the application identifier (as returned by appl_init()) of the accessory to close. Do not close any windows your accessory had open, the system will do this for you. Also, do not require any feedback from the user when this is received. Treat this message as a 'Cancel' from the user.
	AP_TERM		This message is sent when the system requests that the application terminate. This is usually the result of a resolution change but may also occur if another application sends this message to gain total control of the system. The application should shut down immediately after closing windows, freeing resources, etc... msg[5] indicates the reason for the shut down as follows: AP_TERM (50) = Just shut down. AP_RESCHG (57) = Resolution Change.If for some reason, your process can not shut down you must inform the AES by sending an AP_TFAIL (51) message by using shel_write() mode 10 (see shel_write()). Note: Desk Accessories wil always be sent AC_CLOSE messages, not AP_TERM.
	AP_TFAIL		This message should be sent to the system (see shel_write()) when an application has received an AP_TERM (50) message and cannot shut down. msg[0] should contain AP_TFAIL and msg[1] should contain the application error code.
	AP_RESCHG		This message is actually a sub-command and is only found as a possible value in the AP_TERM (50) message (see above).
	SHUT_COMPLETED		This message is sent to the application which requested a shutdown when the shutdown is complete and was successful.
	RESCH_COMPLETED		This message is sent to an application when a resolution change it requested is completed. msg[3] contains 1 if the resolution change was successful and 0 if an error occurred.
	AP_DRAGDROP		This message indicates that another application wishes to initiate a drap and drop session. msg[3] indicates the handle of the window which had an object dropped on it or -1 if no specific window was targeted. msg[4-5] contains the X and Y position of the mouse when the object was 'dropped'. msg[6] indicates the keyboard shift state at the time of the drop (as in evnt_keybd() ). msg[7] is a two-byte ASCII packed pipe identifier which gives the file extension of the pipe to open. For more information about the drag & drop protocal, see Chapter 2: GEMDOS.
	SH_WDRAW		This message is sent to the Desktop to ask it to update an open drive window. msg[3] should contain the drive number to update (0 = A:, 1 = B:) or -1 to update all windows.
	CH_EXIT		This message is sent when a child process that the application has started, returns. msg[3] contains the child's application identifier and msg[4] contains its exit code.
Version Notes	WM_UNTOPPED, WM_ONTOP, AP_TERM, AP_TFAIL, AP_RESCHG, SHUT_COMPLETED, RESCH_COMPLETED, and CH_EXIT are new as of AES version 4.0. WM_BOTTOM, WM_ICONIFY, WM_UNICONIFY, WM_ALLICONIFY, and WM_TOOLBAR are new as of AES version 4.1. No lower version AES will send these messages. The existence (or acceptance) of these messages should also be checked for by using appl_getinfo().
See Also	evnt_multi()

evnt_multi()

WORD evnt_multi( events, bclicks, bmask, bstate, m1flag, m1x, m1y, m1w, m1h, m2flag, m2x, m2y, m2w, m2h, msg, locount, hicount, mx, my,mb, ks, kc, mc )

WORD events, bclicks, bmask, bstate, m1flag, m1x, m1y, m1w, m1h, m2flag, m2x, m2y, m2w, m2h;

WORD *msg;

WORD locount, hicount;

WORD *mx, *my, *ks, *kc, *mc;

	evnt_multi() suspends the application until a valid message that the application is interested in occurs. This call combines the functionality of evnt_button(), evnt_keybd(), evnt_mesag(), evnt_mouse(), and evnt_timer() into one call. This call is usually the cornerstone of all GEM applications that must process system events.
Opcode	25 (0x19)
Availability	All AES versions.
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:
	Name	Mask	Function
	MU_KEYBD	0x01	Wait for a user keypress.
	MU_BUTTON	0x02	Wait for the specified mouse button state.
	MU_M1	0x04	Wait for a mouse/rectangle event as specified.
	MU_M2	0x08	Wait for a mouse/rectangle event as specified.
	MU_MESAG	0x10	Wait for a message.
	MU_TIMER	0x20	Wait the specified amount of time.
	For usage of bclicks, bmask, bstate, mx, my, kc, and ks, you should consult evnt_button(). For usage of m1flag, m1x, m1y, m1w, m1h, m2flag, m2x, m2y, m2w, and m2h, consult evnt_mouse(). For usage of msg, see evnt_mesag(). For usage of locount and hicount, see evnt_timer().
Binding	intin[0] = events; intin[1] = bclicks; intin[2] = bmask; intin[3] = bstate; intin[4] = m1flag; intin[5] = m1x; intin[6] = m1y; intin[7] = m1w; intin[8] = m1h; intin[9] = m2flag; intin[10] = m2x; intin[11] = m2y; intin[12] = m2w; intin[13] = m2h; intin[14] = locount; intin[15] = hicount; addrin[0] = msg; crys_if(0x19); *mx = intout[1]; *my = intout[2]; *mb = intout[3]; *ks = intout[4]; *kc = intout[5]; *mc = intout[6]; return intout[0];
Return Value	The function 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.
Version Notes	The only facet of evnt_multi() which has changed from AES version 4.0 is that which relates to evnt_mesag(). For further information you should consult that section.
Caveats	Under TOS 1.0, calling this function from a desk accessory with the MU_TIMER mask and locount and hicount being equal to 0 could hang the system.
See Also	evnt_button(), evnt_keybd(), evnt_mesag(), evnt_mouse(), evnt_timer()

evnt_timer()

WORD evnt_timer( locount, hicount )

WORD locount, hicount;

	evnt_timer() releases control to the operating system until a specified amount of time has passed.
Opcode	24 (0x18)
Availability	All AES versions.
Parameters	locount is the low word of a 32-bit time value specified in milliseconds. hicount is the high portion of that 32-bit value.
Binding	intin[0] = locount; intin[1] = hicount; return crys_if(0x18);
Return Value	The return value is reserved and is currently always 1.
Caveats	Under TOS 1.0, calling this function from a desk accessory with a both parameters having a value of 0 will hang the system.
Comments	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.
See Also	evnt_multi()

Form Library

The Form Library contains utility functions for the use and control of dialog boxes, alert boxes, and user input. The members of the Form Library are:

form_alert()

form_button()

form_center()

form_dial()

form_do()

form_error()

WORD form_alert( default, alertstr )

WORD default;

CHAR *alertstr;

	form_alert() displays a standardized alert box and returns the user's selection.
Opcode	52 (0x34)
Availability	All AES versions.
Parameters	default contains the number of the exit button which is to be made default (1-3). alertstr contains a formatted string as follows: "[#][Alert Text][Buttons]". # specifies the icon to display in the alert as follows:
		#	Icon Displayed
		0	No Icon
		1
		2
		3
		4
		5
	'Alert Text' is a text string of as many as 5 lines composed of up to 30 characters each. Each line is separated by a '|' character. 'Buttons' is a text string to define as many as 3 buttons up to 10 characters each. If only one button is used, its text may be as long as 30 characters. Again, each button is separated by a '|' character
Binding	intin[0] = default; addrin[0] = alertstr; return crys_if(0x34);
Return Value	form_alert() returns a WORD indicating which button was used to exit by the user (A possible value of 1-3).
Version Notes	Icons #4-5 are only available as of AES version 4.1.
Caveats	Several versions of the AES have special quirks related to this function. By following the quidelines below you should avoid any difficulty:1. All AES versions below 1.06 have some difficulty formatting alert strings padded with spaces. If you want your alerts to look right on all AES versions, do not pad any button or line with spaces with the exception below. 2. Add one space to the end of the longest text line on an alert. This will prevent the right edge from touching the border in some AES versions.

form_button()

WORD form_button( tree, obj, clicks, newobj )

OBJECT *tree;

WORD obj, clicks, newobj;

	form_button() is a utility function designed to aid in the creation of a custom form_do() handler.
Opcode	56 (0x38)
Availability	All AES versions.
Parameters	tree is a pointer to a valid object tree in memory you wish to process button events for. obj is the object index into tree which was clicked on and which needs to be processed. clicks is the number of times the mouse button was clicked. newobj returns the next object to gain edit focus or 0 if there are no editable objects. If the top bit of newobj is set, this indicates that a TOUCHEXIT object was double-clicked.
Binding	intin[0] = obj; intin[1] = clicks; addrin[0] = tree; crys_if(0x38); *newobj = intout[1]; return intout[0];
Return Value	form_button() returns a 0 if it exits finding an EXIT or TOUCHEXIT object selected or 1 otherwise.
Comments	To use this function properly, the application should take the following steps:1. Monitor mouse clicks with evnt_multi() or evnt_button(). 2. When a click occurs, use objc_find() to determine if the click occurred over the object. 3. If so, call form_button() with the appropriate values.This function was not originally documented by Atari. You may have to add bindings for this function to some earlier 'C' compilers.
See Also	form_do(), form_keybd()

form_center()

WORD form_center( tree, x, y, w, h )

OBJECT *tree;

WORD *x, *y, *w, *h;

	form_center() is used to modify an object's coordinates so that it will appear in the center of the display screen.
Opcode	54 (0x36)
Availability	All AES versions.
Parameters	tree points to a valid OBJECT structure (see discussion of resources) which the application wishes to have centered. x, y, w, and h, return a clipping rectangle suitable for use in objc_draw().
Binding	addrin[0] = tree; crys_if(0x36); *x = intout[1]; *y = intout[2]; *w = intout[3]; *h = intout[4]; return intout[0];
Return Value	The return value is currently reserved. Currently it equals 1.
Comments	The values that form_center() returns in x, y, w, and h, are not necessarily the same as the object's. These values take into account negative borders, outlining, and shadowing. This is meant to provide a suitable clipping rectangle for objc_draw()
See Also	objc_draw()

form_dial()

WORD form_dial( mode, x1, y1, w1, h1, x2, y2, w2, h2 )

WORD mode, x1, y1, w1, h1, x2, y2, w2, h2;

	form_dial() is used to reserve and release screen space for dialog usage. In addition, it also optionally provides grow/shrink box effects.
Opcode	51 (0x33)
Availability	All AES versions.
Parameters	mode specifies the action to take and the meaning of remaining parameters as follows:
	Name	#	Action
	FMD_START	0	This mode reserves the screen space for a dialog. x2, y2, w2, and h2, contain the coordinates of the dialog to be used (usually obtained through form_center()).
	FMD_GROW	1	This mode draws an expanding box from the coordinates specified in x1, y1, w1, and h1 to the coordinates specified in x2, y2, w2, and h2. This call is optional and is not required to display a dialog.
	FMD_SHRINK	2	This mode draws a shrinking box from the coordinates specified in x2, y2, w2, and h2 to the coordinates specified in x1, y1, w1, and h1. This call is optional and is not required to display a dialog.
	FMD_FINISH	3	This mode releases the screen space for a dialog (previously reserved with mode 0). x2, y2, w2, and h2 contain the coordinates of the space to release. One of the side-effects of this call is a WM_REDRAW message sent to any window which the dialog was covering.
Binding	intin[0] = mode; intin[1] = x1; intin[2] = y1; intin[3] = w1; intin[4] = h1; intin[5] = x2; intin[6] = y2; intin[7] = w2; intin[8] = h2; return crys_if(0x33);
Return Value	The function returns 0 is an error occurred or non-zero otherwise.
Version Notes	The AES does not currently make use of mode FMD_START. The call should, however, still be executed for upward compatibility.
See Also	graf_growbox(), graf_shrinkbox()

form_do()

WORD form_do( tree, editobj )

OBJECT *tree;

WORD editobj;

	form_do() provides an automated dialog handling function to the calling application. It suspends program control, handling all radio buttons, selectable objects, etc... until an object with the TOUCHEXIT or EXIT flag is selected.
Opcode	50 (0x32)
Availability	All AES versions.
Parameters	tree is a pointer to a valid object tree (see the discussion on objects in this chapter) which contains a dialog with at least one EXIT or TOUCHEXIT button or object. editobj is the object index into tree which specifies the desired initial location of the edit cursor (the object must be flagged as EDITABLE). If the form has no text editable fields, you should use 0.
Binding	intin[0] = editobj; addrin[0] = tree; return crys_if(0x32);
Return Value	form_do() returns the object index of the EXIT or TOUCHEXIT button which was selected. If the object was double clicked, bit 15 will be set. This means that to obtain the actual object number you should mask off the result with 0x7FFF.

form_error()

WORD form_error( error )

WORD error;

	form_error() displays a pre-defined error alert box to the user.
Opcode	53 (0x35)
Availability	All AES versions.
Parameters	error specifies a MS-DOS error code as follows:
	Name	GEMDOS Error #	error	Message
	FERR_FILENOTFOUND	-33	2	File Not Found The application can not find the folder or file that you tried to access.
	FERR_PATHNOTFOUND	-34	3	Path Not Found The application cannot find the folder or file that you tried to access.
	FERR_NOHANDLES	-35	4	No More File Handles The application does not have room to open another document. To make room, close any open document that you do not need.
	FERR_ACCESSDENIED	-36	5	Access Denied An item with this name already exists in the directory, or this item is set to read-only status.
	FERR_LOWMEM	-39	8	Insufficient Memory There is not enough memory for the application you just tried to run.
	FERR_BADENVIRON	-41	10	Invalid Environment There is not enough memory for the application you just tried to run.
	FERR_BADFORMAT	-42	11	Invalid Format There is not enough memory for the application you just tried to run.
	FERR_BADDRIVE	-46	15	Invalid Drive Specification The drive you specified does not exist.
	FERR_DELETEDIR	-47	16	Attempt To Delete Working Directory You cannot delete the folder in which you are working.
	FERR_NOFILES	-49	18	No More Files The application can not find the folder or file that you tried to access.
	The GEMDOS error number can be translated into a MS-DOS code by subtracting 31 from the absolute value of the error code.
Binding	intin[0] = error; return crys_if(0x35);
Return Value	The function returns the exit button clicked as in form_alert(). It is, however, insignifigant as all of the error alerts have only one button.
Caveats	Not every GEMDOS error code has a matching alert box.
See Also	form_alert()

form_keybd()

WORD form_keybd( tree, obj, nextobj, kc, newobj, keyout )

OBJECT *tree;

WORD obj, nextobj, kc;

The File Selector Library contains two functions for displaying the system file selector (or currently installed alternate file selector) and prompting the user to select a file. The members of this library are:

fsel_exinput()

fsel_input()

fsel_exinput()

WORD fsel_exinput( path, file, button, title )

CHAR *path, *file;

WORD *button;

CHAR *title;

	fsel_exinput() displays the system file selector and offers the user an opportunity to choose a complete GEMDOS path specification.
Opcode	91 (0x5B)
Availability	Available from AES version 1.40.
Parameters	path should be a pointer to a character buffer at least 128 bytes long (applications wishing to access CD-ROM's should allocate at least 200 bytes). On input the buffer should contain a complete GEMDOS path specification including a drive specifier, path string, and wildcard mask as follows: 'drive:\path\mask'. The mask can be any valid GEMDOS wildcard (usually *.*). On function exit, path contains final path of the selected file (you will have to strip the mask). file should point to a character buffer 13 bytes long (12 character filename plus NULL). On input its contents will be placed on the filename line of the selector (usually this value can simply be a empty string). On function exit, file contains the filename which the user selected. button is a short pointer which upon function exit will contain FSEL_CANCEL (0) if the user selected CANCEL or FSEL_OK (1) if OK. title should be a pointer to a character string up to 30 characters long which contains the title to appear in the file selector (usually indicates which action the user is about to take).
Binding	addrin[0] = path; addrin[1] = file; addrin[2] = label; crys_if(0x5B); *button = intout[1]; return intout[0];
Return Value	fsel_exinput() returns 0 if an error occured and 1 otherwise.
Version Notes	Some 'C' compilers (Lattice for example) provide a special function which allows fsel_exinput() to be used even on earlier AES versions.
Comments	The path parameter to this function should be validated to ensure that the path actually exists prior to calling this function to prevent confusing the user. This call should always be used as opposed to fsel_input() when it is available. Otherwise, the user has no reminder as to what function s/he is actually undertaking.
See Also	fsel_input()

fsel_input()

WORD fsel_input( path, file, button )

CHAR *path, *file;

WORD *button;

	fsel_input() displays the system file selector and allows the user to select a valid GEMDOS path and file.
Opcode	90 (0x5A)
Availability	All AES versions.
Parameters	All parameters are consistent with fsel_exinput() with the notable lack of title.
Binding	addrin[0] = path; addrin[1] = file; crys_if(0x5A); *button = intout[1]; return intout[0];
Return Value	fsel_input() returns a 0 if an error occurred or 1 otherwise.
Comments	You should never use this function in place of fsel_exinput() when fsel_exinput() is available.
See Also	fsel_exinput()

Graphics Library

The Graphics Library provides applications with a variety of utility functions which serve to provide common screen effects, mouse control, and the obtaining of basic screen attributes. The functions of the Graphics Library are as follows:

graf_dragbox()

graf_growbox()

graf_handle()

graf_mkstate()

graf_mouse()

graf_movebox()

graf_rubberbox()

graf_shrinkbox()

graf_slidebox()

WORD graf_dragbox( w, h, sx, sy, bx, by, bw, bh, endx, endy )

WORD w, h, sx, sy, bx, by, bw, bh;

WORD *endx, *endy;

	graf_dragbox() allows the user to move a box frame within the constraints of a bounding rectangle. This call is most often used to give the user a visual 'clue' when an object is being moved on screen.
Opcode	71 (0x47)
Availability	All AES versions.
Parameters	w and h specify the initial width and height of the box to draw. sx and sy specify the starting x and y screen coordinates. bx, by, bw, and bh, give the coordinates of the bounding rectangle. endx and endy are WORD pointers which, on function exit, will be filled in with the ending x and y position of the box.
Binding	intin[0] = w; intin[1] = h; intin[2] = sx; intin[3] = sy; intin[4] = bx; intin[5] = by; intin[6] = bw; intin[7] = bh; crys_if(0x47); *endx = intout[1]; *endy = intout[2]; return intout[0];
Return Value	graf_dragbox() returns a 0 if an error occurred during execution or greater than zero otherwise.
Comments	This call should be made only when the mouse button is depressed. The call returns when the mouse button is released.
See Also	graf_slidebox()

graf_growbox()

WORD graf_growbox( x1, y1, w1, h1, x2, y2, w2, h2 )

WORD x1, y1, w2, h2, x2, y2, w2, h2;

	graf_growbox() is used to provide a visual 'clue' to a user by animating an outline of a box from one set of coordinates to another. It is the complement function to graf_shrinkbox().
Opcode	73 (0x49)
Availability	All AES versions.
Parameters	x1, y1, w1, and h1 are the screen coordinates of the starting rectangle (where the outline will grow from). x2, y2, w2, and h2 are the screen coordinates of the ending rectangle (where the outline will grow to).
Binding	intin[0] = x1; intin[1] = y1; intin[2] = w1; intin[3] = h1; intin[4] = x2; intin[5] = y2; intin[6] = w2; intin[7] = h2; return crys_if(0x49);
Return Value	graf_growbox() returns 0 if an error occured or non-zero otherwise.
Caveats	There is currently no defined method of handling an error generated by this function.
Comments	This function is what is called by GEM's form_dial(FMD_GROW,...
See Also	form_dial(), graf_shrinkbox()

graf_handle()

WORD graf_handle( wcell, hcell, wbox, hbox );

WORD *wcell, *hcell, *wbox, *hbox;

	graf_handle() returns important information regarding the physical workstation currently in use by the AES.
Opcode	77 (0x4D)
Availability	All AES versions.
Parameters	wcell and hcell are WORD pointers which on function exit will be filled in with the width and height, respectively, of the current system character set. wbox and hbox are WORD pointers which on function exit will be filled in with the width and height, respectively, of the minimum bounding box of a BOXCHAR character.
Binding	crys_if(0x4D); *charw = intout[1]; *charh = intout[2]; *boxw = intout[3]; *boxh = intout[4]; return intout[0];
Return Value	This function returns the VDI handle for the current physical workstation used by the AES.
Caveats	There is currently no defined method of handling an error generated by this function.
Comments	The return value of this function is required to open a virtual screen workstation.
See Also	v_opnvwk()

graf_mkstate()

WORD graf_mkstate( mx, my, mb, ks )

WORD *mx, *my, *mb, *ks;

	graf_mkstate() returns information about the current state of the mouse pointer, buttons, and keyboard shift-key state.
Opcode	79 (0x4F)
Availability	All AES versions.
Parameters	mx and my are WORD pointers, which, on function exit will be filled in with the current x and y coordinates of the mouse pointer. mb is a WORD pointer, which, on function exit will be filled in with the current button state of the mouse as defined in evnt_button().
Binding	crys_if(0x4F); *mx = intout[1]; *my = intout[2]; *mb = intout[3]; *ks = intout[4]; return intout[0];
Return Value	The function return is currently reserved and currently equals 1.
See Also	evnt_button(), vq_mouse()

graf_mouse()

WORD graf_mouse( mode, formptr )

WORD mode;

VOIDP formptr;

	graf_mouse() alters the appearance of the mouse form and can be used to hide and display the mouse pointer from the screen.
Opcode	78 (0x4E)
Availability	All AES versions.
Parameters	mode is defined as follows:
	mode	#	Meaning	Shape
	ARROW	0	Change the current mouse cursor shape.
	TEXT_CRSR	1	Change the current mouse cursor shape.
	BUSY_BEE	2	Change the current mouse cursor shape.
	POINT_HAND	3	Change the current mouse cursor shape.
	FLAT_HAND	4	Change the current mouse cursor shape.
	THIN_CROSS	5	Change the current mouse cursor shape.
	THICK_CROSS	6	Change the current mouse cursor shape.
	OUTLN_CROSS	7	Change the current mouse cursor shape.
	USER_DEF	255	Change the current mouse cursor shape.	Form is defined below.
	M_OFF	256	Remove the mouse cursor from the screen.	No shape change.
	M_ON	257	Display the mouse cursor.	No shape change.
	M_SAVE	258	Save the current mouse form in an AES provided buffer. Check appl_getinfo() for the presence of this feature.	No shape change.
	M_LAST	259	Restore the most recently saved mouse form. Check appl_getinfo() for the presence of this feature.	Changes the shape as indicated.
	M_RESTORE	260	Restore the mouse form to its last shape. Check appl_getinfo() for the presence of this feature.	Changes the shape as indicated.
	If mode is equal to USER_DEF, formptr must point to a MFORM structure as defined below (if mode is different than USER_DEF, formptr should be NULL): typedef struct { short mf_xhot; short mf_yhot; short mf_nplanes; short mf_fg; short mf_bg; short mf_mask[16]; short mf_data[16]; } MFORM;
	mf_xhot and mf_yhot are the location of the mouse 'hot-spot'. These values should be in the range 0 to 15 and define what offset into the bitmap is actually the 'point'. mf_nplanes specifies the number of bit-planes used by the mouse pointer. Currently, the value of 1 is the only legal value. mf_fg and mf_bg are the mask and data colors of the mouse specified as palette indexes. Usually these values will be 0 and 1 respectively. mf_mask is an array of 16 WORD's which define the mask portion of the mouse form. mf_data is an array of 16 WORD's which define the data portion of the mouse form. As of AES 4.0 and beyond, the AES may not allow a mouse form to change to benefit another application. If it is absolutely necessary for the application to display its mouse form, logically OR the mode parameter with M_FORCE (0x8000) and make the call. This will force the AES to change to your mouse form. It should, however, be done within the scope of a wind_update() sequence.
Binding	intin[0] = mode; addrin[0] = formptr; return crys_if(0x4E);
Return Value	graf_mouse() returns a 0 if an error occurred or non-zero otherwise.
Caveats	There is currently no defined method of handling an error generated by this function.
See Also	vsc_form()

graf_movebox()

WORD graf_movebox( bw, bh, sx, sy, ex, ey )

WORD bw, bh, sx, sy, ex, ey;

	graf_movebox() animates a moving box between two points on the screen. It is used to give the user a visual 'clue' to an action undertaken by the application.
Opcode	72 (0x48)
Availability	All AES versions.
Parameters	bw and bh specify the width and height, respectively, of the box to animate. sx and sy specify the starting coordinates of the box. ex and ey specify the ending coordinates of the box.
Binding	intin[0] = bw; intin[1] = bh; intin[2] = sx; intin[3] = sy; intin[4] = ex; intin[5] = ey; return crys_if(0x48);
Return Value	The return value is 0 if an error occured or non-zero otherwise.
Caveats	There is currently no defined method for handling an error generated by this call.
Comments	Some older 'C' bindings referred to this call as graf_mbox(). If your compiler still uses this call you should update it.

graf_rubberbox()

WORD graf_rubberbox( bx, by, minw, minh, endw, endh )

WORD bx, by, minw, minh;

WORD *endw, *endh;

	graf_rubberbox() allows the user to change the size of a box outline with a fixed starting point.
Opcode	70 (0x46)
Availability	All AES versions.
Parameters	bx and by define the fixed upper-left corner of the box to stretch or shrink. minw and minh specify the minimum width and height that the rectangle can be shrunk to. endw and endh are WORD pointers which will be filled in with the ending width and height of the box when the mouse button is released.
Binding	intin[0] = bx; intin[1] = by; intin[2] = minw; intin[3] = minh; crys_if(0x46); *endw = intout[1]; *endh = intout[2]; return intout[0];
Return Value	graf_rubberbox() returns 0 if an error occurred or non-zero otherwise.
Caveats	There is currently no defined method for handling an error generated by this call.
Comments	This function should only be entered when the user has depressed the mouse button as it returns when the mouse button is released.
See Also	graf_dragbox(), graf_slidebox()

graf_shrinkbox()

WORD graf_shrinkbox( x1, y1, w1, h1, x2, y2, w2, h2 )

WORD x1, y1, w1, h1, x2, y2, w2, h2;

	graf_shrinkbox() displays an animated box shrinking from one rectangle to another. It should be used to provide the user with a visual 'clue' to an action. It is the complement function to graf_growbox().
Opcode	74 (0x4A)
Availability	All AES versions.
Parameters	x1, y1, w1, and h1 are the coordinates of the rectangle to shrink to. x2, y2, w2, and h2 are the coordinates of the rectangle to shrink from.
Binding	intin[0] = x1; intin[1] = y1; intin[2] = w1; intin[3] = h1; intin[4] = x2; intin[5] = y2; intin[6] = w2; intin[7] = h2; return crys_if(0x4A);
Return Value	The function returns 0 if an error occurred or non-zero otherwise
Caveats	There is currently no defined method of handling an error from this call.
Comments	This function is essentially the same as form_dial(FMD_SHRINK,...
See Also	form_dial(), graf_growbox()

graf_slidebox()

WORD graf_slidebox( tree, parent, obj, orient )

OBJECT *tree;

WORD parent, obj,orient;

	graf_slidebox() allows the user to slide a child object within the bounds of its parent. It is often used to implement slider controls.
Opcode	76 (0x4C)
Availability	All AES versions.
Parameters	tree is pointer to the object tree containing the child and parent objects. parent is the object index of an object which bounds the movement of the child. child is the object index of the object which can be moved within the bounds of parent. orient specifies the orientation of the allowed movement. 0 is horizontal (left-right), 1 is vertical (up-down).
Binding	intin[0] = parent; intin[1] = child; intin[2] = orient; addrin[0] = tree; return crys_if(0x4C);
Return Value	The function returns a value specifying the relative offset of the child within the parent as a number between 0 and 1000.
Comments	This call can be used easily with sliders built into dialogs by making the slider bar a TOUCHEXIT and calling this function when it is clicked. This call should only be made when the mouse button is depressed as it returns when it is released.
See Also	graf_movebox()

graf_watchbox()

WORD graf_watchbox( tree, obj, instate, outstate )

OBJECT *tree;

WORD obj, instate, outstate;

	graf_watchbox() modifies the given state of a specified object depending on whether the pointer is within the bounds of the object or outside the bounds of the object as long as the left mouse button is held down.
Opcode	75 (0x4B)
Availability	All AES versions.
Parameters	tree is a pointer to the ROOT object of the tree which contains the object you wish to watch. obj is the object index of the object to watch. instate is the ob_state (see objc_change()) to apply while the mouse is inside of the bounds of the object. outstate is the ob_state to apply while the mouse is outside of the bounds of the object.
Binding	intin[0] = 0; intin[1] = obj; intin[2] = instate; intin[3] = outstate; addrin[0] = tree; return crys_if(0x4B);
Return Value	graf_watchbox() returns a 0 if the mouse button was released outside of the object or a 1 if the button was released inside of the object.
Comments	As this call returns when the mouse button is released, it should only be made when the mouse button is depressed. This call is used internally by form_button() and form_do() and is usually only necessary if you are replacing one of these handlers.
See Also	form_button()

Menu Library

WORD menu_attach( flag, tree, item, mdata )

WORD flag;

OBJECT *tree;

WORD item;

MENU *mdata;

	menu_attach() allows an application to attach, change, or remove a sub-menu. It also allows the application to inquire information regarding a currently defined sub-menu.
Opcode	37 (0x25)
Availability	This function is only available from AES version 3.30 and above. In AES versions 4.0 and greater, appl_getinfo() should be used to determine its exact functionality.
Parameters	flag indicates the action the application desires as follows:
	#	Define		Meaning
	0	ME_INQUIRE		Return information on a sub-menu attached to the menu item designated by tree and item in mdata.
	1	ME_ATTACH		Attach or change a sub-menu. mdata should be initialized by the application. tree and item should be the OBJECT pointer and index to the menu which is to have the sub-menu attached. If mdata is NULLPTR, any sub-menu attached will be removed.
	2	ME_REMOVE		Remove a sub-menu. tree and item should be the OBJECT pointer and index to the menu item which a sub-menu was attached to. mdata should be NULLPTR.
	In all cases except ME_REMOVE, mdata should point to a MENU structure as defined here: typedef struct { OBJECT *mn_tree; WORD mn_menu; WORD mn_item; WORD mn_scroll; WORD mn_keystate; } MENU;
	The MENU structure members are defined as follows:
	Member		Meaning
	mn_tree		Points to the OBJECT tree of the sub-menu.
	mn_menu		Is an index to the parent object of the menu items.
	mn_item		Is the starting menu item.
	mn_scroll		If SCROLL_NO (0), the menu will not scroll. If SCROLL_YES (1), and the number of menu items exceed the menu scroll height, arrows will appear which allow the user to scroll selections.
	mn_keystate		This member is unused and should be 0 for this call.
Binding	intin[0] = flag; intin[1] = item; addrin[0] = tree; addrin[1] = mdata; return crys_if(0x25);
Return Value	menu_attach() returns 0 if an error occurred and the sub-menu could not be attached or 1 if the operation was successful.
Caveats	AES versions supporting menu_attach() less than 4.1 contain a bug which causes the AES to crash when changing or removing a sub-menu attachment. At present, if you wish to attach a scrolling menu, the menu items must be G_STRING's.
Comments	If a menu bar having attachments is removed with menu_bar( NULL, MENU_REMOVE ) those attachments are removed by the system and must be reattached with this call if the menu is redisplayed at a later time. Several recommendations regarding sub-menus should be adhered to:1. Menu items which will have sub-menus attached to them should be padded with blanks to the end of the menu. 2. Menu items which will have sub-menus attached to them should not have a keyboard equivalent. 3. Sub-menus will display faster if a byte-boundary is specified. 4. Sub-menus will be shifted vertically to align the start object with the main menu item which it is attached to. 5. Sub-menus will always be adjusted to automatically fit on the screen. 6. There can be a maximum of 64 sub-menu attachments per process (attaching a sub-menu to more than one menu item counts as only one attachment). 7. Do not attach a sub-menu to itself. 8. As a user-interface guideline, there should only be one level of sub-menus, though it is possible to have up to four levels currently. 9. menu_istart() works only on sub-menus attached with menu_attach().
See Also	menu_istart(), menu_settings(), menu_popup()

menu_bar()

WORD menu_bar( tree, mode )

OBJECT *tree;

WORD mode;

	menu_bar() displays a specialized OBJECT tree on the screen as the application menu. It can also be used to determine the owner of the currently displayed menu bar in a multitasking AES.
Opcode	30 (0x1E)
Availability	All AES versions.
Parameters	tree is a pointer to an OBJECT tree which has been formatted for use as a system menu (for more information on the OBJECT format of a menu see the discussion on objects in this chapter). mode is a flag indicating the action to take as follows:
	Name	mode	Meaning
	MENU_REMOVE	0	Erase the menu bar specified in tree.
	MENU_INSTALL	1	Display the menu bar specified in tree.
	MENU_INQUIRE	-1	Return the AES application identifier of the process which owns the currently displayed system menu. tree can be set to NULL. The AES version must be greater than 4.0 and appl_getinfo() must indicate that this is feature is supported.
Binding	intin[0] = mode; addrin[0] = tree; return crys_if(0x1E);
Return Value	If mode is MENU_REMOVE (0) or MENU_INSTALL (1), the return value indicates an error condition where >0 means no error and 0 means an error occurred. In inquiry mode (mode = MENU_INQUIRE (-1)), menu_bar() returns the application identified of the process which owns the currently displayed menu bar.
Comments	The safest way to redraw an application's menu bar is to redraw it only if you are sure it is currently the active menu bar. In a non-multitasking AES, this is a certainty, however, in a multitasking AES you should first inquire the menu bar's owner within the scope of a wind_update( BEG_UPDATE ) call to prevent the system from swapping active menu bars while in the process of redrawing.
See Also	menu_ienable(), menu_icheck()

menu_icheck()

WORD menu_icheck( tree, obj, check )

OBJECT *tree;

WORD obj, check;

	menu_icheck() adds/removes a checkmark in front of a menu item.
Opcode	31 (0x1F)
Availability	All AES versions.
Parameters	tree specifies the object tree of the current menu. obj should be the object index of a menu item. If check is UNCHECK (0), no checkmark will be displayed next to this item whereas if check is CHECK (1), a checkmark will be displayed.
Binding	intin[0] = obj; intin[1] = check; addrin[0] = obj; return crys_if(0x1F);
Return Value	menu_icheck() returns 0 if an error occurred or non-zero otherwise.
See Also	objc_change()

menu_ienable()

WORD menu_ienable( tree, obj, flag )

OBJECT *tree;

WORD obj, flag;

	menu_ienable() enables/disables menu items.
Opcode	32 (0x20)
Availability	All AES versions.
Parameters	tree specifies the object tree of the menu to alter. obj is the object index of the menu item to modify. flag should be set to DISABLE (0) to disable the item or ENABLE (1) to enable it.
Binding	intin[0] = obj; intin[1] = flag; addrin[0] = tree; return crys_if(0x20);
Return Value	menu_icheck() returns 0 if an error occurred or non-zero otherwise.
See Also	objc_change()

menu_istart()

WORD menu_istart( flag, tree, imenu, item )

WORD flag;

OBJECT *tree;

WORD imenu, item;

	menu_istart() shifts a sub-menu that is attached to a menu item to align vertically with the specified object in the sub-menu.
Opcode	38 (0x26)
Availability	This function is only available with AES versions 3.30 and above.
Parameters	flag should be set to MIS_SETALIGN (1) to modify the alignment of a sub-menu and its parent menu item. If flag is set to MIS_GETALIGN (0), no modifications will be made, however the sub-menu item index which is currently aligned with its parent menu item is returned. tree points to the object tree of the menu to alter. imenu specifies the object within the submenu which will be aligned with menu item item.
Binding	intin[0] = flag; intin[1] = imenu; intin[2] = item; addrin[0] = tree; return crys_if(0x26);
Return Value	menu_istart() returns 0 if an error occurred or the positive object index of the sub-menu item which is currently aligned with its parent menu item.
Comments	Generally, a sub-menu is aligned so that the currently selected sub-menu item is aligned with its parent menu.
See Also	menu_attach()

menu_popup()

WORD menu_popup( menu, xpos, ypos, mdata )

MENU *menu;

WORD xpos, ypos;

MENU *menu;

	menu_popup() displays a popup menu and returns the user's selection.
Opcode	36 (0x24)
Availability	This function is only available with AES versions 3.30 and above.
Parameters	menu points to a MENU structure (defined under menu_attach()) containing the popup menu. xpos and ypos specify the location at which the upper-left corner of the starting object will be placed. If the function returns a value of 1, the MENU structure pointed to by mdata will be filled in with the ending state of the menu (including the object the user selected). As of AES version 4.1, if menu.mn_scroll is set to SCROLL_LISTBOX (-1) when this function is called, a drop-down list box will be displayed instead of a popup menu. Dropdown list boxes will only display a scroll bar if at least eight entries exist. If you want to force the scroll bar to appear, pad the object with empty G_STRING objects with their DISABLED flag set.
Binding	intin[0] = xpos; intin[1] = ypos; addrin[0] = menu; addrin[1] = mdata; return crys_if(0x24);
Return Value	menu_popup() returns 0 if an error occurred or 1 if successful.
See Also	menu_attach(), menu_settings()

menu_register()

WORD menu_register( ap_id, title )

WORD ap_id;

char *title;

	menu_register() registers desk accessories in the 'Desk' menu and renames MultiTOS applications which appear there.
Opcode	35 (0x23)
Availability	All AES versions.
Parameters	ap_id specifies the application identifier of the application to register. title points to a NULL-terminated string containing the title which is to appear in the 'Desk' menu for the accessory or application. If ap_id is set to REG_NEWNAME (-1) then the process name given in title will be used as the new process name. The new process name should be exactly eight characters terminated with a NULL. Pad the string with space characters if necessary.
Binding	intin[0] = ap_id; addrin[0] = title; return crys_if(0x23);
Return Value	menu_register() returns a -1 if an error occurred or the menu identifier otherwise.
Version Notes	Applications other than desk accessories should not call this function unless they are running under MultiTOS.
Comments	Desk accessories should store the return value as this is the value that will be included with future AC_OPEN messages to identify the accessory. Applications running under MultiTOS may use this function to provide a more functional title for the 'Desk' menu than the program's filename. Calling menu_register() with a parameter of REG_NEWNAME is used to change the internal process name of the application returned by appl_find() and appl_search(). This is useful if you know another process will attempt to find your application as a specific process name and the user may have renamed your application filename (normally used as the process name).

menu_settings()

WORD menu_settings( flag, set )

WORD flag;

MN_SET *set;

	menu_settings() changes the global settings for popup and scrollable menus.
Opcode	39 (0x27)
Availability	This function is only available with AES versions 3.30 and above.
Parameters	If flag is 0, current settings are read into the MN_SET structure pointed to by set. If flag is 1, current settings are set from the MN_SET structure pointed to by set. MN_SET is defined as follows: typedef struct { /* Submenu-display delay in milliseconds */ LONG display; /* Submenu-drag delay in milliseconds */ LONG drag; /* Single-click scroll delay in milliseconds*/ LONG delay; /* Continuous-scroll delay in milliseconds */ LONG speed; /* Menu scroll height (in items) */ WORD height; } MN_SET;
Binding	intin[0] = flag; addrin[0] = set; return crys_if(0x27);
Return Value	menu_settings() always returns 1.
Comments	The defaults set by menu_settings() are global and not local to an application. You should therefore limit your use of this function to system applications like CPX's and so forth.

menu_text()

WORD menu_text( tree, obj, text )

OBJECT *tree;

WORD obj;

char *text;

	menu_text() changes the text of a menu item.
Opcode	34 (0x22)
Availability	All AES versions.
Parameters	tree specifies the object tree of the menu bar. obj specifies the object index of the menu item to change. text points to a NULL-terminated character string containing the new text.
Binding	intin[0] = obj; addrin[0] = tree; addrin[1] = text; return crys_if(0x22);
Return Value	menu_text() returns a 0 if an error occurred or non-zero otherwise.
Comments	The new menu item text must be no larger than the original menu item text.

menu_tnormal()

WORD menu_tnormal( tree, obj, flag )

OBJECT *tree;

WORD obj, flag;

	menu_tnormal() highlights/un-highlights a menu-title.
Opcode	33 (0x21)
Availability	All AES versions.
Parameters	tree specifies the object tree of the menu. obj specifies the object index of the title to change. flag should be set to HIGHLIGHT (0) to display the title in reverse (highlighted) or UNHIGHLIGHT (1) to display it normally.
Binding	intin[0] = obj intin[1] = flag addrin[1] = tree return crys_if(0x21);
Return Value	menu_tnormal() returns 0 if an error occurred or non-zero otherwise.
Comments	This call is usually called by an application after a MN_SELECTED message is received and processed to return the menu title to normal.

Object Library

The Object Library is responsible for the drawing and manipulation of AES objects such as boxes, strings, icons, etc. See earlier in this chapter for a complete discussion of AES objects. The Object Library includes the following functions:

objc_add()

objc_change()

objc_delete()

objc_draw()

objc_edit()

objc_find()

objc_offset()

objc_order()

WORD objc_add( tree, parent, child )

OBJECT *tree;

WORD parent, child;

	objc_add() establishes a child object's relationship to its parent.
Opcode	40 (0x28)
Availability	All AES versions.
Parameters	tree specifies the object tree to modify. parent and child specify the parent and child object to update.
Binding	intin[0] = parent; intin[1] = child; addrin[0] = tree; return crys_if(0x28);
Return Value	objc_add() returns a 0 if an error occurred or non-zero otherwise.
Comments	In order for this function to work, the object to be added must be already be a member of the OBJECT array. This function simply updates the ob_next, ob_head, and ob_tail structure members of OBJECTs in the object tree. These fields should be initialized to NIL (0) in the child to be added.
See Also	objc_order(), objc_delete()

objc_change()

WORD objc_change( tree, obj, rsvd, ox, oy, ow, oh, newstate, drawflag )

OBJECT *tree;

WORD obj, rsvd, ox, oy, ow, oh, newstate, drawflag;

	objc_change() changes the display state of an object.
Opcode	47 (0x2F)
Availability	All AES versions.
Parameters	tree specifies the object tree of the object to modify. obj specifies the object to modify. rsvd is reserved and should be 0. ox, oy, ow, and oh specify the clipping rectangle if the object is to be redrawn. newstate specifies the new state of the object (same as ob_state). If drawflag is NO_DRAW (0) the object is not redrawn whereas if drawflag is REDRAW (1) the object is redrawn.
Binding	intin[0] = obj; intin[1] = rsvd; intin[2] = ox; intin[3] = oy; intin[4] = ow; intin[5] = oh; intin[6] = newstate; intin[7] = drawflag; addrin[0] = tree; return crys_if(0x2F);
Return Value	objc_change() returns 0 if an error occurred and non-zero otherwise.
Comments	In general, if not redrawing the object, it is usually quicker to manipulate the object tree directly.
See Also	objc_draw()

objc_delete()

WORD objc_delete( tree, obj )

OBJECT *tree;

WORD obj;

	objc_delete() removes an object from an object tree.
Opcode	41 (0x29)
Availability	All AES versions.
Parameters	tree specifies the object tree of the object to delete. obj is the object to be deleted.
Binding	intin[0] = obj; addrin[0] = tree; return crys_if(0x29);
Return Value	objc_delete() returns 0 if an error occurred or non-zero otherwise.
Comments	This function does not move other objects in the tree structure, it simply unlinks the specified object from the object chain by updating the other object's ob_next, ob_head, and ob_tail structure members.
See Also	objc_add()

objc_draw()

WORD objc_draw( tree, obj, depth, ox, oy, ow, oh )

OBJECT *tree;

WORD obj, depth, ox, oy, ow, oh;

	objc_draw() renders an AES object tree on screen.
Opcode	42 (0x2A)
Availability	All AES versions.
Parameters	tree specifies the object tree to draw. obj specifies the object index at which drawing is to begin. depth specifies the maximum object depth to draw (a value of 1 searches only first generation objects, a value of 2 searches up to second generation objects, up to a maximum of 7 to search all objects). ox, oy, ow, and oh specify an AES style rectangle which defines the clip rectangle to enforce during drawing.
Binding	intin[0] = obj; intin[1] = depth; intin[2] = ox; intin[3] = oy; intin[4] = ow; intin[5] = oh; addrin[0] = tree; return crys_if(0x2A);
Return Value	objc_draw() returns 0 if an error occurred or non-zero otherwise.

objc_edit()

WORD objc_edit( tree, obj, kc, idx, mode )

OBJECT *tree;

WORD obj, kc;

WORD *idx

WORD mode;

	objc_edit() allows manual control of an editable text field.
Opcode	46 (0x2E)
Availability	All AES versions.
Parameters	tree specifies the object tree containing the editable object obj to modify. mode specifies the action of the call and the meaning of the other parameters as follows:
	mode	Value	Meaning
	ED_START	0	Reserved for future use. Do not call.
	ED_INIT	1	Display the edit cursor in the object specified. kc is ignored. The WORD pointed to by idx is filled in with the current index of the edit cursor in the field.
	ED_CHAR	2	A key has been pressed that needs special processing. kc contains the keyboard scan code in the high byte and ASCII code in the low byte. idx points to the current index of the text cursor in the field. idx will be updated as a result of this call.
	ED_END	3	Turn off the text cursor.
Binding	intin[0] = obj; intin[1] = kc; intin[2] = *idx; intin[3] = mode; addrin[0] = tree; crys_if(0x2E); *idx = intout[1]; return intout[0];
Return Value	objc_edit() returns 0 if an error occurred or non-zero otherwise.
Comments	This function is usually used in conjunction with form_keybd() in a custom form_do() handler.
See Also	form_keybd()

objc_find()

WORD objc_find( tree, obj, depth, ox, oy )

OBJECT *tree;

WORD obj, depth, ox, oy;

	objc_find() determines which object is found at a given coordinate.
Opcode	43 (0x2B)
Availability	All AES versions.
Parameters	tree specifies the object tree containing the objects to search. The search starts from object index obj forward in the object tree. depth specifies the depth in the tree to search (a value of 1 searches only first generation objects, a value of 2 searches up to second generation objects, up to a maximum of 7 to search all objects). ox and oy specify the coordinate to search at.
Binding	intin[0] = obj; intin[1] = depth; intin[2] = ox; intin[3] = oy; addrin[0] = tree; return crys_if(0x2B);
Return Value	objc_find() returns the object index of the object found at coordinates ( ox, oy ) or -1 if no object is found.

objc_offset()

WORD objc_offset( tree, obj, ox, oy )

OBJECT *tree;

WORD obj;

WORD *ox, *oy;

	objc_offset() calculates the true screen coordinates of an object.
Opcode	44 (0x2C)
Availability	All AES versions.
Parameters	tree specifies the object tree containing obj. The WORDs pointed to by ox and oy will be filled in with the true X and Y screen position of object obj.
Binding	intin[0] = obj; addrin[0] = tree; crys_if(0x2C); *ox = intout[1]; *oy = intout[2]; return intout[0];
Return Value	objc_offset() returns 0 if an error occurred or non-zero otherwise.
Comments	The ob_x and ob_y structure members of objects give an offset from their parent as opposed to true screen location. This call is used to determine a true screen coordinate. The values returned by objc_offset() coupled with the ob_width and ob_height members do not take into account negative borders, shadowing, or sculpturing. When redrawing an object you are responsible for using these values to and the object's state to compensate for a correct clipping rectangle.
See Also	objc_draw()

objc_order()

WORD objc_order( tree, obj, pos )

OBJECT *tree;

WORD obj, pos;

	objc_order() changes the position of an object relative to other child objects of the same parent.
Opcode	45 (0x2D)
Availability	All AES versions.
Parameters	tree specifies the object tree of object obj which is to be moved. pos specifies the new position of the object as follows:
		Name	pos	Meaning
		OO_LAST	-1	Make object the last child.
		OO_FIRST	0	Make object the first child.
		-	1	Make object the second child.
		-	2-	etc...
Binding	intin[0] = obj; intin[1] = pos; addrin[0] = tree; return crys_if(0x2D);
Return Value	objc_order() returns 0 if an error occurred or non-zero otherwise.
Comments	objc_order() does not actually move structure elements in memory. It works by updating the OBJECT tree's ob_head, ob_tail, and ob_next fields to 'move' the OBJECT in the tree hierarchy.

objc_sysvar()

WORD objc_sysvar( mode, which, in1, in2, out1, out2 )

WORD mode, which, in1, in2;

WORD *out1, *out2;

	objc_sysvar() returns/modifies information about the color and placement of 3D object effects.
Opcode	48 (0x30)
Availability	Available as of AES version 3.40.
Parameters	mode determines whether attributes should be read or modified. A value of SV_INQUIRE (0) will read the current values whereas a value of SV_SET (1) will modify the current values. which determines what attribute you wish to read or modify. When reading values, in1 and in2 are unused. The two return values are placed in the WORDs pointed to by out1 and out2. When modifying values, out1 and out2 are unused. in1 and in2 specify the new values for the attribute. The meanings of the two input/output values referred to as val1 and val2 are as follows:
	Name	which	Values
	LK3DIND	1	If val1 is 1, the text of indicator objects does move when selected, otherwise, if 0, it does not. If val2 is 1, the color of indicator objects does change when selected, otherwise, if 0, it does not.
	LK3DACT	2	Same as LK3DIND for activator objects.
	INDBUTCOL	3	val1 specifies the default color for indicator objects. val2 is unused.
	ACTBUTCOL	4	val1 specifies the default color for activator objects. val2 is unused.
	BACKGRCOL	5	val1 specifies the default color for background objects. val2 is unused.
	AD3DVAL	6	val1 specifies the number of extra pixels on each horizontal side of an indicator or activator object needed to accomodate 3D effects. val2 specifies the number of extra pixels on each vertical side of an indicator or activator object needed to accomodate 3D effects. This setting may only be read, not modified.
Binding	intin[0] = mode; intin[1] = which; intin[2] = in1; intin[3] = in2; crys_if(0x30); *out1 = intout[1]; *out2 = intout[2]; return intout[0];
Return Value	objc_sysvar() returns 0 if unsuccessful or non-zero otherwise.
Comments	Applications should not use objc_sysvar() to change these settings since all changes are global. Only CPXs or Desk Accessories designed to modify these parameters should.

Resource Library

The Resource Library is responsibe for the loading/unloading of resource files and the manipulation of resource objects in memory. The members of the Resource Library are:

rsrc_free()

rsrc_gaddr()

rsrc_load()

rsrc_obfix()

rsrc_rcfix()

WORD rsrc_free( VOID )

	rsrc_free() releases memory allocated by rsrc_load() for an application's resource.
Opcode	111 (0x6F)
Availability	All AES versions.
Binding	return crys_if(0x6F);
Return Value	rsrc_free() returns 0 if an error occurred or non-zero otherwise.
Comments	rsrc_free() should be called before an application which loaded a resource using rsrc_load() exits.
See Also	rsrc_load()

rsrc_gaddr()

WORD rsrc_gaddr( type, index, addr )

WORD type, index;

VOIDPP addr;

	rsrc_gaddr() returns the address of an object loaded with rsrc_load().
Opcode	112 (0x70)
Availability	All AES versions.
Parameters	The pointer pointed to by addr will be filled in with the address of the indexth resource object of type type. Valid values for type are as follows:
		Name	type	Resource Object
		R_TREE	0	Object tree
		R_OBJECT	1	Individual object
		R_TEDINFO	2	TEDINFO structure
		R_ICONBLK	3	ICONBLK structure
		R_BITBLK	4	BITBLK structure
		R_STRING	5	Free String data
		R_IMAGEDATA	6	Free Image data
		R_OBSPEC	7	ob_spec field within OBJECTs
		R_TEPTEXT	8	te_ptext within TEDINFOs
		R_TEPTMPLT	9	te_ptmplt within TEDINFOs
		R_TEPVALID	10	te_pvalid within TEDINFOs
		R_IBPMASK	11	ib_pmask within ICONBLKs
		R_IBPDATA	12	ib_pdata within ICONBLKs
		R_IBPTEXT	13	ib_ptext within ICONBLKs
		R_BIPDATA	14	bi_pdata within BITBLKs
		R_FRSTR	15	Free string
		R_FRIMG	16	Free image
Binding	intin[0] = type; intin[1] = index; crys_if(0x70); *addr = addrout[0]; return intout[0];
Return Value	rsrc_gaddr() returns a 0 if the address in addr is valid or non-zero if the object did not exist.
Comments	This function is most often used to obtain the address of OBJECT trees, 'free' strings, and 'free' images after loading a resource file.
See Also	rsrc_saddr()

rsrc_load()

WORD rsrc_load( fname )

char *fname;

	rsrc_load() loads and allocates memory for the named resource file.
Opcode	110 (0x6E)
Availability	All AES versions.
Parameters	fname is a character pointer to a NULL-terminated GEMDOS file specification of the resource to load.
Binding	addrin[0] = fname; return crys_if(0x6E);
Return Value	rsrc_load() returns 1 if successful or zero if an error occurred.
Comments	In addition to loading the resource, all OBJECT coordinates are converted from character based coordinates to screen coordinates.
See Also	rsrc_free()

rsrc_obfix()

WORD rsrc_obfix( tree, obj )

OBJECT *tree;

WORD obj;

	rsrc_obfix() converts an object's coordinates from character-based to pixel-based.
Opcode	114 (0x72)
Availability	All AES versions.
Parameters	tree specifies the OBJECT tree containing the object obj to convert.
Binding	intin[0] = obj; addrin[0] = tree; return crys_if(0x72);
Return Value	rsrc_obfix() always returns a 0.
Comments	All objects in '.RSC' files have their coordinates based on character positions rather than screen coordinates to allow an object tree to be shown in any resolution. This function converts those character coordinates to pixel coordinates based on the current screen resolution.
See Also	rsrc_load(), rsrc_rcfix()

rsrc_rcfix()

WORD rsrc_rcfix( rc_header )

VOID *rc_header;

	rsrc_rcfix() fixes up coordinates and memory pointers of raw resource data in memory.
Opcode	115 (0x73)
Availability	Available only in AES versions 4.0 and greater. The presence of this call should also be checked for using appl_getinfo().
Parameters	rc_header is a pointer to an Atari Resource Construction Set (or compatible) resource file header in memory.
Binding	addrin[0] = rc_header; return crys_if(0x73);
Return Value	rsrc_rcfix() returns a non-zero if successful or zero otherwise.
Comments	If a resource has already been loaded with rsrc_load() it must be freed by rsrc_free() prior to this call. In addition, resources identified with this call must likewise be freed before program termination or another resource file is needed.
See Also	rsrc_obfix()

rsrc_saddr()

WORD rsrc_saddr( type, index, addr )

WORD type, index;

VOID *addr;

	rsrc_saddr() sets the address of a resource element.
Opcode	113 (0x71)
Availability	All AES versions.
Parameters	type specifies the type of resource element to set as defined under rsrc_gaddr(). index specifies the index of the element to modify (0 based). addr specifies the actual address that will be placed in the appropriate data structure.
Binding	intin[0] = type; intin[1] = index; addrin[0] = addr; return crys_if(0x71);
Return Value	rsrc_saddr() returns 0 if an error occurred or non-zero otherwise.
Comments	In most cases, direct manipulation of the structures involved is quicker and easier than using this call.
See Also	rsrc_gaddr(), rsrc_load()

Scrap Library

The Scrap Library is used to maintain the location of the clipboard directory used for interprocess data exchange. The members of the Scrap Library are:

scrp_read()

WORD scrp_read( cpath )

char *cpath;

	scrp_read() returns the location of the current clipboard directory.
Opcode	80 (0x50)
Availability	All AES versions.
Parameters	cpath is a pointer to a character buffer of at least 128 bytes into which the clipboard path will be placed.
Binding	addrin[0] = cpath; return crys_if(0x50);
Return Value	scrp_read() returns 0 if the clipboard path had not been set or non-zero if cpath was properly updated.
Caveats	The system scrap directory is a global resource. Some programs incorrectly call scrp_write() with a path and filename when only a pathname should be used. The following is an example of a correctly formatted cpath argument: C:\CLIPBRD\Unfortunately, not all programs adhere exactly to this standard. For this reason, programs reading this information from scrp_read() should be especially careful that the information returned is parsed correctly. In addition, don't count on a trailing backslash or the existence of a drive specification.
Comments	If a value of 0 is returned and the application wishes to write a scrap to the clipboard you should follow these steps: Create a folder '\CLIPBRD\' on the root directory of the user's boot drive ('C:' or 'A:'). Write your scrap to the directory as 'SCRAP.???' where '???' signifies the type of information contained in the file. Allow other applications to access this information by calling scrp_write() with the new clipboard path. For example "C:\CLIPBRD\".A detailed discussion of the proper clipboard data exchange protocol, including information about a scrap directory semaphore useful with MultiTOS, is given earlier in this chapter.
See Also	scrp_write()

scrp_write()

WORD scrp_write( cpath )

char *cpath;

	scrp_write() sets the location of the clipboard directory.
Opcode	81 (0x51)
Availability	All AES versions.
Parameters	cpath points to a NULL-terminated path string containing a valid drive and path specification with a closing backslash. The following is an example of a correctly formatted cpath argument: C:\CLIPBRD\
Binding	addrin[0] = cpath; return crys_if(0x51);
Return Value	scrp_write() returns 0 if an error occurred or non-zero otherwise.
Comments	The scrap directory is a global resource. This call should only be used in two circumstances as follows: when used to set the default location of the scrap directory using a CPX or accessory at bootup or by the user's request. when scrp_read() returns an error value and you need to create the clipboard to write information to it.The clipboard data exchange protocol is discussed in greater detail earlier in this chapter.
See Also	scrp_read()