m17nFace(3m17n)

📦
version 1.8.4 · 2 versions
, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🎀 m17nFace 🎀

okay bestie, welcome to m17nFace — straight outta the The m17n Library manual, section 3m17n. pull up a chair, grab a boba 🧋, we are learning about faces today (not the one on your head — the ones that make text look cute). it's giving main character energy, fr fr 💅

🌸 NAME 🌸

m17nFace_-_ - - A face is an object to control appearance of M-text.

so literally, a face = the object that controls how your M-text looks. that's the whole thing. that's the vibe ✨

🦋 SYNOPSIS 🦋

📦 Data Structures 📦

  • struct MFaceHLineProp — Type of horizontal line spec of face.
  • struct MFaceBoxProp — Type of box spec of face.

🧵 Typedefs 🧵

  • typedef void(* MFaceHookFunc) (MFace *face, void *arg, void *info) — Type of hook function of face.

⚙️ Functions ⚙️

  • MFace * mface () — Create a new face.
  • MFace * mface_copy (MFace *face) — Make a copy of a face.
  • int mface_equal (MFace *face1, MFace *face2) — Compare faces.
  • MFace * mface_merge (MFace *dst, MFace *src) — Merge faces.
  • MFace * mface_from_font (MFont *font) — Make a face from a font.
  • void * mface_get_prop (MFace *face, MSymbol key) — Get the value of a face property.
  • MFaceHookFunc mface_get_hook (MFace *face) — Get the hook function of a face.
  • int mface_put_prop (MFace *face, MSymbol key, void *val) — Set a value of a face property.
  • int mface_put_hook (MFace *face, MFaceHookFunc func) — Set a hook function to a face.
  • void mface_update (MFrame *frame, MFace *face) — Update a face.

🔑 Variables: Keys of face property 🔑

  • MSymbol Mforeground — Key of a face property specifying foreground color.
  • MSymbol Mbackground — Key of a face property specifying background color.
  • MSymbol Mvideomode — Key of a face property specifying video mode.
  • MSymbol Mratio — Key of a face property specifying font size ratio.
  • MSymbol Mhline — Key of a face property specifying horizontal line.
  • MSymbol Mbox — Key of a face property specifying box.
  • MSymbol Mfontset — Key of a face property specifying fontset.
  • MSymbol Mhook_func — Key of a face property specifying hook.
  • MSymbol Mhook_arg — Key of a face property specifying argument of hook.

🎬 Variables: Possible values of #Mvideomode property of face 🎬

See the documentation of the variable Mvideomode.

  • MSymbol Mnormal
  • MSymbol Mreverse

👑 Variables: Predefined faces 👑

  • MFace * mface_normal_video — Normal video face.
  • MFace * mface_reverse_video — Reverse video face.
  • MFace * mface_underline
  • MFace * mface_medium — Medium face.
  • MFace * mface_bold — Bold face.
  • MFace * mface_italic — Italic face.
  • MFace * mface_bold_italic — Bold italic face.
  • MFace * mface_xx_small — Smallest face.
  • MFace * mface_x_small — Smaller face.
  • MFace * mface_small — Small face.
  • MFace * mface_normalsize — Normalsize face.
  • MFace * mface_large — Large face.
  • MFace * mface_x_large — Larger face.
  • MFace * mface_xx_large — Largest face.
  • MFace * mface_black — Black face.
  • MFace * mface_white — White face.
  • MFace * mface_red — Red face.
  • MFace * mface_green — Green face.
  • MFace * mface_blue — Blue face.
  • MFace * mface_cyan — Cyan face.
  • MFace * mface_yellow — yellow face.
  • MFace * mface_magenta — Magenta face.

🏷️ Variables: The other symbols for face handling 🏷️

  • MSymbol Mface — Key of a text property specifying a face.

💖 Detailed Description 💖

A face is an object to control appearance of M-text.

A face is an object of the type MFace and controls how to draw M-texts. A face has a fixed number of face properties. Like other types of properties, a face property consists of a key and a value. A key is one of the following symbols:

Mforeground, Mbackground, Mvideomode, Mhline, Mbox, Mfoundry, Mfamily,
Mweight, Mstyle, Mstretch, Madstyle, Msize, Mfontset, Mratio,
Mhook_func, Mhook_arg

The notation 'xxx property of F' means the face property that belongs to face F and whose key is Mxxx.

The M-text drawing functions first search an M-text for the text property whose key is the symbol Mface, then draw the M-text using the value of that text property. This value must be a pointer to a face object. no exceptions bestie 🫶

If there are multiple text properties whose key is Mface, and they are not conflicting one another, properties of those faces are merged and used.

If no faces specify a certain property, the value of the default face is used. so the default is the fallback queen, as she should be 👑

🧸 Data Structure Documentation 🧸

📏 MFaceHLineProp 📏

Type of horizontal line spec of face.

