Home AESAES Extended file-selectorsExtended file-selectors Geneva libraryGeneva library

8.11 Form library

This library contains useful functions for handling dialog and alert boxes of all kinds. The following routines are available for this purpose:

form_alert Displays standardized alert box
form_button Simulates a mouse-click
form_center Centres an object
form_dial Reserves and releases screen memory
form_do Processes a dialog
form_error Outputs operating system error alert
form_keybd Processes keyboard input
form_popup Manages a popup-menu
form_wbutton Simulates a mouse-click (in window)
form_wkeybd Processes keyboard input (in window)
form_xdial Reserves/releases screen memory (Flydials)
form_xdo Extended dialog handling
form_xerr Outputs operating system error alert (MagiC)
xfrm_popup Manages a popup-menu (extended version)
x_form_center Centres an object (Geneva)
x_form_error Outputs operating system error alert (Geneva)
x_form_filename Convert to/from a standard GEMDOS filename in editable field in a dialog.
x_form_mouse Handle mouse clicks in a dialog, including editable cursor movement.

Note: Some of these functions are only present under MagiC, and offer additional convenience (e.g. movable dialog boxes).

See also: Dialog boxes   Style guidelines   Scrollable input fields

8.11.1 form_alert

Name: »Form alert box« - Display an alert box.
 
Opcode: 52
 
Syntax: int16_t form_alert ( int16_t fo_adefbttn, CONST int8_t *fo_astring );
 
Description: The call form_alert displays a standardized alert box on the screen and returns the index of the button with which the alert box was exited. During this the AES saves the background and restores it after the alert box is closed.
 
The parameter fo_adefbttn determines the index of the default exit button of the alert box. The following apply:
 

Value Meaning
0 No default button
1 First button
2 Second button
3 Third button

The parameter fo_astring is a pointer to the formatted string that determines the appearance of the alert box. The format is '[n][lines][buttons]' where n is the index number of the icon to be included:
 
n Meaning Icon
   
0 No icon  
1 Exclamation mark

2 Question mark

3 Stop sign

4 Info icon, as of AES 4.10

5 Diskette icon, as of AES 4.10

6 Bomb, XaAES

7 System, XaAES


Note: The available icons should not be used in an arbitrary manner, but should suit the situation in each case, i.e.:
 
  • 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.
     


The component lines describes the individual text lines that are to appear in the alert box. There can be up to five text lines, each with a maximum of 30 characters, which are separated from each other by a '|' character.
 
The component buttons describes the texts for up to three buttons with up to 10 characters each, which are separated by a '|' character from each other.
 
Note: All AES versions below 1.06 have problems formatting alert strings padded with spaces; to make alerts look right with all AES versions, do not pad any line or button with spaces, apart from adding one space to the longest text line of an alert (to prevent the last character touching the right border in some AES versions).
 
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 */
 

Return value: This will be the index of the button with which the alert box was quit; the button at far left has the index 1, and so on in sequence.
 
Availability: All AES versions.
 
Group: Form library
 
See also: Binding
 

8.11.1.1 Bindings for form_alert

C: int16_t form_alert ( int16_t fo_adefbttn, CONST int8_t *fo_astring );
 
Binding:
 
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) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 52 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] fo_adefbttn
addr_in addr_in[0] fo_astring
int_out int_out[0] Return value

8.11.2 form_button

Name: »Form button« - Simulate the clicking on an object.
 
Opcode: 56
 
Syntax: int16_t form_button ( OBJECT *fo_btree, int16_t fo_bobject, int16_t fo_bclicks, int16_t *fo_bnxtobj );
 
Description: The call form_button simulates mouse clicks on an object. The following apply:
 
Parameter Meaning
   
fo_btree Address of the object tree in memory
fo_bobject Object to be processed
fo_bclicks Number of mouse clicks
fo_bnxtobj New current object, or 0 if the next object has the status HIDDEN or DISABLED, or is not editable

Note: At a double-click on an object with TOUCHEXIT, bit 15 will be set in the parameter fo_bnxtobj. The rectangle list will not be taken into account by this function.
 
