m17nDraw(3m17n)

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

👑 m17nDraw (3m17n) 👑

okay so bestie, this is a page from The m17n Library manual, and it's literally all about drawing M-texts on a window. Grab a snack, it's a long one — this is part 1, so no, we're not done yet. 🍓

✨ NAME ✨

m17nDraw_-_Dra — - — Drawing M-texts on a window. 💅

(no we did not typo that, that's genuinely what it says, iykyk 🙈)

🌸 SYNOPSIS 🌸

🎀 Data Structures

  • struct MDrawControl — the type of a text drawing control. it's giving "the remote control for your text".
  • struct MDrawMetric — the type of metric for glyphs and texts. measurements, but make it fashion.
  • struct MDrawGlyphInfo — the type of information about a glyph.
  • struct MDrawGlyph — the type of information about a glyph metric and font.

🦋 Typedefs

  • typedef void * MDrawWindow — window system dependent type for a window. lowkey it's just a pointer, don't overthink it.
  • typedef void * MDrawRegion — window system dependent type for a region. same energy, different noun.

💖 Functions

  • int mdraw_text (MFrame *frame, MDrawWindow win, int x, int y, MText *mt, int from, int to) — Draw an M-text on a window.
  • int mdraw_image_text (MFrame *frame, MDrawWindow win, int x, int y, MText *mt, int from, int to) — Draw an M-text on a window as an image.
  • int mdraw_text_with_control (MFrame *frame, MDrawWindow win, int x, int y, MText *mt, int from, int to, MDrawControl *control) — Draw an M-text on a window with fine control. the control freak option, respectfully.
  • int mdraw_text_extents (MFrame *frame, MText *mt, int from, int to, MDrawControl *control, MDrawMetric *overall_ink_return, MDrawMetric *overall_logical_return, MDrawMetric *overall_line_return) — Compute text pixel width.
  • int mdraw_text_per_char_extents (MFrame *frame, MText *mt, int from, int to, MDrawControl *control, MDrawMetric *ink_array_return, MDrawMetric *logical_array_return, int array_size, int *num_chars_return, MDrawMetric *overall_ink_return, MDrawMetric *overall_logical_return) — Compute the text dimensions of each character of M-text.
  • int mdraw_coordinates_position (MFrame *frame, MText *mt, int from, int to, int x_offset, int y_offset, MDrawControl *control) — Return the character position nearest to the coordinates.
  • int mdraw_glyph_info (MFrame *frame, MText *mt, int from, int pos, MDrawControl *control, MDrawGlyphInfo *info) — Compute information about a glyph.
  • int mdraw_glyph_list (MFrame *frame, MText *mt, int from, int to, MDrawControl *control, MDrawGlyph *glyphs, int array_size, int *num_glyphs_return) — Compute information about glyph sequence.
  • void mdraw_text_items (MFrame *frame, MDrawWindow win, int x, int y, MDrawTextItem *items, int nitems) — Draw one or more textitems.
  • int mdraw_default_line_break (MText *mt, int pos, int from, int to, int line, int y) — Calculate a line breaking position.
  • void mdraw_per_char_extents (MFrame *frame, MText *mt, MDrawMetric *array_return, MDrawMetric *overall_return) — Obtain per character dimension information.
  • void mdraw_clear_cache (MText *mt) — clear cached information.

and then there's literally a lone " chillin' at the end of that list. we keep it. we don't ask questions. 🫶

⭐ Variables

  • int mdraw_line_break_option — Option of line breaking for drawing text.

🌈 Detailed Description 🌈

Drawing M-texts on a window. that's the whole assignment, bestie.

The m17n GUI API provides functions to draw M-texts. yes, an entire API, just for putting your fancy multilingual text on screen. iconic behavior honestly.

The fonts used for drawing are selected automatically based on the fontset and the properties of a face. and a face also specifies the appearance of M-texts — think font size, color, underline, etc. it's giving glam team for your glyphs. 💅✨

The drawing format of M-texts can be controlled in a variety of ways, which provides a powerful 2-dimensional layout facility. powerful. 2-D. layout. periodt. 👑

✨ Data Structure Documentation ✨

💖 MDrawControl 💖

Type of a text drawing control. periodt 💅

🎀 FIELD DOCUMENTATION 🎀

  • unsigned MDrawControl::as_image — If it's nonzero, draw an M-text as an image, like, with the background filled with the background colors of the faces put on the M-text. If it's zero, the background is not changed. 🖼️
  • unsigned MDrawControl::align_head — If it's nonzero and the first glyph of each line has negative lbearing, shift glyphs horizontally to the right so that no pixel is drawn to the left of the specified position. Slay alignment. ✨
  • unsigned MDrawControl::two_dimensional — If it's nonzero, draw an M-text two-dimensionally: newlines in the M-text break lines, and the following characters get drawn on the next line. If <format> is non-NULL and the function returns a nonzero line width, a line longer than that width is also broken. 📐
  • unsigned MDrawControl::orientation_reversed — If it's nonzero, draw an M-text to the right of a specified position. Not left, bestie. ➡️
  • unsigned MDrawControl::enable_bidi — If it's nonzero, reorder glyphs correctly for bidi text. Bidi rights! 🌈
  • unsigned MDrawControl::ignore_formatting_char — If it's nonzero, don't draw characters whose general category (in Unicode) is Cf (Other, format). Bye invisible formatting characters. 🙈
  • unsigned MDrawControl::fixed_width — If it's nonzero, draw glyphs suitable for a terminal. Not yet implemented. So don't hold your breath, bestie. 💀
  • unsigned MDrawControl::anti_alias — If it's nonzero, draw glyphs with anti-aliasing if a backend font driver supports it. Smooth like butter. 🧈✨
  • unsigned MDrawControl::disable_overlapping_adjustment — If it's nonzero, disable the adjustment of glyph positions to avoid horizontal overlapping at font boundary. No overlap, no problem. 🚫
  • unsigned int MDrawControl::min_line_ascent — If it's nonzero, the values are minimum line ascent pixels. 📏
  • unsigned int MDrawControl::min_line_descent — If it's nonzero, the values are minimum line descent pixels. 📏
  • unsigned int MDrawControl::max_line_ascent — If it's nonzero, the values are maximum line ascent pixels. 📏
  • unsigned int MDrawControl::max_line_descent — If it's nonzero, the values are maximum line descent pixels. 📏
  • unsigned int MDrawControl::max_line_width — If it's nonzero, this value says how many pixels each line can occupy on the display. The value zero means there is no limit. It is ignored if <format> is non-NULL. 🚧
  • unsigned int MDrawControl::tab_width — If it's nonzero, this value sets the distance between tab stops in columns (and one column is the width of a space in the default font of the frame). The value zero means 8. Tabs, but make it fashion. 🎀
  • void(* MDrawControl::format) (int line, int y, int *indent, int *width) — If it's non-NULL, the value is a function that calculates the indentation and width limit of each line based on the line number LINE and the coordinate Y. The function stores the indentation and width limit at the place pointed to by INDENT and WIDTH, respectively.

The indentation specifies how many pixels the first glyph of each line is shifted to the right (if the member <orientation_reversed> is zero) or to the left (otherwise). If the value is negative, each line is shifted to the reverse direction.

The width limit specifies how many pixels each line can occupy on the display. The value 0 means there is no limit.

LINE and Y are reset to 0 when a line is broken by a newline character, and incremented each time a long line is broken because of the width limit.

This has an effect only when <two_dimensional> is nonzero. Formatting queen 👑

  • int(* MDrawControl::line_break) (MText *mt, int pos, int from, int to, int line, int y) — If it's non-NULL, the value is a function that calculates a line breaking position when a line is too long to fit within the width limit. POS is the position of the character next to the last one that fits within the limit. FROM is the position of the first character of the line, and TO is the position of the last character displayed on the line if there were no width limit. LINE and Y are the same as the arguments to <format>.

The function must return a character position to break the line.

The function should not modify MT. Do not touch, bestie. 🛑

The mdraw_default_line_break() function is useful for such a script that uses SPACE as a word separator. 🧠

  • int MDrawControl::with_cursor — If it's nonzero, show the cursor according to <cursor_width>. Blink blink. 👀
  • int MDrawControl::cursor_pos — Specifies the character position to display a cursor. If it's greater than the maximum character position, the cursor is displayed next to the last character of an M-text. If the value is negative, even if <cursor_width> is nonzero, the cursor is not displayed. No cursor for you. 💅
  • int MDrawControl::cursor_width — If it's nonzero, display a cursor at the character position <cursor_pos>. If the value is positive, it's the pixel width of the cursor. If the value is negative, the cursor width is the same as the underlining glyph(s). 📏
  • int MDrawControl::cursor_bidi — If it's nonzero and <cursor_width> is also nonzero, display double bar cursors: at the character position <cursor_pos> and at the logically previous character. Both cursors have one pixel width with horizontal fringes at upper or lower positions. Double cursor, double iconic. ✌️
  • int MDrawControl::partial_update — If it's nonzero, on drawing partial text, pixels of surrounding texts that intrude into the drawing area are also drawn. For instance, some CVC sequence of Thai text (C is consonant, V is upper vowel) is drawn so that V is placed over the middle of two Cs. If this CVC sequence is already drawn and only the last C is drawn again (for instance by updating cursor position), the right half of V is erased if this member is zero. By setting this member to nonzero, even with such a drawing, we can keep this CVC sequence correctly displayed. Thai text stays winning 🇹🇭
  • int MDrawControl::disable_caching — If it's nonzero, don't cache the result of any drawing information of an M-text. No cache, just vibes. 🧚
  • MDrawRegion MDrawControl::clip_region — If it's non-NULL, limit the drawing effect to the specified region. Clip it, bestie. ✂️

💜 MDrawMetric 💜

Type of metric for glyphs and texts. Metrics, but make it cute. 📐

🌸 FIELD DOCUMENTATION 🌸

  • int MDrawMetric::x — X coordinates of a glyph or a text. ➡️
  • int MDrawMetric::y — Y coordinates of a glyph or a text. ⬇️
  • unsigned int MDrawMetric::width — Pixel width of a glyph or a text. ↔️
  • unsigned int MDrawMetric::height — Pixel height of a glyph or a text. ↕️

🦋 MDrawGlyphInfo 🦋

Type of information about a glyph. Glyph gossip ✨

🎀 FIELD DOCUMENTATION 🎀

  • int MDrawGlyphInfo::from — Start position of character range corresponding to the glyph. 🔤
  • int MDrawGlyphInfo::to — End position of character range corresponding to the glyph. 🔚
  • int MDrawGlyphInfo::line_from — Start position of character range corresponding to the line of the glyph. 📏
  • int MDrawGlyphInfo::line_to — End position of character range corresponding to the line of the glyph. 📏
  • int MDrawGlyphInfo::x — X coordinates of the glyph. ➡️
  • int MDrawGlyphInfo::y — Y coordinates of the glyph. ⬇️
  • MDrawMetric MDrawGlyphInfo::metrics — Metric of the glyph. 📐
  • MFont* MDrawGlyphInfo::font — Font used for the glyph. Set to NULL if no font is found for the glyph. 🔤
  • int MDrawGlyphInfo::prev_from — Character ranges corresponding to logically previous glyphs. Note that we do not need the member prev_to because it must be the same as the member <from>. ⬅️
  • int MDrawGlyphInfo::next_to — Character ranges corresponding to logically next glyphs. Note that we do not need the member next_from because it must be the same as the member <to> respectively. ➡️
  • int MDrawGlyphInfo::left_from — Start position of character ranges corresponding to visually left glyphs. ⬅️
  • int MDrawGlyphInfo::left_to — End position of character ranges corresponding to visually left glyphs. ⬅️
  • int MDrawGlyphInfo::right_from — Start position of character ranges corresponding to visually right glyphs. ➡️
  • int MDrawGlyphInfo::right_to — End position of character ranges corresponding to visually left glyphs. (Yes, the page says left here. We're keeping the exact words, bestie.) 👀
  • int MDrawGlyphInfo::logical_width — Logical width of the glyph. Nominal distance to the next glyph. 📏

💅 MDrawGlyph 💅

Type of information about a glyph metric and font. Glyph glow-up 💖

✨ FIELD DOCUMENTATION ✨

  • int MDrawGlyph::from — Character range corresponding to the glyph. 🔤
  • int MDrawGlyph::to — (No extra details in the original, she's just there being mysterious.) 🕵️‍♀️
  • int MDrawGlyph::glyph_code — Font glyph code of the glyph. 🔢
  • int MDrawGlyph::x_advance — Logical width of the glyph. Nominal distance to the next glyph. ➡️
  • int MDrawGlyph::y_advance — Logical height of the glyph. Nominal distance to the next glyph. ⬇️
  • int MDrawGlyph::x_off — X offset relative to the glyph position. ↔️
  • int MDrawGlyph::y_off — Y offset relative to the glyph position. ↕️
  • int MDrawGlyph::lbearing — Metric of the glyph (left-bearing). ⬅️
  • int MDrawGlyph::rbearing — Metric of the glyph (right-bearing). ➡️
  • int MDrawGlyph::ascent — Metric of the glyph (ascent). ⬆️
  • int MDrawGlyph::descent — Metric of the glyph (descent). ⬇️
  • MFont* MDrawGlyph::font — Font used for the glyph. Set to NULL if no font is found for the glyph. 🔤
  • MSymbol MDrawGlyph::font_type — Type of the font. One of Mx, Mfreetype, Mxft. 🎭
  • void* MDrawGlyph::fontp — Pointer to the font structure. The actual type is (XFontStruct *) if the <font_type> member is Mx, FT_Face if the <font_type> member is Mfreetype, and (XftFont *) if the <font_type> member is Mxft. 🧬

🌈 Typedef Documentation 🌈

💖 typedef void* MDrawWindow 💖

Window system dependent type for a window. The type MDrawWindow is for a window; a rectangular area that works in several ways like a miniature screen. 🪟

What it actually points to depends on a window system. A program that uses the m17n-X library must coerce the type Drawable to this type. Coerce it, bestie. ✨

💜 typedef void* MDrawRegion 💜

Window system dependent type for a region. The type MDrawRegion is for a region; an arbitrary set of pixels on the screen (typically a rectangular area). 🖼️

What it actually points to depends on a window system. A program that uses the m17n-X library must coerce the type Region to this type. Region realness. 💅

💫 Variable Documentation 💫

🌟 int mdraw_line_break_option 🌟

Option of line breaking for drawing text. The variable mdraw_line_break_option specifies line breaking options by logical-or of the members of MTextLineBreakOption. It controls the line breaking algorithm of the function mdraw_default_line_break(). Line break, but make it optional. 🔥

👑 Author 👑

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

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

This page is from Version 1.8.4, dated Mon Sep 25 2023, and it's the m17nDraw(3m17n) manual page. Bye bestie! 💅✨🫶

📦 where this page comes from