Tk_ComputeTextLayout(3) Tk Library Procedures 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.
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 num-Chars numChars
Chars 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 new-
line/return character is encountered.
Tk_Justify justify (in) How to justify the lines in a multi-line text layout. Pos-sible Possible
sible 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 new-lines/returns newlines/returns
lines/returns are ignored, then they will be treated as reg-ular regular
ular characters, being measured and displayed in a platform-dependent platformdependent
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 pix-els, pixels,
els, 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 cor-ner corner
ner of the text layout when it is being drawn, or the coor-dinates coordinates
dinates of a point (with respect to the upper-left hand cor-ner corner
ner 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 lay-out, layout,
out, 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 corre-sponding corresponding
sponding value is not calculated.
int width, height (in) Specifies the width and height, in pixels, of the rectangu-lar rectangular
lar area to compare for intersection against the text lay-out. layout.
out.
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; sup-port support
port 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 convert- |
ing between character and byte offsets.
The routines described here are built on top of the programming interface described in the Tk_Mea-sureChars Tk_MeasureChars
sureChars 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 under-lined underlined
lined text, an underlined font should be constructed and used. All characters, including tabs, new-line/return newline/return
line/return characters, and spaces at the ends of lines, can be underlined using this method. How-ever, However,
ever, 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 xvalue
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 zerowidth
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 consid-ered considered
ered 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 char-acters characters
acters 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 over-laps overlaps
laps 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 addi-tional additional
tional 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 behavior
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 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 pos-sible possible
sible 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 cen-tered centered
tered 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 new-line/returns. newline/returns.
line/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
Tk 8.1 Tk_ComputeTextLayout(3)
|