Protocols

XAcc

XSSI protocol

15.14 xFSL interface

GDOS, which for years suffered a shadowy existence on the Atari platform, has enjoyed rising popularity since the introduction of vector fonts at the latest. Ever more programs offer the possibility to use a font different from the system font for output (and partly also for input).

Now to be able to select a font, one needs a font-selector. And so that not every programmer had to concoct his own brew, and to obtain consistent operation, there grew a desire for a system extension that made a font-selector available to all programs - just like a file- selector.

The first program of this type was the 'UFSL' by Michael Thänitz. Via a cookie it makes available routines for calling a font-selector. This interface is already being used by a number of programs, and there are also further font-selectors that can be called via this interface.

Although one can now call a font-selector via the UFSL interface, it has already been subject to a number of - partly incompatible - alterations and extensions. That is why most programs today assume that they have only the original, simple UFSL interface available to them. The result is therefore that the extensions remain unused, and when a somewhat more powerful font-selector is required in a program, one is thrown back to having to write a new one specially for that program. In a somewhat exaggerated form there is presented here the idea of an external font-selector ad absurdum ...

Due to the 'wild growth' of the UFSL interface it seemed more sensible to draw a clear line under this and develop a completely new interface that is then also offered via a new cookie.

This text describes this new interface, which can not simply call a font-selector, but can also exert an influence on it in many ways.

• 15.14.1 About the xFSL interface
• 15.14.2 xFSL tips and notes
• 15.14.3 xFSL revisions history
• 15.14.4 UFSL/xFSL program overview
• 15.14.5 The UFSL interface
• 15.14.6 Notes for authors of other font-selectors

15.14.1 About the xFSL interface

With the xFSL interface, the caller (i.e. the program that calls the font-selector) has appreciably more influence on the font-selector, its behaviour, and on the fonts offered for selection.

During the conception of the new interface, the attempt was made to pay regard to the capabilities of various programming languages (e.g. the avoidance of pointers to functions), and at the same time to be prepared for possible extensions of the interface.

The adaptation of a program to the xFSL interface should be a matter of a few minutes, specially as sample calls in various programming languages are provided. The conversion of special requests may require somewhat more effort, of course, but should not present an insoluble problem.

There follows a description of the xFSL cookie as well as the various xFSL calls and parameters ...

• 15.14.1.1 The xFSL cookie
• 15.14.1.2 The simplified call (xfsl_input)
• 15.14.1.3 The extended xFSL call
• 15.14.1.4 The font-flags
• 15.14.1.5 xFSL return codes
• 15.14.1.6 The Pure-C event structure

15.14.1.1 The xFSL cookie

If a font-selector is installed that supports the xFSL interface, then a cookie 'xFSL' exists whose value is a pointer to the following structure:

typedef struct
{
  unsigned long xfsl;       /* Magic 'xFSL'              */
  unsigned int  revision;   /* Interface revision        */
  unsigned long product;    /* Font-selector identifier  */
  unsigned int  version;    /* Font-selector version     */
  xFSL_INPUT    xfsl_input; /* Simplified call           */
  xFSL_INIT     xfsl_init;  /* Init call                 */
  xFSL_EVENT    xfsl_event; /* Event call                */
  xFSL_EXIT     xfsl_exit;  /* Exit call                 */
  xFSL_INFO     xfsl_info;  /* Info call                 */
} xFSL;

Die Komponenten der Struktur im einzelnen:

15.14.1.2 The simplified call (xfsl_input)

xfsl_input is the entry point for a simplified call. With it one can only call the font-selector as a modal dialog. In addition one can specify a heading, and restrict the type of fonts that the selector is to present for selection.

int xfsl_input (int           vdihandle,
                unsigned int  fontflags,
                const char   *headline,
                int          *id,
                int          *size
               );

The parameters in detail:

Return values

xfsl_input returns a negative number if an error has arisen. A 0 is returned if 'Cancel' was selected. If a 1 is returned, then a new font was selected.

The return values are the same for all xFSL functions, and upwardly compatible to the return values of the UFSL.

15.14.1.3 The extended xFSL call

The extended xFSL call consists of three individual function calls:

In C it can look like this, for instance:

xhandle = xfsl->xfsl_init (vdihandle, &xpar);
if (xhandle >= 0)
{
  do
  {
    ret = xfsl->xfsl_event (xhandle, 0L);
    if (ret == xFS_HELP)
      ...;  /* Call Help function  */
    else if (ret == xFS_POPUP)
      ...;  /* Handle popup       */
    else if (ret == xFS_EVENT)
      ...;  /* Handle AES event   */
  } while ((ret != xFS_OK) && (ret != xFS_STOP));
  xfsl->xfsl_exit (xhandle);
}

This splitting up into three has the advantage, amongst others, that the handling of the events (HELP button, popup, AES events) does not have to pass pointers to functions (which presents difficulties in some programming languages). Also the interface can be extended easily by furher events if these should ever become necessary.

15.14.1.3.1 xfsl_init

This call not only brings up the font-selector on the screen, it also determines which fonts are to be displayed, whether a user-popup is being used and several other things.

int xsfl_init (int       vdihandle,
               xFSL_PAR *xpar
              );

The two parameters mean:

The following applies again for the return codes of the function: A negative return value indicates an error. Positive values here have a slightly different meaning: A 0 means that the font-selector was opened (successfully) as a modal dialog. Any other positive values correspond to the window handle of the opened font-selector. This way you can register the font-selector window with an AV-server, for instance.

On success (return value larger or equal to 0) you should store the handle in a variable, as it will still be needed for the following calls (xfsl_event and xfsl_exit).

Note: If the font-selector is to be displayed as a window, but xfsl_init returns the error xFS_NO_WINDOW (no more windows available), then one should attempt to display the font-selector at least as a dialog (clear control-flag CC_WINDOW and call xfsl_init again).

Remember: The user wants a font-selector, not an error-message!

15.14.1.3.2 xfsl_event

When the font-selector has been initialized and brought to the screen, xfsl_event takes over the main work.

int xfsl_event (int    xhandle,
                EVENT *event
               );

The two parameters mean:

The possible return values of xfsl_event:

15.14.1.3.3 xfsl_exit

With the xfsl_exit call the font-selector is removed from the screen again:

void xfsl_exit (int xhandle);

Here xhandle is again the handle of the font-selector, as returned by xfsl_init.

xfsl_exit must be called always when the use of the font-selector is to be ended, be it that a font was chosen or 'Cancel' was selected, or that xfsl_event reported an error. If already the xfsl_init call failed, then xfsl_exit may not be called (logical, since one has no valid handle).

The call of xfsl_exit should also not be forgotten on arrival of the AC_CLOSE and AP_TERM messages!

15.14.1.3.4 The info call (xfsl_info)

With this call one can inquire about some of the features of the installed font-selector:

long xfsl_info (void);

If the return value is positive, then the following flags represent the features that are present (negative return values are, as usual, error-messages):

Name	Value	Meaning
XF_SIZE	0x0001	Size changes possible
XF_COLOR	0x0002	Colour changes possible
XF_ATTR	0x0004	Attribute changes possible
XF_WIDTH	0x0008	Width changes possible
XF_KERN	0x0010	Kerning changes possible
XF_SKEW	0x0020	Slope/skew changes possible
XF_ALIGN	0x0040	Alignment changes possible
XF_ROTATION	0x0080	Text rotation possible
XF_FIX31	0x0100	fix31 support
XF_POPUP	0x0200	Popup support
XF_DRAGDROP	0x0400	Drag&Drop support
XF_MAPPING	0x0800	Understands mapping

Further features of the font-selector can be inquired indirectly via the control element of the xFSL_PAR structure: On a successful xfsl_init call, those control-flags that the font-selector does not know are cleared.

15.14.1.3.5 The VDI workstation in the xFSL interface

With the xfsl_input and xfsl_init calls one can pass the handle of a virtual VDI workstation already opened by the user in each case.

The further behaviour of the font-selector depends on whether one actually passes a workstation handle or just a NULL:

If one passes a valid handle, then the font-selector will try to ascertain the current font on the corresponding workstation and then - provided it matches the passed font-flags - to also set it and offer it for selection. If the current font does not match the fontflags setting (say if only vector fonts are to be offered but the current font is a bitmap font), then the font-selector will select a font from those on offer and present it as the current font.