The correct usage of the function is as follows:
 
  • 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.

Warning: This function was not originally documented by Atari, so you may need to add bindings for it to some earlier 'C' compilers.
 
Return value: The return value of the function is 0 if an EXIT or TOUCHEXIT object was selected, else it is positive.
 
Availability: All AES versions.
 
Group: Form library
 
See also: Binding   OBJECT   evnt_multi   form_keybd
 

8.11.2.1 Bindings for form_button

C: int16_t form_button ( OBJECT *fo_btree, int16_t fo_bobject, int16_t fo_bclicks, int16_t *fo_bnxtobj );
 
Binding:
 
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] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 56 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 2 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] fo_bobject
int_in+2 int_in[1] fo_bclicks
addr_in addr_in[0] fo_btree
int_out int_out[0] Return value
int_out+2 int_out[1] fo_bnxtobj

8.11.3 form_center

Name: »Form centered object« - Centre an object on the screen.
 
Opcode: 54
 
Syntax: int16_t form_center ( OBJECT *fo_ctree, int16_t *fo_cx, int16_t *fo_cy, int16_t *fo_cw, int16_t *fo_ch );
 
Description: The call form_center modifies an object's coordinates so that it will appear at the centre of the display screen, and returns the actual position of the object. The following apply:
 

Parameter Meaning
fo_ctree Address of the object tree
fo_cx X-coordinate, and
fo_cy Y-coordinate of top left of object
fo_cw Width, and
fo_ch Height of object (each centred)

Note: The function also takes special attributes of the object into account, such as OUTLINED, for instance (but not SHADOWED).
 
As of PC-GEM/3 the object tree is no longer centred in the Y-direction on the whole screen. The reason given for this is that users of large screen monitors would otherwise have to cover too large a distance from the menu bar to the object (perhaps a dialog box).
 
Return value: The return value is always 1.
 
Availability: All AES versions.
 
Group: Form library
 
See also: Binding   x_form_center   OBJECT   objc_offset
 

8.11.3.1 Bindings for form_center

C: int16_t form_center ( OBJECT *fo_ctree, int16_t *fo_cx, int16_t *fo_cy, int16_t *fo_cw, int16_t *fo_ch );
 
Binding:
 
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]);
}
GEM-Arrays:
 

Address Element Contents
control control[0] 54 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 5 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] fo_ctree
int_out int_out[0] Return value
int_out+2 int_out[1] fo_cx
int_out+4 int_out[2] fo_cy
int_out+6 int_out[3] fo_cw
int_out+8 int_out[4] fo_ch

8.11.4 form_dial

Name: »Form dialog space« - Reserve or release memory for a dialog object.
 
Opcode: 51
 
Syntax: 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 );
 
Description: The call form_dial takes on various tasks, depending on the passed parameters. The following apply:
 
Parameter Meaning
   
fo_diflag Action to be performed
0 = FMD_START Reserve screen space for a dialog
1 = FMD_GROW Draw several expanding rectangles from the coordinates fo_dilittlx/y/w/hto fo_dibigx/y/w/h
2 = FMD_SHRINK Draw several shrinking rectangles from fo_dibigx/y/w/h to fo_dilittlx/y/w/h
3 = FMD_FINISH Release the reserved screen space again
1000 = X_FMD_START (Geneva)
Store the information in the rectangular screen area described by the fo_dibig parameters for restoration later; if there is insufficient free memory for the area to be saved, then form_dial will return a 0 (error) condition
1003 = X_FMD_FINISH (Geneva)
Copy back the information previously saved with X_FMD_START; this MUST be done whenever X_FMD_START is used, but not if an error occurred during the X_FMD_START
fo_dilittlx X-coordinate, and
fo_dilittly Y-coordinate of top left corner,
fo_dilittlw Width, and
fo_dilittlh Height of the smallest rectangle
fo_dibigx X-coordinate, and
fo_dibigy Y-coordinate of top left corner,
fo_dibigw Width, and
fo_dibigh Height of the largest rectangle

