Spec-Zone .ru
спецификации, руководства, описания, API
Spec-Zone .ru
спецификации, руководства, описания, API
Библиотека разработчика Mac Разработчик
Поиск

 

Эта страница руководства является частью версии 5.0 Инструментов XCode

Получить эти инструменты:

Если Вы выполняете версию Инструментов XCode кроме 5,0, просматриваете документацию локально:

Читать страницы руководства

Страницы руководства предназначаются как справочник для людей, уже понимающих технологию.

  • Чтобы изучить, как руководство организовано или узнать о синтаксисе команды, прочитайте страницу руководства для страниц справочника (5).

  • Для получения дополнительной информации об этой технологии, ищите другую документацию в Библиотеке Разработчика Apple.

  • Для получения общей информации о записи сценариев оболочки, считайте Shell, Пишущий сценарий Учебника для начинающих.



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_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 numChars
                                                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 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  automatic  wrapping;  lines
                                                will  get as long as they need to be and only wrap if a new-
                                                line/return character is encountered.

       Tk_Justify justify (in)                  How to justify the lines in a multi-line text layout.   Pos-sible Possible
                                                sible  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  new-lines/returns newlines/returns
                                                lines/returns are ignored, then they will be treated as reg-ular regular
                                                ular characters, being measured and displayed in a platform-dependent platformdependent
                                                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 total height, in pixels,
                                                of  all the lines in the text layout, or the height, in pix-els, pixels,
                                                els, 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 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 cor-ner corner
                                                ner of the text layout when it is being drawn, or the  coor-dinates coordinates
                                                dinates of a point (with respect to the upper-left hand cor-ner corner
                                                ner 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  lay-out, layout,
                                                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 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 corre-sponding corresponding
                                                sponding value is not calculated.

       int width, height (in)                   Specifies the width and height, in pixels, of the  rectangu-lar rectangular
                                                lar  area  to compare for intersection against the text lay-out. layout.
                                                out.

       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; sup-port support
       port 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 convert-ing converting
       ing between character and byte offsets.

       The  routines  described  here are built on top of the programming interface described in the Tk_Mea-sureChars Tk_MeasureChars
       sureChars 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_DrawTextLayout, Tk_DistanceToTextLayout, 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 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  produce  natively  under-lined underlined
       lined  text, an underlined font should be constructed and used.  All characters, including tabs, new-line/return newline/return
       line/return characters, and spaces at the ends of lines, can be underlined using this  method.   How-ever, However,
       ever,  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 xvalue
       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  hypothetical  zero-width zerowidth
       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  consid-ered considered
       ered 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, *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 purposes, but tab char-acters characters
       acters 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 over-laps overlaps
       laps 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 addi-tional additional
       tional 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 behavior
       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  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 pos-sible possible
       sible 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 cen-tered centered
       tered 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  new-line/returns. newline/returns.
       line/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 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                                                   8.1                             Tk_ComputeTextLayout(3)

Сообщение о проблемах

Способ сообщить о проблеме с этой страницей руководства зависит от типа проблемы:

Ошибки содержания
Ошибки отчета в содержании этой документации к проекту Tk.
Отчеты об ошибках
Сообщите об ошибках в функциональности описанного инструмента или API к Apple через Генератор отчетов Ошибки и к проекту Tk через их страницу создания отчетов ошибки.
Форматирование проблем
Отчет, форматирующий ошибки в интерактивной версии этих страниц со ссылками на отзыв ниже.