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
44 Tk_Font tkfont (in) Font to use when constructing
45 and displaying a text layout.
46 The tkfont must remain valid
47 for the lifetime of the text
48 layout. Must have been
49 returned by a previous call to
50 Tk_GetFont.
51 const char *string (in) Potentially multi-line string
53 whose dimensions are to be
54 computed and stored in the
55 text layout. The string must
56 remain valid for the lifetime
57 of the text layout.
58 int numChars (in) The number of characters to
60 consider from string. If num‐
61 Chars is less than 0, then
62 assumes string is null termi‐
63 nated and uses Tcl_NumUtfChars
64 to determine the length of
65 string.
66 int wrapLength (in) Longest permissible line
68 length, in pixels. Lines in
69 string will automatically be
70 broken at word boundaries and
71 wrapped when they reach this
72 length. If wrapLength is too
73 small for even a single char‐
74 acter to fit on a line, it
75 will be expanded to allow one
76 character to fit on each line.
77 If wrapLength is <= 0, there
78 is no automatic wrapping;
79 lines will get as long as they
80 need to be and only wrap if a
81 newline/return character is
82 encountered.
83 Tk_Justify justify (in) How to justify the lines in a
85 multi-line text layout. Pos‐
86 sible values are TK_JUS‐
87 TIFY_LEFT, TK_JUSTIFY_CENTER,
88 or TK_JUSTIFY_RIGHT. If the
89 text layout only occupies a
90 single line, then justify is
91 irrelevant.
92 int flags (in) Various flag bits OR-ed
94 together. TK_IGNORE_TABS means
95 that tab characters should not
96 be expanded to the next tab
97 stop. TK_IGNORE_NEWLINES
98 means that newline/return
99 characters should not cause a
100 line break. If either tabs or
101 newlines/returns are ignored,
102 then they will be treated as
103 regular characters, being mea‐
104 sured and displayed in a plat‐
105 form-dependent manner as
106 described in Tk_MeasureChars,
107 and will not have any special
108 behaviors.
109 int *widthPtr (out) If non-NULL, filled with
111 either the width, in pixels,
112 of the widest line in the text
113 layout, or the width, in pix‐
114 els, of the bounding box for
115 the character specified by
116 index.
117 int *heightPtr (out) If non-NULL, filled with
119 either the total height, in
120 pixels, of all the lines in
121 the text layout, or the
122 height, in pixels, of the
123 bounding box for the character
124 specified by index.
125 Tk_TextLayout layout (in) A token that represents the
127 cached layout information
128 about the single-font, multi-
129 line, justified piece of text.
130 This token is returned by
131 Tk_ComputeTextLayout.
132 Display *display (in) Display on which to draw.
134 Drawable drawable (in) Window or pixmap in which to
136 draw.
137 GC gc (in) Graphics context to use for
139 drawing text layout. The font
140 selected in this GC must cor‐
141 respond to the tkfont used
142 when constructing the text
143 layout.
144 int x, y (in) Point, in pixels, at which to
146 place the upper-left hand cor‐
147 ner of the text layout when it
148 is being drawn, or the coordi‐
149 nates of a point (with respect
150 to the upper-left hand corner
151 of the text layout) to check
152 against the text layout.
153 int firstChar (in) The index of the first charac‐
155 ter to draw from the given
156 text layout. The number 0
157 means to draw from the begin‐
158 ning.
159 int lastChar (in) The index of the last charac‐
161 ter up to which to draw. The
162 character specified by
163 lastChar itself will not be
164 drawn. A number less than 0
165 means to draw all characters
166 in the text layout.
167 int underline (in) Index of the single character
169 to underline in the text lay‐
170 out, or a number less than 0
171 for no underline.
172 int index (in) The index of the character
174 whose bounding box is desired.
175 The bounding box is computed
176 with respect to the upper-left
177 hand corner of the text lay‐
178 out.
179 int *xPtr, *yPtr (out) Filled with the upper-left
181 hand corner, in pixels, of the
182 bounding box for the character
183 specified by index. Either or
184 both xPtr and yPtr may be
185 NULL, in which case the corre‐
186 sponding value is not calcu‐
187 lated.
188 int width, height (in) Specifies the width and
190 height, in pixels, of the rec‐
191 tangular area to compare for
192 intersection against the text
193 layout.
194 Tcl_Interp *interp (out) Postscript code that will
196 print the text layout is
197 appended to the result of
198 interpreter interp.
199______________________________________________________________________________
200
202 These routines are for measuring and displaying single-font, multi-
203 line, justified text. To measure and display simple single-font, sin‐
204 gle-line strings, refer to the documentation for Tk_MeasureChars.
205 There is no programming interface in the core of Tk that supports
206 multi-font, multi-line text; support for that behavior must be built on
207 top of simpler layers. Note that unlike the lower level text display
208 routines, the functions described here all operate on character-ori‐
209 ented lengths and indices rather than byte-oriented values. See the
210 description of Tcl_UtfAtIndex for more details on converting between
211 character and byte offsets.
212 The routines described here are built on top of the programming inter‐
214 face described in the Tk_MeasureChars documentation. Tab characters
215 and newline/return characters may be treated specially by these proce‐
216 dures, but all other characters are passed through to the lower level.
217 Tk_ComputeTextLayout computes the layout information needed to display
219 a single-font, multi-line, justified string of text and returns a
220 Tk_TextLayout token that holds this information. This token is used in
221 subsequent calls to procedures such as Tk_DrawTextLayout, Tk_Distance‐
222 ToTextLayout, and Tk_FreeTextLayout. The string and tkfont used when
223 computing the layout must remain valid for the lifetime of this token.
224 Tk_FreeTextLayout is called to release the storage associated with lay‐
226 out when it is no longer needed. A layout should not be used in any
227 other text layout procedures once it has been released.
228 Tk_DrawTextLayout uses the information in layout to display a single-
230 font, multi-line, justified string of text at the specified location.
231 Tk_UnderlineTextLayout uses the information in layout to display an
233 underline below an individual character. This procedure does not draw
234 the text, just the underline. To produce natively underlined text, an
235 underlined font should be constructed and used. All characters,
236 including tabs, newline/return characters, and spaces at the ends of
237 lines, can be underlined using this method. However, the underline
238 will never be drawn outside of the computed width of layout; the under‐
239 line will stop at the edge for any character that would extend par‐
240 tially outside of layout, and the underline will not be visible at all
241 for any character that would be located completely outside of the lay‐
242 out.
243 Tk_PointToChar uses the information in layout to determine the charac‐
245 ter closest to the given point. The point is specified with respect to
246 the upper-left hand corner of the layout, which is considered to be
247 located at (0, 0). Any point whose y-value is less that 0 will be con‐
248 sidered closest to the first character in the text layout; any point
249 whose y-value is greater than the height of the text layout will be
250 considered closest to the last character in the text layout. Any point
251 whose x-value is less than 0 will be considered closest to the first
252 character on that line; any point whose x-value is greater than the
253 width of the text layout will be considered closest to the last charac‐
254 ter on that line. The return value is the index of the character that
255 was closest to the point, or one more than the index of any character
256 (to indicate that the point was after the end of the string and that
257 the corresponding caret would be at the end of the string). Given a
258 layout with no characters, the value 0 will always be returned, refer‐
259 ring to a hypothetical zero-width 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 did not 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 interpreter interp's 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)