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
43

ARGUMENTS

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
53       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
60       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
68       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
85       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
94       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
111       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
119       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
127       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
134       Display *display (in)                    Display on which to draw.
135
136       Drawable drawable (in)                   Window  or  pixmap in which to
137                                                draw.
138
139       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
146       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
155       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
161       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
169       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
174       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
181       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
190       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
196       Tcl_Interp *interp (out)                 Postscript   code   that  will
197                                                print  the  text   layout   is
198                                                appended to interp->result.
199_________________________________________________________________
200
201

DESCRIPTION

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
214       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
219       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
226       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
230       Tk_DrawTextLayout uses the information in layout to display  a  single-
231       font, multi-line, justified string of text at the specified location.
232
233       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
245       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
260       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
279       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
287       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
295       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

DISPLAY MODEL

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
317       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
325       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
336       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

KEYWORDS

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