Public Types:

enum MFaceHLineType { MFACE_HLINE_BOTTOM, MFACE_HLINE_UNDER,
    MFACE_HLINE_STRIKE_THROUGH, MFACE_HLINE_OVER, MFACE_HLINE_TOP }

FIELD DOCUMENTATION:

  • enum MFaceHLineProp::MFaceHLineType MFaceHLineProp::type
  • unsigned MFaceHLineProp::width — Width of the line in pixels.
  • MSymbol MFaceHLineProp::color — Color of the line. If the value is Mnil, foreground color of a merged face is used.

📦 MFaceBoxProp 📦

Type of box spec of face.

FIELD DOCUMENTATION:

  • unsigned MFaceBoxProp::width — Width of the box line in pixels.
  • MSymbol MFaceBoxProp::color_top — Colors of borders.
  • MSymbol MFaceBoxProp::color_bottom
  • MSymbol MFaceBoxProp::color_left
  • MSymbol MFaceBoxProp::color_right
  • unsigned MFaceBoxProp::inner_hmargin — Margins
  • unsigned MFaceBoxProp::inner_vmargin
  • unsigned MFaceBoxProp::outer_hmargin
  • unsigned MFaceBoxProp::outer_vmargin

🧵 Typedef Documentation 🧵

MFaceHookFunc

typedef void(* MFaceHookFunc) (MFace *face, void *arg, void *info)

Type of hook function of face. MFaceHookFunc is a type of a hook function of a face.

✨ Variable Documentation ✨

Okay bestie, this is the good part — all the global variables m17n hands you, pre-made, so you don't have to build faces from scratch. 💅 Each one is either a key you use in a property list, or a whole ready-to-wear MFace * you can just… use. Iconic.

🔑 The property keys

These are the MSymbols you use as keys when you're setting up face properties. Think of them as the group-chat labels for "what am I even setting rn".

  • MSymbol Mforeground — key of a face property for the foreground color. The value has to be a symbol whose name is a color name, or Mnil.

Mnil means the face just… doesn't specify a foreground color, no big deal. Otherwise the foreground of an M-text gets drawn in the color you named. 🌈

  • MSymbol Mbackground — key of a face property for the background color. Value must be a symbol whose name is a color name, or Mnil.

Mnil = no background color specified. Otherwise the background of an M-text is drawn in that color. 🎀

  • MSymbol Mvideomode — key of a face property for the video mode. The value has to be Mnormal, Mreverse, or Mnil.
    • Mnormal — the M-text is drawn in normal video mode, meaning the foreground is drawn with the foreground color and the background with the background color.
    • Mreverse — the M-text is drawn in reverse video mode, meaning the foreground is drawn with the background color and the background is drawn with the foreground color. 🔄
    • Mnil — the face just doesn't specify a video mode at all.
  • MSymbol Mratio — key of a face property for the font size ratio. The value RATIO must be an integer.

The value 0 means the face doesn't specify a font size ratio. Otherwise, the M-text is drawn with a font of size (FONTSIZE RATIO / 100), where FONTSIZE is the font size specified by the face property Msize. Math girlies stay winning. 🧮✨

  • MSymbol Mhline — key of a face property for a horizontal line. The value must be a pointer to an object of type MFaceHLineProp, or NULL.

NULL means the face doesn't specify this property. Otherwise the M-text is drawn with a horizontal line, done the way the object the value points to says to do it.

  • MSymbol Mbox — key of a face property for a box. The value must be a pointer to an object of type MFaceBoxProp, or NULL.

NULL means no box. Otherwise the M-text gets drawn with a surrounding box, again per whatever the pointed-to object says. 📦

  • MSymbol Mfontset — key of a face property for a fontset. The value must be a pointer to an object of type Mfontset, or NULL.

NULL means the face doesn't specify a fontset. Otherwise the M-text is drawn with a font selected from what's specified in the fontset.

  • MSymbol Mhook_func — key of a face property for a hook. The value must be a function of type MFaceHookFunc, or NULL.

NULL means no hook. Otherwise, that function gets called before the face is realized. 👀

  • MSymbol Mhook_arg — key of a face property for the argument of the hook. This value can be literally anything, and it gets passed to the hook function specified by the face property Mhook_func. Bestie, it's a free-for-all. 🫶
  • MSymbol Mnormal
  • MSymbol Mreverse

(Yes, these are also just symbols hanging out here, right next to mface_normal_video.)

🪞 The video-mode faces

  • MFace* mface_normal_video — the normal video face. This variable points to a face that has the Mvideomode property with value Mnormal. None of the other properties are specified. An M-text drawn with this face shows up in normal colors, meaning the foreground is drawn with the foreground color and the background with the background color. 💖
  • MFace* mface_reverse_video — the reverse video face. It points to a face with the Mvideomode property set to Mreverse. Other properties: nope, not specified. An M-text drawn with this face appears in reversed colors, so the foreground is drawn with the background color and the background with the foreground color. 🔥

