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.1.3.9  The user-popup                                        TOS

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

 poptext       Pointer to a text that is to appear before the popup, 
               or 0L. The font-selector is free to ignore this text.

 num_entries   Number of entries (i.e. lines) in popup. If there is a 
               zero here than no popup will be displayed. One should 
               not use more than 16 entries, even though some font- 
               selectors may support more in some circumstances.

 sel_entry     The selected entry in the popup (count starts from 0). 
               The font-selector stores the number of the selected 
               popup entry here and reads out the value anew at each 
               xfsl_event call. In this way you can also force the 
               font-selector to activate the entry with number 5 
               instead of the selected number 3, for instance, (at 
               xFS_POPUP the font-selector only reports which entry 
               was selected, though this is only activated on jumping 
               back into the font-selector).

 popup         This is a pointer to an array of xFSL_PENTRY elements 
               as shown below. At the specified address there have to 
               be exactly as many elements as were specified in 
               num_entries.

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!