Note: With the opcode FMD_FINISH, all affected windows receive a WM_REDRAW message from the AES. However the menu bar can not be restored in this way, as it lies outside the working area of the desktop window.
 
At the time of writing, the AES does not use FMD_START, but the call should still be executed for upwards compatibility.
 
The opcodes FMD_GROW and FMD_SHRINK in PC-GEM Version 2.0 fell as victims of the lawsuit between Apple and Digital Research.
 
Return value: An error has arisen only if the value 0 is returned.
 
Availability: All AES versions.
 
Group: Form library
 
See also: Binding   evnt_mesag   form_xdial   graf_growbox   graf_shrinkbox
 

8.11.4.1 Bindings for form_dial

C: 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 );
 
Binding:
 
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) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 51 # Function opcode
control+2 control[1] 9 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] fo_diflag
int_in+2 int_in[1] fo_dilittlx
int_in+4 int_in[2] fo_dilittly
int_in+6 int_in[3] fo_dilittlw
int_in+8 int_in[4] fo_dilittlh
int_in+10 int_in[5] fo_dibigx
int_in+12 int_in[6] fo_dibigy
int_in+14 int_in[7] fo_dibigw
int_in+16 int_in[8] fo_dibigh
int_out int_out[0] Return value

8.11.5 form_do

Name: »Form do dialog« - Process the dialog with input from the user.
 
Opcode: 50
 
Syntax: int16_t form_do ( OBJECT *fo_dotree, int16_t fo_dostartob );
 
Description: The call form_do takes over the processing of user actions in a dialog form from the calling application, suspending program control and handling all selectable objects, radio buttons etc. The following apply:
 
Parameter Meaning
   
fo_dotree Pointer to object tree of the dialog box
fo_dostartob Index of the editable object where the text cursor should be at the opening of the dialog (the object must have the EDITABLE flag set); it will be 0 if the object tree contains no editable object

Note: The function only returns once the user activates an object with the EXIT or TOUCHEXIT flag, and restores control to the calling program.
 
Return value: This will be the index of the object which was used to close the dialog. With a double-click, in addition bit 15 will be set.
 
Availability: All AES versions.
 
Group: Form library
 
See also: Binding   form_xdo   OBJECT
 

8.11.5.1 Bindings for form_do

C: int16_t form_do ( OBJECT *fo_dotree, int16_t fo_dostartob );
 
Binding:
 
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) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 50 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] fo_dostartob
addr_in addr_in[0] fo_dotree
int_out int_out[0] Return value

8.11.6 form_error

Name: »Form error« - Display an alert box form for TOS errors.
 
Opcode: 53
 
Syntax: int16_t form_error ( int16_t fo_enum );
 
Description: The call form_error outputs an MS-DOS error number as a plain text description (i.e. in an alert box form that contains a stop sign icon at the left side of the box, a text string holding an explanatory error message or just 'TOS error #X' and a 'Cancel' button).
 
The parameter fo_enum is here the corresponding error number.
 
Note: This function is present for reasons of compatibility to PC-GEM. Hence on TOS systems one first has to translate the GEMDOS error number to the MS-DOS coding. For the conversion (GEMDOS -> MS-DOS) one can use, say, the following formula: (~fo_enum) - 30.
 
In N.AES there is an extended form of form_error with all GEMDOS error-codes. Its presence can be checked with appl_getinfo (opcode 64).
 
Geneva interpreted a negative number as a GEMDOS/BIOS error-code, and an appropriate error-message is displayed. For instance, the call:
form_error(-33);
produces an alert with the text 'There is no file with this name'.
 
Return value: This will be the index (1-3) of the selected exit button. However, with current GEM versions only one button is available in error alerts.
 
Availability: All AES versions.
 
Group: Form library
 
See also: Binding   form_xerr   form_error in N.AES
 

8.11.6.1 Bindings for form_error

C: int16_t form_error ( int16_t fo_enum );
 
Binding:
 
