GEMLIB
0.44.0
|
user interaction with dialogs & error messages More...
Data Structures | |
struct | SCANX |
struct | XDO_INF |
struct | POPUP_INIT_args |
Macros | |
#define | form_alert(a, b) mt_form_alert(a,b,aes_global) |
#define | form_button(a, b, c, d) mt_form_button(a,b,c,d,aes_global) |
#define | form_center(a, b, c, d, e) mt_form_center(a,b,c,d,e,aes_global) |
#define | form_center_grect(a, b) mt_form_center_grect(a,b,aes_global) |
#define | form_dial(a, b, c, d, e, f, g, h, i) mt_form_dial(a,b,c,d,e,f,g,h,i,aes_global) |
#define | form_do(a, b) mt_form_do(a,b,aes_global) |
#define | form_error(a) mt_form_error(a,aes_global) |
#define | form_keybd(a, b, c, d, e, f) mt_form_keybd(a,b,c,d,e,f,aes_global) |
#define | form_popup(a, b, c) mt_form_popup(a,b,c,aes_global) |
#define | form_wbutton(a, b, c, d, e) mt_form_wbutton(a,b,c,d,e,aes_global) |
#define | form_wkeybd(a, b, c, d, e, f, g) mt_form_wkeybd(a,b,c,d,e,f,g,aes_global) |
#define | form_xdial(a, b, c, d, e, f, g, h, i, j) mt_form_xdial(a,b,c,d,e,f,g,h,i,j,aes_global) |
#define | form_xdial_grect(a, b, c, d) mt_form_xdial_grect(a,b,c,d,aes_global) |
#define | form_xdo(a, b, c, d, e) mt_form_xdo(a,b,c,d,e,aes_global) |
#define | form_xerr(a, b) mt_form_xerr(a,b,aes_global) |
#define | xfrm_popup(a, b, c, d, e, f, g, h, i) mt_xfrm_popup(a,b,c,d,e,f,g,h,i,aes_global) |
#define | objc_wchange(a, b, c, d, e) mt_objc_wchange(a,b,c,d,e,aes_global) |
#define | objc_wdraw(a, b, c, d, e) mt_objc_wdraw(a,b,c,d,e,aes_global) |
#define | objc_wedit(a, b, c, d, e, f) mt_objc_wedit(a,b,c,d,e,f,aes_global) |
#define | objc_xedit(a, b, c, d, e, f) mt_objc_xedit(a,b,c,d,e,f,aes_global) |
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) |
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.
#define form_alert | ( | a, | |
b | |||
) | mt_form_alert(a,b,aes_global) |
single-thread version of mt_form_alert()
#define form_button | ( | a, | |
b, | |||
c, | |||
d | |||
) | mt_form_button(a,b,c,d,aes_global) |
single-thread version of mt_form_button()
#define form_center | ( | a, | |
b, | |||
c, | |||
d, | |||
e | |||
) | mt_form_center(a,b,c,d,e,aes_global) |
single-thread version of mt_form_center()
#define form_center_grect | ( | a, | |
b | |||
) | mt_form_center_grect(a,b,aes_global) |
single-thread version of mt_form_center_grect()
#define form_dial | ( | a, | |
b, | |||
c, | |||
d, | |||
e, | |||
f, | |||
g, | |||
h, | |||
i | |||
) | mt_form_dial(a,b,c,d,e,f,g,h,i,aes_global) |
single-thread version of mt_form_dial()
#define form_do | ( | a, | |
b | |||
) | mt_form_do(a,b,aes_global) |
single-thread version of mt_form_do()
#define form_error | ( | a | ) | mt_form_error(a,aes_global) |
single-thread version of mt_form_error()
#define form_keybd | ( | a, | |
b, | |||
c, | |||
d, | |||
e, | |||
f | |||
) | mt_form_keybd(a,b,c,d,e,f,aes_global) |
single-thread version of mt_form_keybd()
#define form_popup | ( | a, | |
b, | |||
c | |||
) | mt_form_popup(a,b,c,aes_global) |
single-thread version of mt_form_popup()
#define form_wbutton | ( | a, | |
b, | |||
c, | |||
d, | |||
e | |||
) | mt_form_wbutton(a,b,c,d,e,aes_global) |
single-thread version of mt_form_wbutton()
#define form_wkeybd | ( | a, | |
b, | |||
c, | |||
d, | |||
e, | |||
f, | |||
g | |||
) | mt_form_wkeybd(a,b,c,d,e,f,g,aes_global) |
single-thread version of mt_form_wkeybd()
#define form_xdial | ( | a, | |
b, | |||
c, | |||
d, | |||
e, | |||
f, | |||
g, | |||
h, | |||
i, | |||
j | |||
) | mt_form_xdial(a,b,c,d,e,f,g,h,i,j,aes_global) |
single-thread version of mt_form_xdial()
#define form_xdial_grect | ( | a, | |
b, | |||
c, | |||
d | |||
) | mt_form_xdial_grect(a,b,c,d,aes_global) |
single-thread version of mt_form_xdial_grect()
#define form_xdo | ( | a, | |
b, | |||
c, | |||
d, | |||
e | |||
) | mt_form_xdo(a,b,c,d,e,aes_global) |
single-thread version of mt_form_xdo()
#define form_xerr | ( | a, | |
b | |||
) | mt_form_xerr(a,b,aes_global) |
single-thread version of mt_form_xerr()
#define objc_wchange | ( | a, | |
b, | |||
c, | |||
d, | |||
e | |||
) | mt_objc_wchange(a,b,c,d,e,aes_global) |
single-thread version of mt_objc_wchange()
#define objc_wdraw | ( | a, | |
b, | |||
c, | |||
d, | |||
e | |||
) | mt_objc_wdraw(a,b,c,d,e,aes_global) |
single-thread version of mt_objc_wdraw()
#define objc_wedit | ( | a, | |
b, | |||
c, | |||
d, | |||
e, | |||
f | |||
) | mt_objc_wedit(a,b,c,d,e,f,aes_global) |
single-thread version of mt_objc_wedit()
#define objc_xedit | ( | a, | |
b, | |||
c, | |||
d, | |||
e, | |||
f | |||
) | mt_objc_xedit(a,b,c,d,e,f,aes_global) |
single-thread version of mt_objc_xedit()
#define xfrm_popup | ( | a, | |
b, | |||
c, | |||
d, | |||
e, | |||
f, | |||
g, | |||
h, | |||
i | |||
) | mt_xfrm_popup(a,b,c,d,e,f,g,h,i,aes_global) |
single-thread version of mt_xfrm_popup()
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.
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
|
global_aes | global AES array |
Several versions of the AES have special quirks related to this function. By following the guidelines below you should avoid any difficulty:
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.
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 |
To use this function properly, the application should take the following steps:
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.
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 |
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()
see mt_form_center()
tree | mt_form_center() |
r | mt_form_center() [option CHECK_NULLPTR] r may be NULL |
global_aes | global AES array |
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.
mode | specifies the action to take and the meaning of remaining parameters as follows:
|
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 |
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.
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 |
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.
error_code | specifies a MS-DOS error code as follows:
|
global_aes | global AES array |
short mt_form_keybd | ( | OBJECT * | tree, |
short | editfocus, | ||
short | nextobj, | ||
short | key, | ||
short * | newobj, | ||
short * | keyout, | ||
short * | global_aes | ||
) |
processes keyboard input for dialog box control.
tree | points to a valid OBJECT tree containing the dialog you wish to process. |
editfocus | is the object index of the object which currently has edit focus (0 if none). |
nextobj | When return value is 1 and keyout is not 0 to indicate it was not used, the value in nextobj is passed back in newobj. Setting both 'object' and 'nextobj' to the same value is recomended, since then if editfocus change happens, 'newobj' will be different from value passsed in 'object'. |
key | is the value returned from mt_evnt_keybd() or mt_evnt_multi() which represents the keypresses' scan code and ASCII value. |
newobj | is a WORD pointer which can have two meanings :
[option CHECK_NULLPTR] newobj may be NULL |
keyout | 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] keyout may be NULL |
global_aes | global AES array |
0 | if a default OF_EXIT object was triggered by this call |
1 | if the dialog should continue to be processed. |
XaAES implements a keyboard navigation system that is totally dependant on the usage of this function. Therefore, always let the AES get a chance to act on keypresses by calling this function when servicing a dialog!
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 | ||
) |
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 |
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.
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
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 |
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 | ||
) |
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 |
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
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) :
|
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 |
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 | ||
) |
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 |
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
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 |
short mt_form_xerr | ( | long | errcode, |
char * | errfile, | ||
short * | global_aes | ||
) |
extended function that display a pre-defined error alert box to the user.
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 |
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 | ||
) |
tree | |
x | |
y | |
firstscrlob | |
lastscrlob | |
nlines | |
init | |
param | |
lastscrlpos | |
global_aes | global AES array |