Tk_ComputeTextLayout(3)Tk
_________________________________________________________________
NAME
Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLay-
out, Tk_UnderlineTextLayout, Tk_PointToChar, Tk_CharBbox,
Tk_DistanceToTextLayout, Tk_IntersectTextLayout, Tk_Text-
LayoutToPostscript - routines to measure and display sin-
gle-font, multi-line, justified text.
SYNOPSIS
#include <<tk.h>>
Tk_TextLayout
Tk_ComputeTextLayout(tkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr)
void
Tk_FreeTextLayout(layout)
void
Tk_DrawTextLayout(display, drawable, gc, layout, x, y, firstChar, lastChar)
void
Tk_UnderlineTextLayout(display, drawable, gc, layout, x, y, underline)
int
Tk_PointToChar(layout, x, y)
int
Tk_CharBbox(layout, index, xPtr, yPtr, widthPtr, heightPtr)
int
Tk_DistanceToTextLayout(layout, x, y)
int
Tk_IntersectTextLayout(layout, x, y, width, height)
void
Tk_TextLayoutToPostscript(interp, layout)
ARGUMENTS
Tk_Font tkfont (in) Font to use when
constructing and
displaying a text
layout. The
tkfont must
remain valid for
the lifetime of
the text layout.
Must have been
returned by a
previous call to
Tk_GetFont.
const char *string (in) Potentially
multi-line string
whose dimensions
are to be com-
puted and stored
in the text lay-
out. The string
must remain valid
for the lifetime
of the text lay-
out.
int numChars (in) The number of
characters to
consider from
string. If num-
Chars is less
than 0, then
assumes string is
null terminated
and uses
strlen(string).
int wrapLength (in) Longest permissi-
ble line length,
in pixels. Lines
in string will
automatically be
broken at word
boundaries and
wrapped when they
reach this
length. If
wrapLength is too
small for even a
single character
to fit on a line,
it will be
expanded to allow
one character to
fit on each line.
If wrapLength is
<= 0, there is no
automatic wrap-
ping; lines will
get as long as
they need to be
and only wrap if
a newline/return
character is
encountered.
Tk_Justify justify (in) How to justify
the lines in a
multi-line text
layout. Possible
values are
TK_JUSTIFY_LEFT,
TK_JUSTIFY_CEN-
TER, or TK_JUS-
TIFY_RIGHT. If
the text layout
only occupies a
single line, then
justify is irrel-
evant.
int flags (in) Various flag bits
OR-ed together.
TK_IGNORE_TABS
means that tab
characters should
not be expanded
to the next tab
stop.
TK_IGNORE_NEW-
LINES means that
newline/return
characters should
not cause a line
break. If either
tabs or new-
lines/returns are
ignored, then
they will be
treated as regu-
lar characters,
being measured
and displayed in
a platform-depen-
dent manner as
described in
Tk_MeasureChars,
and will not have
any special
behaviors.
int *widthPtr (out) If non-NULL,
filled with
either the width,
in pixels, of the
widest line in
the text layout,
or the width, in
pixels, of the
bounding box for
the character
specified by
index.
int *heightPtr (out) If non-NULL,
filled with
either the total
height, in pix-
els, of all the
lines in the text
layout, or the
height, in pix-
els, of the
bounding box for
the character
specified by
index.
Tk_TextLayout layout (in) A token that rep-
resents the
cached layout
information about
the single-font,
multi-line, jus-
tified piece of
text. This token
is returned by
Tk_ComputeText-
Layout.
Display *display (in) Display on which
to draw.
Drawable drawable (in) Window or pixmap
in which to draw.
GC gc (in) Graphics context
to use for draw-
ing text layout.
The font selected
in this GC must
correspond to the
tkfont used when
constructing the
text layout.
int x, y (in) Point, in pixels,
at which to place
the upper-left
hand corner of
the text layout
when it is being
drawn, or the
coordinates of a
point (with
respect to the
upper-left hand
corner of the
text layout) to
check against the
text layout.
int firstChar (in) The index of the
first character
to draw from the
given text lay-
out. The number
0 means to draw
from the begin-
ning.
int lastChar (in) The index of the
last character up
to which to draw.
The character
specified by
lastChar itself
will not be
drawn. A number
less than 0 means
to draw all char-
acters in the
text layout.
int underline (in) Index of the sin-
gle character to
underline in the
text layout, or a
number less than
0 for no under-
line.
int index (in) The index of the
character whose
bounding box is
desired. The
bounding box is
computed with
respect to the
upper-left hand
corner of the
text layout.
int *xPtr, *yPtr (out) Filled with the
upper-left hand
corner, in pix-
els, of the
bounding box for
the character
specified by
index. Either or
both xPtr and
yPtr may be NULL,
in which case the
corresponding
value is not cal-
culated.
int width, height (in) Specifies the
width and height,
in pixels, of the
rectangular area
to compare for
intersection
against the text
layout.
Tcl_Interp *interp (out) Postscript code
that will print
the text layout
is appended to
interp->result.
_________________________________________________________________
DESCRIPTION
These routines are for measuring and displaying single-
font, multi-line, justified text. To measure and display
simple single-font, single-line strings, refer to the doc-
umentation for Tk_MeasureChars. There is no programming
interface in the core of Tk that supports multi-font,
multi-line text; support for that behavior must be built
on top of simpler layers.
The routines described here are built on top of the pro-
gramming interface described in the Tk_MeasureChars docu-
mentation. Tab characters and newline/return characters
may be treated specially by these procedures, but all
other characters are passed through to the lower level.
Tk_ComputeTextLayout computes the layout information
needed to display a single-font, multi-line, justified
string of text and returns a Tk_TextLayout token that
holds this information. This token is used in subsequent
calls to procedures such as Tk_DrawTextLayout, Tk_Dis-
tanceToTextLayout, and Tk_FreeTextLayout. The string and
tkfont used when computing the layout must remain valid
for the lifetime of this token.
Tk_FreeTextLayout is called to release the storage associ-
ated with layout when it is no longer needed. A layout
should not be used in any other text layout procedures
once it has been released.
Tk_DrawTextLayout uses the information in layout to dis-
play a single-font, multi-line, justified string of text
at the specified location.
Tk_UnderlineTextLayout uses the information in layout to
display an underline below an individual character. This
procedure does not draw the text, just the underline. To
produce natively underlined text, an underlined font
should be constructed and used. All characters, including
tabs, newline/return characters, and spaces at the ends of
lines, can be underlined using this method. However, the
underline will never be drawn outside of the computed
width of layout; the underline will stop at the edge for
any character that would extend partially outside of lay-
out, and the underline will not be visible at all for any
character that would be located completely outside of the
layout.
Tk_PointToChar uses the information in layout to determine
the character closest to the given point. The point is
specified with respect to the upper-left hand corner of
the layout, which is considered to be located at (0, 0).
Any point whose y-value is less that 0 will be considered
closest to the first character in the text layout; any
point whose y-value is greater than the height of the text
layout will be considered closest to the last character in
the text layout. Any point whose x-value is less than 0
will be considered closest to the first character on that
line; any point whose x-value is greater than the width of
the text layout will be considered closest to the last
character on that line. The return value is the index of
the character that was closest to the point. Given a lay-
out with no characters, the value 0 will always be
returned, referring to a hypothetical zero-width place-
holder character.
Tk_CharBBox uses the information in layout to return the
bounding box for the character specified by index. The
width of the bounding box is the advance width of the
character, and does not include any left or right bearing.
Any character that extends partially outside of layout is
considered to be truncated at the edge. Any character
that would be located completely outside of layout is con-
sidered to be zero-width and pegged against the edge. The
height of the bounding box is the line height for this
font, extending from the top of the ascent to the bottom
of the descent; information about the actual height of
individual letters is not available. For measurement pur-
poses, a layout that contains no characters is considered
to contain a single zero-width placeholder character at
index 0. If index was not a valid character index, the
return value is 0 and *xPtr, *yPtr, *widthPtr, and
*heightPtr are unmodified. Otherwise, if index did spec-
ify a valid, the return value is non-zero, and *xPtr,
*yPtr, *widthPtr, and *heightPtr are filled with the
bounding box information for the character. If any of
xPtr, yPtr, widthPtr, or heightPtr are NULL, the corre-
sponding value is not calculated or stored.
Tk_DistanceToTextLayout computes the shortest distance in
pixels from the given point (x, y) to the characters in
layout. Newline/return characters and non-displaying
space characters that occur at the end of individual lines
in the text layout are ignored for hit detection purposes,
but tab characters are not. The return value is 0 if the
point actually hits the layout. If the point didn't hit
the layout then the return value is the distance in pixels
from the point to the layout.
Tk_IntersectTextLayout determines whether a layout lies
entirely inside, entirely outside, or overlaps a given
rectangle. Newline/return characters and non-displaying
space characters that occur at the end of individual lines
in the layout are ignored for intersection calculations.
The return value is -1 if the layout is entirely outside
of the rectangle, 0 if it overlaps, and 1 if it is
entirely inside of the rectangle.
Tk_TextLayoutToPostscript outputs code consisting of a
Postscript array of strings that represent the individual
lines in layout. It is the responsibility of the caller
to take the Postscript array of strings and add some
Postscript function operate on the array to render each of
the lines. The code that represents the Postscript array
of strings is appended to interp->result.
DISPLAY MODEL
When measuring a text layout, space characters that occur
at the end of a line are ignored. The space characters
still exist and the insertion point can be positioned
amongst them, but their additional width is ignored when
justifying lines or returning the total width of a text
layout. All end-of-line space characters are considered
to be attached to the right edge of the line; this behav-
ior is logical for left-justified text and reasonable for
center-justified text, but not very useful when editing
right-justified text. Spaces are considered variable
width characters; the first space that extends past the
edge of the text layout is clipped to the edge, and any
subsequent spaces on the line are considered zero width
and pegged against the edge. Space characters that occur
in the middle of a line of text are not suppressed and
occupy their normal space width.
Tab characters are not ignored for measurement calcula-
tions. If wrapping is turned on and there are enough tabs
on a line, the next tab will wrap to the beginning of the
next line. There are some possible strange interactions
between tabs and justification; tab positions are calcu-
lated and the line length computed in a left-justified
world, and then the whole resulting line is shifted so it
is centered or right-justified, causing the tab columns
not to align any more.
When wrapping is turned on, lines may wrap at word breaks
(space or tab characters) or newline/returns. A dash or
hyphen character in the middle of a word is not considered
a word break. Tk_ComputeTextLayout always attempts to
place at least one word on each line. If it cannot
because the wrapLength is too small, the word will be bro-
ken and as much as fits placed on the line and the rest on
subsequent line(s). If wrapLength is so small that not
even one character can fit on a given line, the wrapLength
is ignored for that line and one character will be placed
on the line anyhow. When wrapping is turned off, only
newline/return characters may cause a line break.
When a text layout has been created using an underlined
tkfont, then any space characters that occur at the end of
individual lines, newlines/returns, and tabs will not be
displayed underlined when Tk_DrawTextLayout is called,
because those characters are never actually drawn - they
are merely placeholders maintained in the layout.
KEYWORDS
font