Functions
MFont *	mfont ()
	Create a new font.

MFont *	mfont_parse_name (const char *name, MSymbol format)
	Create a font by parsing a fontname.

char *	mfont_unparse_name (MFont *font, MSymbol format)
	Create a fontname from a font.

MFont *	mfont_copy (MFont *font)
	Make a copy of a font.

void *	mfont_get_prop (MFont *font, MSymbol key)
	Get a property value of a font.

int	mfont_put_prop (MFont font, MSymbol key, void val)
	Put a property value to a font.

MSymbol *	mfont_selection_priority ()
	Return the font selection priority.

int	mfont_set_selection_priority (MSymbol *keys)
	Set the font selection priority.

MFont *	mfont_find (MFrame frame, MFont spec, int *score, int max_size)
	Find a font.

int	mfont_set_encoding (MFont *font, MSymbol encoding_name, MSymbol repertory_name)
	Set encoding of a font.

char *	mfont_name (MFont *font)
	Create a fontname from a font.

MFont *	mfont_from_name (const char *name)
	Create a new font from fontname.

int	mfont_resize_ratio (MFont *font)
	Get resize information of a font.

MPlist *	mfont_list (MFrame frame, MFont font, MSymbol language, int maxnum)
	Get a list of fonts.

MPlist *	mfont_list_family_names (MFrame *frame)
	Get a list of font famiy names.

int	mfont_check (MFrame frame, MFontset fontset, MSymbol script, MSymbol language, MFont *font)
	Check the usability of a font.

int	mfont_match_p (MFont font, MFont spec)
	Check is a font matches with a font spec.

MFont *	mfont_open (MFrame frame, MFont font)
	Open a font.

MFont *	mfont_encapsulate (MFrame frame, MSymbol data_type, void data)
	Encapusulate a font.

int	mfont_close (MFont *font)
	Close a font.

Variables
MPlist *	mfont_freetype_path
	List of font files and directories that contain font files.

Variables: Keys of font property.
MSymbol	Mfoundry
	Key of font property specifying foundry.

MSymbol	Mfamily
	Key of font property specifying family.

MSymbol	Mweight
	Key of font property specifying weight.

MSymbol	Mstyle
	Key of font property specifying style.

MSymbol	Mstretch
	Key of font property specifying stretch.

MSymbol	Madstyle
	Key of font property specifying additional style.

MSymbol	Mspacing
	Key of font property specifying spacing.

MSymbol	Mregistry
	Key of font property specifying registry.

MSymbol	Msize
	Key of font property specifying size.

MSymbol	Motf
	Key of font property specifying file name.

MSymbol	Mfontfile
	Key of font property specifying file name.

MSymbol	Mresolution
	Key of font property specifying resolution.

MSymbol	Mmax_advance
	Key of font property specifying max advance width.

MSymbol	Mfontconfig
	Symbol of name "fontconfig".

MSymbol	Mx
	Symbol of name "x".

MSymbol	Mfreetype
	Symbol of name "freetype".

MSymbol	Mxft
	Symbol of name "xft".

Detailed Description

@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.

<ul>

<li> 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.

    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

XLFD fields not listed in the above table are ignored.

<li> 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.

    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

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.

    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

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.

<li> 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.

</ul>

Function Documentation

◆ mfont()

MFont * mfont ( )

Create a new font.

The mfont() function creates a new font object that has no property.

Return value:: This function returns a pointer to the created font object.

◆ mfont_parse_name()

MFont * mfont_parse_name	(	const char *	name,
		MSymbol	format
	)

Create a font by parsing a fontname.

The mfont_parse_name() function creates a new font object. The properties are extracted fontname name.

format specifies the format of name. If format is Mx, name is parsed as XLFD (X Logical Font Description). If format is Mfontconfig, name is parsed as Fontconfig's textual representation of font. If format is Mnil, name is at first parsed as XLFD, and it it fails, parsed as Fontconfig's representation.

Return value:: If the operation was successful, this function returns a pointer to the created font. Otherwise it returns NULL.

◆ mfont_unparse_name()

char * mfont_unparse_name	(	MFont *	font,
		MSymbol	format
	)

Create a fontname from a font.

The mfont_unparse_name() function creates a fontname string from font font according to format.

format must be Mx or Mfontconfig. If it is Mx, the fontname is in XLFD (X Logical Font Description) format. If it is Mfontconfig, the fontname is in the style of Fontconfig's text representation.

Return value:: This function returns a newly allocated fontname string, which is not freed unless the user explicitly does so by free().

◆ mfont_copy()

MFont * mfont_copy ( MFont * font )

Make a copy of a font.

The mfont_copy() function returns a new copy of font font.

◆ mfont_get_prop()

void * mfont_get_prop	(	MFont *	font,
		MSymbol	key
	)

Get a property value of a font.

The mfont_get_prop() function gets the value of key property of font font. key must be one of the following symbols:

Mfoundry, Mfamily, Mweight, Mstyle, Mstretch, Madstyle, Mregistry, Msize, Mresolution, Mspacing.