If the user now selects a font and closes the font-selector with 'OK' then this font will also be set immediately on the passed workstation, so that the calling program no longer has to do this.

For this one should note that the font-selector also opens its own VDI workstation and uses this internally and for the selection of the fonts. Amongst other things it will also call vst_load_fonts for this workstation (provided a GDOS is installed). This can lead to some unexpected results if no vst_load_fonts has been called yet on the passed workstation and the user selects a font in the font-selector that only becomes available after a vst_load_fonts call!

Instead of a workstation handle however one can also simply pass a NULL. The font-selector will then ascertain the current font from the passed parameters (for a xfsl_input call) or from the xFSL_PAR structure (for a xfsl_init call).

The selected font will then (logically) only be returned in the parameters or the xFSL_PAR structure and the caller then has to set it him/herself.

15.14.1.3.6 The xFSL_PAR structure

With this structure you have extensive influence on the behaviour of the font-selector and the type of fonts displayed. Therefore the description of the options is somewhat on the long side ...

typedef struct
{
 int            par_size;    /* Size of xFSL_PAR structure     */
 int            pfi_size;    /* Size of PFONTINFO structure    */
 unsigned long  control;     /* Control-flags                  */
 const char    *headline;    /* Header, or 0L                  */
 const char    *example;     /* Sample text, or 0L             */
 const char    *helptext;    /* Text of the HELP button, or 0L */
 PFONTINFO     *font;        /* Pointer to Fontinfo structure  */
 unsigned int   fontflags;   /* Permitted font types           */
 const char    *poptext;     /* Text before the popup, or 0L   */
 int            num_entries; /* Number of entries (0..n)       */
 int            sel_entry;   /* Selected entry (0..n-1)        */
 xFSL_PENTRY   *popup;       /* Pointer to a popup, or 0L      */
 char          *helpinfo;    /* Pointer to Help-file/-page     */
} xFSL_PAR;

Despite the multitude of entries everything is really quite simple, the more so that the fields that you do not need, or whose meaning is not yet clear to you, can simply be filled with zeros, whereupon the font-selector will then assume sensible default values.

The fields in detail:

To stress once more: Fields that you do not require or do not yet understand can simply be set to zero at first. Exceptions are only:

• par_size, the size of the xFSL_PAR structure itself
   

• pfi_size, the size of the PFONTINFO structure
   

• font, the pointer to the PFONTINFO structure
   

15.14.1.3.7 The control-flags

With the control-flags one can influence the benaviour of the font- selector.

Name	Value	Meaning
CC_WINDOW	0x0001	Font-selector as a window
CC_APPMODAL	0x0002	Font-selector is application-modal
CC_FIX31	0x0004	All size specifications in 1/65536 point
CC_FAKESTYLE	0x0008	Simulate styles (only bitmap fonts)
CC_CLOSER	0x0010	Window with Closer, no OK button
CC_NOSIZE	0x0100	Do not alter size
CC_NOCOLOR	0x0200	Do not alter colour
CC_NOATTR	0x0400	Do not alter attributes
CC_NOWIDTH	0x0800	Do not alter width
CC_NOKERN	0x1000	Do not alter kerning
CC_NOSKEW	0x2000	Do not alter skewing
CC_NOALIGN	0x4000	Do not alter alignment
CC_NOROTATION	0x8000	Do not alter text rotation
CC_DFLTSIZE	0x10000	'Default' font size
CC_INVSTYLE	0x20000	'Inverse' attribute

The function of the individual flags should be clear already from the names and short descriptions. Here still a few notes:

• CC_APPMODAL
  'application-modal' means that the program is put in a mode in which only the font-selector can be processed. Essentially this means that the font-selector intercepts all WM_TOPPED messages for other windows of the calling program and does not pass them on, but makes itself the topped window instead. This is meant to tell the user that he should first deal with the font-selector before he can initiate another action in the program.
   
  The caller in this mode should of course forego topping its own windows with wind_set(WF_TOP).
   

• CC_FAKESTYLE
  This is a specialty that only Calvino offers at present: For those bitmap fonts for which no light, italic or bold variants are present, the missing cuts are each simulated with the VDI function vst_effects.
   

