MyFonts		Using non-BGI fonts within Pascal programs.
ver 1.53	Copyright (c) 1993 by Matthias Kppe.

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

1  General Information
----------------------

MyFonts is a Turbo Pascal unit. With MyFonts, you can use non-BGI fonts
within pascal programs. Following font types are supported:

 * VGA BIOS fonts		8, 14, 16 pixels high
 * DOS CPI fonts		code-page dependent, 8, 14, 16 pixels high
 * Windows bitmap fonts		(if present in your system)
 * Windows vector fonts		NEW! (if present in your system)
 * BGI fonts			NEW: direct utilization - better output

At the program start-up, the used fonts are declared. Then, you can access
these fonts by identifying numbers. So you will be able to exchange fonts
dynamically.

Font output is done with routines which are compatible to the Graph unit.
MyFonts provides the following techniques:
 * clipping (limitting output to a rectangle)
 * TV text markers switch the text color
 * Windows-compatible text metrics
 * synthesization of bold font variants (for Windows and BGI)
 * character space justification
 * text alignment also at the base line and the leading line

The MyFonts unit is part of the MyMouse software package. It is based on
the following units:

- Gr	    This unit is the commonly used graphic interface. The graphics
	    mode is to be set by SetGrMode first. Please read Gr's
  documentation for more information.

- Memory    This Turbo Vision unit is used for dynamically reserving memory
	    for the font glyphs and releasing it again if it is needed.
  Before MyFonts is used, Memory must be initialized by an InitMemory call.
  If you wish to use many big fonts, you should largen the buffer area by
  changing the Memory.MaxBufMem variable.


2  Font Declaration
-------------------

A variant record (TFontRec) stores the font information. These FontRecs are
stored in a Turbo Vision collection, FontCollection. So, fonts are declared
by
   FontCollection^.Insert(FontRec);

This is done by following routine:

function DefFont(Font: PFontRec): Word;

  This function adds a loaded font to the font collection. The font number
  is returned.

For adding FontRec, you will enter

  DefFont(FontRec);

Here, FontRec is a pointer to a TFontRec on the heap. The following functions
allocate TFontRecs:

function LoadCPIFont(FName: PathStr; ReqCP, ReqLength: Word;
  CharSpace, AVertAdd, AHeight: Integer): PFontRec;

  This function loads a font from an MS-DOS code-page information file
  (*.CPI). Following are the parameters.
  * FName is the CPI file name (e.g. 'C:\DOS\EGA.CPI')
  * ReqCP is the required code-page (normally 437)
  * ReqLength is the required font height in pixels (8, 14, or 16)
  * CharSpace is the standard extra character space (normally 0)
    used for stretching text horizontally
  * AVertAdd is the vertical additive value (normally 0)
    used for moving a glyph vertically for correcting differences
  * AHeight is normally zero or the virtual font height

function LoadBgiFileFont(FName: PathStr; ReqHeight, AMultX, ADivX, AMultY,
  ADivY: Integer; CharSpace, AVertAdd, AHeight: Integer;
  Attr: Word): PFontRec;

  This function replaces LoadBgiFont of earlier versions.

  Loads a scalable BGI font (*.CHR).
  * FName is the CHR file name (e.g. 'C:\TP\BGI\SANS.CHR').
    If you wish to load a linked font, set FixedAddr(p) for this parameter
    (p is a pointer to the font).
  * ReqHeight is the required character height.
  * AMultX, ADivX, AMultY, ADivY specify the font scaling.
  * CharSpace, AVertAdd, AHeight s.a.
  * Attr is the attribute to be synthesized (ftNormal for normal fonts,
    ftBold for bold font versions). Add ftNoDescent if the descents of
    the characters need not be counted.

  NOTE: * Set ReqHeight = 0, and the font is scaled with the specified
	  scaling factors and divisors.
	* Set ReqHeight <> 0, and the font is scaled so that it reaches the
	  specified height. The scaling parameters can be set zero, or they
	  specify a height/width proportion.

  MyFonts does not use the BGI for drawing these fonts. You will need a
  line-drawing routine for drawing the fonts. Therefore, you must put the
  BGI unit to your program's USES list. If you need more drawing performance,
  we advise you to order the MetaGraph unit.

function LoadBIOSFont(ReqLength: Word;
  CharSpace, AVertAdd, AHeight: Integer): PFontRec;

  This function loads an internal VGA BIOS font.
  * ReqLength is the required font height in pixels (8, 14, or 16)
  * CharSpace, AVertAdd, AHeight s.a.
  NOTE: BIOS fonts need hardly any memory.