If font is a return value of mfont_find(), key can also be one of the following symbols:

Mfont_ascent, Mfont_descent, Mmax_advance.

Return value:: If key is Mfoundry, Mfamily, Mweight, Mstyle, Mstretch, Madstyle, Mregistry, or Mspacing, this function returns the corresponding value as a symbol. If the font does not have key property, it returns Mnil. If key is Msize, Mresolution, Mfont_ascent, Mfont_descent, or Mmax_advance, this function returns the corresponding value as an integer. If the font does not have key property, it returns 0. If key is something else, it returns NULL and assigns an error code to the external variable merror_code.

◆ mfont_put_prop()

int mfont_put_prop	(	MFont *	font,
		MSymbol	key,
		void *	val
	)

Put a property value to a font.

The mfont_put_prop() function puts a font property whose key is key and value is val to font font. key must be one of the following symbols:

Mfoundry, Mfamily, Mweight, Mstyle, Mstretch, Madstyle, Mregistry, Msize, Mresolution.

If key is Msize or Mresolution, val must be an integer. Otherwise, val must be a symbol of a property value name. But, if the name is "nil", a symbol of name "Nil" must be specified.

◆ mfont_selection_priority()

MSymbol * mfont_selection_priority ( )

Return the font selection priority.

The mfont_selection_priority() function returns a newly created array of six symbols. The elements are the following keys of font properties ordered by priority.

Mfamily, Mweight, Mstyle, Mstretch, Madstyle, Msize.

The m17n library selects the best matching font according to the order of this array. A font that has a different value for a property of lower priority is preferred to a font that has a different value for a property of higher priority.

◆ mfont_set_selection_priority()

int mfont_set_selection_priority ( MSymbol * keys )

Set the font selection priority.

The mfont_set_selection_priority() function sets font selection priority according to keys, which is an array of six symbols. Each element must be one of the below. No two elements must be the same.

Mfamily, Mweight, Mstyle, Mstretch, Madstyle, Msize.

See the documentation of the function mfont_selection_priority() for details.

◆ mfont_find()

MFont * mfont_find	(	MFrame *	frame,
		MFont *	spec,
		int *	score,
		int	max_size
	)

Find a font.

The mfont_find() function returns a pointer to the available font that matches best the specification spec on frame frame.

score, if not NULL, must point to a place to store the score value that indicates how well the found font matches to spec. The smaller score means a better match.

◆ mfont_set_encoding()

int mfont_set_encoding	(	MFont *	font,
		MSymbol	encoding_name,
		MSymbol	repertory_name
	)

Set encoding of a font.

The mfont_set_encoding() function sets the encoding information of font font.

encoding_name is a symbol representing a charset that has the same encoding as the font.

repertory_name is Mnil or a symbol representing a charset that has the same repertory as the font. If it is Mnil, whether a specific character is supported by the font is asked to each font driver.

Return value:: If the operation was successful, this function returns 0. Otherwise it returns -1 and assigns an error code to the external variable merror_code.

◆ mfont_name()

char * mfont_name ( MFont * font )

Create a fontname from a font.

This function is obsolete. Use mfont_unparse_name instead.

◆ mfont_from_name()

MFont * mfont_from_name ( const char * name )

Create a new font from fontname.

This function is obsolete. Use mfont_parse_name() instead.

◆ mfont_resize_ratio()

int mfont_resize_ratio ( MFont * font )

Get resize information of a font.

The mfont_resize_ratio() function lookups the m17n database <font, reisize> and returns a resizing ratio (in percentage) of FONT. For instance, if the return value is 150, that means that the m17n library uses an 1.5 time bigger font than a specified size.

◆ mfont_list()

MPlist * mfont_list	(	MFrame *	frame,
		MFont *	font,
		MSymbol	language,
		int	maxnum
	)

Get a list of fonts.

The mfont_list() functions returns a list of fonts available on frame frame. font, if not NULL, limits fonts to ones that match with font. language, if not Mnil, limits fonts to ones that support language. maxnum, if greater than 0, limits the number of fonts.

language argument exists just for backward compatibility, and the use is deprecated. Use Mlanguage font property instead. If font already has Mlanguage property, language is ignored.

Return value:: This function returns a plist whose keys are family names and values are pointers to the object MFont. The plist must be freed by m17n_object_unref(). If no font is found, it returns NULL.

◆ mfont_list_family_names()

MPlist * mfont_list_family_names ( MFrame * frame )

Get a list of font famiy names.

The mfont_list_family_names() functions returns a list of font family names available on frame frame.

Return value:

This function returns a plist whose keys are Msymbol and values are symbols representing font family names. The elements are sorted by alphabetical order. The plist must be freed by m17n_object_unref(). If not font is found, it returns NULL.

◆ mfont_check()

int mfont_check	(	MFrame *	frame,
		MFontset *	fontset,
		MSymbol	script,
		MSymbol	language,
		MFont *	font
	)

Check the usability of a font.

The mfont_check() function checkes if font can be used for script and language in fontset on frame.