• CC_CLOSER
  If this flag and CC_WINDOW are set, then the font-selector is provided with a Closer, while the 'OK' and the 'Cancel' buttons are hidden. This is intenderd for cases where the font-selector is to be used as a pure Drag&Drop selector.
   

• CC_NO...
  With these flags one can determine which settings are not to be altered. For instance, a program may want to prevent the size of a font being changed, while a change of the font itself is to be allowed. In that case the caller only has to set the CC_NOSIZE flag.
   
  But please note that despite a set CC_NO... flag you always have to pass a valid value. The meaning of these flags therefore is that the preset values may not be changed, and not that these values are not of interest.
   

Please note: Not all font-selectors support all of the control-flags! If a font-selector does not support a flag, then it will simply ignore it. On a successful(!) xfsl_init call, the font-selector will clear those flags in the control element of the xFSL_PAR structure that it does not understand.

15.14.1.3.8 The PFONTINFO structure

This structure describes a font. After calling the font-selector it contains the selected font. In addition these specifications are evaluated by the font-selector already at the call (and the described font displayed), if a zero is passed as the VDI handle.

typedef struct
{
 int          fontid;     /* ID of the font               */
 int          fonttype;   /* Type of font                 */
 char        *fontname;   /* Name of the font             */
 union fsize  fontsize;   /* Font size in pt or fix31     */
 union fsize  fontwidth;  /* Width in pt or fix31         */
 char         trackkern;  /* Track kerning                */
 char         pairkern;   /* Pair kerning                 */
 int          fontattr;   /* Attributes                   */
 int          fontskew;   /* Skew                         */
 int          fontcol;    /* Colour                       */
 int          backcol;    /* Text background colour       */
 int          halign;     /* Horizontal text alignment    */
 int          valign;     /* Vertical text alignment      */
 int          rotation;   /* Text rotation in 1/10 degree */
 int          validtype;  /* Type (V_CHAR_...) or mapping */
 int         *validchars; /* Valid characters, or  0L     */
} PFONTINFO;

The elements in detail:

Still missing are the two parameters validtype and validchars:

Sometimes it is important to ensure that the font contains certain characters. There are two possibilities for this:

If validchars is zero, one can select with validtype one of the following four groups of characters:

These four groups ought to cover the most common applications.

If both validtype and validchars are zero, then the font-selector will treat this as V_CHAR_IND; the same for othr invalid values in validtype.

Should the four groups not suffice at times, then one can instead also specify more precisely with validtype and validchars which characters are required:

Future GDOSes will probably support further mappings (BICS, Unicode, ...). Thanks to the coding used, the font-selector will also handle these correctly: The mapping is simply passed in validtype and then the presence of a character tested with validchars.

Note: The various possibilities available with the validtype and validchars parameters should be used sparingly and with some thought, as the required testing of the characters may - depending on the GDOS - take quite a lot of time.

15.14.1.3.9 The user-popup

For the user-defined popup (user-popup in short) the following fields exist in the xFSL_PAR structure:

An entry in the popup is built up as follows:

typedef struct
{
 char         *entry;      /* Text of the popup entry        */
 PFONTINFO    *fontinfo;   /* Pointer to Fontinfo structure  */
 unsigned int  fontflags;  /* Permitted font types           */
 long          funcflags;  /* Function-flags, only for HuGo! */
} xFSL_PENTRY;

The meaning of the elements of this structure should be clear from the preceding explanations. The function-flags correspond to the control- flags, apart from the flags that influence the global behaviour of the font-selector (CC_WINDOW etc.). These are ignored here.

Important: The pointer to the PFONTINFO structure may not be NULL!

