Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

Tk_MeasureChars(3)                          Tk Library Procedures                         Tk_MeasureChars(3)



____________________________________________________________________________________________________________

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

SYNOPSIS
       #include <tk.h>

       int
       Tk_MeasureChars(tkfont, string, numBytes, maxPixels, flags, lengthPtr)

       int
       Tk_TextWidth(tkfont, string, numBytes)

       Tk_DrawChars(display, drawable, gc, tkfont, string, numBytes, x, y)

       Tk_UnderlineChars(display, drawable, gc, tkfont, string, x, y, firstByte, lastByte)


ARGUMENTS
       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 Tk_GetFont.

       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, new-lines, newlines,
                                          lines, and other control characters) will be measured or displayed
                                          in a platform-dependent manner.

       int numBytes (in)                  The maximum number of bytes to consider when measuring or  drawing
                                          string.  Must be greater than or equal to 0.

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

       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
                                          maxPixels; otherwise, a character must fit completely to  be  con-
                                          sidered.   TK_WHOLE_WORDS means stop on a word boundary, if possi-ble. possible.
                                          ble.  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
                                          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.

       int *lengthPtr (out)               Filled with the number of pixels occupied by the number of charac-ters characters
                                          ters returned as the result of Tk_MeasureChars.

       Display *display (in)              Display on which to draw.

       Drawable drawable (in)             Window or pixmap in which to draw.

       GC gc (in)                         Graphics  context  for drawing characters.  The font selected into
                                          this GC must be the same as the tkfont.

       int x, y (in)                      Coordinates at which to place the left edge of the  baseline  when
                                          displaying string.

       int firstByte (in)                 The index of the first byte of the first character to underline in
                                          the string.  Underlining begins at the left edge of  this  charac-ter. character.
                                          ter.

       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 lastByte will
                                          not itself be underlined.
____________________________________________________________________________________________________________

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  Tk_ComputeText-Layout. Tk_ComputeTextLayout.
       Layout.   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.   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 Tcl_UtfAtIndex and related routines.

       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 charac-ters characters
       ters that have no glyph are measured and displayed by these procedures in a  platform-dependent  man-ner; manner;
       ner;  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 Tk_ComputeTextLayout for  a
       programming interface that supports the platform-independent expansion of tab characters into columns
       and newlines/returns into multi-line text.

       Tk_MeasureChars is used both to compute the length of a given string and to compute how many  charac-ters characters
       ters  from  a  string  fit  in a given amount of space.  The return value is the number of bytes from
       string that fit in the space specified by maxPixels subject to the conditions described by flags.  If
       all characters fit, the return value will be numBytes.  *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  *lengthPtr is filled with the distance between the left edge of string[0] and the right edge of
       string[4].

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

       Tk_DrawChars draws the string at the given location in the given drawable.

       Tk_UnderlineChars underlines the given range of characters in the given string.  It does not draw the
       characters (which are assumed to have been displayed previously by 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 con-structed constructed
       structed and used.

SEE ALSO
       font(n), FontId(3)

KEYWORDS
       font, measurement



Tk                                                   8.1                                  Tk_MeasureChars(3)