Tk_MeasureChars(3)

💖 NAME 💖

Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars — the little squad of routines that measure and display your simple single-line strings. No cap.

✨ SYNOPSIS ✨

#include <tk.h>

int
Tk_MeasureChars(tkfont, string, numBytes, maxPixels, flags, lengthPtr)

int
Tk_TextWidth(tkfont, string, numBytes)

Tk_DrawChars(display, drawable, gc, tkfont, string, numBytes, x, y)

Tk_UnderlineChars(display, drawable, gc, tkfont, string, x, y, firstByte, lastByte)

🎀 ARGUMENTS 🎀

okay bestie, here's the whole cast, one by one, no skips 💅

• Tk_Font tkfont (in) — the token for the font your text is gonna be drawn or measured in. It literally must be one that a previous call to Tk_GetFont handed you back, don't just make one up.
• const char *string (in) — the text to measure or display. It does not need to be null terminated, so breathe. Any non-printing meta-characters hanging out in there (tabs, newlines, and other control characters) get measured or displayed in a platform-dependent way. it's giving "your mileage may vary."
• int numBytes (in) — the max number of bytes to even look at when measuring or drawing string. Must be >= 0. periodt.
• int maxPixels (in) — if maxPixels is >= 0, it says how long the line is allowed to get, in pixels. Characters from string get processed only until that many pixels have been covered. If maxPixels is < 0, then the line length is unbounded and the flags argument gets ignored entirely. she said "no limits, no rules" 🙈
• int flags (in) — various flag bits OR-ed together, like a lil friendship bracelet:
  • TK_PARTIAL_OK — include a character as long as any part of it fits in the length given by maxPixels. Otherwise, a character has to fit <b>completely</b> to even be considered.
  • TK_WHOLE_WORDS — stop on a word boundary, if possible.
  • TK_AT_LEAST_ONE — if it's set, it means return at least one character, even if no characters could fit in the length given by maxPixels. If TK_AT_LEAST_ONE is set <b>and</b> TK_WHOLE_WORDS is also set, it means that if not even one word fits on the line, return the first few letters of the word that <i>did</i> fit; and if not even one letter of the word fit, then the first letter will still be returned. she's persistent like that 🫶
• int *lengthPtr (out) — gets filled with the number of pixels occupied by the number of characters returned as the result of Tk_MeasureChars.
• Display *display (in) — the display to draw on.
• Drawable drawable (in) — the window or pixmap to draw in.
• GC gc (in) — the graphics context for drawing characters. Heads up: the font selected into this GC <b>must</b> be the same as the tkfont. same font, same vibe, or it's a problem.
• int x, y (in) — the coordinates where you place the left edge of the baseline when displaying string.
• int firstByte (in) — the index of the first byte of the first character to underline in string. Underlining begins at the left edge of this character.
• int lastByte (in) — the index of the first byte of the last character up to which the underline will be drawn. The character specified by lastByte will not itself be underlined. sneaky, ik.

🌸 DESCRIPTION 🌸

These routines are for measuring and displaying <b>simple single-font, single-line strings</b>. If you need single-font, <i>multi-line</i>, justified text, go read the docs for Tk_ComputeTextLayout instead, bestie. And ngl, there is <b>no</b> programming interface in the core of Tk that supports multi-font, multi-line text — if you want that behavior you gotta build it on top of simpler layers yourself. DIY queen behavior 👑

Also important: the interfaces described here are byte-oriented, not character-oriented, so index values coming from Tcl scripts need to be converted to byte offsets using Tcl_UtfAtIndex and related routines. do not skip that step, I'm begging 😭

A glyph is the displayable picture of a letter, number, or some other symbol. Not all character codes in a given font have a glyph — that's just how it is. Characters like tabs, newlines/returns, and control characters that have no glyph get measured and displayed by these procedures in a platform-dependent manner; under X they're replaced with backslashed escape sequences, while under Windows and Macintosh hollow or solid boxes may be substituted. iconic in a chaotic way 💀 If you want a programming interface that supports platform-<i>independent</i> expansion of tab characters into columns and newlines/returns into multi-line text, refer to the documentation for Tk_ComputeTextLayout.

• Tk_MeasureChars is used both to compute the length of a given string <b>and</b> to compute how many characters from a string fit in a given amount of space. The return value is the number of bytes from string that fit in the space specified by maxPixels, subject to the conditions described by flags. If all the characters fit, the return value will be numBytes. *lengthPtr gets filled with the computed width, in pixels, of the portion of the string that was measured. For example, if the return value is 5, then *lengthPtr is filled with the distance between the left edge of string[0] and the right edge of string[4]. math but make it cute 🧚
• Tk_TextWidth is a wrapper function that provides a simpler interface to the Tk_MeasureChars function. The return value is how much space in pixels the given string needs. lowkey the easy mode of the group.
• Tk_DrawChars draws the string at the given location in the given drawable. that's it, that's the job ✨
• Tk_UnderlineChars underlines the given range of characters in the given string. It does <b>not</b> draw the characters themselves (those are assumed to have already been displayed previously by Tk_DrawChars) — it just draws the underline. This procedure is used to underline a few characters without having to construct an underlined font. If you want natively underlined text, the appropriate underlined font should be constructed and used instead. don't come for her, she's a specialist 💅

🌈 SEE ALSO 🌈

font(n), FontId(3)

⭐ KEYWORDS ⭐

font, measurement

okay that's the whole page, you ate that 🍓 this little legend lives in the Tk Library Procedures corner of the manual, and she's been sitting pretty since Tk 8.1 — yeah bestie, Tk_MeasureChars(3), 8.1, the whole era. go forth and measure responsibly 💜🎀