通讯编程

开发平台：
Visual C++

TextLayout.3：源码内容
							'"
'" 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.
'" 
'" RCS: @(#) $Id: TextLayout.3,v 1.5 1999/04/21 21:53:22 rjohnson Exp $
'" 
.so man.macros
.TH Tk_ComputeTextLayout 3 8.1 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, heightPtrfB)fR
.sp
void
fBTk_FreeTextLayout(fIlayoutfB)fR
.sp
void
fBTk_DrawTextLayout(fIdisplay, drawable, gc, layout, x, y, firstChar, lastCharfB)fR
.sp
void
fBTk_UnderlineTextLayout(fIdisplay, drawable, gc, layout, x, y, underlinefB)fR
.sp
int
fBTk_PointToChar(fIlayout, x, yfB)fR
.sp
int
fBTk_CharBbox(fIlayout, index, xPtr, yPtr, widthPtr, heightPtrfB)fR
.sp
int
fBTk_DistanceToTextLayout(fIlayout, x, yfB)fR
.sp
int
fBTk_IntersectTextLayout(fIlayout, x, y, width, heightfB)fR
.sp
void
fBTk_TextLayoutToPostscript(fIinterp, layoutfB)fR
.SH ARGUMENTS
.AS Tk_TextLayout "*xPtr, *yPtr"
.AP Tk_Font tkfont in
Font to use when constructing and displaying a text layout.  The
fItkfontfR must remain valid for the lifetime of the text layout.  Must
have been returned by a previous call to fBTk_GetFontfR.
.AP "const char" *string in
Potentially multi-line string whose dimensions are to be computed and
stored in the text layout.  The fIstringfR must remain valid for the
lifetime of the text layout.  
.AP int numChars in
The number of characters to consider from fIstringfR.  If
fInumCharsfR is less than 0, then assumes fIstringfR is null
.VS 8.1
terminated and uses fBTcl_NumUtfCharsfR to determine the length of
fIstringfR.
.VE
.AP int wrapLength in
Longest permissible line length, in pixels.  Lines in fIstringfR will
automatically be broken at word boundaries and wrapped when they reach
this length.  If fIwrapLengthfR 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 fIwrapLengthfR 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 fIjustifyfR 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_MeasureCharsfR, 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 fIindexfR.
.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 fIindexfR.
.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_ComputeTextLayoutfR.
.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 fItkfontfR 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 fIlastCharfR 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 fIindexfR.  Either or both fIxPtrfR
and fIyPtrfR 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->resultfR.
.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_MeasureCharsfR.  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.  
.VS 8.1
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
fBTcl_UtfAtIndexfR for more details on converting between character
and byte offsets.
.VE 8.1
.PP
The routines described here are built on top of the programming interface
described in the fBTk_MeasureCharsfR 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_ComputeTextLayoutfR computes the layout information needed to
display a single-font, multi-line, justified fIstringfR of text and
returns a Tk_TextLayout token that holds this information.  This token is
used in subsequent calls to procedures such as fBTk_DrawTextLayoutfR,
fBTk_DistanceToTextLayoutfR, and fBTk_FreeTextLayoutfR.  The
fIstringfR and fItkfontfR used when computing the layout must remain
valid for the lifetime of this token.  
.PP
fBTk_FreeTextLayoutfR is called to release the storage associated with
fIlayoutfR when it is no longer needed.  A fIlayoutfR should not be used
in any other text layout procedures once it has been released. 
.PP
fBTk_DrawTextLayoutfR uses the information in fIlayoutfR to display a
single-font, multi-line, justified string of text at the specified location.
.PP
fBTk_UnderlineTextLayoutfR uses the information in fIlayoutfR 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 fIlayoutfR; the
underline will stop at the edge for any character that would extend
partially outside of fIlayoutfR, and the underline will not be visible
at all for any character that would be located completely outside of the
layout.
.PP
fBTk_PointToCharfR uses the information in fIlayoutfR to determine the
character closest to the given point.  The point is specified with respect
to the upper-left hand corner of the fIlayoutfR, which is considered to be
located at (0, 0).  Any point whose fIyfR-value is less that 0 will be
considered closest to the first character in the text layout; any point
whose fIyfR-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 fIxfR-value is less than 0 will be considered closest to the first
character on that line; any point whose fIxfR-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 fIlayoutfR with no characters, the value 0 will
always be returned, referring to a hypothetical zero-width placeholder
character.  
.PP
fBTk_CharBboxfR uses the information in fIlayoutfR to return the
bounding box for the character specified by fIindexfR.  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 
fIlayoutfR is considered to be truncated at the edge.  Any character
that would be located completely outside of fIlayoutfR 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
fIlayoutfR that contains no characters is considered to contain a
single zero-width placeholder character at index 0.  If fIindexfR was
not a valid character index, the return value is 0 and fI*xPtrfR,
fI*yPtrfR, fI*widthPtrfR, and fI*heightPtrfR are unmodified.
Otherwise, if fIindexfR did specify a valid, the return value is
non-zero, and fI*xPtrfR, fI*yPtrfR, fI*widthPtrfR, and
fI*heightPtrfR are filled with the bounding box information for the
character.  If any of fIxPtrfR, fIyPtrfR, fIwidthPtrfR, or
fIheightPtrfR are NULL, the corresponding value is not calculated or
stored.
.PP
fBTk_DistanceToTextLayoutfR computes the shortest distance in pixels from
the given point (fIx, yfR) to the characters in fIlayoutfR.
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 fIlayoutfR.  If the point didn't hit the fIlayoutfR
then the return value is the distance in pixels from the point to the
fIlayoutfR.
.PP
fBTk_IntersectTextLayoutfR determines whether a fIlayoutfR 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 fIlayoutfR are ignored for
intersection calculations.  The return value is -1 if the fIlayoutfR is
entirely outside of the rectangle, 0 if it overlaps, and 1 if it is
entirely inside of the rectangle.
.PP
fBTk_TextLayoutToPostscriptfR outputs code consisting of a Postscript
array of strings that represent the individual lines in fIlayoutfR.  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->resultfR.
.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_ComputeTextLayoutfR
always attempts to place at least one word on each line.  If it cannot
because the fIwrapLengthfR 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
fIwrapLengthfR is so small that not even one character can fit on a
given line, the fIwrapLengthfR 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 fItkfontfR,
then any space characters that occur at the end of individual lines,
newlines/returns, and tabs will not be displayed underlined when 
fBTk_DrawTextLayoutfR is called, because those characters are never
actually drawn - they are merely placeholders maintained in the
fIlayoutfR.  
.SH KEYWORDS
font

						