* Merged 8.1 branch into the main trunk

1 files changed, 29 insertions, 22 deletions

diff --git a/doc/MeasureChar.3 b/doc/MeasureChar.3
index 53baf88..2df934c 100644
--- a/doc/MeasureChar.3
+++ b/doc/MeasureChar.3
@@ -4,10 +4,10 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: MeasureChar.3,v 1.2 1998/09/14 18:22:52 stanton Exp $
+'\" RCS: @(#) $Id: MeasureChar.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_MeasureChars 3 "" Tk "Tk Library Procedures"
+.TH Tk_MeasureChars 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
 Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to measure and display simple single-line strings.
@@ -16,16 +16,16 @@ Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to me
 \fB#include <tk.h>\fR
 .sp
 int
-\fBTk_MeasureChars(\fItkfont, string, maxChars, maxPixels, flags, lengthPtr\fB)\fR
+\fBTk_MeasureChars(\fItkfont, string, numBytes, maxPixels, flags, lengthPtr\fB)\fR
 .sp
 int
-\fBTk_TextWidth(\fItkfont, string, numChars\fB)\fR
+\fBTk_TextWidth(\fItkfont, string, numBytes\fB)\fR
 .sp
 void
-\fBTk_DrawChars(\fIdisplay, drawable, gc, tkfont, string, numChars, x, y\fB)\fR
+\fBTk_DrawChars(\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y\fB)\fR
 .sp
 void
-\fBTk_UnderlineChars(\fIdisplay, drawable, gc, tkfont, string, x, y, firstChar, lastChar\fB)\fR
+\fBTk_UnderlineChars(\fIdisplay, drawable, gc, tkfont, string, x, y, firstByte, lastByte\fB)\fR
 .sp
 .SH ARGUMENTS
 .AS "const char" firstChar
@@ -37,9 +37,11 @@ Text to be measured or displayed.  Need not be null terminated.  Any
 non-printing meta-characters in the string (such as tabs, newlines, and
 other control characters) will be measured or displayed in a
 platform-dependent manner.  
-.AP int maxChars in
-The maximum number of characters to consider when measuring \fIstring\fR.
-Must be greater than or equal to 0.
+.VS 8.1
+.AP int numBytes in
+The maximum number of bytes to consider when measuring or drawing
+\fIstring\fR.  Must be greater than or equal to 0.
+.VE 8.1
 .AP int maxPixels in
 If \fImaxPixels\fR is greater than 0, it specifies the longest permissible
 line length in pixels.  Characters from \fIstring\fR are processed only
@@ -59,9 +61,6 @@ letter will still be returned.
 .AP int *lengthPtr out
 Filled with the number of pixels occupied by the number of characters
 returned as the result of \fBTk_MeasureChars\fR.
-.AP int numChars in
-The total number of characters to measure or draw from \fIstring\fR.  Must
-be greater than or equal to 0.
 .AP Display *display in
 Display on which to draw.
 .AP Drawable drawable in
@@ -72,13 +71,15 @@ must be the same as the \fItkfont\fR.
 .AP int "x, y" in
 Coordinates at which to place the left edge of the baseline when displaying
 \fIstring\fR.  
-.AP int firstChar in
-The index of the first character to underline in the \fIstring\fR.  
-Underlining begins at the left edge of this character.
-.AP int lastChar in
-The index of the last character up to which the underline will 
-be drawn.  The character specified by \fIlastChar\fR will not itself be
-underlined.
+.VS 8.1
+.AP int firstByte in
+The index of the first byte of the first character to underline in the
+\fIstring\fR.  Underlining begins at the left edge of this character.
+.AP int lastByte in
+The index of the first byte of the last character up to which the
+underline will be drawn.  The character specified by \fIlastByte\fR
+will not itself be underlined.
+.VE 8.1
 .BE
 
 .SH DESCRIPTION
@@ -88,7 +89,13 @@ single-line, strings.  To measure and display single-font, multi-line,
 justified text, refer to the documentation for \fBTk_ComputeTextLayout\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.
+top of simpler layers.  
+.VS 8.1
+Note that the interfaces described here are
+byte-oriented not character-oriented, so index values coming from Tcl
+scripts need to be converted to byte offsets using the
+\fBTcl_UtfAtIndex\fR and related routines.
+.VE 8.1
 .PP
 A glyph is the displayable picture of a letter, number, or some other
 symbol.  Not all character codes in a given font have a glyph.
@@ -103,10 +110,10 @@ newlines/returns into multi-line text.
 .PP
 \fBTk_MeasureChars\fR is used both to compute the length of a given
 string and to compute how many characters from a string fit in a given
-amount of space.  The return value is the number of characters from
+amount of space.  The return value is the number of bytes from
 \fIstring\fR that fit in the space specified by \fImaxPixels\fR subject to
 the conditions described by \fIflags\fR.  If all characters fit, the return
-value will be \fImaxChars\fR.  \fI*lengthPtr\fR is filled with the computed
+value will be \fInumBytes\fR.  \fI*lengthPtr\fR is filled with the computed
 width, in pixels, of the portion of the string that was measured.  For
 example, if the return value is 5, then \fI*lengthPtr\fR is filled with the
 distance between the left edge of \fIstring\fR[0] and the right edge of