MAN page from Old RedHat 5.X tk-8.0.2-16.i386.rpm

Tk_ComputeTextLayout

Section: Tk Library Procedures (3)
Updated:
Index

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_TextLayoutTk_ComputeTextLayout(tkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr)voidTk_FreeTextLayout(layout)voidTk_DrawTextLayout(display, drawable, gc, layout, x, y, firstChar, lastChar)voidTk_UnderlineTextLayout(display, drawable, gc, layout, x, y, underline)intTk_PointToChar(layout, x, y)intTk_CharBbox(layout, index, xPtr, yPtr, widthPtr, heightPtr)intTk_DistanceToTextLayout(layout, x, y)intTk_IntersectTextLayout(layout, x, y, width, height)voidTk_TextLayoutToPostscript(interp, layout)

ARGUMENTS

Tk_Font tkfont (in)
Font to use when constructing and displaying a text layout. Thetkfont must remain valid for the lifetime of the text layout. Musthave been returned by a previous call to Tk_GetFont.

const char *string (in)
Potentially multi-line string whose dimensions are to be computed andstored in the text layout. The string must remain valid for thelifetime of the text layout.

int numChars (in)
The number of characters to consider from string. IfnumChars is less than 0, then assumes string is nullterminated and uses strlen(string).

int wrapLength (in)
Longest permissible line length, in pixels. Lines in string willautomatically be broken at word boundaries and wrapped when they reachthis length. If wrapLength is too small for even a singlecharacter to fit on a line, it will be expanded to allow one character tofit on each line. If wrapLength is <= 0, there is no automaticwrapping; lines will get as long as they need to be and only wrap if anewline/return character is encountered.

Tk_Justify justify (in)
How to justify the lines in a multi-line text layout. Possible valuesare TK_JUSTIFY_LEFT, TK_JUSTIFY_CENTER, or TK_JUSTIFY_RIGHT. If the textlayout only occupies a single line, then justify is irrelevant.

int flags (in)
Various flag bits OR-ed together. TK_IGNORE_TABS means that tab charactersshould not be expanded to the next tab stop. TK_IGNORE_NEWLINES means thatnewline/return characters should not cause a line break. If either tabs ornewlines/returns are ignored, then they will be treated as regularcharacters, being measured and displayed in a platform-dependent manner asdescribed 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 widestline 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 allthe lines in the text layout, or the height, in pixels, of the boundingbox 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 byTk_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 inthis GC must correspond to the tkfont used when constructing thetext layout.

int x, y (in)
Point, in pixels, at which to place the upper-left hand corner of thetext layout when it is being drawn, or the coordinates of a point (withrespect to the upper-left hand corner of the text layout) to checkagainst 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 characterspecified by lastChar itself will not be drawn. A number lessthan 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 numberless than 0 for no underline.

int index (in)
The index of the character whose bounding box is desired. The boundingbox 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 boxfor the character specified by index. Either or both xPtrand yPtr may be NULL, in which case the corresponding valueis 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 tointerp->result.

DESCRIPTION

These routines are for measuring and displaying single-font, multi-line,justified text. To measure and display simple single-font, single-linestrings, refer to the documentation for Tk_MeasureChars. There isno programming interface in the core of Tk that supports multi-font,multi-line text; support for that behavior must be built on top ofsimpler layers.

The routines described here are built on top of the programming interfacedescribed in the Tk_MeasureChars documentation. Tab characters andnewline/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 todisplay a single-font, multi-line, justified string of text andreturns a Tk_TextLayout token that holds this information. This token isused in subsequent calls to procedures such as Tk_DrawTextLayout,Tk_DistanceToTextLayout, and Tk_FreeTextLayout. Thestring and tkfont used when computing the layout must remainvalid for the lifetime of this token.

Tk_FreeTextLayout is called to release the storage associated withlayout when it is no longer needed. A layout should not be usedin any other text layout procedures once it has been released.

Tk_DrawTextLayout uses the information in layout to display asingle-font, multi-line, justified string of text at the specified location.

Tk_UnderlineTextLayout uses the information in layout todisplay an underline below an individual character. This procedure doesnot draw the text, just the underline. To produce natively underlinedtext, an underlined font should be constructed and used. All characters,including tabs, newline/return characters, and spaces at the ends oflines, can be underlined using this method. However, the underline willnever be drawn outside of the computed width of layout; theunderline will stop at the edge for any character that would extendpartially outside of layout, and the underline will not be visibleat all for any character that would be located completely outside of thelayout.

