8.11 Form library

• The exclamation mark should be used for any kind of message that the user should just confirm briefly.
   

• The question mark serves for all queries that should be answered before an action takes place (e.g. the deletion of a file).
   

• The stop sign should be employed for serious problems which it is imperative that the user knows about.
   

MagiC:

Due to the compatibility to GEM/3, alert boxes here can contain up to 40 characters per text line and 20 characters per button. In addition, all alert boxes may be operated completely via the keyboard, with the function key [F1] servicing the left, [F2] the centre and [F3] the right button.
 

ViewMAX/2

and later parse the 'default button' parameter as two bytes; the low byte is the default button and the high byte is the Cancel button (ESC is a shortcut for it). This style of parameter will crash earlier GEM versions.
 

Under Geneva,

the alert string can contain left bracket ('[') characters within the text of the buttons. These denote the keyboard equivalents to be used for the buttons. For example, this defines an alert with the equivalents [Alternate][H] and [Alternate][Y]:
 
form_alert( 1, "[1][Hi there!][[Hi!|B[ye!]" );
 
If an alert button does not contain a pre-defined keyboard equivalent, it will be considered for an automatic keyboard equivalent.
 
Note: DO NOT use this type of alert string when running without Geneva, as this will have some unpredictable results.
 
Additionally, if an alert would normally not have a default button, Geneva always forces the rightmost button to be the default. For example:
 
form_alert( 2, "[1][Hi!][OK]" ); /* OK is the default */
 

int16_t form_alert (int16_t fo_adefbttn,
                    CONST int8_t *fo_astring)
{
   int_in[0]  = fo_adefbttn;
   addr_in[0] = fo_astring;

   return ( crys_if(52) );
}

• Monitor mouse clicks with evnt_multi or evnt_button
• Once a click occurs, use obj_find to check if the click was made on the object.
• If it was, call form_button with the appropriate values.

int16_t form_button (OBJECT *fo_btree, int16_t fo_bobject,
                     int16_t fo_bclicks, int16_t *fo_bnxtobj)
{
   int_in[0]  = fo_bobject;
   int_in[1]  = fo_bclicks;
   addr_in[0] = fo_btree;

   crys_if (56);

   *fo_bnxtobj = int_out[1];
   return ( int_out[0] );
}

int16_t form_center (OBJECT *fo_ctree, int16_t *fo_cx,
                     int16_t *fo_cy, int16_t *fo_cw,
                     int16_t *fo_ch)
{
   addr_in[0] = fo_ctree;

   crys_if (54);

   *fo_cx = int_out[1];
   *fo_cy = int_out[2];
   *fo_cw = int_out[3];
   *fo_ch = int_out[4];

   return (int_out[0]);
}

int16_t form_dial (int16_t fo_diflag, int16_t fo_dilittlx,
                   int16_t fo_dilittly, int16_t fo_dilittlw,
                   int16_t fo_dilittlh, int16_t fo_dibigx,
                   int16_t fo_dibigy, int16_t fo_dibigw,
                   int16_t fo_dibigh)
{
   int_in[0]  = fo_diflag;
   int_in[1]  = fo_dilittlx;
   int_in[2]  = fo_dilittly;
   int_in[3]  = fo_dilittlw;
   int_in[4]  = fo_dilittlh;
   int_in[5]  = fo_dibigx;
   int_in[6]  = fo_dibigy;
   int_in[7]  = fo_dibigw;
   int_in[8]  = fo_dibigh;

   return ( crys_if(51) );
}

int16_t form_do (OBJECT *fo_dotree, int16_t fo_dostartob)
{
   int_in[0]  = fo_dostartob;
   addr_in[0] = fo_dotree;

   return ( crys_if(50) );
}

int16_t form_error (int16_t fo_enum)
{
   int_in[0] = fo_enum;
   return ( crys_if(53) );
}

int16_t form_keybd (OBJECT *fo_ktree, int16_t fo_kobject,
                    int16_t fo_kobnext, int16_t fo_kchar,
                    int16_t *fo_knxtobject,
                    int16_t *fo_knxtchar)
{
   int_in[0]  = fo_kobject;
   int_in[1]  = fo_kchar;
   int_in[2]  = fo_kobnext;
   addr_in[0] = fo_ktree;

   crys_if (55);

   *fo_knxtobject = int_out[1];
   *fo_knxtchar   = int_out[2];

   return ( int_out[0] );
}

int16_t form_popup (OBJECT *tree, int16_t x, int16_t y)
{
   int_in[0]  = x;
   int_in[1]  = y;
   addr_in[0] = tree;

   return ( crys_if(135) );
}

int16_t form_wbutton (OBJECT *fo_btree, int16_t fo_bobject,
                      int16_t fo_bclicks, int16_t *fo_bnxtobj,
                      int16_t whandle)
{
   int_in[0]  = fo_bobject;
   int_in[1]  = fo_bclicks;
   int_in[2]  = whandle;

   addr_in[0] = fo_btree;

   crys_if (63);

   *fo_bnxtobj = int_out[1];
   return ( int_out[0] );
}