If the text of an entry starts with a `-', then the relevant entry is disabled (displayed in light type and not selectable). This is mainly intended for separation lines between entries.

Application

In principle one can see three fields of use for the user-popup:

1. Each popup entry sets the font for a given part of a program. So for example one could allow only non-proportional fonts in a given program window, no vector fonts in another one, and all fonts in a third.
    

2. Each entry makes a given group of fonts available. For instance, if one frequently requires vector fonts, one could construct a popup with the entries 'Vector fonts only' and 'All fonts'.
    

3. The popup however can be used also for something completely different. One could accommodate information here that though it has nothing to do with fonts, affects the window for which one wants to set a font. For instance, one could offer a choice of the way that inverse characters are to be displayed in a console window in the form of a popup having entries 'Inverse', 'Bold', 'Underlined' available for selection.
    
   If one wants to alienate the purpose of the popup in this way, then with the xFS_POPUP message one has to transfer the changed font (which can be recognized by the set FF_CHANGED flag) to all other popup entries, as otherwise the font that is displayed in the font-selector would change!
    

15.14.1.4 The font-flags

With the font-flags one can restrict the fonts offered for selection:

The values have been chosen in such a way that the individual flags may be OR'd with each other. So, for instance if one uses for the font-flags FF_MONOSPACED|FF_VECTOR, then only non-proportional vector fonts will be offered for selection.

In addition the following applies:

• FF_SYSTEM has priority, i.e. if this flag is set then the system font will be made available for selection too in any event.
   

• If FF_SYSTEM is not set, then the system font will be offered for selection only when its properties correspond to the set flags.
   

• If neither FF_MONOSPACED nor FF_PROPORTIONAL is set, then the font-flags are treated as if both flags are set.
   
  This applies in a similar way for FF_VECTOR and FF_BITMAP.
   

• If FF_VECTOR is set, the all vector font formats will be offered automatically. A finer subdivision is possible with the flags FF_SPD, ..., FF_CFN, if desired.
   
  Please note: Calamus fonts (and therefore the FF_CFN flag) are not supported by any GDOS at present!
   

• The flag FF_CHANGED is only used to mark in the user-popup the settings that have changed. The font-selector only sets this flag but does not itself evaluate it.
   

15.14.1.5 xFSL return codes

All xFSL calls return consistent return codes (return values). A negative number represents an error, a positive number (or zero) means success or an event.

These values were chosen to be upwardly compatible to the UFSL font- selector (this knows the return codes -4, -3, -2, -1, 0 and 1).

In addition, GEMDOS error messages (values smaller or equal to -32) can occur; in particular, xfsl_init can also return the value EINVFN (-32) if the font-selector does not support the extended call.

With the xfsl_init call, positive return values correspond to the font-selector's window handle (0 means that the font-selector was opened as a modal dialog).

It is possible that the list of return codes will be extended in the future for further errors (values smaller than -9) or events (values greater that 4). This should be respected during the design of the program: Unknown errors should lead to an abort, unknown events should be ignored.

15.14.1.6 The Pure-C event structure

The GEM library of Pure-C uses a special structure in which the parameters of the AES function evnt_multi are coalesced. This structure is also used by xfsl_event.

typedef struct /* Special type for EventMulti */
{
 /* Input parameters */
 int ev_mflags,
     ev_mbclicks, ev_bmask, ev_mbstate,
     ev_mm1flags, ev_mm1x, ev_mm1y, ev_mm1width, ev_mm1height,
     ev_mm2flags, ev_mm2x, ev_mm2y, ev_mm2width, ev_mm2height,
     ev_mtlocount, ev_mthicount;

 /* Output parameters */
 int ev_mwich,
     ev_mmox, ev_mmoy, ev_mmobutton, ev_mmokstate,
     ev_mkreturn, ev_mbreturn;

 /* Message-Buffer */
 int ev_mmgpbuf[8];
} EVENT;

The elements of the structure correspond to those of the evnt_multi call. The order of the parameters too - apart from a few exceptions - is identical. The field ev_mwich contains the occurred events in the same coding as ev_mflags in evnt_multi.

15.14.2 xFSL tips and notes

In the following sections an attempt is made to give some tips and notes for the xFSL interface.

15.14.2.1 A simple xFSL call

In view of the multitude of parameters and setting options, the following note seems appropriate:

An xFSL call is simpler than it appears at first. In particular one can adopt here the strategy of 'step-by-step refinement', since one can set (almost) all parameters to zero at first.

A possible simple xFSL call can look like this, for instance:

#include <stdio.h>
#include <aes.h>
#include <vdi.h>
#include <xfsl.h>

void call_xfsl (void)
{
  int xhandle, xret;
  xFSL_PAR xpar;
  PFONTINFO pfont;
  xFSL *xfsl;

  memset (&xpar, 0, sizeof (xFSL_PAR));
  memset (&pfont, 0, sizeof (PFONTINFO));

  xpar.par_size = sizeof (xFSL_PAR);
  xpar.pfi_size = sizeof (PFONTINFO);
  xpar.font = &pfont;
  xpar.font->fontcol = BLACK;

  if (get_cookie ('xFSL', &xfsl))
  {
    xhandle = xfsl->xfsl_init (0, &xpar);
    if (xhandle >= 0)
    {
     do
       xret = xfsl->xfsl_event (xhandle, 0L);
     while (xret > xFS_OK);
     xfsl->xfsl_exit (xhandle);
     if (xret == xFS_STOP)
       printf ("Cancel\n");
     else if (xret == xFS_OK)
       printf ("Font with ID %d selected\n", xpar.font->fontid);
     else if (xret < 0)
       printf ("Error %d\n", xret);
   }
   else
     printf ("Error %d\n", xhandle);
  }
  else
    printf ("Cookie not found!\n");
}

With the two memset calls all elements of the structures xFSL_PAR and PFONTINFO are set to zero. Subsequently some absolutely necessary values are entered:

• The size of the two structures xFSL_PAR and PFONTINFO
   

• The address of the PFONTINFO structure is entered in the xFSL_PAR structure
   

• The font colour is set to black (one could also omit this, but normally one wants to write in black type on a white background)
   

MNo further preparation is required, and now the actual call follows. First the xFSL cookie is searched for and on success the font-selector will be initialized by passing the xFSL_PAR structure. If this call was successful (xhandle is greater or equal to zero), then the font-selector is already on the screen. In the main loop one now waits until the font-selector is terminated either with xFS_STOP or xFS_OK by the user, or until an error occurs (other positive return values are simply ignored here). With the call of xfsl_exit the font-selector is removed from the screen once more and subsequently the return value is evaluated.

That wasn't too complicated, was it? From here on you can now continue experimenting with various parameters and flags.

15.14.2.2 xFSL Questions and Answers

How can I find out which features the font-selector offers?

Directly, this can be done for some features by using the function xfsl_info. Indirectly, further features can be inquired for with the control field in the xFSL_PAR structure: After a successful xfsl_init call the font-selector will clear those control-flags that it does not understand.

How should my program behave when it realizes that the font-selector does not support the desired feature?

If some kind of font-selector is installed, then it also ought to be used in any case. Depending on how important the missing feature is, your program could look for alternatives (e.g. via the Font protocol) or attempt to compensate for the missing feature.

Once again: The user wanted a font-selector, not an error-message! If the missing feature can be compensated for only with difficulty, then you should inform the user once(!) with a corresponding note, but call up the font-selector nevertheless. Even if the selection can then not be made with the desired convenience, it is still far less frustrating for the user than not being able to select a font at all.

Some examples: If the popup is to be used to set the font for a given program window, then if the popup is missing the font should be set for the topped window of the program. If the font-selector does not support the locking of size-changes, then the returned size should simply be ignored and - if it differs from the desired size - the user informed about this by a note.

Incidentally, one should not rely on the font-selector supporting the same features the next time it is called! The font-selectors that work with an overlay (XFSL.OVL) can be substituted at any time without a Reset by re-copying the overlay.

What's all this 'mapping' about?

Vector fonts generally contain more than the familiar 256 characters, and furthermore they are not normally in the accustomed ASCII coding (for example the space character may lie at position 0 instead of 32). Therefore the pertinent characters of the font are 'mapped' to the 'normal' 256 characters, so that the space character lies as usual in position 32, no matter what position it has within the font. This is designated as 'ASCII mapping'.

The ASCII mapping is active by default, but due to this one cannot access the characters that lie outside the ASCII character set. Hence a second mapping, 'Direct mapping', is available. Here one has access to all characters of a font. However, for this one also has to know what type of font one is dealing with and how many characters the font contains: Speedo fonts usually have 564 characters, TrueType fonts can (theoretically) contain up to 65536 characters. One can get this information after switching to Direct mapping with the VDI function vqt_fontinfo:

int minADE, maxADE;

vst_charmap(handle,0); vqt_fontinfo(handle,&minADE,&maxADE,dumarray,&dummy,dumarray);

In minADE one gets the smallest, in maxADE the largest valid character index.

Direct mapping only has limited use for normal applications. Unlike ASCII mapping which provides consistent mapping for all types of fonts, one needs to know here exactly what kind of font one is dealing with. Thus, for instance, the Speedo symbol fonts have a different coding to the 'normal' Speedo fonts. This means that at position 64 of such a symbol font, say, one will not find the same character as for a 'normal' Speedo font.

Other mappings than ASCII are therefore of no interest to the majority of programs at present. But future GDOSes or equivalents may possibly also offer other consistent mappings (e.g. Unicode or BICS), where one can once more rely on the same character appearing always at a given position (similar to ASCII mapping but also including positions higher than 255).

Note: NVDI from NVDI 4 onwards is able to use Unicode mapping.

15.14.2.3 xFSL technical programming notes

The description of the xFSL interface in this text is effected in Pure-C. In the following sections the data-types and specifics of Pure-C are described in greater detail, so that xFSL calls succeed in other programming languages and C-dialects as well.

15.14.2.3.1 Data-types

The following data-types are used in this (part of the) text:

Name	Size
int	16-bit signed
unsigned int	16-bit unsigned
long	32-bit signed
unsigned long	32-bit unsigned

The data-type 'char' is an (ASCII) character and is used here only as a pointer type, i.e. as a pointer to a C-string (series of characters terminated with a NULL-byte).

Union

A union corresponds to a variable record in Pascal. It is a structure whose individual elements lie 'on top of each other', i.e. occupy the same block of memory. Which element is valid at a given time depends on the context, or is left to the programmer.

Example: In the structure PFONTINFO a union `fsize' is used for the size specification:

