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

FreeBSD Manual Pages

  
 
  

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

______________________________________________________________________________

NAME
       Tk_ComputeTextLayout,  Tk_FreeTextLayout,  Tk_DrawTextLayout, Tk_Under-
       lineTextLayout, Tk_PointToChar,	Tk_CharBbox,  Tk_DistanceToTextLayout,
       Tk_IntersectTextLayout, Tk_TextLayoutToPostscript - routines to measure
       and display single-font,	multi-line, justified text.

SYNOPSIS
       #include	<tk.h>

       Tk_TextLayout
       Tk_ComputeTextLayout(tkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr)

       void
       Tk_FreeTextLayout(layout)

       void
       Tk_DrawTextLayout(display, drawable, gc,	layout,	x, y, firstChar, lastChar)

       void
       Tk_UnderlineTextLayout(display, drawable, gc, layout, x,	y, underline)

       int
       Tk_PointToChar(layout, x, y)

       int
       Tk_CharBbox(layout, index, xPtr,	yPtr, widthPtr,	heightPtr)

       int
       Tk_DistanceToTextLayout(layout, x, y)

       int
       Tk_IntersectTextLayout(layout, x, y, width, height)

       void
       Tk_TextLayoutToPostscript(interp, layout)

ARGUMENTS
       Tk_Font tkfont (in)			Font to	use when  constructing
						and  displaying	a text layout.
						The tkfont must	 remain	 valid
						for  the  lifetime of the text
						layout.	 Must  have  been  re-
						turned	by  a previous call to
						Tk_GetFont.

       const char *string (in)			Potentially multi-line	string
						whose  dimensions  are	to  be
						computed  and  stored  in  the
						text  layout.  The string must
						remain valid for the  lifetime
						of the text layout.

       int numChars (in)			The  number  of	 characters to
						consider from string.  If num-
						Chars is less than 0, then as-
						sumes string  is  null	termi-
						nated and uses Tcl_NumUtfChars
						to  determine  the  length  of
						string.

       int wrapLength (in)			Longest	   permissible	  line
						length,	in pixels.   Lines  in
						string	will  automatically be
						broken at word boundaries  and
						wrapped	 when  they reach this
						length.	 If wrapLength is  too
						small  for even	a single char-
						acter to fit  on  a  line,  it
						will  be expanded to allow one
						character to fit on each line.
						If  wrapLength	is <= 0, there
						is  no	 automatic   wrapping;
						lines will get as long as they
						need to	be and only wrap if  a
						newline/return	 character  is
						encountered.

       Tk_Justify justify (in)			How to justify the lines in  a
						multi-line  text layout.  Pos-
						sible	values	 are   TK_JUS-
						TIFY_LEFT,  TK_JUSTIFY_CENTER,
						or  TK_JUSTIFY_RIGHT.  If  the
						text  layout  only  occupies a
						single line, then  justify  is
						irrelevant.

       int flags (in)				Various	 flag  bits  OR-ed to-
						gether.	 TK_IGNORE_TABS	 means
						that tab characters should not
						be expanded to	the  next  tab
						stop.	    TK_IGNORE_NEWLINES
						means	that	newline/return
						characters  should not cause a
						line break.  If	either tabs or
						newlines/returns  are ignored,
						then they will be  treated  as
						regular	characters, being mea-
						sured and displayed in a plat-
						form-dependent	manner	as de-
						scribed	 in   Tk_MeasureChars,
						and  will not have any special
						behaviors.

       int *widthPtr (out)			If non-NULL, filled  with  ei-
						ther  the width, in pixels, of
						the widest line	 in  the  text
						layout,	 or the	width, in pix-
						els, of	the bounding  box  for
						the character specified	by in-
						dex.

       int *heightPtr (out)			If non-NULL, filled  with  ei-
						ther the total height, in pix-
						els, of	all the	lines  in  the
						text layout, or	the height, in
						pixels,	of  the	 bounding  box
						for the	character specified by
						index.

       Tk_TextLayout layout (in)		A token	 that  represents  the
						cached	  layout   information
						about the single-font,	multi-
						line, justified	piece of text.
						This  token  is	 returned   by
						Tk_ComputeTextLayout.

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

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

       GC gc (in)				Graphics context  to  use  for
						drawing	text layout.  The font
						selected in this GC must  cor-
						respond	 to  the  tkfont  used
						when  constructing  the	  text
						layout.

       int x, y	(in)				Point,	in pixels, at which to
						place the upper-left hand cor-
						ner of the text	layout when it
						is being drawn,	or the coordi-
						nates of a point (with respect
						to the upper-left hand	corner
						of  the	 text layout) to check
						against	the text layout.

       int firstChar (in)			The index of the first charac-
						ter  to	 draw  from  the given
						text  layout.	The  number  0
						means  to draw from the	begin-
						ning.

       int lastChar (in)			The index of the last  charac-
						ter  up	to which to draw.  The
						character     specified	    by
						lastChar  itself  will	not be
						drawn.	A number less  than  0
						means  to  draw	all characters
						in the text layout.

       int underline (in)			Index of the single  character
						to  underline in the text lay-
						out, or	a number less  than  0
						for no underline.

       int index (in)				The  index  of	the  character
						whose bounding box is desired.
						The  bounding  box is computed
						with respect to	the upper-left
						hand  corner  of the text lay-
						out.

       int *xPtr, *yPtr	(out)			Filled	with  the   upper-left
						hand corner, in	pixels,	of the
						bounding box for the character
						specified by index.  Either or
						both  xPtr  and	 yPtr  may  be
						NULL, in which case the	corre-
						sponding value is  not	calcu-
						lated.

       int width, height (in)			Specifies    the   width   and
						height,	in pixels, of the rec-
						tangular  area	to compare for
						intersection against the  text
						layout.

       Tcl_Interp *interp (out)			Postscript   code   that  will
						print the text layout  is  ap-
						pended to the result of	inter-
						preter interp.
