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

Form Library
[AES Function Reference]

user interaction with dialogs & error messages More...

Data Structures

struct  SCANX
struct  XDO_INF
struct  POPUP_INIT_args

Functions

short mt_form_alert (short DefButton, const char *Str, short *global_aes)
short mt_form_button (OBJECT *, short Bobject, short Bclicks, short *Bnxtobj, short *global_aes)
short mt_form_center (OBJECT *, short *Cx, short *Cy, short *Cw, short *Ch, short *global_aes)
short mt_form_center_grect (OBJECT *, GRECT *r, short *global_aes)
short mt_form_dial (short Flag, short Sx, short Sy, short Sw, short Sh, short Bx, short By, short Bw, short Bh, short *global_aes)
short mt_form_do (OBJECT *, short StartObj, short *global_aes)
short mt_form_error (short ErrorCode, short *global_aes)
short mt_form_keybd (OBJECT *, short Kobject, short Kobnext, short Kchar, short *Knxtobject, short *Knxtchar, short *global_aes)
short mt_form_popup (OBJECT *tree, short x, short y, short *global)
short mt_form_wbutton (OBJECT *fo_btree, short fo_bobject, short fo_bclicks, short *fo_bnxtobj, short whandle, short *global)
short mt_form_wkeybd (OBJECT *fo_ktree, short fo_kobject, short fo_kobnext, short fo_kchar, short *fo_knxtobject, short *fo_knxtchar, short whandle, short *global)
short mt_form_xdial (short fo_diflag, short fo_dilittlx, short fo_dilittly, short fo_dilittlw, short fo_dilittlh, short fo_dibigx, short fo_dibigy, short fo_dibigw, short fo_dibigh, void **flydial, short *global)
short mt_form_xdial_grect (short fo_diflag, const GRECT *fo_dilittl, const GRECT *fo_dibig, void **flydial, short *global)
short mt_form_xdo (OBJECT *tree, short startob, short *lastcrsr, XDO_INF *tabs, void *flydial, short *global)
short mt_form_xerr (long errcode, char *errfile, short *global)
short mt_xfrm_popup (OBJECT *tree, short x, short y, short firstscrlob, short lastscrlob, short nlines, void __CDECL(*init)(struct POPUP_INIT_args), void *param, short *lastscrlpos, short *global)

Detailed Description

user interaction with dialogs & error messages

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


Function Documentation

short mt_form_alert short  default_button,
const char *  alert_string,
short global_aes
 

displays a standardized alert box and returns the user's selection.

Parameters:
default_button contains the number of the exit button which is to be made default (1-3)
alert_string contains a formatted string "[x][Alert Text][Buttons]" where
  • x specifies the icon to display in the alert as follows:
  • '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.
global_aes global AES array
Returns:
a word indicating which button was used to exit by the user (A possible value of 1-3).
Since:
All AES versions. Icons #4-5 are only available as of AES version 4.1.
Several versions of the AES have special quirks related to this function. By following the guidelines below you should avoid any difficulty:
  • 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.
  • 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.

short mt_form_button OBJECT tree,
short  object,
short  clicks,
short nextobj,
short global_aes
 

is a utility function designed to aid in the creation of a custom mt_form_do() handler.

Parameters:
tree is a pointer to a valid object tree in memory you wish to process button events for.
object 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 needs to be clicked.
nextobj the next object to gain edit focus or 0 if there are no editable objects. If the top bit of nextobj is set, this indicates that a OF_TOUCHEXIT object was double-clicked.
[option CHECK_NULLPTR] nextobj may be NULL
global_aes global AES array
Returns:
0 if it exits finding an OF_EXIT or OF_TOUCHEXIT object selected or 1 otherwise.
Since:
All AES versions.
See also:
mt_form_do(), mt_form_keybd()
To use this function properly, the application should take the following steps:
  1. Monitor mouse clicks with mt_evnt_multi() or mt_evnt_button().
  2. When a click occurs, use mt_objc_find() to determine if the click occurred over the object.
  3. If so, call mt_form_button() with the appropriate values.

