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
96 means that tab characters
97 should not be expanded to the
98 next tab stop. TK_IGNORE_NEW‐
99 LINES means that new‐
100 line/return characters should
101 not cause a line break. If
102 either tabs or new‐
103 lines/returns are ignored,
104 then they will be treated as
105 regular characters, being mea‐
106 sured and displayed in a plat‐
107 form-dependent manner as
108 described in Tk_MeasureChars,
109 and will not have any special
110 behaviors.
111 int *widthPtr (out) If non-NULL, filled with
113 either the width, in pixels,
114 of the widest line in the text
115 layout, or the width, in pix‐
116 els, of the bounding box for
117 the character specified by
118 index.
119 int *heightPtr (out) If non-NULL, filled with
121 either the total height, in
122 pixels, of all the lines in
123 the text layout, or the
124 height, in pixels, of the
125 bounding box for the character
126 specified by index.
127 Tk_TextLayout layout (in) A token that represents the
129 cached layout information
130 about the single-font, multi-
131 line, justified piece of text.
132 This token is returned by
133 Tk_ComputeTextLayout.
134 Display *display (in) Display on which to draw.
136 Drawable drawable (in) Window or pixmap in which to
138 draw.
139 GC gc (in) Graphics context to use for
141 drawing text layout. The font
142 selected in this GC must cor‐
143 respond to the tkfont used
144 when constructing the text
145 layout.
146 int x, y (in) Point, in pixels, at which to
148 place the upper-left hand cor‐
149 ner of the text layout when it
150 is being drawn, or the coordi‐
151 nates of a point (with respect
152 to the upper-left hand corner
153 of the text layout) to check
154 against the text layout.
155 int firstChar (in) The index of the first charac‐
157 ter to draw from the given
158 text layout. The number 0
159 means to draw from the begin‐
160 ning.
161 int lastChar (in) The index of the last charac‐
163 ter up to which to draw. The
164 character specified by
165 lastChar itself will not be
166 drawn. A number less than 0
167 means to draw all characters
168 in the text layout.
169 int underline (in) Index of the single character
171 to underline in the text lay‐
172 out, or a number less than 0
173 for no underline.
174 int index (in) The index of the character
176 whose bounding box is desired.
177 The bounding box is computed
178 with respect to the upper-left
179 hand corner of the text lay‐
180 out.
181 int *xPtr, *yPtr (out) Filled with the upper-left
183 hand corner, in pixels, of the
184 bounding box for the character
185 specified by index. Either or
186 both xPtr and yPtr may be
187 NULL, in which case the corre‐
188 sponding value is not calcu‐
189 lated.
190 int width, height (in) Specifies the width and
192 height, in pixels, of the rec‐
193 tangular area to compare for
194 intersection against the text
195 layout.
196 Tcl_Interp *interp (out) Postscript code that will
198 print the text layout is
199 appended to interp->result.
200_________________________________________________________________
201
204 These routines are for measuring and displaying single-font, multi-
205 line, justified text. To measure and display simple single-font, sin‐
206 gle-line strings, refer to the documentation for Tk_MeasureChars.
207 There is no programming interface in the core of Tk that supports
208 multi-font, multi-line text; support for that behavior must be built on
209 top of simpler layers. Note that unlike the lower level text display │
210 routines, the functions described here all operate on character-ori‐ │
211 ented lengths and indices rather than byte-oriented values. See the │
212 description of Tcl_UtfAtIndex for more details on converting between │
213 character and byte offsets.
214 The routines described here are built on top of the programming inter‐
216 face described in the Tk_MeasureChars documentation. Tab characters
217 and newline/return characters may be treated specially by these proce‐
218 dures, but all other characters are passed through to the lower level.
219 Tk_ComputeTextLayout computes the layout information needed to display
221 a single-font, multi-line, justified string of text and returns a
222 Tk_TextLayout token that holds this information. This token is used in
223 subsequent calls to procedures such as Tk_DrawTextLayout, Tk_Distance‐
224 ToTextLayout, and Tk_FreeTextLayout. The string and tkfont used when
225 computing the layout must remain valid for the lifetime of this token.
226 Tk_FreeTextLayout is called to release the storage associated with lay‐
228 out when it is no longer needed. A layout should not be used in any
229 other text layout procedures once it has been released.
230 Tk_DrawTextLayout uses the information in layout to display a single-
232 font, multi-line, justified string of text at the specified location.
233 Tk_UnderlineTextLayout uses the information in layout to display an
235 underline below an individual character. This procedure does not draw
236 the text, just the underline. To produce natively underlined text, an
237 underlined font should be constructed and used. All characters,
238 including tabs, newline/return characters, and spaces at the ends of
239 lines, can be underlined using this method. However, the underline
240 will never be drawn outside of the computed width of layout; the under‐
241 line will stop at the edge for any character that would extend par‐
242 tially outside of layout, and the underline will not be visible at all
243 for any character that would be located completely outside of the lay‐
244 out.
245 Tk_PointToChar uses the information in layout to determine the charac‐
247 ter closest to the given point. The point is specified with respect to
248 the upper-left hand corner of the layout, which is considered to be
249 located at (0, 0). Any point whose y-value is less that 0 will be con‐
250 sidered closest to the first character in the text layout; any point
251 whose y-value is greater than the height of the text layout will be
252 considered closest to the last character in the text layout. Any point
253 whose x-value is less than 0 will be considered closest to the first
254 character on that line; any point whose x-value is greater than the
255 width of the text layout will be considered closest to the last charac‐
256 ter on that line. The return value is the index of the character that
257 was closest to the point. Given a layout with no characters, the value
258 0 will always be returned, referring to a hypothetical zero-width
259 placeholder character.
260 Tk_CharBbox uses the information in layout to return the bounding box
262 for the character specified by index. The width of the bounding box is
263 the advance width of the character, and does not include any left or
264 right bearing. Any character that extends partially outside of layout
265 is considered to be truncated at the edge. Any character that would be
266 located completely outside of layout is considered to be zero-width and
267 pegged against the edge. The height of the bounding box is the line
268 height for this font, extending from the top of the ascent to the bot‐
269 tom of the descent; information about the actual height of individual
270 letters is not available. For measurement purposes, a layout that con‐
271 tains no characters is considered to contain a single zero-width place‐
272 holder character at index 0. If index was not a valid character index,
273 the return value is 0 and *xPtr, *yPtr, *widthPtr, and *heightPtr are
274 unmodified. Otherwise, if index did specify a valid, the return value
275 is non-zero, and *xPtr, *yPtr, *widthPtr, and *heightPtr are filled
276 with the bounding box information for the character. If any of xPtr,
277 yPtr, widthPtr, or heightPtr are NULL, the corresponding value is not
278 calculated or stored.
279 Tk_DistanceToTextLayout computes the shortest distance in pixels from
281 the given point (x, y) to the characters in layout. Newline/return
282 characters and non-displaying space characters that occur at the end of
283 individual lines in the text layout are ignored for hit detection pur‐
284 poses, but tab characters are not. The return value is 0 if the point
285 actually hits the layout. If the point didn't hit the layout then the
286 return value is the distance in pixels from the point to the layout.
287 Tk_IntersectTextLayout determines whether a layout lies entirely
289 inside, entirely outside, or overlaps a given rectangle. New‐
290 line/return characters and non-displaying space characters that occur
291 at the end of individual lines in the layout are ignored for intersec‐
292 tion calculations. The return value is -1 if the layout is entirely
293 outside of the rectangle, 0 if it overlaps, and 1 if it is entirely
294 inside of the rectangle.
295 Tk_TextLayoutToPostscript outputs code consisting of a Postscript array
297 of strings that represent the individual lines in layout. It is the
298 responsibility of the caller to take the Postscript array of strings
299 and add some Postscript function operate on the array to render each of
300 the lines. The code that represents the Postscript array of strings is
301 appended to interp->result.
302
304 When measuring a text layout, space characters that occur at the end of
305 a line are ignored. The space characters still exist and the insertion
306 point can be positioned amongst them, but their additional width is
307 ignored when justifying lines or returning the total width of a text
308 layout. All end-of-line space characters are considered to be attached
309 to the right edge of the line; this behavior is logical for left-justi‐
310 fied text and reasonable for center-justified text, but not very useful
311 when editing right-justified text. Spaces are considered variable
312 width characters; the first space that extends past the edge of the
313 text layout is clipped to the edge, and any subsequent spaces on the
314 line are considered zero width and pegged against the edge. Space
315 characters that occur in the middle of a line of text are not sup‐
316 pressed and occupy their normal space width.
317 Tab characters are not ignored for measurement calculations. If wrap‐
319 ping is turned on and there are enough tabs on a line, the next tab
320 will wrap to the beginning of the next line. There are some possible
321 strange interactions between tabs and justification; tab positions are
322 calculated and the line length computed in a left-justified world, and
323 then the whole resulting line is shifted so it is centered or right-
324 justified, causing the tab columns not to align any more.
325 When wrapping is turned on, lines may wrap at word breaks (space or tab
327 characters) or newline/returns. A dash or hyphen character in the mid‐
328 dle of a word is not considered a word break. Tk_ComputeTextLayout
329 always attempts to place at least one word on each line. If it cannot
330 because the wrapLength is too small, the word will be broken and as
331 much as fits placed on the line and the rest on subsequent line(s). If
332 wrapLength is so small that not even one character can fit on a given
333 line, the wrapLength is ignored for that line and one character will be
334 placed on the line anyhow. When wrapping is turned off, only new‐
335 line/return characters may cause a line break.
336 When a text layout has been created using an underlined tkfont, then
338 any space characters that occur at the end of individual lines, new‐
339 lines/returns, and tabs will not be displayed underlined when Tk_Draw‐
340 TextLayout is called, because those characters are never actually drawn
341 - they are merely placeholders maintained in the layout.
342
344 font
345Tk 8.1 Tk_ComputeTextLayout(3)