______________________________________________________________________________

DESCRIPTION
       These routines are for measuring	 and  displaying  single-font,	multi-
       line,  justified	text.  To measure and display simple single-font, sin-
       gle-line	strings,  refer	 to  the  documentation	 for  Tk_MeasureChars.
       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 unlike the lower level text display
       routines, the functions described here all  operate  on	character-ori-
       ented  lengths  and  indices rather than	byte-oriented values.  See the
       description of Tcl_UtfAtIndex for more details  on  converting  between
       character and byte offsets.

       The  routines described here are	built on top of	the programming	inter-
       face described in the Tk_MeasureChars  documentation.   Tab  characters
       and  newline/return characters may be treated specially by these	proce-
       dures, but all other characters are passed through to the lower level.

       Tk_ComputeTextLayout computes the layout	information needed to  display
       a  single-font,	multi-line,  justified	string	of  text and returns a
       Tk_TextLayout token that	holds this information.	 This token is used in
       subsequent  calls to procedures such as Tk_DrawTextLayout, Tk_Distance-
       ToTextLayout, and Tk_FreeTextLayout.  The string	and tkfont  used  when
       computing the layout must remain	valid for the lifetime of this token.

       Tk_FreeTextLayout is called to release the storage associated with lay-
       out when	it is no longer	needed.	 A layout should not be	 used  in  any
       other text layout procedures once it has	been released.

       Tk_DrawTextLayout  uses	the information	in layout to display a single-
       font, multi-line, justified string of text at the specified location.

       Tk_UnderlineTextLayout uses the information in layout to	display	an un-
       derline	below  an  individual character.  This procedure does not draw
       the text, just the underline.  To produce natively underlined text,  an
       underlined  font	 should	 be constructed	and used.  All characters, in-
       cluding tabs, newline/return characters,	and  spaces  at	 the  ends  of
       lines,  can  be	underlined  using this method.	However, the underline
       will never be drawn outside of the computed width of layout; the	under-
       line  will  stop	 at  the edge for any character	that would extend par-
       tially outside of layout, and the underline will	not be visible at  all
       for  any	character that would be	located	completely outside of the lay-
       out.

       Tk_PointToChar uses the information in layout to	determine the  charac-
       ter closest to the given	point.	The point is specified with respect to
       the upper-left hand corner of the layout, which is considered to	be lo-
       cated  at  (0, 0).  Any point whose y-value is less that	0 will be con-
       sidered closest to the first character in the text  layout;  any	 point
       whose  y-value  is  greater  than the height of the text	layout will be
       considered closest to the last character	in the text layout.  Any point
       whose  x-value  is  less	than 0 will be considered closest to the first
       character on that line; any point whose x-value	is  greater  than  the
       width of	the text layout	will be	considered closest to the last charac-
       ter on that line.  The return value is the index	of the character  that
       was  closest  to	the point, or one more than the	index of any character
       (to indicate that the point was after the end of	the  string  and  that
       the  corresponding  caret  would	be at the end of the string).  Given a
       layout with no characters, the value 0 will always be returned,	refer-
       ring to a hypothetical zero-width placeholder character.

       Tk_CharBbox  uses  the information in layout to return the bounding box
       for the character specified by index.  The width	of the bounding	box is
       the  advance  width  of the character, and does not include any left or
       right bearing.  Any character that extends partially outside of	layout
       is considered to	be truncated at	the edge.  Any character that would be
       located completely outside of layout is considered to be	zero-width and
       pegged  against	the  edge.  The	height of the bounding box is the line
       height for this font, extending from the	top of the ascent to the  bot-
       tom  of	the descent; information about the actual height of individual
       letters is not available.  For measurement purposes, a layout that con-
       tains no	characters is considered to contain a single zero-width	place-
       holder character	at index 0.  If	index was not a	valid character	index,
       the  return  value is 0 and *xPtr, *yPtr, *widthPtr, and	*heightPtr are
       unmodified.  Otherwise, if index	did specify a valid, the return	 value
       is  non-zero,  and  *xPtr,  *yPtr, *widthPtr, and *heightPtr are	filled
       with the	bounding box information for the character.  If	any  of	 xPtr,
       yPtr,  widthPtr,	 or heightPtr are NULL,	the corresponding value	is not
       calculated or stored.

       Tk_DistanceToTextLayout computes	the shortest distance in  pixels  from
       the  given  point  (x,  y) to the characters in layout.	Newline/return
       characters and non-displaying space characters that occur at the	end of
       individual  lines in the	text layout are	ignored	for hit	detection pur-
       poses, but tab characters are not.  The return value is 0 if the	 point
       actually	hits the layout.  If the point did not hit the layout then the
       return value is the distance in pixels from the point to	the layout.

       Tk_IntersectTextLayout determines whether a layout  lies	 entirely  in-
       side,  entirely outside,	or overlaps a given rectangle.	Newline/return
       characters and non-displaying space characters that occur at the	end of
       individual  lines  in  the layout are ignored for intersection calcula-
       tions.  The return value	is -1 if the layout is entirely	outside	of the
       rectangle, 0 if it overlaps, and	1 if it	is entirely inside of the rec-
       tangle.

       Tk_TextLayoutToPostscript outputs code consisting of a Postscript array
       of  strings  that  represent the	individual lines in layout.  It	is the
       responsibility of the caller to take the	Postscript  array  of  strings
       and add some Postscript function	operate	on the array to	render each of
       the lines.  The code that represents the	Postscript array of strings is
       appended	to interpreter interp's	result.

