Unix/Linux Go Back    


CentOS 7.0 - man page for tk_intersecttextlayout (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Tk_ComputeTextLayout(3) 	      Tk Library Procedures		  Tk_ComputeTextLayout(3)

_________________________________________________________________________________________________

NAME
       Tk_ComputeTextLayout,	Tk_FreeTextLayout,   Tk_DrawTextLayout,   Tk_UnderlineTextLayout,
       Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_IntersectTextLayout,  Tk_TextLay-
       outToPostscript - 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 numChars is less than 0, then  assumes  string
						is  null  terminated  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 character 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  auto-
						matic  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.   Possible  values  are  TK_JUSTIFY_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  measured  and  displayed in a
						platform-dependent manner as described in Tk_Mea-
						sureChars,  and  will not have any special behav-
						iors.

       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 pixels, 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  infor-
						mation	about the single-font, multi-line, justi-
						fied 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  correspond  to
						the  tkfont  used when constructing the text lay-
						out.

       int x, y (in)				Point, in pixels, at which to  place  the  upper-
						left  hand  corner  of the text layout when it is
						being drawn, or the coordinates 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 character to draw from the
						given  text  layout.   The number 0 means to draw
						from the beginning.

       int lastChar (in)			The index of the last character 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 layout, 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
						layout.

       int *xPtr, *yPtr (out)			Filled with the upper-left hand corner,  in  pix-
						els, of the bounding box for the character speci-
						fied by index.	Either or both xPtr and yPtr  may
						be NULL, in which case the corresponding value is
						not calculated.

       int width, height (in)			Specifies the width and height, in pixels, of the
						rectangular  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, single-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-oriented lengths and indices rather than byte-oriented  val-
       ues.  See the description of Tcl_UtfAtIndex for more details on converting between charac-
       ter and byte offsets.

       The routines described here are built on top of the programming interface described in the
       Tk_MeasureChars	documentation.	 Tab  characters  and  newline/return  characters  may be
       treated specially by these procedures, 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_DrawTextLay-
       out, Tk_DistanceToTextLayout, and Tk_FreeTextLayout.  The string and tkfont used when com-
       puting the layout must remain valid for the lifetime of this token.

       Tk_FreeTextLayout  is  called  to release the storage associated with layout 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 pro-
       duce 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 underline will stop at the edge for any character
       that would extend partially outside of layout, and the underline will not  be  visible  at
       all for any character that would be located completely outside of the layout.

       Tk_PointToChar  uses  the  information in layout to determine the character 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 considered 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 character  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  hypotheti-
       cal 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 out-
       side 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 bottom of the descent; information about the actual height of
       individual letters is not available.  For measurement purposes, a layout that contains  no
       characters  is considered to contain a single zero-width placeholder character at index 0.
       If index was not a valid character index, the return value is 0 and *xPtr, *yPtr,  *width-
       Ptr,  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  bound-
       ing  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 char-
       acters that occur at the end of individual lines in the text layout are	ignored  for  hit
       detection  purposes, but tab characters are not.  The return value is 0 if the point actu-
       ally 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.  Newline/return characters and non-displaying space charac-
       ters  that occur at the end of individual lines in the layout are ignored for intersection
       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-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 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 suppressed and occupy their normal space width.

       Tab characters are not ignored for measurement calculations.  If wrapping 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 middle 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 newline/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, newlines/returns, and tabs will not be dis-
       played underlined when Tk_DrawTextLayout 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)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:50 PM.