2
'\" Copyright (c) 1996 Sun Microsystems, Inc.
4
'\" See the file "license.terms" for information on usage and redistribution
5
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7
'\" RCS: @(#) $Id: TextLayout.3,v 1.2 1998/09/14 18:22:54 stanton Exp $
10
.TH Tk_ComputeTextLayout 3 "" Tk "Tk Library Procedures"
13
Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_UnderlineTextLayout, Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_IntersectTextLayout, Tk_TextLayoutToPostscript \- routines to measure and display single-font, multi-line, justified text.
19
\fBTk_ComputeTextLayout(\fItkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr\fB)\fR
22
\fBTk_FreeTextLayout(\fIlayout\fB)\fR
25
\fBTk_DrawTextLayout(\fIdisplay, drawable, gc, layout, x, y, firstChar, lastChar\fB)\fR
28
\fBTk_UnderlineTextLayout(\fIdisplay, drawable, gc, layout, x, y, underline\fB)\fR
31
\fBTk_PointToChar(\fIlayout, x, y\fB)\fR
34
\fBTk_CharBbox(\fIlayout, index, xPtr, yPtr, widthPtr, heightPtr\fB)\fR
37
\fBTk_DistanceToTextLayout(\fIlayout, x, y\fB)\fR
40
\fBTk_IntersectTextLayout(\fIlayout, x, y, width, height\fB)\fR
43
\fBTk_TextLayoutToPostscript(\fIinterp, layout\fB)\fR
46
.AS Tk_TextLayout "*xPtr, *yPtr"
48
Font to use when constructing and displaying a text layout. The
49
\fItkfont\fR must remain valid for the lifetime of the text layout. Must
50
have been returned by a previous call to \fBTk_GetFont\fR.
51
.AP "const char" *string in
52
Potentially multi-line string whose dimensions are to be computed and
53
stored in the text layout. The \fIstring\fR must remain valid for the
54
lifetime of the text layout.
56
The number of characters to consider from \fIstring\fR. If
57
\fInumChars\fR is less than 0, then assumes \fIstring\fR is null
58
terminated and uses \fBstrlen(\fIstring\fB)\fR.
60
Longest permissible line length, in pixels. Lines in \fIstring\fR will
61
automatically be broken at word boundaries and wrapped when they reach
62
this length. If \fIwrapLength\fR is too small for even a single
63
character to fit on a line, it will be expanded to allow one character to
64
fit on each line. If \fIwrapLength\fR is <= 0, there is no automatic
65
wrapping; lines will get as long as they need to be and only wrap if a
66
newline/return character is encountered.
67
.AP Tk_Justify justify in
68
How to justify the lines in a multi-line text layout. Possible values
69
are TK_JUSTIFY_LEFT, TK_JUSTIFY_CENTER, or TK_JUSTIFY_RIGHT. If the text
70
layout only occupies a single line, then \fIjustify\fR is irrelevant.
72
Various flag bits OR-ed together. TK_IGNORE_TABS means that tab characters
73
should not be expanded to the next tab stop. TK_IGNORE_NEWLINES means that
74
newline/return characters should not cause a line break. If either tabs or
75
newlines/returns are ignored, then they will be treated as regular
76
characters, being measured and displayed in a platform-dependent manner as
77
described in \fBTk_MeasureChars\fR, and will not have any special behaviors.
79
If non-NULL, filled with either the width, in pixels, of the widest
80
line in the text layout, or the width, in pixels, of the bounding box for the
81
character specified by \fIindex\fR.
82
.AP int *heightPtr out
83
If non-NULL, filled with either the total height, in pixels, of all
84
the lines in the text layout, or the height, in pixels, of the bounding
85
box for the character specified by \fIindex\fR.
86
.AP Tk_TextLayout layout in
87
A token that represents the cached layout information about the single-font,
88
multi-line, justified piece of text. This token is returned by
89
\fBTk_ComputeTextLayout\fR.
90
.AP Display *display in
91
Display on which to draw.
92
.AP Drawable drawable in
93
Window or pixmap in which to draw.
95
Graphics context to use for drawing text layout. The font selected in
96
this GC must correspond to the \fItkfont\fR used when constructing the
99
Point, in pixels, at which to place the upper-left hand corner of the
100
text layout when it is being drawn, or the coordinates of a point (with
101
respect to the upper-left hand corner of the text layout) to check
102
against the text layout.
104
The index of the first character to draw from the given text layout.
105
The number 0 means to draw from the beginning.
107
The index of the last character up to which to draw. The character
108
specified by \fIlastChar\fR itself will not be drawn. A number less
109
than 0 means to draw all characters in the text layout.
111
Index of the single character to underline in the text layout, or a number
112
less than 0 for no underline.
114
The index of the character whose bounding box is desired. The bounding
115
box is computed with respect to the upper-left hand corner of the text layout.
116
.AP int "*xPtr, *yPtr" out
117
Filled with the upper-left hand corner, in pixels, of the bounding box
118
for the character specified by \fIindex\fR. Either or both \fIxPtr\fR
119
and \fIyPtr\fR may be NULL, in which case the corresponding value
121
.AP int "width, height" in
122
Specifies the width and height, in pixels, of the rectangular area to
123
compare for intersection against the text layout.
124
.AP Tcl_Interp *interp out
125
Postscript code that will print the text layout is appended to
126
\fIinterp->result\fR.
131
These routines are for measuring and displaying single-font, multi-line,
132
justified text. To measure and display simple single-font, single-line
133
strings, refer to the documentation for \fBTk_MeasureChars\fR. There is
134
no programming interface in the core of Tk that supports multi-font,
135
multi-line text; support for that behavior must be built on top of
138
The routines described here are built on top of the programming interface
139
described in the \fBTk_MeasureChars\fR documentation. Tab characters and
140
newline/return characters may be treated specially by these procedures,
141
but all other characters are passed through to the lower level.
143
\fBTk_ComputeTextLayout\fR computes the layout information needed to
144
display a single-font, multi-line, justified \fIstring\fR of text and
145
returns a Tk_TextLayout token that holds this information. This token is
146
used in subsequent calls to procedures such as \fBTk_DrawTextLayout\fR,
147
\fBTk_DistanceToTextLayout\fR, and \fBTk_FreeTextLayout\fR. The
148
\fIstring\fR and \fItkfont\fR used when computing the layout must remain
149
valid for the lifetime of this token.
151
\fBTk_FreeTextLayout\fR is called to release the storage associated with
152
\fIlayout\fR when it is no longer needed. A \fIlayout\fR should not be used
153
in any other text layout procedures once it has been released.
155
\fBTk_DrawTextLayout\fR uses the information in \fIlayout\fR to display a
156
single-font, multi-line, justified string of text at the specified location.
158
\fBTk_UnderlineTextLayout\fR uses the information in \fIlayout\fR to
159
display an underline below an individual character. This procedure does
160
not draw the text, just the underline. To produce natively underlined
161
text, an underlined font should be constructed and used. All characters,
162
including tabs, newline/return characters, and spaces at the ends of
163
lines, can be underlined using this method. However, the underline will
164
never be drawn outside of the computed width of \fIlayout\fR; the
165
underline will stop at the edge for any character that would extend
166
partially outside of \fIlayout\fR, and the underline will not be visible
167
at all for any character that would be located completely outside of the
170
\fBTk_PointToChar\fR uses the information in \fIlayout\fR to determine the
171
character closest to the given point. The point is specified with respect
172
to the upper-left hand corner of the \fIlayout\fR, which is considered to be
173
located at (0, 0). Any point whose \fIy\fR-value is less that 0 will be
174
considered closest to the first character in the text layout; any point
175
whose \fIy\fR-value is greater than the height of the text layout will be
176
considered closest to the last character in the text layout. Any point
177
whose \fIx\fR-value is less than 0 will be considered closest to the first
178
character on that line; any point whose \fIx\fR-value is greater than the
179
width of the text layout will be considered closest to the last character on
180
that line. The return value is the index of the character that was closest
181
to the point. Given a \fIlayout\fR with no characters, the value 0 will
182
always be returned, referring to a hypothetical zero-width placeholder
185
\fBTk_CharBBox\fR uses the information in \fIlayout\fR to return the
186
bounding box for the character specified by \fIindex\fR. The width of the
187
bounding box is the advance width of the character, and does not include any
188
left or right bearing. Any character that extends partially outside of
189
\fIlayout\fR is considered to be truncated at the edge. Any character
190
that would be located completely outside of \fIlayout\fR is considered to
191
be zero-width and pegged against the edge. The height of the bounding
192
box is the line height for this font, extending from the top of the
193
ascent to the bottom of the descent; information about the actual height
194
of individual letters is not available. For measurement purposes, a
195
\fIlayout\fR that contains no characters is considered to contain a
196
single zero-width placeholder character at index 0. If \fIindex\fR was
197
not a valid character index, the return value is 0 and \fI*xPtr\fR,
198
\fI*yPtr\fR, \fI*widthPtr\fR, and \fI*heightPtr\fR are unmodified.
199
Otherwise, if \fIindex\fR did specify a valid, the return value is
200
non-zero, and \fI*xPtr\fR, \fI*yPtr\fR, \fI*widthPtr\fR, and
201
\fI*heightPtr\fR are filled with the bounding box information for the
202
character. If any of \fIxPtr\fR, \fIyPtr\fR, \fIwidthPtr\fR, or
203
\fIheightPtr\fR are NULL, the corresponding value is not calculated or
206
\fBTk_DistanceToTextLayout\fR computes the shortest distance in pixels from
207
the given point (\fIx, y\fR) to the characters in \fIlayout\fR.
208
Newline/return characters and non-displaying space characters that occur at
209
the end of individual lines in the text layout are ignored for hit detection
210
purposes, but tab characters are not. The return value is 0 if the point
211
actually hits the \fIlayout\fR. If the point didn't hit the \fIlayout\fR
212
then the return value is the distance in pixels from the point to the
215
\fBTk_IntersectTextLayout\fR determines whether a \fIlayout\fR lies
216
entirely inside, entirely outside, or overlaps a given rectangle.
217
Newline/return characters and non-displaying space characters that occur
218
at the end of individual lines in the \fIlayout\fR are ignored for
219
intersection calculations. The return value is \-1 if the \fIlayout\fR is
220
entirely outside of the rectangle, 0 if it overlaps, and 1 if it is
221
entirely inside of the rectangle.
223
\fBTk_TextLayoutToPostscript\fR outputs code consisting of a Postscript
224
array of strings that represent the individual lines in \fIlayout\fR. It
225
is the responsibility of the caller to take the Postscript array of
226
strings and add some Postscript function operate on the array to render
227
each of the lines. The code that represents the Postscript array of
228
strings is appended to \fIinterp->result\fR.
231
When measuring a text layout, space characters that occur at the end of a
232
line are ignored. The space characters still exist and the insertion point
233
can be positioned amongst them, but their additional width is ignored when
234
justifying lines or returning the total width of a text layout. All
235
end-of-line space characters are considered to be attached to the right edge
236
of the line; this behavior is logical for left-justified text and reasonable
237
for center-justified text, but not very useful when editing right-justified
238
text. Spaces are considered variable width characters; the first space that
239
extends past the edge of the text layout is clipped to the edge, and any
240
subsequent spaces on the line are considered zero width and pegged against
241
the edge. Space characters that occur in the middle of a line of text are
242
not suppressed and occupy their normal space width.
244
Tab characters are not ignored for measurement calculations. If wrapping
245
is turned on and there are enough tabs on a line, the next tab will wrap
246
to the beginning of the next line. There are some possible strange
247
interactions between tabs and justification; tab positions are calculated
248
and the line length computed in a left-justified world, and then the
249
whole resulting line is shifted so it is centered or right-justified,
250
causing the tab columns not to align any more.
252
When wrapping is turned on, lines may wrap at word breaks (space or tab
253
characters) or newline/returns. A dash or hyphen character in the middle
254
of a word is not considered a word break. \fBTk_ComputeTextLayout\fR
255
always attempts to place at least one word on each line. If it cannot
256
because the \fIwrapLength\fR is too small, the word will be broken and as
257
much as fits placed on the line and the rest on subsequent line(s). If
258
\fIwrapLength\fR is so small that not even one character can fit on a
259
given line, the \fIwrapLength\fR is ignored for that line and one
260
character will be placed on the line anyhow. When wrapping is turned
261
off, only newline/return characters may cause a line break.
263
When a text layout has been created using an underlined \fItkfont\fR,
264
then any space characters that occur at the end of individual lines,
265
newlines/returns, and tabs will not be displayed underlined when
266
\fBTk_DrawTextLayout\fR is called, because those characters are never
267
actually drawn \- they are merely placeholders maintained in the
added
removed
doc/TextLayout.3