Note:
This function was not originally documented by Atari.

short mt_form_center OBJECT tree,
short cx,
short cy,
short cw,
short ch,
short global_aes
 

is used to modify an object's coordinates so that it will appear in the center of the display screen.

Parameters:
tree points to a valid OBJECT structure which the application wishes to have centered.
cx 
cy 
cw 
ch is a clipping rectangle suitable for use in objc_draw() returned.
[option CHECK_NULLPTR] cx, cy, cw and/or ch may be NULL
global_aes global AES array
Returns:
is currently reserved. Currently it equals 1.
Since:
All AES versions.
See also:
mt_objc_draw()
The values that mt_form_center() returns in cx, cy, cw, and ch, 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 mt_objc_draw()

short mt_form_center_grect OBJECT tree,
GRECT r,
short global_aes
 

see mt_form_center()

Parameters:
tree mt_form_center()
r mt_form_center()
[option CHECK_NULLPTR] r may be NULL
global_aes global AES array
Returns:
see mt_form_center()
Since:
see mt_form_center()

short mt_form_dial short  mode,
short  x1,
short  y1,
short  w1,
short  h1,
short  x2,
short  y2,
short  w2,
short  h2,
short global_aes
 

is used to reserve and release screen space for dialog usage. In addition, it also optionally provides grow/shrink box effects.

Parameters:
mode specifies the action to take and the meaning of remaining parameters as follows:
  • FMD_START : 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 mt_form_center()).
  • FMD_GROW 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 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 This mode releases the screen space for a dialog (previously reserved with mode FMD_START). 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.
x1 
y1 
w1 
h1 the first rectangle (usage depends on mode)
x2 
y2 
w2 
h2 the second rectangle (usage depends on mode)
global_aes global AES array
Returns:
non-zero if succeeded.
Since:
All AES versions.
See also:
mt_graf_growbox(), mt_graf_shrinkbox()
The AES does not currently make use of mode FMD_START. The call should, however, still be executed for upward compatibility.

short mt_form_do OBJECT tree,
short  startobj,
short global_aes
 

provides an automated dialog handling function to the calling application.

Parameters:
tree is a pointer to a valid object tree which contains a dialog with at least one OF_EXIT or OF_TOUCHEXIT button or object.
startobj is the object index into tree which specifies the desired initial location of the edit cursor (the object must be flagged as OF_EDITABLE). If the form has no text editable fields, you should use 0.
global_aes global AES array
Returns:
the object index of the OF_EXIT or OF_TOUCHEXIT button which was selected. If the object was double clicked, the top bit will be set. This means that to obtain the actual object number you should mask it out with 0x7FFF.
Since:
All AES versions.
It suspends program control, handles all radio buttons, selectable objects, etc... until an object with the OF_TOUCHEXIT or OF_EXIT flag is selected.

short mt_form_error short  error_code,
short global_aes
 

displays a pre-defined error alert box to the user.

Parameters:
error_code specifies a MS-DOS error code as follows:
  • FERR_FILENOTFOUND : File Not Found The application can not find the folder or file that you tried to access.
  • FERR_PATHNOTFOUND : Path Not Found The application cannot find the folder or file that you tried to access.
  • FERR_NOHANDLES : 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 : Access Denied An item with this name already exists in the directory, or this item is set to read-only status.
  • FERR_LOWMEM : Insufficient Memory There is not enough memory for the application you just tried to run.
  • FERR_BADENVIRON : Invalid Environment There is not enough memory for the application you just tried to run.
  • FERR_BADFORMAT : Invalid Format There is not enough memory for the application you just tried to run.
  • FERR_BADDRIVE : Invalid Drive Specification The drive you specified does not exist.
  • FERR_DELETEDIR : Attempt To Delete Working Directory You cannot delete the folder in which you are working.
  • FERR_NOFILES : No More Files The application can not find the folder or file that you tried to access.
