NAME

       Tk_ComputeTextLayout,  Tk_FreeTextLayout,  Tk_DrawTextLay­
       out, Tk_UnderlineTextLayout, Tk_PointToChar,  Tk_CharBbox,
       Tk_DistanceToTextLayout,  Tk_IntersectTextLayout, Tk_Text­
       LayoutToPostscript - routines to measure and display  sin­
       gle-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.
                                                multi-line string
                                                whose  dimensions
                                                are  to  be  com­
                                                puted and  stored
                                                in  the text lay­
                                                out.  The  string
                                                must remain valid
                                                for the  lifetime
                                                of  the text lay­
                                                out.

       int             numChars       (in)      The   number   of
                                                characters     to
                                                consider     from
                                                string.   If num­
                                                Chars   is   less
                                                than    0,   then
                                                assumes string is
                                                null   terminated |
                                                and          uses |
                                                Tcl_NumUtfChars   |
                                                to determine  the |
                                                length of string.

       int             wrapLength     (in)      Longest permissi­
                                                ble  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
                                                automatic   wrap­
                                                ping;  lines will
                                                get  as  long  as
                                                they  need  to be
                                                and only wrap  if
                                                a  newline/return
                                                character      is
                                                encountered.
                                                the  lines  in  a
                                                multi-line   text
                                                layout.  Possible
                                                values        are
                                                TK_JUSTIFY_LEFT,
                                                TK_JUSTIFY_CEN­
                                                TER,  or  TK_JUS­
                                                TIFY_RIGHT.    If
                                                the  text  layout
                                                only  occupies  a
                                                single line, then
                                                justify is irrel­
                                                evant.

       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_NEW­
                                                LINES  means that
                                                newline/return
                                                characters should
                                                not cause a  line
                                                break.  If either
                                                tabs   or    new­
                                                lines/returns are
                                                ignored,     then
                                                they    will   be
                                                treated as  regu­
                                                lar   characters,
                                                being    measured
                                                and  displayed in
                                                a platform-depen­
                                                dent   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
                                                pixels,   of  the
                                                specified      by
                                                index.

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

       Tk_TextLayout   layout         (in)      A token that rep­
                                                resents       the
                                                cached     layout
                                                information about
                                                the  single-font,
                                                multi-line,  jus­
                                                tified  piece  of
                                                text.  This token
                                                is   returned  by
                                                Tk_ComputeText­
                                                Layout.

       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 draw­
                                                ing text  layout.
                                                The font selected
                                                in this  GC  must
                                                correspond to the
                                                tkfont used  when
                                                constructing  the
                                                text layout.

       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
                                                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  lay­
                                                out.  The  number
                                                0  means  to draw
                                                from  the  begin­
                                                ning.

       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 char­
                                                acters   in   the
                                                text layout.

       int             underline      (in)      Index of the sin­
                                                gle  character to
                                                underline in  the
                                                text layout, or a
                                                number less  than
                                                0  for  no under­
                                                line.

       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
                                                specified      by
                                                index.  Either or
                                                both   xPtr   and
                                                yPtr may be NULL,
                                                in which case the
                                                corresponding
                                                value is not cal­
                                                culated.

       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 doc­
       umentation 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 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  pro­
       gramming  interface described in the Tk_MeasureChars docu­
       mentation.  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_DrawTextLayout,  Tk_Dis­
       tanceToTextLayout,  and Tk_FreeTextLayout.  The string and

       Tk_FreeTextLayout is called to release the storage associ­
       ated 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  dis­
       play  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 underline will stop at the  edge  for
       any  character that would extend partially outside of lay­
       out, 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 lay­
       out with  no  characters,  the  value  0  will  always  be
       returned,  referring  to  a hypothetical zero-width place­
       holder 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 con­
       sidered 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
       poses, 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,  *widthPtr,  and
       *heightPtr are unmodified.  Otherwise, if index did  spec­
       ify  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  corre­
       sponding 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 purposes,
       but tab characters are not.  The return value is 0 if  the
       point  actually  hits the layout.  If the point didn't 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 characters 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  behav­
       ior  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
       in the middle of a line of text  are  not  suppressed  and
       occupy their normal space width.

       Tab  characters  are  not ignored for measurement calcula­
       tions.  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 calcu­
       lated 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 bro­
       ken 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
       displayed  underlined  when  Tk_DrawTextLayout  is called,
       because those characters are never actually drawn  -  they
       are merely placeholders maintained in the layout.


KEYWORDS

       font