\section{Specifying fonts}

XPCE's font specification is a two-stage process.  In the first stage,
XPCE physical fonts are mapped to fonts of the underlying windowing
system. In this stage, fonts are identified by their {\em family},
{\em style} and {\em size}.  For example

\begin{code}
font(screen, roman, 13)
\end{code}

Refers to a fixed-width font designed for use on the screen that has
normal weight, no italics and 13-pixels high characters.

In the second stage, logical font-names are mapped to their physical
implementation.  At this level, fonts are identified by a single name
from an extensible, but preferably small set.


\subsection{Physical fonts}

The default physical font set is built when the first font object is
opened (i.e.\ its window counterpart is located and made available to
the text-drawing functions).  This set is created from resources on
the display object.  The first resource is {\em font_families}, which
defines a chain with names of the font-families.  The default value is:%
    \footnote{See section~\ref{sec:resources} for the resource syntax.}

\begin{code}
Pce.Display.font_families: [ screen_fonts, \ 
			     courier_fonts, \ 
			     helvetica_fonts, \ 
			     times_fonts \ 
			   ]
\end{code}

Each of these names refer to the name of another resource of class
\class{display}, enumerating the members of this font family.  The
default value can be examined using the online manual.  Below is the
default value for of the {\tt screen_fonts} font-set for X11:

\begin{code}
Pce.Display.screen_fonts: [ font(screen, roman, 10, "6x10"), \ 
			    font(screen, roman, 12, "6x12"), \ 
			    font(screen, roman, 13, "8x13"), \ 
			    font(screen, roman, 14, "7x14"), \ 
			    font(screen, roman, 15, "9x15"), \ 
			    font(screen, bold, 13, "8x13bold"), \ 
			    font(screen, bold, 14, "7x14bold"), \ 
			    font(screen, bold, 15, "9x15bold") \ 
			  ]
\end{code}

The set of predefined physical fonts can be examined using the
FontViewer demo application accessible through the online manual tools.


\subsubsection{Defining additional fonts}

If an application needs additional fonts, such fonts can be declared
using directives. The 4th initialisation argument of class \class{font}
determines the window-system font that will be mapped.  For example, the
the 14-points adobe symbol may be approached using the directive below%
    \footnote{xfontsel(1) was used to locate the font.}

\begin{code}
:- new(_, font(symbol, roman, 14,
	       '-*-symbol-*-*-*-*-14-*-*-*-*-*-adobe-*')).
\end{code}

This specification has various drawbacks.  For example, another library
or application loaded on top of the same XPCE process may be using the
symbol/roman/14 specification, but bound to another window-system font.
A user may try to run your application on an X11 environment that
does not have this font. Part of these problems can be eliminated by
binding the font to a logical font name. See also
section~\ref{sec:fontalias}.

\begin{code}
:- send(@display, font_alias,
	adobesymbol,
	font(symbol, roman, 14,
	     '-*-symbol-*-*-*-*-14-*-*-*-*-*-adobe-*')).
\end{code}

The application will refer to this font using the font-alias.  If the
user has other preferences or the font is not available, the user may
specify the font using the Pce.Display.user_font resource described
in section~\ref{sec:fontalias}.


\subsection{Logical fonts}		\label{sec:fontalias}.

It is not wise let your application code speak about physical fonts as
the user or interface guidelines may prefer using a different
font-palette. For this reason the display defines a mapping between
logical font names and physical fonts. Applications are encouraged to
use logical font names as much as possible and leave the assignment to
physical fonts to the users preferences.  XPCE predefines the following
logical font-names.  The value gives the default assignment for these
fonts.

\begin{itemize}
\newcommand{\font}[2]{\tick{\makebox[1in][l]{#1}#2}}
    \font{normal}{font(helvetica, roman, 12)}
The default font. Normally a proportional roman font. Should be easy to
read.
    \font{bold}{font(helvetica, bold, 12)}
Bold version of the normal font.
    \font{italic}{font(helvetica, oblique, 12)}
Slanted version of the normal font.  Note that italic fonts should not
be used for long text as italics is generally not easy to read on most
displays.
    \font{small}{font(helvetica, roman, 10)}
Small version of the normal font.  To be used in notes, subscripts, etc.
May not be so easy to read, so avoid using it for long texts.
    \font{large}{font(helvetica, roman, 14)}
Slightly larger version of the normal font.
    \font{boldlarge}{font(helvetica, bold, 14)}
Bold version of large.
    \font{huge}{font(helvetica, roman, 18)}
Even larger font.  To be used for titles, etc.
    \font{boldhuge}{font(helvetica, bold, 18)}
Bold version of huge.
    \font{fixed}{font(screen, roman, 13)}
Terminal font. To be used for code fragments, code editors, etc. Should
be easy to read.
\end{itemize}

The end-user of an XPCE application can define the resource
Pce.Display.user_fonts to overrule fonts.  The example below
re-binds the most commonly used fonts to be slightly larger and
choose from the times font family rather than the helvetica
fonts.

\begin{code}
Pce.Display.user_fonts: [ normal := font(times, roman, 14), \ 
			  bold   := font(times, bold, 14), \ 
			  italic := font(times, italic, 14) \ 
			]
\end{code}

The mapping between logical font names and physical fonts is realised
by the methods `display <->font_alias' additional font aliases may
be loaded using `display ->load_font_aliases'.

Class \class{font} predefined conversion will translate names to font
objects.  This implies that for any method expecting a font object the
programmer can specify the font-name instead.  In those (rare) cases
where a font needs to be passed, but the type-specification does not
require this, the conversion must be done explicitly.  The preferred
way to make the conversion is using the font type object:

\begin{code}
	...,
	get(type(font), check, bold, BoldFont),
	...,
\end{code}

{}