global_aes global AES array
Returns:
the exit button clicked as in mt_form_alert(). It is, however, insignifigant as all of the error alerts have only one button.
Since:
All AES versions.
See also:
mt_form_alert()
Note:
The GEMDOS error number can be translated into the code expected in error_code by subtracting 31 from the absolute value of the GEMDOS error code.

Not every GEMDOS error code has a matching alert box.

short mt_form_keybd OBJECT tree,
short  object,
short  reserved,
short  key,
short nextobject,
short nextchar,
short global_aes
 

processes keyboard input for dialog box control.

Parameters:
tree points to a valid OBJECT tree containing the dialog you wish to process.
object is the object index of the object which currently has edit focus (0 if none).
reserved should be 1.
key is the value returned from mt_evnt_keybd() or mt_evnt_multi() which represents the keypresses' scan code and ASCII value.
nextobject is a WORD pointer which is filled in on function exit to be the new object with edit focus unless the return key was pressed with a default object present in which case it equals the object index of the object that was the default.
[option CHECK_NULLPTR] nextobject may be NULL
nextchar is the value ready to be passed on to mt_objc_edit() if no processing was required or 0 if the key was processed and handled by the call.
[option CHECK_NULLPTR] nextchar may be NULL
global_aes global AES array
Returns:
0 if a default OF_EXIT object was triggered by this call or 1 if the dialog should continue to be processed.
Since:
All AES versions.
See also:
mt_objc_edit(), mt_form_do(), mt_form_button()
It handles special keys such as return, escape, tab, etc... It is only of real use if you are writing a customized mt_form_do() routine.

Note:
This function was not originally documented by Atari.

short mt_form_popup OBJECT tree,
short  x,
short  y,
short global_aes
 

Parameters:
tree is a pointer to a valid object tree
x 
y coordinates around which the tree will be centered, or 0 (the position of the tree is not changed).
global_aes global AES array
Returns:
the index of the object which has been clicked by the user to close the popup, or -1.
Since:
the availability of this function can be checked by calling mt_appl_getinfo() with the parameter AES_MENU
Selectable objects of this dialog don't need to have the OF_SELECTABLE flag set. If an object don't have to be selectable, then set the flag OS_DISABLED.

The object type of the root object (index 0) shall be either G_BOX or G_IBOX.

Note:
One shall ensure that the tree object fit entierely in the screen.

short mt_form_wbutton OBJECT fo_btree,
short  fo_bobject,
short  fo_bclicks,
short fo_bnxtobj,
short  whandle,
short global_aes
 

Service button event for window dialogs

Parameters:
fo_btree as for mt_form_button()
fo_bobject as for mt_form_button()
fo_bclicks as for mt_form_button()
fo_bnxtobj as for mt_form_button()
[option CHECK_NULLPTR] fo_bnxtobj may be NULL
whandle window handle
global_aes global AES array
Returns:
as for mt_form_button()
Since:
MagiC 5.10

short mt_form_wkeybd OBJECT fo_ktree,
short  fo_kobject,
short  fo_kobnext,
short  fo_kchar,
short fo_knxtobject,
short fo_knxtchar,
short  whandle,
short global_aes
 

Parameters:
fo_ktree as for mt_form_keybd()
fo_kobject as for mt_form_keybd()
fo_kobnext as for mt_form_keybd()
fo_kchar as for mt_form_keybd()
fo_knxtobject as for mt_form_keybd()
[option CHECK_NULLPTR] fo_knxtobject may be NULL
fo_knxtchar as for mt_form_keybd()
[option CHECK_NULLPTR] fo_knxtchar may be NULL
whandle window handle
global_aes global AES array
Returns:
as for mt_form_keybd()
Since:
MagiC 5.10

short mt_form_xdial short  fo_diflag,
short  fo_dilittlx,
short  fo_dilittly,
short  fo_dilittlw,
short  fo_dilittlh,
short  fo_dibigx,
short  fo_dibigy,
short  fo_dibigw,
short  fo_dibigh,
void **  flydial,
short global_aes
 

