.\" Copyright (C) 2001 Information-technology Promotion Agency (IPA) .\" Copyright (C) 2001-2003 .\" National Institute of Advanced Industrial Science and Technology (AIST) .\" This file si aprt 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, Front-Cover Texts "The m17n library documentation", .\" and no Back-Cover Texts. A copy of the license is included in the .\" appendix entitled "GNU Free Documentation License". .TH "Font" 3m17n "14 Jul 2007" "" "Version 1.4.0" "" "The m17n Library" \" -*- nroff -*- .ad l .nh .SH NAME Font \- Font object. .PP .SS "Variables: Keys of font property." .in +1c .ti -1c .RI "\fBMSymbol\fP \fBMfoundry\fP" .br .RI "\fIKey of font property specifying foundry. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMfamily\fP" .br .RI "\fIKey of font property specifying family. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMweight\fP" .br .RI "\fIKey of font property specifying weight. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMstyle\fP" .br .RI "\fIKey of font property specifying style. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMstretch\fP" .br .RI "\fIKey of font property specifying stretch. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMadstyle\fP" .br .RI "\fIKey of font property specifying additional style. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMspacing\fP" .br .RI "\fIKey of font property specifying spacing. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMregistry\fP" .br .RI "\fIKey of font property specifying registry. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMsize\fP" .br .RI "\fIKey of font property specifying size. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMotf\fP" .br .RI "\fIKey of font property specifying file name. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMfontfile\fP" .br .RI "\fIKey of font property specifying file name. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMresolution\fP" .br .RI "\fIKey of font property specifying resolution. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMmax_advance\fP" .br .RI "\fIKey of font property specifying max advance width. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMfontconfig\fP" .br .RI "\fISymbol of name 'fontconfig'. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMx\fP" .br .RI "\fISymbol of name 'x'. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMfreetype\fP" .br .RI "\fISymbol of name 'freetype'. \fP" .ti -1c .RI "\fBMSymbol\fP \fBMxft\fP" .br .RI "\fISymbol of name 'xft'. \fP" .in -1c .SS "Typedefs" .in +1c .ti -1c .RI "typedef \fBMFont\fP \fBMFont\fP" .br .RI "\fIType of fonts. \fP" .in -1c .SS "Functions" .in +1c .ti -1c .RI "\fBMFont\fP * \fBmfont\fP ()" .br .RI "\fICreate a new font. \fP" .ti -1c .RI "\fBMFont\fP * \fBmfont_parse_name\fP (const char *name, \fBMSymbol\fP format)" .br .RI "\fICreate a font by parsing a fontname. \fP" .ti -1c .RI "char * \fBmfont_unparse_name\fP (\fBMFont\fP *font, \fBMSymbol\fP format)" .br .RI "\fICreate a fontname from a font. \fP" .ti -1c .RI "\fBMFont\fP * \fBmfont_copy\fP (\fBMFont\fP *font)" .br .RI "\fIMake a copy of a font. \fP" .ti -1c .RI "void * \fBmfont_get_prop\fP (\fBMFont\fP *font, \fBMSymbol\fP key)" .br .RI "\fIGet a property value of a font. \fP" .ti -1c .RI "int \fBmfont_put_prop\fP (\fBMFont\fP *font, \fBMSymbol\fP key, void *val)" .br .RI "\fIPut a property value to a font. \fP" .ti -1c .RI "\fBMSymbol\fP * \fBmfont_selection_priority\fP ()" .br .RI "\fIReturn the font selection priority. \fP" .ti -1c .RI "int \fBmfont_set_selection_priority\fP (\fBMSymbol\fP *keys)" .br .RI "\fISet the font selection priority. \fP" .ti -1c .RI "\fBMFont\fP * \fBmfont_find\fP (\fBMFrame\fP *frame, \fBMFont\fP *spec, int *score, int max_size)" .br .RI "\fIFind a font. \fP" .ti -1c .RI "int \fBmfont_set_encoding\fP (\fBMFont\fP *font, \fBMSymbol\fP encoding_name, \fBMSymbol\fP repertory_name)" .br .RI "\fISet encoding of a font. \fP" .ti -1c .RI "char * \fBmfont_name\fP (\fBMFont\fP *font)" .br .RI "\fICreate a fontname from a font. \fP" .ti -1c .RI "\fBMFont\fP * \fBmfont_from_name\fP (const char *name)" .br .RI "\fICreate a new font from fontname. \fP" .ti -1c .RI "int \fBmfont_resize_ratio\fP (\fBMFont\fP *font)" .br .RI "\fIGet resize information of a font. \fP" .ti -1c .RI "\fBMPlist\fP * \fBmfont_list\fP (\fBMFrame\fP *frame, \fBMFont\fP *font, \fBMSymbol\fP language, int maxnum)" .br .RI "\fIGet a list of fonts. \fP" .ti -1c .RI "\fBMPlist\fP * \fBmfont_list_family_names\fP (\fBMFrame\fP *frame)" .br .RI "\fIGet a list of font famiy names. \fP" .ti -1c .RI "int \fBmfont_check\fP (\fBMFrame\fP *frame, \fBMFontset\fP *fontset, \fBMSymbol\fP script, \fBMSymbol\fP language, \fBMFont\fP *font)" .br .RI "\fICheck the usability of a font. \fP" .ti -1c .RI "int \fBmfont_match_p\fP (\fBMFont\fP *font, \fBMFont\fP *spec)" .br .RI "\fICheck is a font matches with a font spec. \fP" .ti -1c .RI "\fBMFont\fP * \fBmfont_open\fP (\fBMFrame\fP *frame, \fBMFont\fP *font)" .br .RI "\fIOpen a font. \fP" .ti -1c .RI "\fBMFont\fP * \fBmfont_encapsulate\fP (\fBMFrame\fP *frame, \fBMSymbol\fP data_type, void *data)" .br .RI "\fIEncapusulate a font. \fP" .ti -1c .RI "int \fBmfont_close\fP (\fBMFont\fP *font)" .br .RI "\fIClose a font. \fP" .in -1c .SS "Variables" .in +1c .ti -1c .RI "\fBMPlist\fP * \fBmfont_freetype_path\fP" .br .RI "\fIList of font files and directories that contain font files. \fP" .in -1c .SH "Detailed Description" .PP The m17n GUI API represents a font by an object of the type \fCMFont\fP. A font can have \fIfont\fP \fIproperties\fP. 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: .PP \fCMfoundry\fP, \fCMfamily\fP, \fCMweight\fP, \fCMstyle\fP, \fCMstretch\fP, \fCMadstyle\fP, \fCMregistry\fP, \fCMsize\fP, \fCMresolution\fP, \fCMspacing\fP. .PP When the key of a font property is \fCMsize\fP or \fCMresolution\fP, its value is an integer. Otherwise the value is a symbol. .PP 'The font property that belongs to font F and whose key is \fCMxxx'\fP may be shortened to 'the xxx property of F'. .PP The value of a foundry property is a symbol representing font foundry information, e.g. adobe, misc, etc. .PP The value of a family property is a symbol representing font family information, e.g. times, helvetica, etc. .PP The value of a weight property is a symbol representing weight information, e.g. normal, bold, etc. .PP The value of a style property is a symbol representing slant information, e.g. normal, italic, etc. .PP The value of a stretch property is a symbol representing width information, e.g. normal, semicondensed, etc. .PP The value of an adstyle property is a symbol representing abstract font family information, e.g. serif, sans-serif, etc. .PP The value of a registry property is a symbol representing registry information, e.g. iso10646-1, iso8895-1, etc. .PP The value of a size property is an integer representing design size in the unit of 1/10 point. .PP The value of a resolution property is an integer representing assumed device resolution in the unit of dots per inch (dpi). .PP The value of a type property is a symbol indicating a font driver; currently Mx or Mfreetype. .PP 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. .PP The m17n library supports three kinds of fonts: Window system fonts, FreeType fonts, and OpenType fonts. .PP .PD 0 .TP 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. .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 XLFD fields not listed in the above table are ignored. .PP .TP 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 \fBmfont_freetype_path\fP is initialized properly according to the configuration of the m17n library and the environment variable \fCM17NDIR\fP. See the documentation of the variable for details. .PP If the m17n library is configured to use the fontconfig library, in addition to \fBmfont_freetype_path\fP, all fonts available via fontconfig are supported. .PP 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. .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 Style names not listed in the above table are treated as 'Regular'. .PP 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. .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 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. .PP .TP 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. .PP .PP .SH "Typedef Documentation" .PP .SS "typedef struct \fBMFont\fP \fBMFont\fP" .PP The type \fBMFont\fP is the structure defining fonts. It contains information about the following properties of a font: foundry, family, weight, style, stretch, adstyle, registry, size, and resolution. .PP This structure is used both for specifying a font in a fontset and for storing information about available system fonts. .PP The internal structure is concealed from an application program. .PP \fBSee Also:\fP.RS 4 \fBmfont()\fP, \fBmfont_from_name()\fP, \fBmfont_find()\fP. .RE .PP .SH "Variable Documentation" .PP .SS "\fBMSymbol\fP \fBMfoundry\fP" .PP 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. .SS "\fBMSymbol\fP \fBMfamily\fP" .PP 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. .SS "\fBMSymbol\fP \fBMweight\fP" .PP 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'). .SS "\fBMSymbol\fP \fBMstyle\fP" .PP 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'). .SS "\fBMSymbol\fP \fBMstretch\fP" .PP 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'). .SS "\fBMSymbol\fP \fBMadstyle\fP" .PP 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'). .SS "\fBMSymbol\fP \fBMspacing\fP" .PP 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). .SS "\fBMSymbol\fP \fBMregistry\fP" .PP 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'). .SS "\fBMSymbol\fP \fBMsize\fP" .PP 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). .SS "\fBMSymbol\fP \fBMotf\fP" .PP 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. .SS "\fBMSymbol\fP \fBMfontfile\fP" .PP 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. .SS "\fBMSymbol\fP \fBMresolution\fP" .PP 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). .SS "\fBMSymbol\fP \fBMmax_advance\fP" .PP 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. .SS "\fBMSymbol\fP \fBMfontconfig\fP" .PP The variable \fBMfontconfig\fP is to be used as an argument of the functions \fBmfont_parse_name()\fP and \fBmfont_unparse_name()\fP. .SS "\fBMSymbol\fP \fBMx\fP" .PP 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 *). .SS "\fBMSymbol\fP \fBMfreetype\fP" .PP 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. .SS "\fBMSymbol\fP \fBMxft\fP" .PP 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 *). .SS "\fBMPlist\fP* \fBmfont_freetype_path\fP" .PP 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.