m17nFont(3m17n)

🌸 m17nFont 🌸

okay bestie, welcome to m17nFont(3m17n) from The m17n Library 💖 this is the font page and it is long, so it comes in two parts — you're reading part 1 rn. grab a snack, we're doing this 🍓

---

✨ NAME ✨

m17nFont — Font. that's it, that's the name. it's giving "the entire font system" 👑

💅 SYNOPSIS 💅

🫶 Functions

• MFont * mfont () — create a brand new font, fresh out the box ✨
• MFont * mfont_parse_name (const char *name, MSymbol format) — make a font by parsing a fontname 🧚
• char * mfont_unparse_name (MFont *font, MSymbol format) — go the other way and build a fontname out of a font 💫
• MFont * mfont_copy (MFont *font) — clone a font, no cap 🪞
• void * mfont_get_prop (MFont *font, MSymbol key) — grab a property value off a font 🔍
• int mfont_put_prop (MFont *font, MSymbol key, void *val) — set a property value on a font 📥
• MSymbol * mfont_selection_priority () — hand back the font selection priority 👑
• int mfont_set_selection_priority (MSymbol *keys) — set that font selection priority 🎚️
• MFont * mfont_find (MFrame *frame, MFont *spec, int *score, int max_size) — go find a font 🔎
• int mfont_set_encoding (MFont *font, MSymbol encoding_name, MSymbol repertory_name) — set a font's encoding 🏷️
• char * mfont_name (MFont *font) — build a fontname from a font ✍️
• MFont * mfont_from_name (const char *name) — create a new font from a fontname 🌱
• int mfont_resize_ratio (MFont *font) — get the resize info for a font 📐
• MPlist * mfont_list (MFrame *frame, MFont *font, MSymbol language, int maxnum) — get a whole 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 whether a font is even usable ✅
• int mfont_match_p (MFont *font, MFont *spec) — check if a font matches 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 (yes that's how it's spelled, we keep it fr fr) 📦
• int mfont_close (MFont *font) — close a font, bye bestie 👋

🎀 Variables

• MPlist * mfont_freetype_path — a 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.

so here's the tea ☕ the m17n GUI API represents a font with an object of type MFont. a font can have font properties. just like every other kind of property out there, a font property is a key + a value situation 🔑➕💎

the key of a font property has to be one of these symbols, periodt:

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

when the key of a font property is Msize or Mresolution, its value is an integer 🔢. otherwise the value is a symbol 🏷️

when we say "xxx property of F", we mean the font property that belongs to font F and whose key is Mxxx. iykyk 💅

• 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 whole purposes: to receive a font specification from an application program, and to present available fonts to an application program 🫱🫲 and when the m17n library presents an available font to an application program, all font properties have a concrete value. no vibes-based guessing, real values only ✨

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 goes like this:

• 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 that aren't in the list above? ignored. not invited to the party 🙈

• FreeType fonts 🆓

the m17n library — if it was configured to use the FreeType library — supports all fonts that can be handled by the FreeType library. the variable #mfont_freetype_path gets initialized properly according to the configuration of the m17n library and the environment variable M17NDIR. go read that variable's docs for the details, bestie 📖

if the m17n library is configured to use the fontconfig library, then on top of #mfont_freetype_path, all fonts available via fontconfig are supported too 🎛️✨

the family name of a FreeType font corresponds to the family property. and the style names of FreeType fonts map onto the weight, style, and stretch properties like this:

• style name Regular → weight medium, style r, stretch normal
• style name Italic → weight medium, style i, stretch normal
• style name Bold → weight bold, style r, stretch normal
• style name Bold Italic → weight bold, style i, stretch normal
• style name Narrow → weight medium, style r, stretch condensed
• style name Narrow Italic → weight medium, style i, stretch condensed
• style name Narrow Bold → weight bold, style r, stretch condensed
• style name Narrow Bold Italic → weight bold, style i, stretch condensed
• style name Black → weight black, style r, stretch normal
• style name Black Italic → weight black, style i, stretch normal
• style name Oblique → weight medium, style o, stretch normal
• style name BoldOblique → weight bold, style o, stretch normal

any style name that isn't in that list gets treated as "Regular" 😐 (iconic of it honestly)

a 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 come with a predefined registry property:

• platform ID 0, encoding ID 3 → registry property unicode-bmp
• platform ID 0, encoding ID 4 → registry property unicode-full
• platform ID 1, encoding ID 0 → registry property apple-roman
• platform ID 3, encoding ID 1 → registry property unicode-bmp
• platform ID 3, encoding ID 1 → registry property unicode-full

so 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. four for the price of one, we love a multitasker 💅✨

• OpenType fonts 🅾️

the m17n library — if it's 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. and 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), then 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 🖼️🔥

---

okay that's part 1 wrapped — part 2 is right there waiting for you, keep scrolling bestie 🫶

✨ Variable Documentation ✨