DISPLAY	MODEL
       When measuring a	text layout, space characters that occur at the	end of
       a line are ignored.  The	space characters still exist and the insertion
       point can be positioned amongst them, but their additional width	is ig-
       nored when justifying lines or returning	the total width	of a text lay-
       out.  All end-of-line space characters are considered to	be attached to
       the right edge of the line; this	behavior is logical for	left-justified
       text and	reasonable for center-justified	text, but not very useful when
       editing right-justified text.  Spaces  are  considered  variable	 width
       characters; the first space that	extends	past the edge of the text lay-
       out is clipped to the edge, and any subsequent spaces on	the  line  are
       considered  zero	 width	and pegged against the edge.  Space characters
       that occur in the middle	of a line of text are not suppressed  and  oc-
       cupy their normal space width.

       Tab  characters are not ignored for measurement calculations.  If wrap-
       ping is turned on and there are enough tabs on a	 line,	the  next  tab
       will  wrap  to the beginning of the next	line.  There are some possible
       strange interactions between tabs and justification; tab	positions  are
       calculated  and the line	length computed	in a left-justified world, and
       then the	whole resulting	line is	shifted	so it is  centered  or	right-
       justified, causing the tab columns not to align any more.

       When wrapping is	turned on, lines may wrap at word breaks (space	or tab
       characters) or newline/returns.	A dash or hyphen character in the mid-
       dle of a	word is	not considered a word break.  Tk_ComputeTextLayout al-
       ways attempts to	place at least one word	on each	line.	If  it	cannot
       because	the  wrapLength	 is  too small,	the word will be broken	and as
       much as fits placed on the line and the rest on subsequent line(s).  If
       wrapLength  is  so small	that not even one character can	fit on a given
       line, the wrapLength is ignored for that	line and one character will be
       placed  on  the	line  anyhow.	When wrapping is turned	off, only new-
       line/return characters may cause	a line break.

       When a text layout has been created using an  underlined	 tkfont,  then
       any  space  characters  that occur at the end of	individual lines, new-
       lines/returns, and tabs will not	be displayed underlined	when  Tk_Draw-
       TextLayout is called, because those characters are never	actually drawn
       - they are merely placeholders maintained in the	layout.

KEYWORDS
       font

Tk				      8.1	       Tk_ComputeTextLayout(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | DISPLAY MODEL | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk_CharBbox.tk86&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help