int16_t form_error (int16_t fo_enum)
{
   int_in[0] = fo_enum;
   return ( crys_if(53) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 53 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] fo_enum
int_out int_out[0] Return value

8.11.7 form_keybd

Name: »Form keyboard« - Process keyboard input in a dialog box form.
 
Opcode: 55
 
Syntax: 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 );
 
Description: The call form_keybd processes keyboard input for the control of forms in dialog boxes. The following apply:
 
Parameter Meaning
   
fo_ktree Address of the object tree
fo_kobject Index of the editable object
fo_kobnext Unused, should be 0
fo_kchar Pressed key's scancode and ASCII value (as from evnt_keybd or evnt_multi)
fo_knxtobject Editable object for next call
fo_knxtchar 0 = Pressed key was a cursor key, [Tab] or [Return], processed and handled by the call
>0 = Character passed to obj_edit without processing

User input may change the editable object (cursor or [Tab] keys), or select the default object ([Return]).
 
Note about MagiC, N.AES: If the value 0x8765 is specified as the object index, then keys will be processed that are pressed together with the [Alternate] key. If a matching object is found then the value 1 will be returned, the character deleted and the appertaining object index passed in fo_knxtobject.
 
Return value: The function returns 0 if an EXIT object was selected, else a positive number if the dialog should continue to be processed.
 
Availability: All AES versions.
 
Group: Form library
 
See also: Binding   OBJECT   objc_edit   form_button   form_wkeybd
 

8.11.7.1 Bindings for form_keybd

C: 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 );
 
Binding:
 
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] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 55 # Function opcode
control+2 control[1] 3 # Entry in int_in
control+4 control[2] 3 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] fo_kobject
int_in+2 int_in[1] fo_kchar
int_in+4 int_in[2] fo_kobnext
addr_in addr_in[0] fo_ktree
int_out int_out[0] Return value
int_out+2 int_out[1] fo_knxtobject
int_out+4 int_out[2] fo_knxtchar

8.11.8 form_popup

Name: »Form Popup« - Manage a popup menu.
 
Opcode: 135
 
Syntax: int16_t form_popup ( OBJECT *tree, int16_t x, int16_t y );
 
Description: The call form_popup displays a popup menu on the screen and takes over its management. The following apply:
 
Parameter Meaning
   
tree Address of the object tree
x X-coordinate, and
y Y-coordinate, around which the box is to be centered

Note: If the parameters x and y have the value 0, then the corresponding values from the object structure will be respected, and the centering is abandoned. At all times the function ensures that the complete popup is displayed on the screen.
 
Selectable objects must have the status SELECTABLE and non-selectable objects the status DISABLED assigned. The object with the index 0 in the object tree should be of the type G_BOX or G_IBOX.
 
Return value: The function returns the index of the selected object from the popup menu, else the value -1.
 
Availability: As of MagiC 1.11, but can also be inquired for by appl_getinfo (opcode 9), as other systems also understand this function.
 
Group: Form library
 
See also: Binding   OBJECT   xfrm_popup
 

8.11.8.1 Bindings for form_popup

C: int16_t form_popup ( OBJECT *tree, int16_t x, int16_t y );
 
Binding:
 
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) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 135 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] x
int_in+2 int_in[1] y
addr_in addr_in[0] tree
int_out int_out[0] Return value

8.11.9 form_wbutton

Name: »Form window button« - Simulate the clicking on an object in a window.
 
Opcode: 63
 
Syntax: int16_t form_wbutton ( OBJECT *fo_btree, int16_t fo_bobject, int16_t fo_bclicks, int16_t *fo_bnxtobj, int16_t whandle );
 
Description: The call form_wbutton simulates the clicking on an object in a window. The following apply:
 
Parameter Meaning
   
fo_btree Address of the object tree
fo_bobject Object to be processed
fo_bclicks Number of mouse clicks
fo_bnxtobj New current object, or 0 if the next object has the status HIDDEN or DISABLED, or is not editable
whandle Window ID

Note: With a double-click on a TOUCHEXIT objec, bit 15 will be set in the parameter fo_bnxtobj.
 
