

                 Vectorial Font Library Documentation
                 ------------------------------------
                   Copyright(c) Daniel, INC 1993
                              ver 3.01


 The Vectorial  font library has  only three functions  to be used  by
 you.


 How it works

 The library  functions builds a  table, such table  is an array  of a
 struct type primitive file with the following fields


 int  OpCode: An  Operation code  that can  take the  following values
                  PFMOVETO or PFLINETO.  These identifiers are defined
                  in fontlib.h

 DOUBLE x:     x value of the vector (a point)
 DOUBLE y:     y value of the vector (a point)

 Note: The DOUBLE  identifier is defined in fontlib.h  as 'double', it
       is  used  to  let  the  user  redefine  the floating point type
       according to its needs wen the library is recompiled

 The definition of the structure used is the following:

 struct primitivefile{
                      int OpCode;
                      DOUBLE x;
                      DOUBLE y;
                      };



 After  the table  is build  a  user  supply function  can output  the
 vectors to any vectorial device,  these includes vectorial files like
 HPGL and DXF format, CNC programs etc.

 The functions must be used in  the order as they are described below,
 first  you must  call UserSetPF()  to initialize  the primitive file,
 InitStyle() initializes the font style  to be used, and Text() builds
 up the table.





                              Functions
                              ---------


--------------------------------------------------------------------------
Prototype:  void UserSetPF( PRIMITIVEFILE UserPF, unsigned long UserSizePF )

Purpose: Sets  the 'user defined Primitive  File', this is a  block of
         memory  used to  store the  table information  for the Text()
         function defined below.

Entry:      ----------------------------------------------------------------
            PRIMITIVEFILE UserPF: A pointer to the memory used to store the
                                  table vectors.
            ----------------------------------------------------------------
            unsigned long UserSizePF: Size of the UserPF
            ----------------------------------------------------------------

Returns:    Nothing!

Further info: PRIMITIVEFILE is a  pointer of type struct primitivefile
              defined in fontlib.h as:

              typedef struct primitivefile *PRIMITIVEFILE;



Example:      -------------------------------------------------
              UserPF can be a statically or dynamically reserved memory.

              For example if you want a 1000 vectors primitive defined
              statically:

              struct primitivefile Display[1000];  /*  declaration */
                      ....
              UserSetPF(Display, 1000);            /* use */
                          .

              or dynamically:

              PRIMITIVEFILE Display;   /* declaration */

              /* allocation */
              Display=(PRIMITIVEFILE) calloc(sizeof(struct primitivefile)*1000);
                        .
                        .
              UserSetPF(Display, 1000);  /* use */
              -------------------------------------------------

NOTE:   UserSetPF() function must be the first function to call.

        The user  is responsible to  allocate the necessary  memory an
        deallocated after its used.

        The memory allocated is used trough the InitStyle(),Text() and
        the output user supply function,  so deallocating must be done
        after the information of the table is used.


----------------------------------------------------------------------------





----------------------------------------------------------------------------
Prototype:  int InitStyle( TEXTSTYLE Style, char *BufferFonts,
                           size_t FontFileLength )

Purpose: Initializes the text style,  and loads the selected font file
         from disk.


Entry:      ----------------------------------------------------------------
            TEXTSTYLE Style:

            A TextStyle struct that contains the following fields:

             char Name[13]
             char FontFile[255]
             BOOLEAN Orient

             DOUBLE Height       /* reserved */
             DOUBLE Width        /* reserved */
             DOUBLE ObliAng      /* reserved */

             BOOLEAN BackWard    /* reserved */
             BOOLEAN UpsideDown  /* reserved */

             Explanation of each field

             char Name[13]: A style  name defined by the user(reserved
             for future use)


             char FontFile[255] The path and name of the font file (.FNT)
                                to be initialize and used

             BOOLEAN Orient     Orientation of the text, it can be
                                HORIZONTAL or VERTICAL positions.
                                HORIZONTAL stands for horizontal text
                                VERTICAL stands for vertical text

             All other fields are reserved for future versions of the
             library and must always be initialized as:

             Height=0.0
             Width=1.0
             ObliAng=0.0
             ----------------------------------------------------------------
             char *BufferFonts:

             This  is   a  pointer  used   to  store  the   font  file
             information, enough memory must  be allocated to load the
             file

             The size allocated must be equal as the file (.FNT) size
             ----------------------------------------------------------------
             size_t FontFileLength

             The size of the font file to be loaded.
             ----------------------------------------------------------------

