Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File13.14.5  The UFSL interface                                        TOS

For the sake of completeness, an English translation of the original 
description by Michael Thänitz of the original UFSL interface follows 
here :

Programming interface:

UFSL is a font-selector box for the AUTO folder. If offers a simple 
programming interface to the programmer via a cookie.

The cookie is called: 'UFSL'.
The cookie returns a pointer to the following structure:

 typedef struct
 {
  unsigned long  id;      /* UFSL ID (UFSL)       */
  unsigned int   version; /* Version (BCD format) */
  int dialtyp;            /* 0=Dialog, 1=Window   */
  int cdecl (*font_selinit)(void);
  int cdecl (*font_selinput)(
              int vdihandle,
              int dummy,
              char *text,    /* Custom text, max. 34 characters  */
              int ftype,     /* 1=Only monospaced fonts, 0=All   */
              int *fretid,   /* Set Font ID                      */
              int *fretsize  /* Set font size                    */
              );
  OBJECT *helpbutton;           /* Type: BOXTEXT                 */
  void cdecl (*helpfunc)(void); /* User-defined Help function    */

  /**** As of Version 0.91 ********************************************/
  char *examplestr;            /* Sample text for font display     */

  /**** As of Version 0.96 ********************************************/
  void cdecl (*msgfunc)(int event, int msgbuf[]);/* Redraw function */

  /**** As of Version 0.97 ********************************************/
  int cdecl (*fontsel_exinput)(
              int vdihandle,
              int ftype,     /* 1=Only monospaced fonts, 0=All     */
              char *text,    /* Custom text, masx. 34 characters   */
              int *fretid,   /* Set font ID                        */
              int *fretsize  /* Set font size                      */
              );
 } UFSL;

Call:

UFSL *ufsl;
ufsl=(UFSL *)get_cookie('UFSL');
ufsl->helpfunc= my_helpfunc;   /* Help function, or NULL */
ufsl->msgfunc = my_msghandler; /* Redraw function, or NULL,
                                  respect (!I)dialtyp(!i)       */
ufsl->fontsel_input(vdihandle,"Please select a font",0,&id,&size);
(!U)or(!u)
ufsl->fontsel_input(vdihandle,NULL,0,&id,&size);

Return codes:

 1 : All OK, values are valid
 0 : Cancel selected
-1 : Out of memory
-2 : Impermissible mutliple call
-3 : Font size could not be identified
-4 : Number of fonts must be greater than zero

Special functions:

void cdecl (*helpfunc)(void); /* User-defined Help function      */

UFSL can call a user-defined Help function via the equally optional 
HELP button. helpfunc requires no parameters and also has no return 
value.

void cdecl (*msgfunc)(int event, int msgbuf[]); /* Redraw function */

When using the UFSL as a window-dialog it is necessary to make a 
Redraw function available. It sends any received events back to the 
calling program, so that after moving the dialog one can restore the 
background windows. msgfunc returns the result of evnt_multi as the 
first parameter and the MsgPipe as the second parameter. A return code 
is not required. The calling program must make available all the 
required routines for window handling. wind_update(..._UPDATE) is not 
set by UFSL, so this is the duty of the calling user program. On 
principle (?) the memory protection of MultiTOS should be switched 
off.

Basically one should give some thought whether all events should be 
replied to appropriately. A WM_TOPPED, which tops other windows of the 
program, should not be answered, since UFSL naturally can only be 
applications modal as UFSL gyrates in its own form_do / evnt_multi.