The function corresponds essentially to form_button, with the difference that the rectangle list of a window is taken into account.
 
Return value: The function returns 0 if an EXIT object was selected, else a positive value.
 
Availability: As of MagiC Version 5.10
 
Group: Form library
 
See also: Binding   OBJECT   evnt_multi   form_keybd
 

8.11.9.1 Bindings for form_wbutton

C: int16_t form_wbutton ( OBJECT *fo_btree, int16_t fo_bobject, int16_t fo_bclicks, int16_t *fo_bnxtobj, int16_t whandle );
 
Binding:
 
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] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 63 # Function opcode
control+2 control[1] 3 # Entry in int_in
control+4 control[2] 2 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] fo_bobject
int_in+2 int_in[1] fo_bclicks
int_in+4 int_in[2] whandle
addr_in addr_in[0] fo_btree
int_out int_out[0] Return value
int_out+2 int_out[1] fo_bnxtobj

8.11.10 form_wkeybd

Name: »Form window keyboard« - Process keyboard input into a form in a window.
 
Opcode: 64
 
Syntax: 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 );
 
Description: The call form_wkeybd processes keyboard input into a form in a window. The following apply:
 
Parameter Meaning
   
fo_ktree Address of the object tree
fo_kobject Index of the editable object
fo_kobnext Unused, should be 0
fo_kchar Pressed key's scancode and ASCII value (as from evnt_keybd or evnt_multi)
fo_knxtobject Editable object for next call
fo_knxtchar 0 = Pressed key was a cursor key, [Tab] or [Return], processed and handled by the call
>0 = Character passed to obj_edit without processing
whandle Window ID

User input may change the editable object (cursor or [Tab] keys), or select the default object (Return).
 
Note about MagiC, XaAES: If the value 0x8765 is specified as the object index, then keys will be processed that are pressed together with the [Alternate] key. If a matching object is found then the value 1 will be returned, the character deleted and the appertaining object index passed in fo_knxtobject.
 
This function essentially corresponds to form_keybd with the difference that here the rectangle list of a window is taken into account.
 
Return value: The function returns 0 if an EXIT object was selected, else a positive number if the dialog should continue to be processed.
 
Availability: As of MagiC Version 5.10, XaAES.
 
Group: Form library
 
See also: Binding   OBJECT   objc_edit   form_button
 

8.11.10.1 Bindings for form_wkeybd

C: 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 );
 
Binding:
 
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] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 64 # Function opcode
control+2 control[1] 4 # Entry in int_in
control+4 control[2] 3 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] fo_kobject
int_in+2 int_in[1] fo_kchar
int_in+4 int_in[2] fo_kobnext
int_in+6 int_in[3] whandle
addr_in addr_in[0] fo_ktree
int_out int_out[0] Return value
int_out+2 int_out[1] fo_knxtobject
int_out+4 int_out[2] fo_knxtchar

8.11.11 form_xdial

Name: »Form Xdialog space« - Reserve or release screen memory for a dialog object when using Flydials.
 
Opcode: 51
 
Syntax: 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 );
 
Description: The call form_xdial takes on various tasks, depending on the passed parameters. The following apply:
 
Parameter Meaning
   
fo_diflag 0 = FMD_START reserves screen memory for the dialog
3 = FMD_FINISH restores the screen and releases the buffer used to save the background in
fo_dilittlx X-coordinate, and
fo_dilittly Y-coordinate of the top left corner,
fo_dilittlw Width, and
fo_dilittlh Height of the smallest growing or shrinking rectangle
fo_dibigx X-coordinate, and
fo_dibigy Y-coordinate of the top left corner,
fo_dibigw Width, and
fo_dibigh Height of the largest growing or shrinking rectangle
flydial See below

Note: If flydial is non-zero, a test is made whether enough memory is available to save the background of the dialog box. A pointer to this saved data is then stored in this variable. If insufficient memory is available to save the background, then the dialog box processed by form_xdo is not movable; in that case also the dialog will display no 'fly corner' ('asses ear').
 
Return value: An error has arisen only if the value 0 is returned.
 
