\&
.sp 1
.ce 3
\s+1\fBChapter 12\fP\s-1
\s+1\fBPEX Fonts\fP\s-1
.sp 2
.nr H1 12
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 12: PEX Fonts
.XE
.LP
The PEX font manipulation mechanisms are the same mechanism as those for
X11 fonts. The PEX font resource is very similar to the font resource
created and managed by X11. PEX fonts that are used with PEX stroke precision
text contain more functionality than is currently found in X11 fonts.
Specifically, stroke precision text requires scalable and rotatable text
fonts.
Because of the added capabilities of PEX fonts, PEX has defined its own
PEX fonts open, close and query requests. However, the PEXlib functions
correlate to the Xlib font functions.
.LP
PEX uses the X11 font path in order to locate PEX font files.
.LP
The first, last and default glyph fields are indices to the first, last
and default glyphs of the font. The default glyph specifies the glyph that
will be displayed when an undefined or non-existent glyph is used.
If the default glyph specifies a non-existent glyph, nothing will be
rendered for undefined or non-existent glyphs. If all glyphs exist is
.PN True ,
then all glyphs within the range of the first and last glyph have non-zero
extents. The stroke font flag indicates whether the font is a PEX font
and is provided so that the application can build font groups that all have
the same text precision.
.LP
A font is not guaranteed to have any properties defined. Whether a property
value is a signed or unsigned, and in what units it is specified must be
derived from prior knowledge of the property. Many fonts will have at least a
CHARSET_REGISTRY (e.g. "ISO8859") and a CHARSET_ENCODING (e.g. "1") property.
.LP
See also information provided in the X Logical Font Description (XLFD)
Conventions defined by the X Consortium.
.bp
.XS
Function Descriptions
.XE
.SH
PEXUnloadFont - Unload PEX Font
.XS
PEXUnloadFont
.XE
.IN "PEXUnloadFont" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXUnloadFont\^(\^Display *\fIdisplay\fP\^, PEXFont \fIfont\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIfont\fP 1i
The resource identifier of the PEX font.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function deletes the association between the resource identifier and the
PEX font. The PEX font itself will be freed when no other resource
references it.
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXFont;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadPEXFont\fP 1i
The specified font resource identifier is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXLoadFont
.RE
.bp
.SH
PEXFreeFontInfo - Free Font Info Returned by PEXListFontsWithInfo and PEXQueryFont
.XS
PEXFreeFontInfo
.XE
.IN "PEXFreeFontInfo" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXFreeFontInfo\^(\^unsigned long \fIcount\fP\^, PEXFontInfo *\fIfont_info\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIcount\fP 1i
The number of font info structures.
.IP \fIfont_info\fP 1i
An array of font info structures.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
.LP
This function deallocates memory returned by
.PN PEXListFontsWithInfo
and
.PN PEXQueryFont .
.RE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.LP
.PN PEXListFontsWithInfo ,
.PN PEXQueryFont
.RE
.bp
.SH
PEXFreeFontNames - Free Font Names Returned by PEXListFonts, PEXListFontsWithInfo
.XS
PEXFreeFontNames
.XE
.IN "PEXFreeFontNames" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXFreeFontNames\^(\^unsigned long \fIcount\fP, char **\fIfont_names\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIcount\fP 1i
The number of font names.
.IP \fIfont_names\fP 1i
An array of font names (null-terminated strings).
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
.LP
This function deallocates memory returned by
.PN PEXListFonts
and
.PN PEXListFontsWithInfo .
.RE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.LP
.PN PEXListFonts ,
.PN PEXListFontsWithInfo
.RE
.bp
.SH
PEXListFonts - List PEX Fonts
.XS
PEXListFonts
.XE
.IN "PEXListFonts" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
char **PEXListFonts\^(\^Display *\fIdisplay\fP\^, char *\fIpattern\fP\^, unsigned int \fImax_names\fP\^, unsigned long *\fIcount_return\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIpattern\fP 1i
A null-terminated string pattern.
.IP \fImax_names\fP 1i
The maximum number of names to be returned.
.IP \fIcount_return\fP 1i
Returns the actual number of font names.
.RE
.SH
Returns
.RS
.LP
An array of font names (null-terminated strings); a null pointer if unsuccessful or if no PEX fonts supported.
.RE
.SH
Description
.RS
.LP
.LP
This function is like X11
.PN XListFonts
except only information
about fonts that can support the full range of PEX text attributes is returned
(i.e. only those fonts that are "PEX usable").
This list may or may not contain some of the same fonts returned by the X11
.PN XListFonts
function. This
function returns a list of entries, each of which
contains the name of a font matching the pattern. The pattern is a
string that uses the ISO Latin-1 encoding and case is not significant in
matching names.
The '?' character (octal value 077) matches any single
character, and the character '*' (octal value 052)
matches any number of characters.
The returned names are null-terminated, in lower-case and are also ISO
Latin-1 encoded strings.
.LP
PEXlib allocates memory for the returned list of font names.
.PN PEXFreeFontNames
should be called to deallocate the memory.
.RE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.LP
.PN PEXListFontsWithInfo ,
.PN PEXFreeFontNames
.RE
.bp
.SH
PEXListFontsWithInfo - List PEX Fonts With Information
.XS
PEXListFontsWithInfo
.XE
.IN "PEXListFontsWithInfo" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
char **PEXListFontsWithInfo\^(\^Display *\fIdisplay\fP\^, char *\fIpattern\fP\^, unsigned int \fImax_names\fP\^, unsigned long *\fIcount_return\fP\^, PEXFontInfo **\fIinfo_return\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIpattern\fP 1i
A null-terminated string pattern.
.IP \fImax_names\fP 1i
The maximum number of names to be returned.
.IP \fIcount_return\fP 1i
Returns the actual number of font names.
.IP \fIfont_info\fP 1i
Returns an array of font info structures (one for each name).
.RE
.SH
Returns
.RS
.LP
An array of font names (null-terminated strings); a null pointer if unsuccessful or if no PEX fonts supported.
.RE
.SH
Description
.RS
.LP
This function is like X11
.PN XListFontsWithInfo
except that only information
about fonts that can support the full range of PEX text attributes is returned
(i.e. those fonts that are "PEX usable"). This list may or may not contain
some of the same fonts returned the X11
.PN XListFontsWithInfo
function.
This function returns a list of entries, each of
which contains information about a font matching the pattern.
The pattern is a string that uses the ISO Latin-1 encoding and
case is not significant in matching names.
The '?' character (octal value 077) matches any single
character, and the character '*' (octal value 052)
matches any number of characters.
The returned names are null-terminated, in lower case and are
also ISO Latin-1 encoded strings.
.LP
The information returned for each font is identical to what
.PN PEXQueryFont
would return.
.LP
PEXlib allocates memory for the returned list of font names and font info.
.PN PEXFreeFontNames
should be called to deallocate the memory for the font names.
.PN PEXFreeFontInfo
should be called to deallocate the memory for the font information.
.RE
.SH
Data Structures
.ID
.Co
typedef struct {
unsigned long first_glyph;
unsigned long last_glyph;
unsigned long default_glyph;
Bool all_exist;
Bool stroke;
unsigned short count; /* number of properties */
PEXFontProp *props;
} PEXFontInfo;
.sp
typedef struct {
Atom name;
unsigned long value;
} PEXFontProp;
.ft P
.DE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.LP
.PN PEXListFonts ,
.PN PEXQueryFont
.br
.PN PEXFreeFontNames ,
.PN PEXFreeFontInfo
.RE
.bp
.SH
PEXLoadFont - Load PEX Font
.XS
PEXLoadFont
.XE
.IN "PEXLoadFont" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
PEXFont PEXLoadFont\^(\^Display *\fIdisplay\fP\^, char *\fIfont_name\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIfont_name\fP 1i
The font name (null-terminated string).
.RE
.SH
Returns
.RS
.LP
The resource identifier of the loaded PEX font.
.RE
.SH
Description
.RS
.LP
This function loads the specified PEX font, if necessary. The font
name should use the ISO Latin-1 encoding and case is not significant
in matching names. PEX fonts are not associated with a particular screen,
and can be used with any renderer or PHIGS workstation resource.
An error will be generated if the specified font is not "PEX usable",
that is, it is not capable of supporting the full range of PEX text
attributes.
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXFont;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadAlloc\fP 1i
The server failed to allocate the resource.
.IP \fIBadPEXFont\fP 1i
The specified font name does not name a usable PEX font.
.RE
.SH
See Also
.RS
.LP
.PN PEXUnloadFont
.RE
.bp
.SH
PEXQueryEncodedTextExtents - Query Encoded Text Extents
.XS
PEXQueryEncodedTextExtents
.XE
.IN "PEXQueryEncodedTextExtents" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
PEXTextExtent *PEXQueryEncodedTextExtents\^(\^Display *\fIdisplay\fP\^, XID \fIresource_id\fP\^, unsigned int \fIfont_table_index\fP\^, int \fIpath\fP\^, double \fIexpansion\fP\^, double \fIspacing\fP\^, double \fIheight\fP\^, int \fIhalign\fP\^, int \fIvalign\fP\^, unsigned long \fIcount\fP\^, PEXListOfEncodedText *\fIencoded_text\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIresource_id\fP 1i
The resource identifier of either a renderer, a workstation or a text font table.
.IP \fIfont_table_index\fP 1i
The text font table index.
.IP \fIpath\fP 1i
The text path
.Pn ( PEXPathRight ,
.PN PEXPathLeft ,
.PN PEXPathUp ,
.PN PEXPathDown ).
.IP \fIexpansion\fP 1i
The text character expansion factor.
.IP \fIspacing\fP 1i
The text character spacing factor.
.IP \fIheight\fP 1i
The text character height.
.IP \fIhalign\fP 1i
The text horizontal text alignment
.Pn ( PEXHAlignNormal ,
.PN PEXHAlignLeft ,
.PN PEXHAlignCenter ,
.PN PEXHAlignRight ).
.IP \fIvalign\fP 1i
The text vertical text alignment
.Pn ( PEXVAlignNormal ,
.PN PEXVAlignTop ,
.PN PEXVAlignCap ,
.PN PEXVAlignHalf ,
.PN PEXVAlignBase ,
.PN PEXVAlignBottom ).
.IP \fIcount\fP 1i
The number of encoded text strings.
.IP \fIencoded_text\fP 1i
An array of encoded text strings.
.RE
.SH
Returns
.RS
.LP
An array of text extents; a null pointer if unsuccessful.
.RE
.SH
Description
.RS
.LP
This function is like
.PN PEXQueryTextExtents ,
except
that multiple encoded text strings are specified. Each text
string in the encoded text list has a character set, a character
set width, an encoding state, and a list of characters. (See
.PN PEXEncodedTextData .)
.LP
The character
set is an index into the current font group. Font groups have
individual fonts which are numbered starting at one; a value of
three would select the third font in the font group currently being
used. If a character set is not available in the current font
group then the default
font group is used. If a character set value is not available in the
default font group then the result is
implementation-dependent. The character set width indicates
the width or size of characters in the strings.
Valid values for character set width are
.PN PEXCSByte ,
.PN PEXCSShort
and
.PN PEXCSLong .
The encoding state is provided for use by the application and is not
interpreted by the PEX server.
.LP
All other aspects of this function are the same as
.PN PEXQueryTextExtents .
.RE
.SH
Data Structures
.ID
.Co
typedef struct {
unsigned short count; /* number of encodings */
PEXEncodedTextData *encoded_text;
} PEXListOfEncodedText;
.sp
typedef struct {
unsigned short character_set;
unsigned char character_set_width;
unsigned char encoding_state;
unsigned short reserved;
unsigned short length;
char *ch;
} PEXEncodedTextData;
.sp
typedef struct {
PEXCoord2D lower_left;
PEXCoord2D upper_right;
PEXCoord2D concat_point;
} PEXTextExtent;
.sp
typedef struct {
float x;
float y;
} PEXCoord2D;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadMatch\fP 1i
The specified resource identifier identifies a table of type other than a
text font table.
.IP \fIBadValue\fP 1i
A specified value for one or text attributes is invalid, or the specified
resource identifier does not identify a valid renderer, workstation or
lookup table resource.
.RE
.SH
See Also
.RS
.LP
.PN PEXQueryTextExtents
.RE
.bp
.SH
PEXQueryFont - Query PEX Font Information
.XS
PEXQueryFont
.XE
.IN "PEXQueryFont" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
PEXFontInfo *PEXQueryFont\^(\^Display *\fIdisplay\fP\^, PEXFont \fIfont\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIfont\fP 1i
The resource identifier of the font.
.RE
.SH
Returns
.RS
.LP
A pointer to the font info structure; a null pointer if unsuccessful.
.RE
.SH
Description
.RS
.LP
This function returns information about the specified PEX font.
The information returned is identical to what
.PN PEXListFontsWithInfo
would return.
.LP
PEXlib allocates memory for the returned list of font information.
.PN PEXFreeFontInfo
should be called to deallocate the memory.
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXFont;
.sp
typedef struct {
unsigned long first_glyph;
unsigned long last_glyph;
unsigned long default_glyph;
Bool all_exist;
Bool stroke;
unsigned short count; /* number of properties */
PEXFontProp *props;
} PEXFontInfo;
.sp
typedef struct {
Atom name;
unsigned long value;
} PEXFontProp;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadPEXFont\fP 1i
The specified font resource identifier is invalid.
.RE
.SH
See Also
.RS
.LP
.RE
.bp
.SH
PEXQueryTextExtents - Query Text Extents
.XS
PEXQueryTextExtents
.XE
.IN "PEXQueryTextExtents" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
PEXTextExtent *PEXQueryTextExtents\^(\^Display *\fIdisplay\fP\^, XID \fIresource_id\fP\^, unsigned int \fIfont_table_index\fP\^, int \fIpath\fP\^, double \fIexpansion\fP\^, double \fIspacing\fP\^, double \fIheight\fP\^, int \fIhalign\fP\^, int \fIvalign\fP\^, unsigned long \fIcount\fP\^, PEXStringData *\fItext\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIresource_id\fP 1i
The resource identifier of either a renderer, a workstation or a text font table.
.IP \fIfont_table_index\fP 1i
The text font table index.
.IP \fIpath\fP 1i
The text path
.Pn ( PEXPathRight ,
.PN PEXPathLeft ,
.PN PEXPathUp ,
.PN PEXPathDown ).
.IP \fIexpansion\fP 1i
The text character expansion factor.
.IP \fIspacing\fP 1i
The text character spacing factor.
.IP \fIheight\fP 1i
The text character height.
.IP \fIhalign\fP 1i
The text horizontal text alignment
.Pn ( PEXHAlignNormal ,
.PN PEXHAlignLeft ,
.PN PEXHAlignCenter ,
.PN PEXHAlignRight ).
.IP \fIvalign\fP 1i
The text vertical text alignment
.Pn ( PEXVAlignNormal ,
.PN PEXVAlignTop ,
.PN PEXVAlignCap ,
.PN PEXVAlignHalf ,
.PN PEXVAlignBase ,
.PN PEXVAlignBottom ).
.IP \fIcount\fP 1i
The number of text strings.
.IP \fItext\fP 1i
An array of text strings.
.RE
.SH
Returns
.RS
.LP
An array of text extents; a null pointer if unsuccessful.
.RE
.SH
Description
.RS
.LP
.LP
This function returns the text extents, in the local 2D text coordinate system,
of each specified text string.
If the resource identifier is a renderer or PHIGS workstation, then the
text font table associated with the renderer or workstation is used.
If the resource identifier is a text font lookup table,
it is used directly. The specified font group
provides the index of the entry that is to be used to obtain the
font group. The first character set in the font will be used.
.LP
Stroke precision is assumed. The text position is (0,0) in
the local 2D text coordinate system.
The extent of each string is computed independent of the other strings.
.LP
If a specified font has no defined default glyph, then undefined glyphs
are taken to have all zero metrics.
.LP
The extent data is returned in memory allocated by PEXlib.
.PN XFree
should be called to deallocate the memory.
.RE
.SH
Data Structures
.ID
.Co
typedef struct {
unsigned short length;
char *ch;
} PEXStringData;
.sp
typedef struct {
PEXCoord2D lower_left;
PEXCoord2D upper_right;
PEXCoord2D concat_point;
} PEXTextExtent;
.sp
typedef struct {
float x;
float y;
} PEXCoord2D;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadMatch\fP 1i
The specified resource identifier identifies a table of type other than a
text font table.
.IP \fIBadValue\fP 1i
A specified value for one or text attributes is invalid, or the specified
resource identifier does not identify a valid renderer, workstation or
lookup table resource.
.RE
.SH
See Also
.RS
.LP
.PN PEXQueryEncodedTextExtents
.RE
.bp