manpagez: man pages & more
man Tk_FreeTextLayout(3)
Home | html | info | man
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

       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.   Potentially  multi-line
       string  whose dimensions are to be computed and stored in the text lay-
       out.  The string must remain valid for the lifetime of the text layout.
       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.  Longest permissible line length, in
       pixels.  Lines in string will automatically be broken  at  word  bound-
       aries  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 automatic wrapping; lines will get as long as they need  to
       be  and only wrap if a newline/return character is encountered.  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.   Vari-
       ous  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_MeasureChars, and will not have any
       special  behaviors.  If non-NULL, filled with either the width, in pix-
       els, of the widest line in the text layout, or the width, in pixels, of
       the  bounding  box  for the character specified by index.  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.  A token that represents the cached  lay-
       out  information  about the single-font, multi-line, justified piece of
       text.  This token is  returned  by  Tk_ComputeTextLayout.   Display  on
       which to draw.  Window or pixmap in which to draw.  Graphics context to
       use for drawing text layout.  The font selected in this GC must  corre-
       spond  to the tkfont used when constructing the text layout.  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.   The index of the first character to draw from the given
       text layout.  The number 0 means to draw from the beginning.  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.  Index of the single character to
       underline in the text layout, or a number less than 0 for no underline.
       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.   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 corresponding value is not cal-
       culated.  Specifies the width and height, in pixels, of the rectangular
       area  to  compare for intersection against the text layout.  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)

TextLayout 8.5.4 - Generated Sun Aug 24 15:19:26 CDT 2008
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.