Availability: When Flydials is in use, whose presence can be checked for with appl_getinfo (opcode 14).
 
Group: Form library
 
See also: Binding   evnt_mesag   form_dial   graf_growbox   graf_shrinkbox
 

8.11.11.1 Bindings for form_xdial

C: 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 );
 
Binding:
 
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) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 51 # Function opcode
control+2 control[1] 9 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] fo_diflag
int_in+2 int_in[1] fo_dilittlx
int_in+4 int_in[2] fo_dilittly
int_in+6 int_in[3] fo_dilittlw
int_in+8 int_in[4] fo_dilittlh
int_in+10 int_in[5] fo_dibigx
int_in+12 int_in[6] fo_dibigy
int_in+14 int_in[7] fo_dibigw
int_in+16 int_in[8] fo_dibigh
addr_in addr_in[0] flydial
addr_in+4 addr_in[1] 0
int_out int_out[0] Return value

8.11.12 form_xdo

Name: »Form do Xdialog« - Process an extended dialog with user input.
 
Opcode: 50
 
Syntax: int16_t form_xdo ( OBJECT *tree, int16_t startob, int16_t *lastcrsr, XDO_INF *tabs, void *flydial );
 
Description: The call form_xdo takes on the handling of user actions in a dialog form. The following apply:
 
Parameter Meaning
   
tree Pointer to object tree of the dialog box
startob Index of the editable object where the text cursor should be at the opening of the dialog (the object must have the EDITABLE flag set); it will be 0 if the object tree contains no editable object
lastcrsr Contains the index of the object where the cursor was at the closing of the dialog
tabs Pointer to keyboard tables, or NULL
flydial The corresponding parameter returned by form_xdial, or NULL if foregoing Flydials
Return value: This will be the index of the object used to close the dialog.
 
Availability: The function is only available under MagiC (as of Version 2.0). The presence of the Flydials and keyboard tables as well as the possibility of establishing the last cursor position can be inquired for with appl_getinfo (opcode 14).
 
Group: Form library
 
See also: Binding   form_do
 

8.11.12.1 Bindings for form_xdo

C: int16_t form_xdo ( OBJECT *tree, int16_t startob, int16_t *lastcrsr, XDO_INF *tabs, void *flydial );
 
Binding:
 
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] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 50 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 2 # Entry in int_out
control+6 control[3] 3 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] startob
addr_in addr_in[0] tree
addr_in+4 addr_in[1] tabs
addr_in+8 addr_in[2] flydial
int_out int_out[0] Return value
int_out+2 int_out[1] lastcrsr

8.11.13 form_xerr

Name: »Form Xerror« - Display an error box for TOS errors (MagiC).
 
Opcode: 136
 
Syntax: int16_t form_xerr ( int32_t errcode, int8_t *errfile );
 
Description: The call form_xerror outputs an error number as a plain text description (i.e. in an alert box form that contains a stop sign icon at the left side of the box, a text string holding an explanatory error message or just 'TOS error #X' and a 'Cancel' button). In contrast to form_error, there is no need for translation from the TOS to the MS-DOS format.
 
Parameter Meaning
   
errcode Normal, negative GEMDOS or BIOS error-code; if this is EBREAK (program termination with [Control]-[C]) or E_OK (no error) then no alert box will be displayed
errfile Path of the file in which the error arose. With a NULL-pointer this parameter will be ignored; -1 means that the message will be prefaced with 'The program returned:'
Return value: This will be the index (1-3) of the selected exit button. However, with current GEM versions only one button is available in error alerts.
 
Availability: The function is available only under MagiC (as of Version 2.0).
 
Group: Form library
 
See also: Binding   form_error
 

8.11.13.1 Bindings for form_xerr

C: int16_t form_xerr ( int32_t errcode, int8_t *errfile );
 
Binding:
 
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) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 136 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] errcode (High)
int_in+2 int_in[1] errcode (Low)
addr_in addr_in[0] errfile
int_out int_out[0] Return value

8.11.14 xfrm_popup