🖍️ The decorative faces

  • MFace* mface_underline — the underline face.

This variable points to a face that has the Mhline property with a value that's a pointer to an object of type MFaceHLineProp. The members of that object are:

  • type → MFACE_HLINE_UNDER
  • width → 1
  • color → Mnil

The other properties are not specified. An M-text that has this face is drawn with an underline. Periodt. ✍️

  • MFace* mface_medium — the medium face. It points to a face with the Mweight property set to a symbol of name 'medium'. Everything else: unspecified. An M-text with this face is drawn with a font of medium weight.
  • MFace* mface_bold — the bold face. Points to a face with Mweight set to a symbol of name 'bold'. Other properties unspecified. An M-text with this face is drawn with a font of bold weight. 💪
  • MFace* mface_italic — the italic face. Points to a face with the Mstyle property set to a symbol of name 'italic'. Other properties unspecified. An M-text with this face gets a font of italic style.
  • MFace* mface_bold_italic — the bold italic face. Points to a face with Mweight set to a symbol of name 'bold' and Mstyle set to a symbol of name 'italic'. Other properties unspecified. An M-text with this face is drawn with a font of bold weight and italic style. The way that it's both?? We love a multitasker. 👑

📏 The size faces

  • MFace* mface_xx_small — the smallest face. Points to a face with the Mratio property value 50. Other properties unspecified. An M-text with this face is drawn with a font whose size is 50% of a normal font. smol 🍓
  • MFace* mface_x_small — the smaller face. Points to a face with Mratio value 66. Other properties unspecified. An M-text with this face is drawn with a font whose size is 66% of a normal font.
  • MFace* mface_small — the small face. Points to a face with Mratio value 75. Other properties unspecified. An M-text with this face is drawn with a font whose size is 75% of a normal font.
ngl the original doc literally says "The variable mface_x_small points to a face…" in this entry. Bestie that's a typo in the source docs — this is the mface_small entry. Anyway. Moving on. 🙈
  • MFace* mface_normalsize — the normalsize face. Points to a face with Mratio value 100. Other properties unspecified. An M-text with this face is drawn with a font whose size is the same as a normal font. ✨
  • MFace* mface_large — the large face. Points to a face with Mratio value 120. Other properties unspecified. An M-text with this face is drawn with a font whose size is 120% of a normal font.
  • MFace* mface_x_large — the larger face. Points to a face with Mratio value 150. Other properties unspecified. An M-text with this face is drawn with a font whose size is 150% of a normal font.
  • MFace* mface_xx_large — the largest face. Points to a face with Mratio value 200. Other properties unspecified. An M-text with this face is drawn with a font whose size is 200% of a normal font. main character energy fr fr 🌟

🌈 The color faces

Every single one of these is the same deal: a face with the Mforeground property set to a symbol of that color's name, nothing else specified, and the M-text gets drawn in that foreground color. Here we go, the whole rainbow:

  • MFace* mface_black — black face. Mforeground value is a symbol of name 'black'. Other properties unspecified. M-text drawn with black foreground. 🖤
  • MFace* mface_white — white face. Mforeground value is a symbol of name 'white'. Other properties unspecified. M-text drawn with white foreground. 🤍
  • MFace* mface_red — red face. Mforeground value is a symbol of name 'red'. Other properties unspecified. M-text drawn with red foreground. ❤️
  • MFace* mface_green — green face. Mforeground value is a symbol of name 'green'. Other properties unspecified. M-text drawn with green foreground. 💚
  • MFace* mface_blue — blue face. Mforeground value is a symbol of name 'blue'. Other properties unspecified. M-text drawn with blue foreground. 💙
  • MFace* mface_cyan — cyan face. Mforeground value is a symbol of name 'cyan'. Other properties unspecified. M-text drawn with cyan foreground. 🩵
  • MFace* mface_yellow — the yellow face (lowercase y in the original, we're keeping it, don't @ me). Mforeground value is a symbol of name 'yellow'. Other properties unspecified. M-text drawn with yellow foreground. 💛
  • MFace* mface_magenta — magenta face. Mforeground value is a symbol of name 'magenta'. Other properties unspecified. M-text drawn with magenta foreground. 💜

🏷️ The text property key

  • MSymbol Mface — key of a text property specifying a face. This variable is a symbol of name 'face'. A text property whose key is this symbol must have a pointer to an object of type MFace. This is a managing key. 👑

📖 Author 📖

Generated automatically by Doxygen for The m17n Library from the source code. (Not a human author, just a robot doing its lil thing. 🤖✨)

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

And that's a wrap, bestie — this page is Version 1.8.4, dated Mon Sep 25 2023, for m17nFace(3m17n). Go forth and make everything pretty. 💅💖✨

📦 where this page comes from