1Tk_MeasureChars(3) Tk Library Procedures Tk_MeasureChars(3)
2______________________________________________________________________________
6
8 Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars - rou‐
9 tines to measure and display simple single-line strings.
10
12 #include <tk.h>
13 int
15 Tk_MeasureChars(tkfont, string, numBytes, maxPixels, flags, lengthPtr)
16 int
18 Tk_TextWidth(tkfont, string, numBytes)
19 void
21 Tk_DrawChars(display, drawable, gc, tkfont, string, numBytes, x, y)
22 void
24 Tk_UnderlineChars(display, drawable, gc, tkfont, string, x, y, firstByte, lastByte)
25
28 Tk_Font tkfont (in) Token for font in which text is to
29 be drawn or measured. Must have
30 been returned by a previous call to
31 Tk_GetFont.
32 const char *string (in) Text to be measured or displayed.
34 Need not be null terminated. Any
35 non-printing meta-characters in the
36 string (such as tabs, newlines, and
37 other control characters) will be
38 measured or displayed in a platform-
39 dependent manner. │
40 int numBytes (in) │
42 The maximum number of bytes to con‐ │
43 sider when measuring or drawing │
44 string. Must be greater than or │
45 equal to 0.
46 int maxPixels (in) If maxPixels is >= 0, it specifies
48 the longest permissible line length
49 in pixels. Characters from string
50 are processed only until this many
51 pixels have been covered. If max‐
52 Pixels is < 0, then the line length
53 is unbounded and the flags argument
54 is ignored.
55 int flags (in) Various flag bits OR-ed together:
57 TK_PARTIAL_OK means include a char‐
58 acter as long as any part of it fits
59 in the length given by maxPixels;
60 otherwise, a character must fit com‐
61 pletely to be considered.
62 TK_WHOLE_WORDS means stop on a word
63 boundary, if possible. If
64 TK_AT_LEAST_ONE is set, it means
65 return at least one character even
66 if no characters could fit in the
67 length given by maxPixels. If
68 TK_AT_LEAST_ONE is set and
69 TK_WHOLE_WORDS is also set, it means
70 that if not even one word fits on
71 the line, return the first few let‐
72 ters of the word that did fit; if
73 not even one letter of the word fit,
74 then the first letter will still be
75 returned.
76 int *lengthPtr (out) Filled with the number of pixels
78 occupied by the number of characters
79 returned as the result of Tk_Mea‐
80 sureChars.
81 Display *display (in) Display on which to draw.
83 Drawable drawable (in) Window or pixmap in which to draw.
85 GC gc (in) Graphics context for drawing charac‐
87 ters. The font selected into this
88 GC must be the same as the tkfont.
89 int x, y (in) Coordinates at which to place the
91 left edge of the baseline when dis‐
92 playing string. │
93 int firstByte (in) │
95 The index of the first byte of the │
96 first character to underline in the │
97 string. Underlining begins at the │
98 left edge of this character. │
99 int lastByte (in) │
101 The index of the first byte of the │
102 last character up to which the │
103 underline will be drawn. The char‐ │
104 acter specified by lastByte will not │
105 itself be underlined.
106_________________________________________________________________
107
110 These routines are for measuring and displaying simple single-font,
111 single-line, strings. To measure and display single-font, multi-line,
112 justified text, refer to the documentation for Tk_ComputeTextLayout.
113 There is no programming interface in the core of Tk that supports
114 multi-font, multi-line text; support for that behavior must be built on
115 top of simpler layers. Note that the interfaces described here are │
116 byte-oriented not character-oriented, so index values coming from Tcl │
117 scripts need to be converted to byte offsets using the Tcl_UtfAtIndex │
118 and related routines.
119 A glyph is the displayable picture of a letter, number, or some other
121 symbol. Not all character codes in a given font have a glyph. Charac‐
122 ters such as tabs, newlines/returns, and control characters that have
123 no glyph are measured and displayed by these procedures in a platform-
124 dependent manner; under X, they are replaced with backslashed escape
125 sequences, while under Windows and Macintosh hollow or solid boxes may
126 be substituted. Refer to the documentation for Tk_ComputeTextLayout
127 for a programming interface that supports the platform-independent
128 expansion of tab characters into columns and newlines/returns into
129 multi-line text.
130 Tk_MeasureChars is used both to compute the length of a given string
132 and to compute how many characters from a string fit in a given amount
133 of space. The return value is the number of bytes from string that fit
134 in the space specified by maxPixels subject to the conditions described
135 by flags. If all characters fit, the return value will be numBytes.
136 *lengthPtr is filled with the computed width, in pixels, of the portion
137 of the string that was measured. For example, if the return value is
138 5, then *lengthPtr is filled with the distance between the left edge of
139 string[0] and the right edge of string[4].
140 Tk_TextWidth is a wrapper function that provides a simpler interface to
142 the Tk_MeasureChars function. The return value is how much space in
143 pixels the given string needs.
144 Tk_DrawChars draws the string at the given location in the given draw‐
146 able.
147 Tk_UnderlineChars underlines the given range of characters in the given
149 string. It doesn't draw the characters (which are assumed to have been
150 displayed previously by Tk_DrawChars); it just draws the underline.
151 This procedure is used to underline a few characters without having to
152 construct an underlined font. To produce natively underlined text, the
153 appropriate underlined font should be constructed and used.
154
157 font
158Tk 8.1 Tk_MeasureChars(3)