Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Tk_MeasureChars(3)	     Tk	Library	Procedures	    Tk_MeasureChars(3)


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

       #include	<tk.h>

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

       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)

       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

       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.

       int numBytes (in)		  The  maximum number of bytes to con-
					  sider	 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  max-
					  Pixels  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	 char-
					  acter	as long	as any part of it fits
					  in the length	 given	by  maxPixels;
					  otherwise, a character must fit com-
					  pletely    to	    be	   considered.
					  TK_WHOLE_WORDS  means	stop on	a word
					  boundary,    if    possible.	    If
					  TK_AT_LEAST_ONE is set, it means re-
					  turn 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  let-
					  ters	of  the	 word that did fit; if
					  not even one letter of the word fit,
					  then	the first letter will still be

       int *lengthPtr (out)		  Filled with the number of pixels oc-
					  cupied  by  the number of characters
					  returned as the  result  of  Tk_Mea-

       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 charac-
					  ters.	 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  dis-
					  playing 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 character.

       int lastByte (in)		  The index of the first byte  of  the
					  last	character  up to which the un-
					  derline will be drawn.  The  charac-
					  ter  specified  by lastByte will not
					  itself be underlined.

       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_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.   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.  Charac-
       ters 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  Tk_ComputeTextLayout
       for  a programming interface that supports the platform-independent ex-
       pansion 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 characters 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 draw-

       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	under-
       line.   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.

       font(n),	FontId(3)

       font, measurement

Tk				      8.1		    Tk_MeasureChars(3)


Want to link to this manual page? Use this URL:

home | help