Name: »XForm popup« - Manage a popup menu (extended MagiC version).
 
Opcode: 135
 
Syntax: 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 )
 
Description: The call xfrm_popup displays a popup menu on the screen, and takes on its management. The followiong apply:
 
Parameter Meaning
   
tree Address of the object tree
x X-coordinate, and
y Y-coordinate around which the box is to be centered
firstscrlob Object index of the first scrollable object
lastscrlob Object index of the last scrollable object
nlines Number of lines actually present
init Callback routine for translating the objects. tree, param and nlines are the parameters that were passed in xfrm_popup. scrollpos specifies the current scroll position. It lies at: 0..(nlines-(lastscrlob-firstscrlob+1). If the popup should not scroll, init == NULL must be passed.
param User-defined parameter
lastscrlpos Last scroll position

Note: If the parameters x and y have the value 0, then the corresponding values from the object structure will be respected, and the centering is abandoned. At all times the function ensures that the complete popup is displayed on the screen.
 
Selectable objects must have the flag SELECTABLE and non-selectable objects the status DISABLED assigned. The object with the index 0 in the object tree should be of the type G_BOX or G_IBOX.
 
  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.
     

Return value: The function returns the index of the selected object from the popup menu, else the value -1.
 
Availability: The function is available as of MagiC 5.03.
 
Group: Form library
 
See also: Binding   OBJECT   form_popup
 

8.11.14.1 Bindings for xfrm_popup

C: 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 )
 
Binding:
 
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] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 135 # Function opcode
control+2 control[1] 6 # Entry in int_in
control+4 control[2] 2 # Entry in int_out
control+6 control[3] 3 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] x
int_in+2 int_in[1] y
int_in+4 int_in[2] firstscrlob
int_in+6 int_in[3] lastscrlob
int_in+8 int_in[4] nlines
int_in+10 int_in[5] lastscrlpos
addr_in addr_in[0] tree
addr_in+4 addr_in[1] init
addr_in+8 addr_in[2] param
int_out int_out[0] Return value
int_out+2 int_out[1] lastscrlpos

8.11.15 x_form_center

Name: »XForm centered object« - Centre an object on the screen (extended version for Geneva).
 
Opcode: 28944
 
Syntax: int16_t x_form_center( OBJECT *tree, int16_t *cx, int16_t *cy, int16_t *cw, int16_t *ch );
 
Description: The function x_form_center will center a dialog on the screen, taking into account all object attributes that can affect the outer border. The following apply:
 

Parameter Meaning
tree Object tree being modified
cx X-coordinate of the outer rectangle
cy Y-coordinate of the outer rectangle
cw Width of the outer rectangle
ch Height of the outer rectangle

This function is essentially identical in purpose to the AES form_center call, however it takes all attributes which can affect the size of the outer border of the object tree (SHADOWED, OUTLINED, 3D effect, etc.) into consideration. The returned rectangle describes the entire area containing these effects.
 
Return value: The function always return a value 1.
 
Availability: The function is only available under Geneva.
 
Group: Form library
 
See also: Binding   form_center
 

8.11.15.1 Bindings for x_form_center

C: int16_t x_form_center( OBJECT *tree, int16_t *cx, int16_t *cy, int16_t *cw, int16_t *ch );
 
Binding:
 
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]);
}
GEM-Arrays:
 

Address Element Contents
control control[0] 28944 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 5 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] tree
int_out int_out[0] Return value
int_out+2 int_out[1] cx
int_out+4 int_out[2] cy
int_out+6 int_out[3] cw
int_out+8 int_out[4] ch

8.11.16 x_form_error

Name: »XForm error« - Display an error box for TOS errors (Geneva).
 
Opcode: 28945
 
Syntax: int16_t x_form_error ( uint8_t *fmt, int16_t errnum );
 
Description: The function x_form_error takes the error-code specified by errnum and finds an appropriate error-message string. It then inserts this text into a program-defined alert string and displays an alert.
 