form xdialog space

Parameters:
fo_diflag specifies the action to take and the meaning of other parameters, as specified in mt_form_dial() documentation. This function performs some additionnal actions (compared to mt_form_dial()) when called with the following values (this is related to the extra flydial parameter) :
  • FMD_START memory is reserved to save the background covered by the dialog
  • FMD_FINISH restore the screen background and free the memory previously reserved
fo_dilittlx 
fo_dilittly 
fo_dilittlw 
fo_dilittlh position and dimension of the little rectangle
fo_dibigx 
fo_dibigy 
fo_dibigw 
fo_dibigh position and dimension of the big rectangle
flydial 0 if you don't want to use the flydial feature, or a pointer to a (void*) variable. See below.
global_aes global AES array
Returns:
non-zero if succeeded.
Since:
The presence of the flydial support can be checked by calling mt_appl_getinfo() with parameter AES_FORM.
If flydial is not equal to 0, it is tested whether sufficiant memory is available in order to save the background of the dialog box. A pointer on the saved data (screen memory under the dialog) is then saved in flydial.

short mt_form_xdial_grect short  fo_diflag,
const GRECT fo_dilittl,
const GRECT fo_dibig,
void **  flydial,
short global_aes
 

Parameters:
fo_diflag see mt_form_xdial()
fo_dilittl see mt_form_xdial()
fo_dibig see mt_form_xdial()
flydial see mt_form_xdial()
global_aes global AES array
Returns:
see mt_form_xdial()
Since:
see mt_form_xdial()

short mt_form_xdo OBJECT tree,
short  startob,
short lastcrsr,
XDO_INF tabs,
void *  flydial,
short global_aes
 

provides an extended automated dialog handling function to the calling application

Parameters:
tree is a pointer to a valid object tree which contains a dialog with at least one OF_EXIT or OF_TOUCHEXIT button or object.
startob is the object index into tree which specifies the desired initial location of the edit cursor (the object must be flagged as OF_EDITABLE). If the form has no text editable fields, you should use 0.
lastcrsr will contain the index of the editable field in which the edit cursor was when the function returned.
[option CHECK_NULLPTR] lastcrsr may be NULL
tabs pointer on keyboard tables, or NULL.
flydial parameter *flydial returned by mt_form_xdial() with FMD_START command.
global_aes global AES array
Returns:
the object index of the OF_EXIT or OF_TOUCHEXIT button which was selected.
Since:
MagiC 2.0. The presence of the flydials, the keyboard tables and the possibility of inquiring the last cursor position can be checked by calling mt_appl_getinfo() with parameter AES_FORM.

short mt_form_xerr long  errcode,
char *  errfile,
short global_aes
 

extended function that display a pre-defined error alert box to the user.

Parameters:
errcode is the error code. This code may be either in MS-DOS format (a positive interger, as expected by mt_form_error()), or directly the GEMDOS/BIOS error code (negative value returned by a GEMDOS or a BIOS function)
errfile path of the file that causes the error (this string will appear in the alert box), or 0L (the parameter will be ignored), or -1L (the alert box will display "program returned:" in place of the filename).
global_aes global AES array
Returns:
the exit button clicked as in mt_form_alert(). It is, however, insignifigant as all of the error alerts have only one button.
Since:
MagiC 2.0
See also:
mt_form_error()
Note:
if errcode is 0 (EOK, no error) or -68 (EBREAK, program aborted by the user by pressing CTRL-C keys), then no form is display.

short mt_xfrm_popup OBJECT tree,
short  x,
short  y,
short  firstscrlob,
short  lastscrlob,
short  nlines,
void __CDECL(*)(struct POPUP_INIT_args init,
void *  param,
short lastscrlpos,
short global_aes
 

Parameters:
tree 
x 
y 
firstscrlob 
lastscrlob 
nlines 
init 
param 
lastscrlpos 
global_aes global AES array
Returns:
Since:
MagiC 5.03


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