Tk_ComputeTextLayout(3) Tk Tk_ComputeTextLayout(3)
_________________________________________________________________
NAME
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.
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.
Page 1 (printed 2/26/99)
Tk_ComputeTextLayout(3) Tk Tk_ComputeTextLayout(3)
const char *string (in) Potentially multi-
line string whose
dimensions are to
be computed and
stored in the text
layout. The string
must remain valid
for the lifetime of
the text layout.
int numChars (in) The number of
characters to
consider from
string. If
numChars is less
than 0, then
assumes string is
null terminated and
uses
strlen(string).
int wrapLength (in) Longest permissible
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 wrapping;
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
Page 2 (printed 2/26/99)
Tk_ComputeTextLayout(3) Tk Tk_ComputeTextLayout(3)
TK_JUSTIFY_LEFT,
TK_JUSTIFY_CENTER,
or
TK_JUSTIFY_RIGHT.
If the text layout
only occupies a
single line, then
justify is
irrelevant.
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_NEWLINES
means that
newline/return
characters should
not cause a line
break. If either
tabs or
newlines/returns
are ignored, then
they will be
treated as regular
characters, being
measured and
displayed in a
platform-dependent
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
Page 3 (printed 2/26/99)
Tk_ComputeTextLayout(3) Tk Tk_ComputeTextLayout(3)
pixels, of all the
lines in the text
layout, or the
height, in pixels,
of the bounding box
for the character
specified by index.
Tk_TextLayout layout (in) A token that
represents the
cached layout
information about
the single-font,
multi-line,
justified piece of
text. This token
is returned by
Tk_ComputeTextLayout.
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 drawing
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
Page 4 (printed 2/26/99)
Tk_ComputeTextLayout(3) Tk Tk_ComputeTextLayout(3)
text layout. The
number 0 means to
draw from the
beginning.
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
characters in the
text layout.
int underline (in) Index of the single
character to
underline in the
text layout, or a
number less than 0
for no underline.
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 pixels,
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
calculated.
int width, height (in) Specifies the width
and height, in
pixels, of the
rectangular area to
Page 5 (printed 2/26/99)
Tk_ComputeTextLayout(3) Tk Tk_ComputeTextLayout(3)
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 documentation
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
programming interface described in the Tk_MeasureChars
documentation. 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_DistanceToTextLayout, 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
associated 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 display
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,
Page 6 (printed 2/26/99)
Tk_ComputeTextLayout(3) Tk Tk_ComputeTextLayout(3)
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 layout, 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 layout with no
characters, the value 0 will always be returned, referring
to a hypothetical zero-width placeholder 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 considered
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 purposes, 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 specify 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
corresponding 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
Page 7 (printed 2/26/99)
Tk_ComputeTextLayout(3) Tk Tk_ComputeTextLayout(3)
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 behavior 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 calculations.
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 calculated 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
Page 8 (printed 2/26/99)
Tk_ComputeTextLayout(3) Tk Tk_ComputeTextLayout(3)
wrapLength is too small, the word will be broken 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
Page 9 (printed 2/26/99)