The fmt should be in standard form_alert format, with a '%s' to indicate the location where the error-message should be inserted. Since an alert can contain no more than five lines of 30 characters each, and the predefined error-messages can take up to three lines, there should be no more than two lines of text surrounding the inserted error text.
 
Example:
 
if( x_form_error( "[1][Error!|%s][Continue|Quit]", -33 ) == 1 )
  continue...
else quit...
Return value: This will be the index (1-3) of the selected exit button.
 
Availability: The function is only available under Geneva.
 
Group: Form library
 
See also: Binding   form_error   form_xerr   form_error in N.AES
 

8.11.16.1 Bindings for x_form_error

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

   addr_in[0] = fmt;

   return ( crys_if(28945) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 28945 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] enum
addr_in addr_in[0] fmt
int_out int_out[0] Return value

8.11.17 x_form_filename

Name: »XForm filename« - Convert to/from a standard GEMDOS filename in editable field in a dialog.
 
Opcode: 28996
 
Syntax: int16_t x_form_filename( OBJECT *tree, int16_t obj, int16_t to_from, uint8_t *string );
 
Description:
 
Parameter Meaning
   
tree Object tree of the dialog containing the editable field
obj Index of the editable object in the tree
to_from Convert to (0) or from (1) the field
string Pointer to the string containing the GEMDOS-formatted (FILENAME.EXT) string.

Since filenames are typically entered in a GEM dialog using the period to separate the filename from the extension, and filenames with less than eight characters before the period are padded with spaces, converting to and from the editable field can be a difficult task.
 
When the mode parameter passed to x_form_filename is 0, the string is converted from the FILENAME.EXT format to the editable field format. When mode is 1, the filename is converted from the editable field and written into string in FILENAME.EXT format. Note that this function assumes that the editable field is an object of type G_FTEXT or G_FBOXTEXT and uses the te_ptmplt string "________.___".
 
Example:
 
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 */
Return value: Return always 1.
 
Availability: The function is only available under Geneva.
 
Group: Form library
 
See also: Binding
 

8.11.17.1 Bindings for x_form_filename

C: int16_t x_form_filename( OBJECT *tree, int16_t obj, int16_t to_from, uint8_t *string );
 
Binding:
 
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) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 28996 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] obj
int_in+2 int_in[1] to_from
addr_in addr_in[0] tree
addr_in+4 addr_in[1] string
int_out int_out[0] Return value

8.11.18 x_form_mouse

Name: »XForm mouse« - Handle mouse clicks in a dialog, including editable cursor movement.
 
Opcode: 28997
 
Syntax: 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 );
 
Description:
 
Parameter Meaning
   
tree Object tree of the dialog
mouse_x X coordinate of the mouse pointer
mouse_y Y coordinate of the mouse pointer
clicks Number of clicks to be processed
edit_obj Object currently having the edit cursor
next_obj Object selected with the mouse
edit_idx Position of edit cursor within field

This function begins by calling form_button. If neither an EXIT nor a TOUCHEXIT button is selected, and the object is EDITABLE, then the editable cursor is moved to the character within the editable field which is under the mouse pointer.
 
Return value: 0 = An object was selected
1 = No object
 
Parameter Meaning
edit_obj New object having the edit cursor
next_obj Selected object, or 0 for none
edit_idx New edit cursor position
Availability: The function is only available under Geneva.
 
Group: Form library
 
See also: Binding
 

8.11.18.1 Bindings for x_form_mouse

C: 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 );
 
Binding:
 
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] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 28997 # Function opcode
control+2 control[1] 6 # Entry in int_in
control+4 control[2] 4 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] tree
int_in int_in[0] mouse_x
int_in+2 int_in[1] mouse_y
int_in+4 int_in[2] clicks
int_in+6 int_in[3] edit_obj
int_in+8 int_in[4] next_obj
int_in+10 int_in[5] edit_idx
int_out int_out[0] Return value
int_out+2 int_out[1] edit_obj
int_out+4 int_out[2] next_obj
int_out+6 int_out[3] edit_idx

Home AESAES Extended file-selectorsExtended file-selectors Geneva libraryGeneva library