1Tk_ComputeTextLayout(3)      Tk Library Procedures     Tk_ComputeTextLayout(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

14       #include <tk.h>
15
16       Tk_TextLayout
17       Tk_ComputeTextLayout(tkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr)
18
19       void
20       Tk_FreeTextLayout(layout)
21
22       void
23       Tk_DrawTextLayout(display, drawable, gc, layout, x, y, firstChar, lastChar)
24
25       void
26       Tk_UnderlineTextLayout(display, drawable, gc, layout, x, y, underline)
27
28       int
29       Tk_PointToChar(layout, x, y)
30
31       int
32       Tk_CharBbox(layout, index, xPtr, yPtr, widthPtr, heightPtr)
33
34       int
35       Tk_DistanceToTextLayout(layout, x, y)
36
37       int
38       Tk_IntersectTextLayout(layout, x, y, width, height)
39
40       void
41       Tk_TextLayoutToPostscript(interp, layout)
42

ARGUMENTS

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
52       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
59       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
67       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
84       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
93       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
110       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
118       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
126       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
133       Display *display (in)                    Display on which to draw.
134
135       Drawable drawable (in)                   Window  or  pixmap in which to
136                                                draw.
137
138       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
145       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
154       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
160       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
168       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
173       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
180       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
189       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
195       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

DESCRIPTION

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
213       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
218       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
225       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
229       Tk_DrawTextLayout  uses  the information in layout to display a single-
230       font, multi-line, justified string of text at the specified location.
231
232       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
244       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
261       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
280       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
288       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
296       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

DISPLAY MODEL

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
318       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
326       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
337       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

KEYWORDS

344       font
345
346
347
348Tk                                    8.1              Tk_ComputeTextLayout(3)
Impressum