union fsize
{
 int   size;    /* Font size in points        */
 fix31 size31;  /* Font size in 1/65536 point */
};

The memory requirement of this union comprises four bytes, as the type fix31 is four bytes long. One could now assign to the element size31 a size-specification in 1/65536 point and then read out the value in whole points from the element size - but this is not to be recommended, as in the conversion of fix31 to points one should always round off (see below).

fix31

The data-type fix31 is a fixed-point number, in which the upper 16 bits represent the signed pre-decimal point (whole number) portion, and the lower 16 bits the unsigned decimal portion. It is used only for the size specification and positioning of fonts, so that one can obtain a precision of 1/65536 point with it.

In the conversion of fix31 to points one must not forget rounding. To quote from the NVDI guide:

One may never, never, ever just cut off the decimal part!

15.14.2.3.2 xFSL parameter passing

The passing of parameters for all xFSL calls is done via the stack according to C-convention. This means that at the call the parameter lying furthest right is placed first on the stack, and the left-most parameter at the end, i.e. when jumping to the font-selector, lies at the top.

15.14.2.3.3 Pure-C and 'cdecl'

Pure-C normally passes the parameters to functions in registers. For passing via the stack one must either use the keyword 'cdecl' (as in the include file XFSL.H) or the compiler switch '-H' must be set.