function LoadWinFont(FName: PathStr; reqNr, reqPt, reqLength: Word;
  CharSpace, AVertAdd, AHeight: Integer; Attr: Word): PFontRec;

  This function loads a Windows bitmap or vector font (*.FON).
  * FName is the FON file name (e.g. 'c:\windows\system\sserife.fon')
  * reqNr is the number of the required font in the file
  * reqPt is the required point size of the font
  * reqLength is the required pixel height of the font
  NOTE: Only one of these three parameters must be specified. The other
	parameters should be set zero.
  * bits in Attr specify required font attributes
    - if Attr = 0, the font is drawn normally
    - if Attr = ftBold, the bold font version is synthesized
    Perhaps you should largen the character space for bold fonts.
  * CharSpace, AVertAdd, AHeight s.a.

  For scalable Windows fonts, you will need a line-drawing routine for
  drawing the fonts. Therefore, you must put the BGI unit to your
  program's USES list. If you need more drawing performance, we advise
  you to order the MetaGraph unit.

function AliasOf(Font: Word; CharSpace, AVertAdd, AHeight: Integer;
  Attr: Word): PFontRec;

  This function loads an alias font, i.e. a reference to another font number.
  * Font is the font identifying number. Forward and backward references
    are allowed.
  * The others parameters make the new font different from the referred font.

  NOTE: Using alias fonts provides a more efficient memory usage than
	multiply loading the same font.
	The double-alias behavior has been modified since version 1.2.

function FullAliasOf(Font: Word): PFontRec;

  This function loads an alias font but does not change any parameters.


One example for vertical correction shall be given: Imagine you have written
an application that uses Windows system font (16 pixels high) if Windows is
installed on the system, and otherwise a 16 pixel BIOS font.
The proportions of these both fonts do not match; the baseline is situated
somewhere else though the fonts have the same height. For correcting the
baseline position, set a value for AVertAdd in one font.
This correction method should not be used. It is old-fashioned. Rather use
the advanced text measure functions of MyFonts.

The large character glyphs are loaded on demand. For allocating memory,
procedure GetBufMem from the Turbo Vision Memory unit is used. If new
memory requests come up, allocated memory will be freed again. This
dynamical reservation is a very efficient method of font administration.

Do not forget to initialize the Memory unit. Remember that the MaxBufMem
variable must be set high enough to provide enough space for fonts.


3  Font Output
--------------

The following font output routines are provided by MyFonts. They are
compatible with the Graph routines.

procedure OutTextXY(x, y: Integer; s: string);
function TextWidth(s: string): Integer;
function TextHeight(s: string): Integer;

  Need not be documented.

procedure SetTextJustify(Horiz, Vert: Word);

  MyFonts provides two new vertical text alignments:
  * BaseLine	aligns at the base line of the characters
  * LeadLine	aligns at the leading line (highest point of capital letters)

procedure SetTextParams(Font: Word; CharSpace: Integer; Color: Word;
  UseMarker: Boolean);

  This procedure is used instead of Graph's SetTextStyle.
  * Font is the identifying number of the required font
  * CharSpace is the additive extra character space. It is added to the
    standard character space and may be negative.
  * Color is the text color. The low byte is the normal color, the high byte
    the highlighted color.
  * Set UseMarker true, if a tilde character (~) shall switch between
    normal and highlighted color (as in Turbo Vision) or be a normal text
    character.

procedure SetMarker(Marker: Char);

  Sets the text marking character. Standard is a tilde character (~).

procedure GetTextMetrics(var Metrics: TTextMetric);

  Returns metric information of the current font. The data structure is
  completely compatible with Windows' TextMetric structure. Read in your SDK
  documentation for more information.

  Following table shows the most important metrics.

  tmHeight		height of the characters
  tmAscent		ascent of the characters (above base line)
  tmDescent		descent of the characters (below base line)
  tmInternalLeading	free space for accents (inside the ascent)
  tmExternalLeading	distance between rows to be used
  tmAveCharWidth	average character width
  tmMaxCharWidth	maximal character width

  NOTE: Some of the non-Windows fonts do not provide the correct values for
	certain advanced metric data.


4  Further Routines
-------------------

procedure InitMyFonts;

  Initializes MyFonts. Must be called at program startup.

procedure DoneMyFonts;

  De-initializes MyFonts. Should be called before terminating the application.

The other routines in the interface should not be used by applications.
They remain undocumented.


5  Variables
------------

The ClipRect (clipping rectangle) and DrawOrigin (drawing origin) variables
are found in the Gr unit together with routines for setting these values.

FontCollection: PFontCollection;

  This collection stores the declared fonts.

The other variables remain undocumented.


6  Further Information
----------------------

The font count begins with zero. It is useful to define constants for
the declared fonts, so that you can easily access the fonts.

Have a look to the Gr graphics protocol documentation for clipping,
draw origin, screen pages, and graphic parameters.

Also have a look at the example sources. This will give you more understanding
of the MyFonts mechanisms and details.

You can adapt the buffer memory size to your application's requirements by
modifying the Memory.MaxBufMem variable. Do read your Turbo Vision
documentation.

-----------------------------------------------------------------------------
				New in Version 1.5
-----------------------------------------------------------------------------

1. Supports scalable Windows fonts.
2. Supports version 3 Windows fonts up to 64 KB size.
3. Direct BGI font drawing provides bold font synthesization, direkt marker
   support, font measures and more compatibility.
4. Supports Windows text metrics.
5. Text alignment at the base line and the leading line.
6. Accelerated and improved alias font handling.
