Provided by: tk8.5-doc_8.5.15-2ubuntu3_all 
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.
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 Tcl_NumUtfChars to
determine the length of 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 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 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 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 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. Note that unlike the lower level text display routines, the functions described
here all operate on character-oriented lengths and indices rather than byte-oriented
values. See the description of Tcl_UtfAtIndex for more details on converting between
character and byte offsets.
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,
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
actually hits the layout. If the point did not 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 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