Manual Pages for UNIX Darwin command on man Tk

Manual Pages for UNIX Darwin command on man Tk_DrawTextLayout

TkComputeTextLayout(3) Tk Library Procedures TkComputeTextLayout(3)

NAME

TkComputeTextLayout, TkFreeTextLayout, TkDrawTextLayout, TkUnder-

lineTextLayout, TkPointToChar, TkCharBbox, TkDistanceToTextLayout,

TkIntersectTextLayout, TkTextLayoutToPostscript - routines to measure

and display single-font, multi-line, justified text.

SYNOPSIS

##iinncclluuddee <>

TkTextLayout TTkkCCoommppuutteeTTeexxttLLaayyoouutt((tkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr)) void TTkkFFrreeeeTTeexxttLLaayyoouutt((layout)) void TTkkDDrraawwTTeexxttLLaayyoouutt((display, drawable, gc, layout, x, y, firstChar, lastChar)) void TTkkUUnnddeerrlliinneeTTeexxttLLaayyoouutt((display, drawable, gc, layout, x, y, underline)) int TTkkPPooiinnttTTooCChhaarr((layout, x, y)) int TTkkCChhaarrBBbbooxx((layout, index, xPtr, yPtr, widthPtr, heightPtr)) int TTkkDDiissttaanncceeTTooTTeexxttLLaayyoouutt((layout, x, y)) int TTkkIInntteerrsseeccttTTeexxttLLaayyoouutt((layout, x, y, width, height)) void TTkkTTeexxttLLaayyoouuttTTooPPoossttssccrriipptt((interp, layout)) AARRGGUUMMEENNTTSS TkFont 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 TTkkGGeettFFoonntt.

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 is less than 0, then

assumes string is null termi- |

nated and uses TTccllNNuummUUttffCChhaarrss | 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 char-

acter 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. TkJustify justify (in) How to justify the lines in a

multi-line text layout. Pos-

sible values are TKJUS-

TIFYLEFT, TKJUSTIFYCENTER, or TKJUSTIFYRIGHT. If the text layout only occupies a single line, then justify is irrelevant.

int flags (in) Various flag bits OR-ed

together. TKIGNORETABS means that tab characters should not be expanded to the

next tab stop. TKIGNORENEW-

LINES means that new-

line/return characters should not cause a line break. If

either tabs or new-

lines/returns are ignored, then they will be treated as

regular characters, being mea-

sured and displayed in a plat-

form-dependent manner as

described in TTkkMMeeaassuurreeCChhaarrss, 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 pix-

els, 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. TkTextLayout 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 TTkkCCoommppuutteeTTeexxttLLaayyoouutt. 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 cor-

respond 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 of the text layout when it

is being drawn, or the coordi-

nates 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 charac-

ter to draw from the given text layout. The number 0

means to draw from the begin-

ning.

int lastChar (in) The index of the last charac-

ter 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, 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 lay-

out.

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 value is not calcu-

lated. int width, height (in) Specifies the width and height, in pixels, of the rectangular area to compare for intersection against the text layout. TclInterp *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, sin-

gle-line strings, refer to the documentation for TTkkMMeeaassuurreeCChhaarrss.

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-ori- |

ented lengths and indices rather than byte-oriented values. See the |

description of TTccllUUttffAAttIInnddeexx for more details on converting between | character and byte offsets.

The routines described here are built on top of the programming inter-

face described in the TTkkMMeeaassuurreeCChhaarrss documentation. Tab characters

and newline/return characters may be treated specially by these proce-

dures, but all other characters are passed through to the lower level. TTkkCCoommppuutteeTTeexxttLLaayyoouutt computes the layout information needed to display

a single-font, multi-line, justified string of text and returns a

TkTextLayout token that holds this information. This token is used in

subsequent calls to procedures such as TTkkDDrraawwTTeexxttLLaayyoouutt, TTkkDDiissttaannccee-

TTooTTeexxttLLaayyoouutt, and TTkkFFrreeeeTTeexxttLLaayyoouutt. The string and tkfont used when computing the layout must remain valid for the lifetime of this token.

TTkkFFrreeeeTTeexxttLLaayyoouutt is called to release the storage associated with lay-

out when it is no longer needed. A layout should not be used in any other text layout procedures once it has been released.

TTkkDDrraawwTTeexxttLLaayyoouutt uses the information in layout to display a single-

font, multi-line, justified string of text at the specified location.

TTkkUUnnddeerrlliinneeTTeexxttLLaayyoouutt 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 under-

line will stop at the edge for any character that would extend par-

tially outside of layout, and the underline will not be visible at all

for any character that would be located completely outside of the lay-

out.

TTkkPPooiinnttTTooCChhaarr uses the information in layout to determine the charac-

ter 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 con-

sidered 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 charac-

ter 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. TTkkCChhaarrBBbbooxx 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 bot-

tom of the descent; information about the actual height of individual

letters is not available. For measurement purposes, a layout that con-

tains no characters is considered to contain a single zero-width place-

holder 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. TTkkDDiissttaanncceeTTooTTeexxttLLaayyoouutt 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 pur-

poses, 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. TTkkIInntteerrsseeccttTTeexxttLLaayyoouutt determines whether a layout lies entirely

inside, entirely outside, or overlaps a given rectangle. New-

line/return characters and non-displaying space characters that occur

at the end of individual lines in the layout are ignored for intersec-

tion 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. TTkkTTeexxttLLaayyoouuttTTooPPoossttssccrriipptt 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.

DDIISSPPLLAAYY MMOODDEELL 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-justi-

fied 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 sup-

pressed and occupy their normal space width.

Tab characters are not ignored for measurement calculations. If wrap-

ping 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 mid-

dle of a word is not considered a word break. TTkkCCoommppuutteeTTeexxttLLaayyoouutt 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 new-

line/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, new-

lines/returns, and tabs will not be displayed underlined when TTkkDDrraaww-

TTeexxttLLaayyoouutt is called, because those characters are never actually drawn

- they are merely placeholders maintained in the layout.

KKEEYYWWOORRDDSS font Tk 8.1 TkComputeTextLayout(3)