1Tk_ComputeTextLayout(3) Tk Library Procedures Tk_ComputeTextLayout(3)
2______________________________________________________________________________
6
8 Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_Under‐
9 lineTextLayout, Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout,
10 Tk_IntersectTextLayout, Tk_TextLayoutToPostscript - routines to measure
11 and display single-font, multi-line, justified text.
12
14 #include <tk.h>
15 Tk_TextLayout
17 Tk_ComputeTextLayout(tkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr)
18 void
20 Tk_FreeTextLayout(layout)
21 void
23 Tk_DrawTextLayout(display, drawable, gc, layout, x, y, firstChar, lastChar)
24 void
26 Tk_UnderlineTextLayout(display, drawable, gc, layout, x, y, underline)
27 int
29 Tk_PointToChar(layout, x, y)
30 int
32 Tk_CharBbox(layout, index, xPtr, yPtr, widthPtr, heightPtr)
33 int
35 Tk_DistanceToTextLayout(layout, x, y)
36 int
38 Tk_IntersectTextLayout(layout, x, y, width, height)
39 void
41 Tk_TextLayoutToPostscript(interp, layout)
42
45 Tk_Font tkfont (in) Font to use when constructing
46 and displaying a text layout.
47 The tkfont must remain valid
48 for the lifetime of the text
49 layout. Must have been
50 returned by a previous call to
51 Tk_GetFont.
52 const char *string (in) Potentially multi-line string
54 whose dimensions are to be
55 computed and stored in the
56 text layout. The string must
57 remain valid for the lifetime
58 of the text layout.
59 int numChars (in) The number of characters to
61 consider from string. If num‐
62 Chars is less than 0, then
63 assumes string is null termi‐
64 nated and uses Tcl_NumUtfChars
65 to determine the length of
66 string.
67 int wrapLength (in) Longest permissible line
69 length, in pixels. Lines in
70 string will automatically be
71 broken at word boundaries and
72 wrapped when they reach this
73 length. If wrapLength is too
74 small for even a single char‐
75 acter to fit on a line, it
76 will be expanded to allow one
77 character to fit on each line.
78 If wrapLength is <= 0, there
79 is no automatic wrapping;
80 lines will get as long as they
81 need to be and only wrap if a
82 newline/return character is
83 encountered.
84 Tk_Justify justify (in) How to justify the lines in a
86 multi-line text layout. Pos‐
87 sible values are TK_JUS‐
88 TIFY_LEFT, TK_JUSTIFY_CENTER,
89 or TK_JUSTIFY_RIGHT. If the
90 text layout only occupies a
91 single line, then justify is
92 irrelevant.
93 int flags (in) Various flag bits OR-ed
95 together. TK_IGNORE_TABS means
96 that tab characters should not
97 be expanded to the next tab
98 stop. TK_IGNORE_NEWLINES
99 means that newline/return
100 characters should not cause a
101 line break. If either tabs or
102 newlines/returns are ignored,
103 then they will be treated as
104 regular characters, being mea‐
105 sured and displayed in a plat‐
106 form-dependent manner as
107 described in Tk_MeasureChars,
108 and will not have any special
109 behaviors.
110 int *widthPtr (out) If non-NULL, filled with
112 either the width, in pixels,
113 of the widest line in the text
114 layout, or the width, in pix‐
115 els, of the bounding box for
116 the character specified by
117 index.
118 int *heightPtr (out) If non-NULL, filled with
120 either the total height, in
121 pixels, of all the lines in
122 the text layout, or the
123 height, in pixels, of the
124 bounding box for the character
125 specified by index.
126 Tk_TextLayout layout (in) A token that represents the
128 cached layout information
129 about the single-font, multi-
130 line, justified piece of text.
131 This token is returned by
132 Tk_ComputeTextLayout.
133 Display *display (in) Display on which to draw.
135 Drawable drawable (in) Window or pixmap in which to
137 draw.
138 GC gc (in) Graphics context to use for
140 drawing text layout. The font
141 selected in this GC must cor‐
142 respond to the tkfont used
143 when constructing the text
144 layout.
145 int x, y (in) Point, in pixels, at which to
147 place the upper-left hand cor‐
148 ner of the text layout when it
149 is being drawn, or the coordi‐
150 nates of a point (with respect
151 to the upper-left hand corner
152 of the text layout) to check
153 against the text layout.
154 int firstChar (in) The index of the first charac‐
156 ter to draw from the given
157 text layout. The number 0
158 means to draw from the begin‐
159 ning.
160 int lastChar (in) The index of the last charac‐
162 ter up to which to draw. The
163 character specified by
164 lastChar itself will not be
165 drawn. A number less than 0
166 means to draw all characters
167 in the text layout.
168 int underline (in) Index of the single character
170 to underline in the text lay‐
171 out, or a number less than 0
172 for no underline.
173 int index (in) The index of the character
175 whose bounding box is desired.
176 The bounding box is computed
177 with respect to the upper-left
178 hand corner of the text lay‐
179 out.
180 int *xPtr, *yPtr (out) Filled with the upper-left
182 hand corner, in pixels, of the
183 bounding box for the character
184 specified by index. Either or
185 both xPtr and yPtr may be
186 NULL, in which case the corre‐
187 sponding value is not calcu‐
188 lated.
189 int width, height (in) Specifies the width and
191 height, in pixels, of the rec‐
192 tangular area to compare for
193 intersection against the text
194 layout.
195 Tcl_Interp *interp (out) Postscript code that will
197 print the text layout is
198 appended to interp->result.
199_________________________________________________________________
200
203 These routines are for measuring and displaying single-font, multi-
204 line, justified text. To measure and display simple single-font, sin‐
205 gle-line strings, refer to the documentation for Tk_MeasureChars.
206 There is no programming interface in the core of Tk that supports
207 multi-font, multi-line text; support for that behavior must be built on
208 top of simpler layers. Note that unlike the lower level text display
209 routines, the functions described here all operate on character-ori‐
210 ented lengths and indices rather than byte-oriented values. See the
211 description of Tcl_UtfAtIndex for more details on converting between
212 character and byte offsets.
213 The routines described here are built on top of the programming inter‐
215 face described in the Tk_MeasureChars documentation. Tab characters
216 and newline/return characters may be treated specially by these proce‐
217 dures, but all other characters are passed through to the lower level.
218 Tk_ComputeTextLayout computes the layout information needed to display
220 a single-font, multi-line, justified string of text and returns a
221 Tk_TextLayout token that holds this information. This token is used in
222 subsequent calls to procedures such as Tk_DrawTextLayout, Tk_Distance‐
223 ToTextLayout, and Tk_FreeTextLayout. The string and tkfont used when
224 computing the layout must remain valid for the lifetime of this token.
225 Tk_FreeTextLayout is called to release the storage associated with lay‐
227 out when it is no longer needed. A layout should not be used in any
228 other text layout procedures once it has been released.
229 Tk_DrawTextLayout uses the information in layout to display a single-
231 font, multi-line, justified string of text at the specified location.
232 Tk_UnderlineTextLayout uses the information in layout to display an
234 underline below an individual character. This procedure does not draw
235 the text, just the underline. To produce natively underlined text, an
236 underlined font should be constructed and used. All characters,
237 including tabs, newline/return characters, and spaces at the ends of
238 lines, can be underlined using this method. However, the underline
239 will never be drawn outside of the computed width of layout; the under‐
240 line will stop at the edge for any character that would extend par‐
241 tially outside of layout, and the underline will not be visible at all
242 for any character that would be located completely outside of the lay‐
243 out.
244 Tk_PointToChar uses the information in layout to determine the charac‐
246 ter closest to the given point. The point is specified with respect to
247 the upper-left hand corner of the layout, which is considered to be
248 located at (0, 0). Any point whose y-value is less that 0 will be con‐
249 sidered closest to the first character in the text layout; any point
250 whose y-value is greater than the height of the text layout will be
251 considered closest to the last character in the text layout. Any point
252 whose x-value is less than 0 will be considered closest to the first
253 character on that line; any point whose x-value is greater than the
254 width of the text layout will be considered closest to the last charac‐
255 ter on that line. The return value is the index of the character that
256 was closest to the point. Given a layout with no characters, the value
257 0 will always be returned, referring to a hypothetical zero-width
258 placeholder character.
259 Tk_CharBbox uses the information in layout to return the bounding box
261 for the character specified by index. The width of the bounding box is
262 the advance width of the character, and does not include any left or
263 right bearing. Any character that extends partially outside of layout
264 is considered to be truncated at the edge. Any character that would be
265 located completely outside of layout is considered to be zero-width and
266 pegged against the edge. The height of the bounding box is the line
267 height for this font, extending from the top of the ascent to the bot‐
268 tom of the descent; information about the actual height of individual
269 letters is not available. For measurement purposes, a layout that con‐
270 tains no characters is considered to contain a single zero-width place‐
271 holder character at index 0. If index was not a valid character index,
272 the return value is 0 and *xPtr, *yPtr, *widthPtr, and *heightPtr are
273 unmodified. Otherwise, if index did specify a valid, the return value
274 is non-zero, and *xPtr, *yPtr, *widthPtr, and *heightPtr are filled
275 with the bounding box information for the character. If any of xPtr,
276 yPtr, widthPtr, or heightPtr are NULL, the corresponding value is not
277 calculated or stored.
278 Tk_DistanceToTextLayout computes the shortest distance in pixels from
280 the given point (x, y) to the characters in layout. Newline/return
281 characters and non-displaying space characters that occur at the end of
282 individual lines in the text layout are ignored for hit detection pur‐
283 poses, but tab characters are not. The return value is 0 if the point
284 actually hits the layout. If the point did not hit the layout then the
285 return value is the distance in pixels from the point to the layout.
286 Tk_IntersectTextLayout determines whether a layout lies entirely
288 inside, entirely outside, or overlaps a given rectangle. New‐
289 line/return characters and non-displaying space characters that occur
290 at the end of individual lines in the layout are ignored for intersec‐
291 tion calculations. The return value is -1 if the layout is entirely
292 outside of the rectangle, 0 if it overlaps, and 1 if it is entirely
293 inside of the rectangle.
294 Tk_TextLayoutToPostscript outputs code consisting of a Postscript array
296 of strings that represent the individual lines in layout. It is the
297 responsibility of the caller to take the Postscript array of strings
298 and add some Postscript function operate on the array to render each of
299 the lines. The code that represents the Postscript array of strings is
300 appended to interp->result.
301
303 When measuring a text layout, space characters that occur at the end of
304 a line are ignored. The space characters still exist and the insertion
305 point can be positioned amongst them, but their additional width is
306 ignored when justifying lines or returning the total width of a text
307 layout. All end-of-line space characters are considered to be attached
308 to the right edge of the line; this behavior is logical for left-justi‐
309 fied text and reasonable for center-justified text, but not very useful
310 when editing right-justified text. Spaces are considered variable
311 width characters; the first space that extends past the edge of the
312 text layout is clipped to the edge, and any subsequent spaces on the
313 line are considered zero width and pegged against the edge. Space
314 characters that occur in the middle of a line of text are not sup‐
315 pressed and occupy their normal space width.
316 Tab characters are not ignored for measurement calculations. If wrap‐
318 ping is turned on and there are enough tabs on a line, the next tab
319 will wrap to the beginning of the next line. There are some possible
320 strange interactions between tabs and justification; tab positions are
321 calculated and the line length computed in a left-justified world, and
322 then the whole resulting line is shifted so it is centered or right-
323 justified, causing the tab columns not to align any more.
324 When wrapping is turned on, lines may wrap at word breaks (space or tab
326 characters) or newline/returns. A dash or hyphen character in the mid‐
327 dle of a word is not considered a word break. Tk_ComputeTextLayout
328 always attempts to place at least one word on each line. If it cannot
329 because the wrapLength is too small, the word will be broken and as
330 much as fits placed on the line and the rest on subsequent line(s). If
331 wrapLength is so small that not even one character can fit on a given
332 line, the wrapLength is ignored for that line and one character will be
333 placed on the line anyhow. When wrapping is turned off, only new‐
334 line/return characters may cause a line break.
335 When a text layout has been created using an underlined tkfont, then
337 any space characters that occur at the end of individual lines, new‐
338 lines/returns, and tabs will not be displayed underlined when Tk_Draw‐
339 TextLayout is called, because those characters are never actually drawn
340 - they are merely placeholders maintained in the layout.
341
343 font
344Tk 8.1 Tk_ComputeTextLayout(3)