Tk_PointToChar uses the information in layout to determine thecharacter closest to the given point. The point is specified with respectto the upper-left hand corner of the layout, which is considered to belocated at (0, 0). Any point whose y-value is less that 0 will beconsidered closest to the first character in the text layout; any pointwhose y-value is greater than the height of the text layout will beconsidered closest to the last character in the text layout. Any pointwhose x-value is less than 0 will be considered closest to the firstcharacter on that line; any point whose x-value is greater than thewidth of the text layout will be considered closest to the last character onthat line. The return value is the index of the character that was closestto the point. Given a layout with no characters, the value 0 willalways be returned, referring to a hypothetical zero-width placeholdercharacter.

Tk_CharBBox uses the information in layout to return thebounding box for the character specified by index. The width of thebounding box is the advance width of the character, and does not include anyleft or right bearing. Any character that extends partially outside of layout is considered to be truncated at the edge. Any characterthat would be located completely outside of layout is considered tobe zero-width and pegged against the edge. The height of the boundingbox is the line height for this font, extending from the top of theascent to the bottom of the descent; information about the actual heightof individual letters is not available. For measurement purposes, alayout that contains no characters is considered to contain asingle zero-width placeholder character at index 0. If index wasnot 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 isnon-zero, and *xPtr, *yPtr, *widthPtr, and*heightPtr are filled with the bounding box information for thecharacter. If any of xPtr, yPtr, widthPtr, orheightPtr are NULL, the corresponding value is not calculated orstored.

Tk_DistanceToTextLayout computes the shortest distance in pixels fromthe given point (x, y) to the characters in layout.Newline/return characters and non-displaying space characters that occur atthe end of individual lines in the text layout are ignored for hit detectionpurposes, but tab characters are not. The return value is 0 if the pointactually hits the layout. If the point didn't hit the layoutthen the return value is the distance in pixels from the point to thelayout.

Tk_IntersectTextLayout determines whether a layout liesentirely inside, entirely outside, or overlaps a given rectangle.Newline/return characters and non-displaying space characters that occurat the end of individual lines in the layout are ignored forintersection calculations. The return value is -1 if the layout isentirely outside of the rectangle, 0 if it overlaps, and 1 if it isentirely inside of the rectangle.

Tk_TextLayoutToPostscript outputs code consisting of a Postscriptarray of strings that represent the individual lines in layout. Itis the responsibility of the caller to take the Postscript array ofstrings and add some Postscript function operate on the array to rendereach of the lines. The code that represents the Postscript array ofstrings is appended to interp->result.

DISPLAY MODEL

When measuring a text layout, space characters that occur at the end of aline are ignored. The space characters still exist and the insertion pointcan be positioned amongst them, but their additional width is ignored whenjustifying lines or returning the total width of a text layout. Allend-of-line space characters are considered to be attached to the right edgeof the line; this behavior is logical for left-justified text and reasonablefor center-justified text, but not very useful when editing right-justifiedtext. Spaces are considered variable width characters; the first space thatextends past the edge of the text layout is clipped to the edge, and anysubsequent spaces on the line are considered zero width and pegged againstthe edge. Space characters that occur in the middle of a line of text arenot suppressed and occupy their normal space width.

Tab characters are not ignored for measurement calculations. If wrappingis turned on and there are enough tabs on a line, the next tab will wrapto the beginning of the next line. There are some possible strangeinteractions between tabs and justification; tab positions are calculatedand the line length computed in a left-justified world, and then thewhole 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 tabcharacters) or newline/returns. A dash or hyphen character in the middleof a word is not considered a word break. Tk_ComputeTextLayoutalways attempts to place at least one word on each line. If it cannotbecause the wrapLength is too small, the word will be broken and asmuch as fits placed on the line and the rest on subsequent line(s). IfwrapLength is so small that not even one character can fit on agiven line, the wrapLength is ignored for that line and onecharacter will be placed on the line anyhow. When wrapping is turnedoff, 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 neveractually drawn - they are merely placeholders maintained in thelayout.

KEYWORDS

font

This document was created byman2html,using the manual pages.