int16_t form_wkeybd (OBJECT *fo_ktree, int16_t fo_kobject,
                     int16_t fo_kobnext, int16_t fo_kchar,
                     int16_t *fo_knxtobject,
                     int16_t *fo_knxtchar, int16_t whandle)
{
   int_in[0]  = fo_kobject;
   int_in[1]  = fo_kchar;
   int_in[2]  = fo_kobnext;
   int_in[3]  = whandle;

   addr_in[0] = fo_ktree;

   crys_if (64);

   *fo_knxtobject = int_out[1];
   *fo_knxtchar   = int_out[2];

   return ( int_out[0] );
}

int16_t form_xdial (int16_t fo_diflag, int16_t fo_dilittlx,
                    int16_t fo_dilittly, int16_t fo_dilittlw,
                    int16_t fo_dilittlh, int16_t fo_dibigx,
                    int16_t fo_dibigy, int16_t fo_dibigw,
                    int16_t fo_dibigh, void **flydial)
{
   int_in[0]  = fo_diflag;
   int_in[1]  = fo_dilittlx;
   int_in[2]  = fo_dilittly;
   int_in[3]  = fo_dilittlw;
   int_in[4]  = fo_dilittlh;
   int_in[5]  = fo_dibigx;
   int_in[6]  = fo_dibigy;
   int_in[7]  = fo_dibigw;
   int_in[8]  = fo_dibigh;
   addr_in[0] = flydial;
   addr_in[1] = 0;            /* reserved */

   return ( crys_if(51) );
}

int16_t form_xdo (OBJECT *tree, int16_t startob,
                  int16_t *lastcrsr,
                  XDO_INF *tabs, void *flydial)
{
   int_in[0]  = startob;
   addr_in[0] = tree;
   addr_in[1] = tabs;
   addr_in[2] = flydial;

   crys_if (50);

   *lastcrsr = int_out[1];
   return ( int_out[0] );
}

int16_t form_xerr (int32_t errcode, int8_t *errfile)
{
   int_in[0]  = errcode (High);
   int_in[1]  = errcode (Low);
   addr_in[0] = errfile;

   return ( crys_if(136) );
}

1. The object tree is initialized automatically by a call of the init routine before the first drawing action.
    

2. The variable scrollpos need not be initialized, as the system always start at scrollpos 0.
    

3. The init routine is responsible for initializing the first and/or last scroll object with an arrow.
    

4. The scrollable objects are firstscrlob ... lastscrlob. The object indices must be consecutive numbers. The objects must lie directly below each other and all must have the same size.
    

int16_t xfrm_popup( OBJECT *tree, int16_t x, int16_t y,
                    int16_t firstscrlob, int16_t lastscrlob,
                    int16_t nlines,
                    void  cdecl (*init)(OBJECT *tree,
                    int16_t scrollpos,
                    int16_t nlines, void *param),
                    void *param, int16_t *lastscrlpos )
{
   int_in[0]  = x;
   int_in[1]  = y;
   int_in[2]  = firstscrlob;
   int_in[3]  = lastscrlob;
   int_in[4]  = nlines;
   int_in[5]  = *lastscrlpos;
   addr_in[0] = tree;
   addr_in[1] = init;
   addr_in[2] = param;

   int_out[1] = *lastscrlpos;   /* Preset this */

   crys_if(135)

   *lastscrlpos = int_out[1];
   return ( int_out[0] );
}

int16_t x_form_center( OBJECT *tree, int16_t *cx, int16_t *cy,
                       int16_t *cw, int16_t *ch )
{
   addr_in[0] = tree;

   crys_if(28944);

   *cx = int_out[1];
   *cy = int_out[2];
   *cw = int_out[3];
   *ch = int_out[4];

   return (int_out[0]);
}

if( x_form_error( "[1][Error!|%s][Continue|Quit]", -33 ) == 1 )
  continue...
else quit...

int16_t x_form_error ( uint8_t *fmt, int16_t errnum )
{
   int_in[0] = errnum;

   addr_in[0] = fmt;

   return ( crys_if(28945) );
}

OBJECT *tree;
char name[13] = "DEFAULT.TXT";

x_form_filename( tree, object, 0, name );
form_do( tree, object );
x_form_filename( tree, object, 1, name );
/* "name" now contains what the user changed it to */

int16_t x_form_filename( OBJECT *tree, int16_t obj,
                         int16_t to_from, uint8_t *string )
{
   int_in[0] = obj;
   int_in[1] = to_from;

   addr_in[0] = tree;
   addr_in[1] = string;

   return ( crys_if(28996) );
}

int16_t x_form_mouse( OBJECT *tree, int16_t mouse_x, int16_t
mouse_y, int16_t clicks, int16_t *edit_obj, int16_t *next_obj,
int16_t *edit_idx )
{
   int_in[0] = mouse_x;
   int_in[1] = mouse_y;
   int_in[2] = clicks;
   int_in[3] = edit_obj;
   int_in[4] = next_obj;
   int_in[5] = edit_idx;

   addr_in[0] = tree;

   crys_if(28997);

   *edit_obj = int_out[1];
   *next_obj = int_out[2];
   *edit_idx = int_out[3];

   return ( int_out[0] );
}