Tk_CharBbox man page on aLinux

Man page or keyword search:  
man Server   7435 pages
apropos Keyword Search (all sections)
Output format
aLinux logo
[printable version]

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
						returned 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
						assumes 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
						together. 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
						described in  Tk_MeasureChars,
						and  will not have any special
						behaviors.

       int *widthPtr (out)			If   non-NULL,	 filled	  with
						either	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
						index.

       int *heightPtr (out)			If   non-NULL,	 filled	  with
						either	the  total  height, in
						pixels, 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
						appended to interp->result.
_________________________________________________________________

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
       underline 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,
       including  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
       located 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.  Given a layout with no characters, the value
       0  will	always	be  returned,  referring  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
       inside,	entirely  outside,  or	overlaps  a  given  rectangle.	  New‐
       line/return  characters	and non-displaying space characters that occur
       at the end of individual lines in the layout are ignored for  intersec‐
       tion  calculations.   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 rectangle.

       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 interp->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
       ignored	when  justifying  lines or returning the total width of a text
       layout.	All end-of-line space characters are considered to be attached
       to the right edge of the line; this behavior is logical for left-justi‐
       fied 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  layout  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 sup‐
       pressed and occupy 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
       always  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)
[top]

List of man pages available for aLinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net