Returns:      OK if the font was loaded

Further info:
              -------------------------------------------------
              TEXTSTYLE is  a typedef of  struct TextStyle defined  in
              fontlib.h as:

              typedef struct TextStyle TEXTSTYLE;

              -------------------------------------------------
              BOOLEAN is defined in fontlib.h as 'int'
              -------------------------------------------------
              HORIZONTAL and VERTICAL is defined in fontlib.h
              -------------------------------------------------
              OK is defined in fontlib.h
              -------------------------------------------------


 Special note:
             If after using the function we need to change the Orient
             value to HORIZONTAL or VERTICAL we must call the function
             again( and of course load the file up to memory)
             This inconvenience will be suppress in new versions of the
             library.



----------------------------------------------------------------------------



----------------------------------------------------------------------------
Prototype:  TEXTOUPUTSTATE Text( const char *Str, FONT_JUSTIFICATION Just,
                                 RW_POINT Pt1,  RW_POINT Pt2, DOUBLE Height,
                                 DOUBLE AngRot, char *BufferFonts);

Purpose:  Builds  the  table  with  the  vectors  that define the text
          'shape'

Entry:      ----------------------------------------------------------------
            const char *Str

            A  pointer with  the user  string from  which the  table is
            constructed
            ----------------------------------------------------------------

            FONT_JUSTIFICATION Just

            This is the justification for the text

            Justification can be:

            DEFAULT (left)       Left justified text
            RIGHT                Right Justified text
            CENTERED             Centered Justified text
            FIT                  Fitted Text
            ALIGNED              Alinged between two,points
            MIDDLE               Proportionally in X and Y legths from 
                                 the point
            ----------------------------------------------------------------
            RW_POINT Pt1 and RW_POINT Pt2

            Please  read the  'Further Info'  for an  explanation about
            RW_POINT.

            Pt1 and Pt2 are used to  store the initial and final value
            of the points  X,Y where the text is  to be displayed, the
            use of  Pt1 and Pt2  depends on the  type of justification
            used

            -----------------------------------------------------------
            Justification    |   Pt1  |   Pt2     | Used in....
            -----------------------------------------------------------
            DEFAULT (left)   |   Used | Not Used  | Pt1 is used as the
                             |        |           | left starting point
                             |        |           | to display the text
                             |        |           |
            -----------------------------------------------------------
            RIGHT            |   Used | Not Used  | Pt1 is used as the
                             |        |           | right justification
                             |        |           | point for the text
                             |        |           |
            -----------------------------------------------------------
            CENTERED         |   Used | Not Used  | Pt1 is used as the
                             |        |           | center point for the
                             |        |           | text
                             |        |           |
            -----------------------------------------------------------
            FIT              |   Used |   Used    | Pt1 and Pt2 are the
                             |        |           | points used to fit
                             |        |           | the text between them
            -----------------------------------------------------------                 
            ALIGNED          |   Used |   Used    | Pt1 is and Pt2 are the
                             |        |           | points used to aligned
                             |        |           | the text between them
                             
            -----------------------------------------------------------
            MIDDLE           |   Used | Not used  | Pt1 is used as the 
                             |        |           | middle point of the 
                             |        |           | text 
                             
            -----------------------------------------------------------


            ----------------------------------------------------------------
            DOUBLE Height

                   This is the desired Height for the text
                   The value must be bigger than 0


            ----------------------------------------------------------------
            DOUBLE AngRot

                   This is the rotation angle for the text

                   The AngRot  must be 0.0  for a fitted  text, fitted
                   text  can be  rotated by  changing the  Pt1 and Pt2
                   points

                   The  AngRot  must  be  a  value  between  0 and 359
                   degrees

                   NOTE: 0=360 degrees

            ----------------------------------------------------------------
            char *BufferFonts


            This is  the pointer that holds  the fontfile information,
            this  pointer was  used in  InitStyle() function explained
            above

            ----------------------------------------------------------------


