Windows PowerShell command on Get-command Tk

Manual Pages for UNIX Operating System command usage for man Tk_CharBbox

Tk Library Procedures Tk_ComputeTextLayout(3TK)

_________________________________________________________________

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_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 pre-

vious call to

Tk_GetFont.

Tk Last change: 8.1 1

Tk Library Procedures Tk_ComputeTextLayout(3TK)

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

acters 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 char-

acter to fit on

each line. If wra-

pLength 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. Tk Last change: 8.1 2

Tk Library Procedures Tk_ComputeTextLayout(3TK)

Possible values are

TK_JUSTIFY_LEFT,

TK_JUSTIFY_CENTER,

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 Tk Last change: 8.1 3

Tk Library Procedures Tk_ComputeTextLayout(3TK)

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, justi-

fied 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 Tk Last change: 8.1 4

Tk Library Procedures Tk_ComputeTextLayout(3TK)

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

line 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 calcu-

lated. int width, height (in) Specifies the width

and height, in pix-

els, of the Tk Last change: 8.1 5

Tk Library Procedures Tk_ComputeTextLayout(3TK)

rectangular area to

compare for inter-

section 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 rou- |

tines, 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 program-

ming interface described in the Tk_MeasureChars documenta-

tion. Tab characters and newline/return characters may be

treated specially by these procedures, but all other charac-

ters 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 pro-

cedures such as Tk_DrawTextLayout, Tk_DistanceToTextLayout,

and Tk_FreeTextLayout. The string and tkfont used when com-

puting the layout must remain valid for the lifetime of this token.

Tk_FreeTextLayout is called to release the storage associ-

ated 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 Last change: 8.1 6

Tk Library Procedures Tk_ComputeTextLayout(3TK)

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

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

acters, 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 char-

acter, and does not include any left or right bearing. Any

character that extends partially outside of layout is con-

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

tains 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 correspond-

ing value is not calculated or stored. Tk Last change: 8.1 7

Tk Library Procedures Tk_ComputeTextLayout(3TK)

Tk_DistanceToTextLayout computes the shortest distance in

pixels from the given point (x, y) to the characters in lay-

out. 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 didn't hit the lay-

out 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 rec-

tangle. 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. Tk Last change: 8.1 8

Tk Library Procedures Tk_ComputeTextLayout(3TK)

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

acter 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

ATTRIBUTES

See attributes(5) for descriptions of the following attri-

butes:

_______________________________________

| ATTRIBUTE TYPE | ATTRIBUTE VALUE|

|____________________|__________________|_

| Availability | runtime/tk-8 |

|____________________|__________________|_

| Interface Stability| Uncommitted |

|____________________|_________________|

NOTES Source for Tk is available on http://opensolaris.org. Tk Last change: 8.1 9