.\" Copyright (C) 2001 Information-technology Promotion Agency (IPA)
.\" Copyright (C) 2001-2011
.\" National Institute of Advanced Industrial Science and Technology (AIST)
.\" This file is part of the m17n library documentation.
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Section, no Front-Cover Texts,
.\" and no Back-Cover Texts. A copy of the license is included in the
.\" appendix entitled "GNU Free Documentation License".
.TH "m17nFont" 3m17n "Mon Sep 25 2023" "Version 1.8.4" "The m17n Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
m17nFont \- Font
.SH SYNOPSIS
.br
.PP
.SS "Functions"
.in +1c
.ti -1c
.RI "\fBMFont\fP * \fBmfont\fP ()"
.br
.RI "Create a new font\&. "
.ti -1c
.RI "\fBMFont\fP * \fBmfont_parse_name\fP (const char *name, MSymbol format)"
.br
.RI "Create a font by parsing a fontname\&. "
.ti -1c
.RI "char * \fBmfont_unparse_name\fP (\fBMFont\fP *font, MSymbol format)"
.br
.RI "Create a fontname from a font\&. "
.ti -1c
.RI "\fBMFont\fP * \fBmfont_copy\fP (\fBMFont\fP *font)"
.br
.RI "Make a copy of a font\&. "
.ti -1c
.RI "void * \fBmfont_get_prop\fP (\fBMFont\fP *font, MSymbol key)"
.br
.RI "Get a property value of a font\&. "
.ti -1c
.RI "int \fBmfont_put_prop\fP (\fBMFont\fP *font, MSymbol key, void *val)"
.br
.RI "Put a property value to a font\&. "
.ti -1c
.RI "MSymbol * \fBmfont_selection_priority\fP ()"
.br
.RI "Return the font selection priority\&. "
.ti -1c
.RI "int \fBmfont_set_selection_priority\fP (MSymbol *keys)"
.br
.RI "Set the font selection priority\&. "
.ti -1c
.RI "\fBMFont\fP * \fBmfont_find\fP (\fBMFrame\fP *frame, \fBMFont\fP *spec, int *score, int max_size)"
.br
.RI "Find a font\&. "
.ti -1c
.RI "int \fBmfont_set_encoding\fP (\fBMFont\fP *font, MSymbol encoding_name, MSymbol repertory_name)"
.br
.RI "Set encoding of a font\&. "
.ti -1c
.RI "char * \fBmfont_name\fP (\fBMFont\fP *font)"
.br
.RI "Create a fontname from a font\&. "
.ti -1c
.RI "\fBMFont\fP * \fBmfont_from_name\fP (const char *name)"
.br
.RI "Create a new font from fontname\&. "
.ti -1c
.RI "int \fBmfont_resize_ratio\fP (\fBMFont\fP *font)"
.br
.RI "Get resize information of a font\&. "
.ti -1c
.RI "\fBMPlist\fP * \fBmfont_list\fP (\fBMFrame\fP *frame, \fBMFont\fP *font, MSymbol language, int maxnum)"
.br
.RI "Get a list of fonts\&. "
.ti -1c
.RI "\fBMPlist\fP * \fBmfont_list_family_names\fP (\fBMFrame\fP *frame)"
.br
.RI "Get a list of font famiy names\&. "
.ti -1c
.RI "int \fBmfont_check\fP (\fBMFrame\fP *frame, \fBMFontset\fP *fontset, MSymbol script, MSymbol language, \fBMFont\fP *font)"
.br
.RI "Check the usability of a font\&. "
.ti -1c
.RI "int \fBmfont_match_p\fP (\fBMFont\fP *font, \fBMFont\fP *spec)"
.br
.RI "Check is a font matches with a font spec\&. "
.ti -1c
.RI "\fBMFont\fP * \fBmfont_open\fP (\fBMFrame\fP *frame, \fBMFont\fP *font)"
.br
.RI "Open a font\&. "
.ti -1c
.RI "\fBMFont\fP * \fBmfont_encapsulate\fP (\fBMFrame\fP *frame, MSymbol data_type, void *data)"
.br
.RI "Encapusulate a font\&. "
.ti -1c
.RI "int \fBmfont_close\fP (\fBMFont\fP *font)"
.br
.RI "Close a font\&. "
.in -1c
.SS "Variables"
.in +1c
.ti -1c
.RI "\fBMPlist\fP * \fBmfont_freetype_path\fP"
.br
.RI "List of font files and directories that contain font files\&. "
.in -1c
.SS "Variables: Keys of font property\&."
.in +1c
.ti -1c
.RI "MSymbol \fBMfoundry\fP"
.br
.RI "Key of font property specifying foundry\&. "
.ti -1c
.RI "MSymbol \fBMfamily\fP"
.br
.RI "Key of font property specifying family\&. "
.ti -1c
.RI "MSymbol \fBMweight\fP"
.br
.RI "Key of font property specifying weight\&. "
.ti -1c
.RI "MSymbol \fBMstyle\fP"
.br
.RI "Key of font property specifying style\&. "
.ti -1c
.RI "MSymbol \fBMstretch\fP"
.br
.RI "Key of font property specifying stretch\&. "
.ti -1c
.RI "MSymbol \fBMadstyle\fP"
.br
.RI "Key of font property specifying additional style\&. "
.ti -1c
.RI "MSymbol \fBMspacing\fP"
.br
.RI "Key of font property specifying spacing\&. "
.ti -1c
.RI "MSymbol \fBMregistry\fP"
.br
.RI "Key of font property specifying registry\&. "
.ti -1c
.RI "MSymbol \fBMsize\fP"
.br
.RI "Key of font property specifying size\&. "
.ti -1c
.RI "MSymbol \fBMotf\fP"
.br
.RI "Key of font property specifying file name\&. "
.ti -1c
.RI "MSymbol \fBMfontfile\fP"
.br
.RI "Key of font property specifying file name\&. "
.ti -1c
.RI "MSymbol \fBMresolution\fP"
.br
.RI "Key of font property specifying resolution\&. "
.ti -1c
.RI "MSymbol \fBMmax_advance\fP"
.br
.RI "Key of font property specifying max advance width\&. "
.ti -1c
.RI "MSymbol \fBMfontconfig\fP"
.br
.RI "Symbol of name 'fontconfig'\&. "
.ti -1c
.RI "MSymbol \fBMx\fP"
.br
.RI "Symbol of name 'x'\&. "
.ti -1c
.RI "MSymbol \fBMfreetype\fP"
.br
.RI "Symbol of name 'freetype'\&. "
.ti -1c
.RI "MSymbol \fBMxft\fP"
.br
.RI "Symbol of name 'xft'\&. "
.in -1c
.SH "Detailed Description"
.PP
.PP
.nf
@addtogroup m17nFont
@brief Font object.
The m17n GUI API represents a font by an object of the type @c
MFont. A font can have @e font @e properties. Like other types
of properties, a font property consists of a key and a value. The
key of a font property must be one of the following symbols:
@c Mfoundry, @c Mfamily, @c Mweight, @c Mstyle, @c Mstretch,
@c Madstyle, @c Mregistry, @c Msize, @c Mresolution, @c Mspacing.
When the key of a font property is @c Msize or @c Mresolution, its
value is an integer. Otherwise the value is a symbol.
The notation "xxx property of F" means the font property that
belongs to font F and whose key is @c Mxxx.
The value of a foundry property is a symbol representing font
foundry information, e.g. adobe, misc, etc.
The value of a family property is a symbol representing font family
information, e.g. times, helvetica, etc.
The value of a weight property is a symbol representing weight
information, e.g. normal, bold, etc.
The value of a style property is a symbol representing slant
information, e.g. normal, italic, etc.
The value of a stretch property is a symbol representing width
information, e.g. normal, semicondensed, etc.
The value of an adstyle property is a symbol representing abstract
font family information, e.g. serif, sans\-serif, etc.
The value of a registry property is a symbol representing registry
information, e.g. iso10646\-1, iso8895\-1, etc.
The value of a size property is an integer representing design
size in the unit of 1/10 point.
The value of a resolution property is an integer representing
assumed device resolution in the unit of dots per inch (dpi).
The value of a type property is a symbol indicating a font driver;
currently Mx or Mfreetype.
The m17n library uses font objects for two purposes: to receive
font specification from an application program, and to present
available fonts to an application program. When the m17n library
presents an available font to an application program, all font
properties have a concrete value.
The m17n library supports three kinds of fonts: Window system fonts,
FreeType fonts, and OpenType fonts.
- Window system fonts
The m17n\-X library supports all fonts handled by an X server and
an X font server. The correspondence between XLFD fields and font
properties are shown below.
.fi
.PP
.PP
.nf
XLFD field property
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-
FOUNDRY foundry
FAMILY_NAME family
WEIGHT_NAME weight
SLANT style
SETWIDTH_NAME stretch
ADD_STYLE_NAME adstyle
PIXEL_SIZE size
RESOLUTION_Y resolution
CHARSET_REGISTRY\-CHARSET_ENCODING registry
.fi
.PP
.PP
.nf
XLFD fields not listed in the above table are ignored.
- FreeType fonts
The m17n library, if configured to use the FreeType library,
supports all fonts that can be handled by the FreeType library.
The variable #mfont_freetype_path is initialized properly according
to the configuration of the m17n library and the environment
variable @c M17NDIR. See the documentation of the variable for
details.
If the m17n library is configured to use the fontconfig library,
in addition to #mfont_freetype_path, all fonts available via
fontconfig are supported.
The family name of a FreeType font corresponds to the family
property. Style names of FreeType fonts correspond to the weight,
style, and stretch properties as below.
.fi
.PP
.PP
.nf
style name weight style stretch
\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\- \-\-\-\-\-\-\-
Regular medium r normal
Italic medium i normal
Bold bold r normal
Bold Italic bold i normal
Narrow medium r condensed
Narrow Italic medium i condensed
Narrow Bold bold r condensed
Narrow Bold Italic bold i condensed
Black black r normal
Black Italic black i normal
Oblique medium o normal
BoldOblique bold o normal
.fi
.PP
.PP
.nf
Style names not listed in the above table are treated as
"Regular".
Combination of a platform ID and an encoding ID corresponds to the
registry property. For example, if a font has the combination (1
1), the registry property is 1\-1. Some frequent combinations have
a predefined registry property as below.
.fi
.PP
.PP
.nf
platform ID encoding ID registry property
\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
0 3 unicode\-bmp
0 4 unicode\-full
1 0 apple\-roman
3 1 unicode\-bmp
3 1 unicode\-full
.fi
.PP
.PP
.nf
Thus, a font that has two combinations (1 0) and (3 1) corresponds
to four font objects whose registries are 1\-0, apple\-roman, 3\-1,
and unicode\-bmp.
- OpenType fonts
The m17n library, if configured to use both the FreeType library
and the OTF library, supports any OpenType fonts. The list of
actually available fonts is created in the same way as in the case
of FreeType fonts. If a fontset instructs to use an OpenType font
via an FLT (Font Layout Table), and the FLT has an OTF\-related
command (e.g. otf:deva), the OTF library converts a character
sequence to a glyph code sequence according to the OpenType layout
tables of the font, and the FreeType library gives a bitmap image
for each glyph.
.fi
.PP
.SH "Variable Documentation"
.PP
.SS "MSymbol Mfoundry"
.PP
Key of font property specifying foundry\&. The variable \fBMfoundry\fP is a symbol of name \fC'foundry'\fP and is used as a key of font property and face property\&. The property value must be a symbol whose name is a foundry name of a font\&.
.br
.SS "MSymbol Mfamily"
.PP
Key of font property specifying family\&. The variable \fBMfamily\fP is a symbol of name \fC'family'\fP and is used as a key of font property and face property\&. The property value must be a symbol whose name is a family name of a font\&.
.br
.SS "MSymbol Mweight"
.PP
Key of font property specifying weight\&. The variable \fBMweight\fP is a symbol of name \fC'weight'\fP and is used as a key of font property and face property\&. The property value must be a symbol whose name is a weight name of a font (e\&.g 'medium', 'bold')\&.
.br
.SS "MSymbol Mstyle"
.PP
Key of font property specifying style\&. The variable \fBMstyle\fP is a symbol of name \fC'style'\fP and is used as a key of font property and face property\&. The property value must be a symbol whose name is a style name of a font (e\&.g 'r', 'i', 'o')\&.
.br
.SS "MSymbol Mstretch"
.PP
Key of font property specifying stretch\&. The variable \fBMstretch\fP is a symbol of name \fC'stretch'\fP and is used as a key of font property and face property\&. The property value must be a symbol whose name is a stretch name of a font (e\&.g 'normal', 'condensed')\&.
.br
.SS "MSymbol Madstyle"
.PP
Key of font property specifying additional style\&. The variable \fBMadstyle\fP is a symbol of name \fC'adstyle'\fP and is used as a key of font property and face property\&. The property value must be a symbol whose name is an additional style name of a font (e\&.g 'serif', '', 'sans')\&.
.br
.SS "MSymbol Mspacing"
.PP
Key of font property specifying spacing\&. The variable \fBMadstyle\fP is a symbol of name \fC'spacing'\fP and is used as a key of font property\&. The property value must be a symbol whose name specifies the spacing of a font (e\&.g 'p' for proportional, 'm' for monospaced)\&.
.br
.SS "MSymbol Mregistry"
.PP
Key of font property specifying registry\&. The variable \fBMregistry\fP is a symbol of name \fC'registry'\fP and is used as a key of font property\&. The property value must be a symbol whose name is a registry name a font registry (e\&.g\&. 'iso8859\-1', 'jisx0208\&.1983\-0')\&.
.br
.SS "MSymbol Msize"
.PP
Key of font property specifying size\&. The variable \fBMsize\fP is a symbol of name \fC'size'\fP and is used as a key of font property and face property\&. The property value must be an integer specifying a font design size in the unit of 1/10 point (on 100 dpi display)\&.
.br
.SS "MSymbol Motf"
.PP
Key of font property specifying file name\&. The variable \fBMfontfile\fP is a symbol of name \fC'fontfile'\fP and is used as a key of font property\&. The property value must be a symbol whose name is a font file name\&.
.br
.SS "MSymbol Mfontfile"
.PP
Key of font property specifying file name\&. The variable \fBMfontfile\fP is a symbol of name \fC'fontfile'\fP and is used as a key of font property\&. The property value must be a symbol whose name is a font file name\&.
.br
.SS "MSymbol Mresolution"
.PP
Key of font property specifying resolution\&. The variable \fBMresolution\fP is a symbol of name \fC'resolution'\fP and is used as a key of font property and face property\&. The property value must be an integer to specifying a font resolution in the unit of dots per inch (dpi)\&.
.br
.SS "MSymbol Mmax_advance"
.PP
Key of font property specifying max advance width\&. The variable \fBMmax_advance\fP is a symbol of name \fC'max\-advance'\fP and is used as a key of font property\&. The property value must be an integer specifying a font's max advance value by pixels\&.
.br
.SS "MSymbol Mfontconfig"
.PP
Symbol of name 'fontconfig'\&. The variable \fBMfontconfig\fP is to be used as an argument of the functions \fBmfont_parse_name()\fP and \fBmfont_unparse_name()\fP\&.
.br
.SS "MSymbol Mx"
.PP
Symbol of name 'x'\&. The variable \fBMx\fP is to be used for a value of member of the structure \fBMDrawGlyph\fP to specify the type of member is actually (XFontStruct *)\&.
.br
.SS "MSymbol Mfreetype"
.PP
Symbol of name 'freetype'\&. The variable \fBMfreetype\fP is to be used for a value of member of the structure \fBMDrawGlyph\fP to specify the type of member is actually FT_Face\&.
.br
.SS "MSymbol Mxft"
.PP
Symbol of name 'xft'\&. The variable \fBMxft\fP is to be used for a value of member of the structure \fBMDrawGlyph\fP to specify the type of member is actually (XftFont *)\&.
.br
.SS "\fBMPlist\fP* mfont_freetype_path"
.PP
List of font files and directories that contain font files\&. The variable \fCmfont_freetype_path\fP is a plist of FreeType font files and directories that contain FreeType font files\&. Key of the element is \fCMstring\fP, and the value is a string that represents a font file or a directory\&.
.PP
The macro \fBM17N_INIT()\fP sets up this variable to contain the sub\-directory 'fonts' of the m17n database and the environment variable 'M17NDIR'\&. The first call of \fBmframe()\fP creates the internal list of the actually available fonts from this variable\&. Thus, an application program, if necessary, must modify the variable before calling \fBmframe()\fP\&. If it is going to add a new element, value must be a string that can be safely freed\&.
.PP
If the m17n library is not configured to use the FreeType library, this variable is not used\&.
.br
.SH "Author"
.PP
Generated automatically by Doxygen for The m17n Library from the source code\&.
.SH COPYRIGHT
Copyright (C) 2001 Information\-technology Promotion Agency (IPA)
.br
Copyright (C) 2001\-2011 National Institute of Advanced Industrial Science and Technology (AIST)
.br
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License
.