1Tk_MeasureChars(3)           Tk Library Procedures          Tk_MeasureChars(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tk_MeasureChars,  Tk_TextWidth,  Tk_DrawChars, Tk_UnderlineChars - rou‐
9       tines to measure and display simple single-line strings.
10

SYNOPSIS

12       #include <tk.h>
13
14       int
15       Tk_MeasureChars(tkfont, string, numBytes, maxPixels, flags, lengthPtr)
16
17       int
18       Tk_TextWidth(tkfont, string, numBytes)
19
20       Tk_DrawChars(display, drawable, gc, tkfont, string, numBytes, x, y)
21
22       Tk_UnderlineChars(display, drawable, gc, tkfont, string, x, y, firstByte, lastByte)
23
24

ARGUMENTS

26       Tk_Font tkfont (in)                Token for font in which text  is  to
27                                          be  drawn  or  measured.   Must have
28                                          been returned by a previous call  to
29                                          Tk_GetFont.
30
31       const char *string (in)            Text  to  be  measured or displayed.
32                                          Need not be  null  terminated.   Any
33                                          non-printing  meta-characters in the
34                                          string (such as tabs, newlines,  and
35                                          other  control  characters)  will be
36                                          measured or displayed in a platform-
37                                          dependent manner.
38
39       int numBytes (in)                  The  maximum number of bytes to con‐
40                                          sider  when  measuring  or   drawing
41                                          string.   Must  be  greater  than or
42                                          equal to 0.
43
44       int maxPixels (in)                 If maxPixels is >= 0,  it  specifies
45                                          the  longest permissible line length
46                                          in pixels.  Characters  from  string
47                                          are  processed  only until this many
48                                          pixels have been covered.   If  max‐
49                                          Pixels  is < 0, then the line length
50                                          is unbounded and the flags  argument
51                                          is ignored.
52
53       int flags (in)                     Various  flag  bits  OR-ed together:
54                                          TK_PARTIAL_OK means include a  char‐
55                                          acter as long as any part of it fits
56                                          in the length  given  by  maxPixels;
57                                          otherwise, a character must fit com‐
58                                          pletely    to     be     considered.
59                                          TK_WHOLE_WORDS  means stop on a word
60                                          boundary,    if    possible.      If
61                                          TK_AT_LEAST_ONE  is  set,  it  means
62                                          return at least one  character  even
63                                          if  no  characters  could fit in the
64                                          length  given  by   maxPixels.    If
65                                          TK_AT_LEAST_ONE     is    set    and
66                                          TK_WHOLE_WORDS is also set, it means
67                                          that  if  not  even one word fits on
68                                          the line, return the first few  let‐
69                                          ters  of  the  word that did fit; if
70                                          not even one letter of the word fit,
71                                          then  the first letter will still be
72                                          returned.
73
74       int *lengthPtr (out)               Filled with  the  number  of  pixels
75                                          occupied by the number of characters
76                                          returned as the  result  of  Tk_Mea‐
77                                          sureChars.
78
79       Display *display (in)              Display on which to draw.
80
81       Drawable drawable (in)             Window or pixmap in which to draw.
82
83       GC gc (in)                         Graphics context for drawing charac‐
84                                          ters.  The font selected  into  this
85                                          GC must be the same as the tkfont.
86
87       int x, y (in)                      Coordinates  at  which  to place the
88                                          left edge of the baseline when  dis‐
89                                          playing string.
90
91       int firstByte (in)                 The  index  of the first byte of the
92                                          first character to underline in  the
93                                          string.   Underlining  begins at the
94                                          left edge of this character.
95
96       int lastByte (in)                  The index of the first byte  of  the
97                                          last   character  up  to  which  the
98                                          underline will be drawn.  The  char‐
99                                          acter specified by lastByte will not
100                                          itself be underlined.
101______________________________________________________________________________
102

DESCRIPTION

104       These routines are for measuring  and  displaying  simple  single-font,
105       single-line  strings.   To measure and display single-font, multi-line,
106       justified text, refer to the  documentation  for  Tk_ComputeTextLayout.
107       There  is  no  programming  interface  in  the core of Tk that supports
108       multi-font, multi-line text; support for that behavior must be built on
109       top  of  simpler  layers.   Note that the interfaces described here are
110       byte-oriented not character-oriented, so index values coming  from  Tcl
111       scripts  need  to be converted to byte offsets using the Tcl_UtfAtIndex
112       and related routines.
113
114       A glyph is the displayable picture of a letter, number, or  some  other
115       symbol.  Not all character codes in a given font have a glyph.  Charac‐
116       ters such as tabs, newlines/returns, and control characters  that  have
117       no  glyph are measured and displayed by these procedures in a platform-
118       dependent manner; under X, they are replaced  with  backslashed  escape
119       sequences,  while under Windows and Macintosh hollow or solid boxes may
120       be substituted.  Refer to the  documentation  for  Tk_ComputeTextLayout
121       for  a  programming  interface  that  supports the platform-independent
122       expansion of tab characters  into  columns  and  newlines/returns  into
123       multi-line text.
124
125       Tk_MeasureChars  is  used  both to compute the length of a given string
126       and to compute how many characters from a string fit in a given  amount
127       of space.  The return value is the number of bytes from string that fit
128       in the space specified by maxPixels subject to the conditions described
129       by  flags.   If  all characters fit, the return value will be numBytes.
130       *lengthPtr is filled with the computed width, in pixels, of the portion
131       of  the  string that was measured.  For example, if the return value is
132       5, then *lengthPtr is filled with the distance between the left edge of
133       string[0] and the right edge of string[4].
134
135       Tk_TextWidth is a wrapper function that provides a simpler interface to
136       the Tk_MeasureChars function.  The return value is how  much  space  in
137       pixels the given string needs.
138
139       Tk_DrawChars  draws the string at the given location in the given draw‐
140       able.
141
142       Tk_UnderlineChars underlines the given range of characters in the given
143       string.   It  does  not  draw the characters (which are assumed to have
144       been displayed previously by Tk_DrawChars); it just  draws  the  under‐
145       line.   This  procedure  is  used to underline a few characters without
146       having to construct an underlined font.  To produce natively underlined
147       text, the appropriate underlined font should be constructed and used.
148

SEE ALSO

150       font(n), FontId(3)
151

KEYWORDS

153       font, measurement
154
155
156
157Tk                                    8.1                   Tk_MeasureChars(3)
Impressum