#  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.
#
#

=head1 NAME

Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars - routines to measure and display simple single-line strings.

=for category C Programming

=head1 SYNOPSIS

B<#include E<lt>tk.hE<gt>>

int
B<Tk_MeasureChars(>I<tkfont, string, maxChars, maxPixels, flags, lengthPtr>B<)>

int
B<Tk_TextWidth(>I<tkfont, string, numChars>B<)>

void
B<Tk_DrawChars(>I<display, drawable, gc, tkfont, string, numChars, x, y>B<)>

void
B<Tk_UnderlineChars(>I<display, drawable, gc, tkfont, string, x, y, firstChar, lastChar>B<)>

=head1 ARGUMENTS

=over 4

=item Tk_Font tkfont (in)

Token for font in which text is to be drawn or measured.  Must have been
returned by a previous call to B<Tk_GetFont>.

=item "const char" *string (in)

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.

=item int maxChars (in)

The maximum number of characters to consider when measuring I<string>.
Must be greater than or equal to 0.

=item int maxPixels (in)

If I<maxPixels> is greater than 0, it specifies the longest permissible
line length in pixels.  Characters from I<string> are processed only
until this many pixels have been covered.  If I<maxPixels> is E<lt>= 0, then
the line length is unbounded and the I<flags> argument is ignored.

=item int flags (in)

Various flag bits OR-ed together: TK_PARTIAL_OK means include a character
as long as any part of it fits in the length given by I<maxPixels>;
otherwise, a character must fit completely to be considered.
TK_WHOLE_WORDS means stop on a word boundary, if possible.  If
TK_AT_LEAST_ONE is set, it means return at least one character even if no
characters could fit in the length given by I<maxPixels>.  If
TK_AT_LEAST_ONE is set and TK_WHOLE_WORDS is also set, it means that if
not even one word fits on the line, return the first few letters of the
word that did fit; if not even one letter of the word fit, then the first
letter will still be returned.

=item int *lengthPtr (out)

Filled with the number of pixels occupied by the number of characters
returned as the result of B<Tk_MeasureChars>.

=item int numChars (in)

The total number of characters to measure or draw from I<string>.  Must
be greater than or equal to 0.

=item Display *display (in)

Display on which to draw.

=item Drawable drawable (in)

Window or pixmap in which to draw.

=item GC gc (in)

Graphics context for drawing characters.  The font selected into this GC
must be the same as the I<tkfont>.

=item int "x, y" (in)

Coordinates at which to place the left edge of the baseline when displaying
I<string>.

=item int firstChar (in)

The index of the first character to underline in the I<string>.
Underlining begins at the left edge of this character.

=item int lastChar (in)

The index of the last character up to which the underline will
be drawn.  The character specified by I<lastChar> will not itself be
underlined.

=back

=head1 DESCRIPTION

These routines are for measuring and displaying simple single-font,
single-line, strings.  To measure and display single-font, multi-line,
justified text, refer to the documentation for B<Tk_ComputeTextLayout>.
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.

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.
Characters such as tabs, newlines/returns, and control characters that
have no glyph are measured and displayed by these procedures in a
platform-dependent manner; under X, they are replaced with backslashed
escape sequences, while under Windows and Macintosh hollow or solid boxes
may be substituted.  Refer to the documentation for
B<Tk_ComputeTextLayout> for a programming interface that supports the
platform-independent expansion of tab characters into columns and
newlines/returns into multi-line text.

B<Tk_MeasureChars> 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
I<string> that fit in the space specified by I<maxPixels> subject to
the conditions described by I<flags>.  If all characters fit, the return
value will be I<maxChars>.  I<*lengthPtr> 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 I<*lengthPtr> is filled with the
distance between the left edge of I<string>[0] and the right edge of
I<string>[4].

B<Tk_TextWidth> is a wrapper function that provides a simpler interface
to the B<Tk_MeasureChars> function.  The return value is how much
space in pixels the given I<string> needs.

B<Tk_DrawChars> draws the I<string> at the given location in the
given I<drawable>.

B<Tk_UnderlineChars> underlines the given range of characters in the
given I<string>.  It doesn't draw the characters (which are assumed to
have been displayed previously by B<Tk_DrawChars>); it just draws the
underline.  This procedure is used to underline a few characters without
having to construct an underlined font.  To produce natively underlined
text, the appropriate underlined font should be constructed and used.

=head1 KEYWORDS

font