The keyword 'cdecl' is a Pure-C-specific extension and so will issue a warning with compiler switch '-A' (ANSI-conform) set.

15.14.3 xFSL revisions history

Revision 4

• Due to a small design error in the older revisions that limited the extendebility of the interface, Revision 4 is not compatible to older revisions. This should not be a problem in practice, as the font-selector will quit calls according to the old scheme with an error. The old Revision 3 will disappear in time.
   

• New parameters in the PFONTINFO structure:
   

  • Text background colour (backcol)
     

  • Text alignment (halign and valign)
     

  • Text rotation (rotation)
     

  • Specification of characters that the selected font has to contain (validtype and validchars)
     

• The PFONTINFO structure is also filled for returns of xFS_STOP with the values of the last font selected in the font-selector
   

• Coding of the font-flags changed (finer differentiation of the vector formats)
   

Revision 3

• The first publicly available interfacen revision
   

Older revisions

• Older revisions can be safely ignored, as these never appeared in a program available to the public at large
   

15.14.4 UFSL/xFSL program overview

There follows an overview of all available font-selectors at this time that dispose of a UFSL or an xFSL interface (or both).

This is followed by a list of programs that use a font-selector with one or both of these interfaces.

15.14.4.1 Font-selector overview

A short overview of the currently existig font-selectors:

UFSL

by Michael Thänitz
This is the prototype of all external font-selectors. The last published version is 0.97, after which Michael unfortunately ceased its development. Thankfully however he has published the source texts.
 

FontSel

by Holger Weets and Christoph Zwerschke
A small but also rather spartan font-selector from Holger Weets, which from Version 1.02 has been developed further by Christoph Zwerschke. As of the Version 1.02 the xFSL interface is supported as well.
 

xUFSL

by Stefan Rogel
The xUFSL offers many additional features to the font-selectors named above. As these could not be accessed via the existing UFSL interface, Stefan has extended the interface. The design of the first version was, to put it carefully, 'controversial'. The last published Version: 1.05. The successor of the xUFSL is ...
 

HuGo

by Stefan Rogel
HuGo! is the successor of the xUFSL adapted to the xFSL interface (the UFSL interface is also still supported, but not the special extensions of the xUFSL to the UFSL interface). The name change was made to avoid confusion.
 

Calvino

by Dirk Haun
Together with HuGo! the first font-selector with a xFSL interface. Calvino too still supports the simple UFSL interface.
 

FONT_SEL und FONT_PAL

by Christian Grunenberg
These two programs work on a Drag&Drop basis, so they support neither the UFSL nor the xFSL interface, but instead support the Font protocol. FONT_SEL is a font-selector, FONT_PAL a font palette (with integrated font-selector).
 

15.14.4.2 Programs that support a font-selector

The following programs support an external font-selector (position at 16.08.1998, all specifications without guarantee):

(+: supported, W: as window-dialog)

15.14.5 The UFSL interface

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 dialtyp       */
ufsl->fontsel_input(vdihandle,"Please select a font",0,&id,&size);
or
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.

15.14.6 Notes for authors of other font-selectors

Authors of other font-selectors are invited to have their program join the xFSL interface. In principle, every font-selector that uses a TSR concept can be furnished with the xFSL interface.

To prevent misunderstandings: The overlay technique and the reentrancy as offered by Calvino and HuGo! are not part of the actual interface and hence need not be supported by other font-selectors. Indeed the interface between the resident part ('shell') and the post-loaded part ('overlay') is also standardized and therefore can be used by other font-selectors as well. A description of this internal interface is available on request, see 'Contact addresses'.

Since a number of programs already support the old UFSL interface, it seems advisable to make this interface available in new font-selectors as well. However a quick look at these programs shows that they call the font-selector almost exclusively as a modal dialog. Thus the recommendation is to build in minimal UFSL support (as a modal dialog only) and instead implement the xFSL interface as widely as possible, since one can now expect that just those - now finally standardized - extensions will be used by programs rather than the UFSL interface.

A font-selector should offer the following additional features if possible:

• Size changes possible
  In particular this means that not just fixed sizes can be chosen, but with vector fonts inbetween sizes can be set as well.
   

• fix31 support
  For some applications the setting of the font size in points is not enough, hence a setting in 1/65536 point should be possible.
   

• User-popup
  With an additional popup, the font-selector can be used more flexibly.
   

• Drag&Drop support
  Besides the 'traditional' call via the cookie, solutions on the Drag&Drop basis are coming more and more into fashion. If the font-selector already supports Drag&Drop natively, then it can be converted easily with a 'front end' program into a full-blown Drag&Drop selector.
   

The following conventions were agreed for an xFSL font-selector:

• If the font-selector has a Closer, then clicking on this will be interpreted as 'Cancel', i.e. xFS_STOP will be returned. If the CC_CLOSER control-flag is set, then the font current at the time will be returned nevertheless (in the PFONTINFO structure in xFSL_PAR).
   

• If the extended call (xfsl_init, xfsl_event and xfsl_exit) is not supported, then at least a dummy function for xfsl_init will be installed that always returns -32 (GEMDOS error-message EINVFN, invalid function number).
   
  But it is urgently requested that the extended call is offered, as this is the one used most frequently.
   

• It does not matter if the font-selector only appears as a modal dialog for the extended call. But with a set CC_WINDOW, xfsl_init should then return xFS_NO_WINDOW, so that the caller can adjust himself to this.
   

Protocols

XAcc

XSSI protocol