<HTML><HEAD><TITLE>Library Procedures - Tk_MeasureChars manual page</TITLE></HEAD><BODY> <H3><A NAME="M2">NAME</A></H3> Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars - routines to measure and display simple single-line strings. <H3><A NAME="M3">SYNOPSIS</A></H3> <B>#include <tk.h></B><BR> int<BR> <B>Tk_MeasureChars(</B><I>tkfont, string, maxChars, maxPixels, flags, lengthPtr</I><B>)</B><BR> int<BR> <B>Tk_TextWidth(</B><I>tkfont, string, numChars</I><B>)</B><BR> void<BR> <B>Tk_DrawChars(</B><I>display, drawable, gc, tkfont, string, numChars, x, y</I><B>)</B><BR> void<BR> <B>Tk_UnderlineChars(</B><I>display, drawable, gc, tkfont, string, x, y, firstChar, lastChar</I><B>)</B><BR> <H3><A NAME="M4">ARGUMENTS</A></H3> <DL> <P><DT>Tk_Font <B>tkfont</B> (in)<DD> Token for font in which text is to be drawn or measured. Must have been returned by a previous call to <B><A HREF="../TkLib/GetFont.htm">Tk_GetFont</A></B>. <P><DT>const char <B>*string</B> (in)<DD> 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. <P><DT>int <B>maxChars</B> (in)<DD> The maximum number of characters to consider when measuring <I>string</I>. Must be greater than or equal to 0. <P><DT>int <B>maxPixels</B> (in)<DD> If <I>maxPixels</I> is greater than 0, it specifies the longest permissible line length in pixels. Characters from <I>string</I> are processed only until this many pixels have been covered. If <I>maxPixels</I> is <= 0, then the line length is unbounded and the <I>flags</I> argument is ignored. <P><DT>int <B>flags</B> (in)<DD> 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</I>; 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</I>. 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. <P><DT>int <B>*lengthPtr</B> (out)<DD> Filled with the number of pixels occupied by the number of characters returned as the result of <B>Tk_MeasureChars</B>. <P><DT>int <B>numChars</B> (in)<DD> The total number of characters to measure or draw from <I>string</I>. Must be greater than or equal to 0. <P><DT>Display <B>*display</B> (in)<DD> Display on which to draw. <P><DT>Drawable <B>drawable</B> (in)<DD> Window or pixmap in which to draw. <P><DT>GC <B>gc</B> (in)<DD> Graphics context for drawing characters. The font selected into this GC must be the same as the <I>tkfont</I>. <P><DT>int <B>x, y</B> (in)<DD> Coordinates at which to place the left edge of the baseline when displaying <I>string</I>. <P><DT>int <B>firstChar</B> (in)<DD> The index of the first character to underline in the <I>string</I>. Underlining begins at the left edge of this character. <P><DT>int <B>lastChar</B> (in)<DD> The index of the last character up to which the underline will be drawn. The character specified by <I>lastChar</I> will not itself be underlined. <P></DL> <H3><A NAME="M5">DESCRIPTION</A></H3> 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><A HREF="../TkLib/TextLayout.htm">Tk_ComputeTextLayout</A></B>. 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. <P> 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><A HREF="../TkLib/TextLayout.htm">Tk_ComputeTextLayout</A></B> for a programming interface that supports the platform-independent expansion of tab characters into columns and newlines/returns into multi-line text. <P> <B>Tk_MeasureChars</B> 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</I> that fit in the space specified by <I>maxPixels</I> subject to the conditions described by <I>flags</I>. If all characters fit, the return value will be <I>maxChars</I>. <I>*lengthPtr</I> 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</I> is filled with the distance between the left edge of <I>string</I>[0] and the right edge of <I>string</I>[4]. <P> <B>Tk_TextWidth</B> is a wrapper function that provides a simpler interface to the <B>Tk_MeasureChars</B> function. The return value is how much space in pixels the given <I>string</I> needs. <P> <B>Tk_DrawChars</B> draws the <I>string</I> at the given location in the given <I>drawable</I>. <P> <B>Tk_UnderlineChars</B> underlines the given range of characters in the given <I>string</I>. It doesn't draw the characters (which are assumed to have been displayed previously by <B>Tk_DrawChars</B>); 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. <H3><A NAME="M6">KEYWORDS</A></H3> <A href="../Keywords/F.htm#font">font</A> <HR><PRE> <A HREF="../copyright.htm">Copyright</A> © 1996 Sun Microsystems, Inc. <A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE> </BODY></HTML>