DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tk_DrawTextLayout(3tk)





Tk_ComputeTextLayout(3Tk Library ProcedureTk_ComputeTextLayout(3)


_________________________________________________________________


NAME

     Tk_ComputeTextLayout, Tk_FreeTextLayout,  Tk_DrawTextLayout,
     Tk_UnderlineTextLayout,     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  pre-
                                              vious    call    to
                                              Tk_GetFont.

Tk                      Last change: 8.1                        1


Tk_ComputeTextLayout(3Tk Library ProcedureTk_ComputeTextLayout(3)


     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 char-
                                              acters  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  char-
                                              acter   to  fit  on
                                              each line.  If wra-
                                              pLength  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.

Tk                      Last change: 8.1                        2


Tk_ComputeTextLayout(3Tk Library ProcedureTk_ComputeTextLayout(3)


                                              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_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
                                              bounding   box  for
                                              the       character
                                              specified by index.

     int *heightPtr (out)                     If non-NULL, filled
                                              with   either   the

Tk                      Last change: 8.1                        3


Tk_ComputeTextLayout(3Tk Library ProcedureTk_ComputeTextLayout(3)


                                              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,  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 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
                                              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

Tk                      Last change: 8.1                        4


Tk_ComputeTextLayout(3Tk Library ProcedureTk_ComputeTextLayout(3)


                                              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 under-
                                              line  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  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 calcu-
                                              lated.

     int width, height (in)                   Specifies the width
                                              and height, in pix-
                                              els,     of     the

Tk                      Last change: 8.1                        5


Tk_ComputeTextLayout(3Tk Library ProcedureTk_ComputeTextLayout(3)


                                              rectangular area to
                                              compare for  inter-
                                              section 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  rou-
     tines,   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 program-
     ming  interface  described in the Tk_MeasureChars documenta-
     tion.  Tab characters and newline/return characters  may  be
     treated specially by these procedures, but all other charac-
     ters 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 pro-
     cedures such as Tk_DrawTextLayout,  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  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  display
     a  single-font,  multi-line, justified string of text at the
     specified location.

Tk                      Last change: 8.1                        6


Tk_ComputeTextLayout(3Tk Library ProcedureTk_ComputeTextLayout(3)


     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 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 con-
     sidered  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 char-
     acters, 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  char-
     acter,  and does not include any left or right bearing.  Any
     character that extends partially outside of layout  is  con-
     sidered  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 con-
     tains 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 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 correspond-
     ing value is not calculated or stored.

Tk                      Last change: 8.1                        7


Tk_ComputeTextLayout(3Tk Library ProcedureTk_ComputeTextLayout(3)


     Tk_DistanceToTextLayout computes the  shortest  distance  in
     pixels from the given point (x, y) to the characters in lay-
     out.  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 did not hit the lay-
     out 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 rec-
     tangle.  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 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.

Tk                      Last change: 8.1                        8


Tk_ComputeTextLayout(3Tk Library ProcedureTk_ComputeTextLayout(3)


     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 char-
     acter 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

Tk                      Last change: 8.1                        9


Man(1) output converted with man2html