Returns:   A TEXTOUPUTSTATE variable (TEXTOUPUTSTATE is explained in Futher
           info below )

           Fields of TEXTOUPUTSTATE:


           RW_POINT LastPt :

              Will have on  return the last X,Y position  point of the
              last character analyzed in the string 'Str'

              --------------------------------------------------------------
           int LastChar  :

              Will  have on  return the  Index of  the last  character
              analyzed in the Str string passed to the function, or an
              error defined as:

              PRIMITIVEFILEOVERFLOW   :  The   array  passed   in  the
              UserSetPF() function (PRIMITIVEFILE  UserPF) was not big
              enough  to hold  all the  vectors needed  for the string
              'Str'.

               This  can  be  solved   making  the  UserPF  bigger  or
               splitting the string 'Str' text in several strings

              USERPRITIVEFILENOTSPECIFIED  The  (PRIMITIVEFILE UserPF)
              was not correctly passed to the UserSetPF() function.

                Check out the (PRIMITIVEFILE UserPF) definition
              ---------------------------------------------------------------

              unsigned long LastPrimitiveIndex;

              The  Maximum  Index  used  in  the  UserPF  for  all the
              vectors. (See the user output function example below)

              ---------------------------------------------------------------

Further info:

               -------------------------------------------------
               TEXTOUPUTSTATE is defined in fontlib.h as:
                   typedef struct TextOutState TEXTOUPUTSTATE;

               -------------------------------------------------
               FONT_JUSTIFICATION  is a enum type defined in fontlib.h as:

               enum Just{ ALIGNED, CENTERED, FIT, MIDDLE, RIGHT, DEFAULT};
                 typedef enum Just FONT_JUSTIFICATION;
               -------------------------------------------------
               RW_POINT is defined in fontlib.h as:
               typedef struct _rxycoord_record {
                                                 DOUBLE x;
                                                 DOUBLE y;
                                                 } _rxycoord;

                typedef _rxycoord RW_POINT;
               -------------------------------------------------

                PRIMITIVEFILEOVERFLOW  and USERPRITIVEFILENOTSPECIFIED
                are defined in fontlib.h
               -------------------------------------------------


               HOW TO USE RETURNED VALUES!!

               RW_POINT  LastPt returned  value  can  be used  to keep
               'writing or  building up the  table for further strings,
               for example a big text that CANT be displayed entirely,
               lets say "This  is a big text, a very  big one" once we
               call the Text() function it returns ( LastChar =12 that
               is the index  of the letter 'g' of the  first big in the
               string) and LastPt has an X,Y point that can be used to
               call again  the Text() function but  passing the string
               Str with "g text, a very big one" and Pt1 will now have
               the value of LastPt, so the whole text can be displayed
               entirely

               -------------------------------------------------

               LineFeed causes the Text Function to 'jump' to the next
               line (Y coord changes, but  X does not, you must change
               it  if  you  want,  an  example  can  be  seen  in  the
               loadtext.c source code)

               Linefeed can be used with fitted text but special care
               must be taken.

               Please see the topic Fitted & Linefeed below


               -------------------------------------------------

 NEW!!! :      To add extended ASCII to the string:

               You  will  need  a  special  code  that  represents the
               Extended ASCII needed in  the string, this special code
               must be defined by you,  we have selected the following
               special code  to be used  in the Extended.c  demo file:
               \\<ASCII CODE>

               \\  is my  identifier that  means that  following it  a
               three number will be found

               ASCII CODE  must be given  in decimal notation  and all
               three  digits  following  the  \\  identifier  must  be
               filled, for example:

               The brown fox jum\\128ps over my bed /* OK */

                but not:

               The brown fox jum\\28ps over my bed /* Wrong */

               Then you must build a  function that will this function
               must analyze all special  codes (your definition of the
               special code) that appear in the string and construct a
               new  string that  will have  instead of  the (\\128  or
               other codes)  a byte with  the value 128

               The AnalizeAndChange() function in the extend.c example
               changes  the special  code with  the ASCII  value, this
               should be the new code to analyze

               You can define your  own special code, I repeat(because
               this is important) you can define your own special code
               and instead of using \\XXX  use $$XXX or &&XX&&, and of
               course  make  your  own  AnalizeAndChange() function to
               deal with it, thats your  problem, but you must pass to
               the  Text()  function  a  string  that  instead  of the
               special  code used  has a  byte with  the special  code
               ASCII number values

               Note  The library  searches all  the characters  in the
               string by their ASCII value, that's why I need the byte
               with the extended value in it.

               example using \\XXX special code

                The brown fox jum\\128ps over my bed   /* Ok */

                will be modified to:

               The brown fox jum ps over my bed   /* OK */
                                ^
                                |
                 The  byte that  goes here   has a
                 value of  128 That character is
                 similar to the  'C' character but
                 with a little tail below. Please
                 if  you have an ASCII table look
                 for the 128 code and see what it
                 represents

                 Please read Upgrade.txt


