diff options
Diffstat (limited to 'doc/TextLayout.3')
| -rw-r--r-- | doc/TextLayout.3 | 270 |
1 files changed, 270 insertions, 0 deletions
diff --git a/doc/TextLayout.3 b/doc/TextLayout.3 new file mode 100644 index 0000000..d4a8399 --- /dev/null +++ b/doc/TextLayout.3 @@ -0,0 +1,270 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) TextLayout.3 1.6 96/12/16 16:48:12 +'\" +.so man.macros +.TH Tk_ComputeTextLayout 3 "" Tk "Tk Library Procedures" +.BS +.SH 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. +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_TextLayout +\fBTk_ComputeTextLayout(\fItkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr\fB)\fR +.sp +void +\fBTk_FreeTextLayout(\fIlayout\fB)\fR +.sp +void +\fBTk_DrawTextLayout(\fIdisplay, drawable, gc, layout, x, y, firstChar, lastChar\fB)\fR +.sp +void +\fBTk_UnderlineTextLayout(\fIdisplay, drawable, gc, layout, x, y, underline\fB)\fR +.sp +int +\fBTk_PointToChar(\fIlayout, x, y\fB)\fR +.sp +int +\fBTk_CharBbox(\fIlayout, index, xPtr, yPtr, widthPtr, heightPtr\fB)\fR +.sp +int +\fBTk_DistanceToTextLayout(\fIlayout, x, y\fB)\fR +.sp +int +\fBTk_IntersectTextLayout(\fIlayout, x, y, width, height\fB)\fR +.sp +void +\fBTk_TextLayoutToPostscript(\fIinterp, layout\fB)\fR + +.SH ARGUMENTS +.AS Tk_TextLayout "*xPtr, *yPtr" +.AP Tk_Font tkfont in +Font to use when constructing and displaying a text layout. The +\fItkfont\fR must remain valid for the lifetime of the text layout. Must +have been returned by a previous call to \fBTk_GetFont\fR. +.AP "const char" *string in +Potentially multi-line string whose dimensions are to be computed and +stored in the text layout. The \fIstring\fR must remain valid for the +lifetime of the text layout. +.AP int numChars in +The number of characters to consider from \fIstring\fR. If +\fInumChars\fR is less than 0, then assumes \fIstring\fR is null +terminated and uses \fBstrlen(\fIstring\fB)\fR. +.AP int wrapLength in +Longest permissible line length, in pixels. Lines in \fIstring\fR will +automatically be broken at word boundaries and wrapped when they reach +this length. If \fIwrapLength\fR 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 \fIwrapLength\fR 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. +.AP 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 \fIjustify\fR is irrelevant. +.AP 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 \fBTk_MeasureChars\fR, and will not have any special behaviors. +.AP 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 \fIindex\fR. +.AP 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 \fIindex\fR. +.AP 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 +\fBTk_ComputeTextLayout\fR. +.AP Display *display in +Display on which to draw. +.AP Drawable drawable in +Window or pixmap in which to draw. +.AP GC gc in +Graphics context to use for drawing text layout. The font selected in +this GC must correspond to the \fItkfont\fR used when constructing the +text layout. +.AP 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. +.AP 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. +.AP int lastChar in +The index of the last character up to which to draw. The character +specified by \fIlastChar\fR itself will not be drawn. A number less +than 0 means to draw all characters in the text layout. +.AP int underline in +Index of the single character to underline in the text layout, or a number +less than 0 for no underline. +.AP 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. +.AP int "*xPtr, *yPtr" out +Filled with the upper-left hand corner, in pixels, of the bounding box +for the character specified by \fIindex\fR. Either or both \fIxPtr\fR +and \fIyPtr\fR may be NULL, in which case the corresponding value +is not calculated. +.AP int "width, height" in +Specifies the width and height, in pixels, of the rectangular area to +compare for intersection against the text layout. +.AP Tcl_Interp *interp out +Postscript code that will print the text layout is appended to +\fIinterp->result\fR. +.BE + +.SH DESCRIPTION +.PP +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 \fBTk_MeasureChars\fR. 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. +.PP +The routines described here are built on top of the programming interface +described in the \fBTk_MeasureChars\fR 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. +.PP +\fBTk_ComputeTextLayout\fR computes the layout information needed to +display a single-font, multi-line, justified \fIstring\fR of text and +returns a Tk_TextLayout token that holds this information. This token is +used in subsequent calls to procedures such as \fBTk_DrawTextLayout\fR, +\fBTk_DistanceToTextLayout\fR, and \fBTk_FreeTextLayout\fR. The +\fIstring\fR and \fItkfont\fR used when computing the layout must remain +valid for the lifetime of this token. +.PP +\fBTk_FreeTextLayout\fR is called to release the storage associated with +\fIlayout\fR when it is no longer needed. A \fIlayout\fR should not be used +in any other text layout procedures once it has been released. +.PP +\fBTk_DrawTextLayout\fR uses the information in \fIlayout\fR to display a +single-font, multi-line, justified string of text at the specified location. +.PP +\fBTk_UnderlineTextLayout\fR uses the information in \fIlayout\fR 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 \fIlayout\fR; the +underline will stop at the edge for any character that would extend +partially outside of \fIlayout\fR, and the underline will not be visible +at all for any character that would be located completely outside of the +layout. +.PP +\fBTk_PointToChar\fR uses the information in \fIlayout\fR to determine the +character closest to the given point. The point is specified with respect +to the upper-left hand corner of the \fIlayout\fR, which is considered to be +located at (0, 0). Any point whose \fIy\fR-value is less that 0 will be +considered closest to the first character in the text layout; any point +whose \fIy\fR-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 \fIx\fR-value is less than 0 will be considered closest to the first +character on that line; any point whose \fIx\fR-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 \fIlayout\fR with no characters, the value 0 will +always be returned, referring to a hypothetical zero-width placeholder +character. +.PP +\fBTk_CharBBox\fR uses the information in \fIlayout\fR to return the +bounding box for the character specified by \fIindex\fR. 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 +\fIlayout\fR is considered to be truncated at the edge. Any character +that would be located completely outside of \fIlayout\fR 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 +\fIlayout\fR that contains no characters is considered to contain a +single zero-width placeholder character at index 0. If \fIindex\fR was +not a valid character index, the return value is 0 and \fI*xPtr\fR, +\fI*yPtr\fR, \fI*widthPtr\fR, and \fI*heightPtr\fR are unmodified. +Otherwise, if \fIindex\fR did specify a valid, the return value is +non-zero, and \fI*xPtr\fR, \fI*yPtr\fR, \fI*widthPtr\fR, and +\fI*heightPtr\fR are filled with the bounding box information for the +character. If any of \fIxPtr\fR, \fIyPtr\fR, \fIwidthPtr\fR, or +\fIheightPtr\fR are NULL, the corresponding value is not calculated or +stored. +.PP +\fBTk_DistanceToTextLayout\fR computes the shortest distance in pixels from +the given point (\fIx, y\fR) to the characters in \fIlayout\fR. +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 \fIlayout\fR. If the point didn't hit the \fIlayout\fR +then the return value is the distance in pixels from the point to the +\fIlayout\fR. +.PP +\fBTk_IntersectTextLayout\fR determines whether a \fIlayout\fR 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 \fIlayout\fR are ignored for +intersection calculations. The return value is \-1 if the \fIlayout\fR is +entirely outside of the rectangle, 0 if it overlaps, and 1 if it is +entirely inside of the rectangle. +.PP +\fBTk_TextLayoutToPostscript\fR outputs code consisting of a Postscript +array of strings that represent the individual lines in \fIlayout\fR. 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 \fIinterp->result\fR. +.PP +.SH 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. +.PP +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. +.PP +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. \fBTk_ComputeTextLayout\fR +always attempts to place at least one word on each line. If it cannot +because the \fIwrapLength\fR 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 +\fIwrapLength\fR is so small that not even one character can fit on a +given line, the \fIwrapLength\fR 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. +.PP +When a text layout has been created using an underlined \fItkfont\fR, +then any space characters that occur at the end of individual lines, +newlines/returns, and tabs will not be displayed underlined when +\fBTk_DrawTextLayout\fR is called, because those characters are never +actually drawn \- they are merely placeholders maintained in the +\fIlayout\fR. +.SH KEYWORDS +font |