Okay bestie, this is the part where we meet the variables — the little symbols that hold the keys to font properties and face properties and all that good stuff. Every single one matters, no skips, fr fr. 💅

MSymbol Mfoundry

Mfoundry is the key of a font property that specifies the foundry. The variable is a symbol of name 'foundry', and it gets used as a key of both font property and face property. The property value has to be a symbol whose name is a foundry name of a font. Slay. ✨

MSymbol Mfamily

Mfamily is the key of a font property that specifies the family. It's a symbol of name 'family', used as a key of font property and face property. The value must be a symbol whose name is a family name of a font. 💖

MSymbol Mweight

Mweight is the key of a font property specifying weight. Symbol of name 'weight', used as key of font property and face property. Value must be a symbol whose name is a weight name of a font (e.g. 'medium', 'bold'). Periodt. 💪

MSymbol Mstyle

Mstyle — key of font property specifying style. Symbol of name 'style', used as key of font property and face property. Value must be a symbol whose name is a style name of a font (e.g. 'r', 'i', 'o'). Iykyk. 🌸

MSymbol Mstretch

Mstretch — key of font property specifying stretch. Symbol of name 'stretch', used as key of font property and face property. Value must be a symbol whose name is a stretch name of a font (e.g. 'normal', 'condensed'). Stretch it out bestie. 🦋

MSymbol Madstyle

Madstyle — key of font property specifying additional style. Symbol of name 'adstyle', used as key of font property and face property. Value must be a symbol whose name is an additional style name of a font (e.g. 'serif', '', 'sans'). Yes, the empty string is in there, iconic. ✨

MSymbol Mspacing

Mspacing — key of font property specifying spacing. The variable Madstyle is a symbol of name 'spacing', and it 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). (Yes, it says Madstyle in the original, bestie — I'm just the messenger 💀)

MSymbol Mregistry

Mregistry — key of font property specifying registry. Symbol of name 'registry', used as a key of font property. Value must be a symbol whose name is a registry name of a font registry (e.g. 'iso8859-1', 'jisx0208.1983-0'). Registry realness. 🎀

MSymbol Msize

Msize — key of font property specifying size. Symbol of name 'size', used as a key of font property and face property. Value must be an integer specifying a font design size in the unit of 1/10 point (on 100 dpi display). Numbers bestie. 🔢

MSymbol Motf

Motf — key of font property specifying file name. The variable Mfontfile is a symbol of name 'fontfile', and it is used as a key of font property. The property value must be a symbol whose name is a font file name. (Yes, the heading is Motf but the prose says Mfontfile — we're just reporting the lore 💀)

MSymbol Mfontfile

Mfontfile — key of font property specifying file name. The variable Mfontfile is a symbol of name 'fontfile', and it is used as a key of font property. The property value must be a symbol whose name is a font file name. Iconic duplicate energy. ✨

MSymbol Mresolution

Mresolution — key of font property specifying resolution. Symbol of name 'resolution', used as a key of font property and face property. Value must be an integer specifying a font resolution in the unit of dots per inch (dpi). DPI girlies rise. 🌈

MSymbol Mmax_advance

Mmax_advance — key of font property specifying max advance width. Symbol of name 'max-advance', used as a key of font property. Value must be an integer specifying a font's max advance value by pixels. Max advance, max slay. 👑

MSymbol Mfontconfig

Mfontconfig — symbol of name 'fontconfig'. It is to be used as an argument of the functions mfont_parse_name() and mfont_unparse_name(). Fontconfig bestie. 🫶

MSymbol Mx

Mx — symbol of name 'x'. It is to be used for a value of <type> member of the structure MDrawGlyph to specify the type of <fontp> member is actually (XFontStruct *). X marks the spot. ✨

MSymbol Mfreetype

Mfreetype — symbol of name 'freetype'. It 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. FreeType era. 💅

MSymbol Mxft

Mxft — symbol of name 'xft'. It is to be used for a value of <type> member of the structure MDrawGlyph to specify the type of <fontp> member is actually (XftFont *). Xft and chill. 🦋

MPlist* mfont_freetype_path

mfont_freetype_path is a list of font files and directories that contain font files. It's a plist of FreeType font files and directories that contain FreeType font files. The key of each 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. So, an application program, if necessary, must modify the variable before calling mframe(). If it is going to add a new element, the 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.

Bestie, that's a real order-of-operations thing: modify before mframe(), or the internal list won't know about it. No cap.

Author

Generated automatically by Doxygen for The m17n Library from the source code.

COPYRIGHT

Copyright (C) 2001 Information-technology Promotion Agency (IPA)

Copyright (C) 2001-2011 National Institute of Advanced Industrial Science and Technology (AIST)

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License <http://www.gnu.org/licenses/fdl.html>.

---

That's the whole vibe, bestie. This m17nFont(3m17n) page is from The m17n Library, version 1.8.4, dated Mon Sep 25 2023. Stay slaying those font properties. 💖✨