----------------------------------------------------------------------------




 Once the table is constructed we must supply a output function.

 This is  where the unsigned  long LastPrimitiveIndex returned  by the
 Text() function comes in to action.

 Lets see a typical user output function used in the demo programs:


 First there was a #define before the programs main

    #define DisplayIndex (OuttextState.LastPrimitiveIndex)

 that makes a more easy writing code, and was used in the PutDisplay()
 function.


The user defined function goes like this:


--------------------------------------------------------------------
void PutDisplay(void);
void PutDisplay(void)
{
   unsigned long i=0;
   int y=tg_getmaxy(); /* get the max Y coord  of the display */

   /* Trace from the first element in the table (0) to the last one (defined)
      in the variable LastPrimitiveIndex returned by Text(), LastPrimitiveIndex
      is updated wen the Text() function is called
    */
   for(i=0;i<DisplayIndex;i++)
      {
       if(Display[i].OpCode==PFMOVETO)
         /* move to the position */
         _moveto((short)Display[i].x,y-(short)Display[i].y);  /* y- stands for inverting axes */
       else   /* this is == Display[i].OpCode==PFLINETO */
          {
           _setcolor(WHITE);
           /* draw to the position */
           _lineto((short)Display[i].x,y-(short)Display[i].y);  /* y- stands for inverting axes */
          }
      }
}
--------------------------------------------------------------------

 All we do in the function is to analyze the Primitive file and see if
 the  Id was  PFMOVETO or  PFLINETO,  then  we use  the _moveto()  and
 _lineto() functions  from Microsoft(c) standard library  with the X,Y
 of the  display file, the  'y-' used in  the _moveto() and  _lineto()
 function:

                                         |
                                         V
_moveto((short)Display[i].x,             y-        (short)Display[i].y)


 is a  changing Y coord convention,  we use the 0,0  coordinate on the
 lower  left  corner,  and  Microsoft(c)  functions  on the Upper Left
 corner


 Another version  of the output user  defined function can be  seen in
 the fnttodxf.c,  this time all vectors  are send to a  dxf file named
 dxffile.dxf that can be loaded  with Autocad(c), this version outputs
 to the  file all vectors.  The dxf file  is really to  big, but a new
 function can be made using the following function.

/*------------------------------------------------------------------------
 *  void TextLeftDxf(...)
 *
 * Left justified Text
 *
 *-------------------------------------------------------------------------*/

 void TextLeftDxf( FILE   *fp,
        char   *layer ,           /* Layer */
        double xinsert ,          /* Left X insertion point*/
        double yinsert ,          /* Left Y insertion point */
        double txtheight,         /* Text height */
        char   *text,             /* string */
        double AngRot,            /* rotation angle */
        char   *TextStyle)        /* style of the text */
{
fprintf(fp,"  0\nTEXT\n  8\n%s\n 10\n%f\n 20\n%f\n 40\n%f\n  1\n%s\n 50\n%f\n  7\n%s\n",
layer,xinsert,yinsert,txtheight,text,AngRot,TextStyle);
}

 Similar functions can be made for centered and fitted text.


------------------------------------------------------------------------

Fitted & Linefeed
------------------

 After the line feed is processed  the new Firstpoint Y is changed and
 its value  returned by the Text()  function, we must then  update the
 first Y point.

 Lets see an example taken from windemo.cpp (OnPaint() function)


   Temp.y=OuttextState.LastPt.y;

   so wen calling  Text() again the first point(x,y)  has a new value,
   and the next string will be output in the next line

 But fitted text  must change also the second point  Y value, to do so
 you  must calculate  the displacement  of the  Y coord  in the second
 point

 The next code does this for you:

   if(TextStruct.Justification==FIT)
     Temp1.y=Temp1.y+(OuttextState.LastPt.y-Temp.y);

 if the justification is fitted
  then
   The second point Y  = The second point Y + (The  returned Y value -
   The initial Y value)


 (The  returned  Y  value  -  The  initial  Y  value)  is equal to the
 displacement in Y of the first point Y displacement

 Note that this is only made if the text is fitted

------------------------------------------------------------------------