Return value:: If the font is usable, return 1. Otherwise return 0.

◆ mfont_match_p()

int mfont_match_p	(	MFont *	font,
		MFont *	spec
	)

Check is a font matches with a font spec.

The mfont_match_p() function checks if font matches with the font-spec spec.

Return value:: If the font matches, 1 is returned. Otherwise 0 is returned.

◆ mfont_open()

MFont * mfont_open	(	MFrame *	frame,
		MFont *	font
	)

Open a font.

The mfont_open() function opens font on frame, and returns a realized font.

Return value:: If the font was successfully opened, a realized font is returned. Otherwize NULL is returned.

See Also:: mfont_close().

◆ mfont_encapsulate()

MFont * mfont_encapsulate	(	MFrame *	frame,
		MSymbol	data_type,
		void *	data
	)

Encapusulate a font.

The mfont_encapsulate() functions realizes a font by encapusulating data data or type data_type on frame. Currently data_tape is Mfontconfig or Mfreetype, and data points to an object of FcPattern or FT_Face respectively.

Return value:: If the operation was successful, a realized font is returned. Otherwise NULL is return.

See Also:: mfont_close().

◆ mfont_close()

int mfont_close ( MFont * font )

Close a font.

The mfont_close() function close a realized font font. font must be opened previously by mfont_open() or mfont_encapsulate ().

Return value:: If the operation was successful, 0 is returned. Otherwise, -1 is returned.

See Also:: mfont_open(), mfont_encapsulate().

Variable Documentation

◆ Mfoundry

MSymbol Mfoundry

Key of font property specifying foundry.

The variable Mfoundry is a symbol of name "foundry" 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.

◆ Mfamily

MSymbol Mfamily

Key of font property specifying family.

The variable Mfamily is a symbol of name "family" 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.

◆ Mweight

MSymbol Mweight

Key of font property specifying weight.

The variable Mweight is a symbol of name "weight" 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").

◆ Mstyle

MSymbol Mstyle

Key of font property specifying style.

The variable Mstyle is a symbol of name "style" 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").

◆ Mstretch

MSymbol Mstretch

Key of font property specifying stretch.

The variable Mstretch is a symbol of name "stretch" 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").

◆ Madstyle

MSymbol Madstyle

Key of font property specifying additional style.

The variable Madstyle is a symbol of name "adstyle" 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").

◆ Mspacing

MSymbol Mspacing

Key of font property specifying spacing.

The variable Madstyle is a symbol of name "spacing" 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).

◆ Mregistry

MSymbol Mregistry

Key of font property specifying registry.

The variable Mregistry is a symbol of name "registry" 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").

◆ Msize

MSymbol Msize

Key of font property specifying size.

The variable Msize is a symbol of name "size" 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).

◆ Motf

MSymbol Motf

Key of font property specifying file name.

The variable Mfontfile is a symbol of name "fontfile" and is used as a key of font property. The property value must be a symbol whose name is a font file name.

◆ Mfontfile

MSymbol Mfontfile

Key of font property specifying file name.

The variable Mfontfile is a symbol of name "fontfile" and is used as a key of font property. The property value must be a symbol whose name is a font file name.

◆ Mresolution

MSymbol Mresolution

Key of font property specifying resolution.

The variable Mresolution is a symbol of name "resolution" 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).

◆ Mmax_advance

MSymbol Mmax_advance

Key of font property specifying max advance width.

The variable Mmax_advance is a symbol of name "max-advance" 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.

◆ Mfontconfig

MSymbol Mfontconfig

Symbol of name "fontconfig".

The variable Mfontconfig is to be used as an argument of the functions mfont_parse_name() and mfont_unparse_name().

◆ Mx

MSymbol Mx

Symbol of name "x".

The variable Mx is to be used for a value of <type> member of the structure MDrawGlyph to specify the type of <fontp> member is actually (XFontStruct *).

◆ Mfreetype

MSymbol Mfreetype

Symbol of name "freetype".

The variable Mfreetype is to be used for a value of <type> member of the structure MDrawGlyph to specify the type of <fontp> member is actually FT_Face.

◆ Mxft

MSymbol Mxft

Symbol of name "xft".

The variable Mxft is to be used for a value of <type> member of the structure MDrawGlyph to specify the type of <fontp> member is actually (XftFont *).

◆ mfont_freetype_path

MPlist* mfont_freetype_path

List of font files and directories that contain font files.

The variable mfont_freetype_path is a plist of FreeType font files and directories that contain FreeType font files. Key of the element is Mstring, and the value is a string that represents a font file or a directory.

The macro M17N_INIT() sets up this variable to contain the sub-directory "fonts" of the m17n database and the environment variable "M17NDIR". The first call of mframe() creates the internal list of the actually available fonts from this variable. Thus, an application program, if necessary, must modify the variable before calling mframe(). If it is going to add a new element, value must be a string that can be safely freed.

If the m17n library is not configured to use the FreeType library, this variable is not used.

Functions

Variables

Variables: Keys of font property.