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 the result
of interpreter interp.
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, or one more than the index of any character (to indicate that the
point was after the end of the string and that the corresponding caret would
be at the end of the string). 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
interpreter
interp's 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