## Tcl8.6.17/Tk8.6.17 Documentation > Tk C API > TextLayout

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  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)
    const char *string (入力in)
    int numChars (入力in)
    int wrapLength (入力in)
    Tk_Justify justify (入力in)
    int flags (入力in)
    int *widthPtr (出力out)
    int *heightPtr (出力out)
    Tk_TextLayout layout (入力in)
    Display *display (入力in)
    Drawable drawable (入力in)
    GC gc (入力in)
    int x, y (入力in)
    int firstChar (入力in)
    int lastChar (入力in)
    int underline (入力in)
    int index (入力in)
    int *xPtr, *yPtr (出力out)
    int width, height (入力in)
    Tcl_Interp *interp (出力out)
  説明 DESCRIPTION
  DISPLAY MODEL
  KEYWORDS

### 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)
  整列文書を構成子表示する時に使う文字形状｡ tkfont は整列文書の寿命がある間は残っている必要がある｡ Tk_GetFont への以前の呼出しにより返されていなければならない｡ 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)
  その寸法が計算されるべき潜在的な複数行文字列であり､整列文書内に保存される｡その string は整列文書の寿命の間中は適正に残す必要がある｡ 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)
  string から文字の個数と看做すべき数｡もし numChars が 0 より小さいと､ string は零終端と仮定され､ string の長さの決定にはTcl_NumUtfChars が使われる｡ 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)
  許容しうる最長行長さ､行単位｡ string 内の行は自動的に語の境界で区切られ､この長さに達すると折畳まれる｡もし wrapLength が一つの文字さえも行に嵌められない程過小の場合､各行に１文字づつ嵌める様拡張される｡もし wrapLength が<= 0 の場合自動折畳みはなくなる; 行は必要とされるだけ文字をとり､行送り/改行文字に遭遇した時のみ折畳む｡ 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 newline/return character is encountered.

Tk_Justify justify (入力in)
  多重行整列文書内の行の端揃えを如何に行うか｡とり得る値はTK_JUSTIFY_LEFT か TK_JUSTIFY_CENTER か TK_JUSTIFY_RIGHT かである｡もし整列文書が一つの行だけを占める場合 justify は無意味である｡ 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)
  多くの旗印ビットの､或は､の結合｡TK_IGNORE_TABS はタブ文字が次のタブ停止まで拡張しないことを表す｡TK_IGNORE_NEWLINES は行送り/改行文字は行替えを起こさせない｡もしタブか行送り/改行が無視された場合､それらは通常の文字として扱われ､Tk_MeasureChars に記述されている通りにOS依存の方法により調整され表示される｡ 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)
  非零､なら画素単位の整列文書内の最大幅の行の幅､若しくは､画素単位の index によって指定された文字についての束縛箱の幅で満たされている｡ 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)
  非零､なら画素単位の整列文書内の全ての行の総合高さ､若しくは､画素単位の､ 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.

Tk_TextLayout layout (入力in)
  一文字文字形状､複数行､文書片の端揃えに関する整列情報の臨時記憶を表現する字句｡この字句は Tk_ComputeTextLayout により返される｡ 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)
  整列文書を描く為に使う画像文脈｡この画像文脈から選択された文字形状は整列文書を構成する時に使われる tkfont に対応しなければならない｡ 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)
  与えられた整列文書から描くべき最初の文字への索引｡数 0 は最初から描くことを意味する｡ 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)
  そこ迄描くべき最後の文字への索引｡ lastChar そのものにより指定された文字は描れない｡ 0 より小さい数は整列文書内の全ての文字を描くことを意味する｡ 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)
  整列文書内で下線を引く文字の索引､但し数が 0 より小さい時は､下線無しのもの｡ 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)
  index で指定される文字の為の束縛箱の左上隅により､画素単位で満たされる｡ xPtr と yPtr のどちらも NULL になり得､その場合､対応する値は算出されない｡ 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 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 命令譜｡ Postscript code that will print the text layout is appended to the result of interpreter interp.

### 説明 DESCRIPTION

此処で記述する算譜機能は､一文字の文字形状､複数行､行端揃え文書等を準備し表示する為のものである｡単なる一文字の文字形状､１行文字列の準備と表示をするためにはTk_MeasureChars に関する説明を参照されたい｡ Tk 核内の相互作用算譜には多文字の文字形状､複数行文書を運営しているものはない; この様な挙動の運営は単純な層の頂上に作成しなければならない｡註意すべきは､下位水準の文書表示算譜機能とは異なり､ここで述べる函数は全てバイト志向の値ではなく､文字志向の長さと索引を扱う｡文字とバイトの間の偏寄の変換に就いての詳細は Tcl_UtfAtIndex の記述を参照されたい｡ 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 values. See the description of Tcl_UtfAtIndex for more details on converting between character and byte offsets.

此処で記述する算譜機能は Tk_MeasureChars 説明書内に記述された算譜の相互作用の先頭に作成される｡タブ文字と行送り/改行文字は特別にこのような手続函数で扱うが他の文字は下位水準に渡される｡ 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 は一文字の文字形状､複数行､文書の行端揃え文字列を表示する為に必要な整列情報を計算し､この情報を保持するTk_TextLayout 字句結果に返す｡この字句結果はそれに引続く Tk_DrawTextLayout や Tk_DistanceToTextLayout や Tk_FreeTextLayout の様な手続函数に呼ばれる｡この字句結果について整列の計算を保持している必要がある場合は string と tkfont が使われる｡ 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 は最早必要としなくなった時に､ layout に結合した記憶域を解除する為に呼ばれる｡ layout はそれが一度解除された後はどの整列文書手続函数でも使用されることはない｡ 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 は指定した位置に一文字の文字形状､複数行､文書の行端揃え文字列を表示する為に layout 内の情報を使う｡ Tk_DrawTextLayout uses the information in layout to display a single-font, multi-line, justified string of text at the specified location.

Tk_UnderlineTextLayout は個別の文字の下に下線を表示する為に layout 内の情報を使用する｡この手続函数は文書の下線位置に描くことはしない｡本質的に下線が引かれた文書を生成する為に下線が引かれた文字形状が構成され使われるべきである｡この方法ではタブ､改行行送り文字行末の空白文字も含めた全ての文字に下線を引くことができる｡しかしながら､下線は計算された layout の幅の外側では描れることはなく; 下線は部分的に layout の外側に延びたどの文字でもその端で止まり､又､完全に layout の外側に位置したどの文字でも下線は不可視である｡ 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 は指定された点に最も近い位置の文字を定める為に layout 内の情報を使う｡その点は layout の左上隅に対して指定され､左上隅が(0, 0)であると看做される｡どの点であれその y-値が 0 より小さいと整列文書内の最初の文字に最も近いと看做され; y-値が整列文書より高いと整列文書の最後の文字に最も近いと看做される｡どの点であれその x-値が 0 より小さいとその行の最初の文字に最も近いと看做され; x-値が整列文書より大きいとその行の最後の文字に最も近いと看做される｡返り値はその点に最も近い文字の索引の値である､或はどれかの文字の索引以上のものである(その点が文字列の末尾の後の点であることを示している､亦､対応する脱字記号は文字列の末尾にある)｡文字のない layout が与えられたら､値 0 が常に返され､仮想的な零幅の場所占有文字を参照している｡文字のない layout が与えられたら､値 0 が常に返され､仮想的な零幅の場所占有文字を参照している｡ 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, or one more than the index of any character (to indicate that the point was after the end of the string and that the corresponding caret would be at the end of the string). Given a layout with no characters, the value 0 will always be returned, referring to a hypothetical zero-width placeholder character.

Tk_CharBbox は index によって指定された文字に関する結合箱に layout 内の情報を返す為に使う｡結合箱の幅は文字の幅と一緒に伸びるが右や左には何の余裕もない｡ layout の外側に部分的に延伸したどのような文字も端位置で切詰められると看做される｡ layout の完全に外側に位置するどのような文字も零幅であって端に対して留まっていると看做される｡結合箱の高さはこの文字形状の行の高さであり､上部の頂上から下部の底迄に拡がり; 個別の文字の実際の高さに関する情報は使用できない｡揃える目的では､文字を含まない layout は索引位置 0 の一つの零幅位置を保有する文字を含むと看做される｡もし index が文字索引として不適である場合､返り値は 0 であり､ *xPtr と *yPtr と *widthPtr と *heightPtr は修正されない｡それ以外の場合､もし index が適切に指定した場合､返り値は非零であり､ *xPtr と *yPtr と *widthPtr と *heightPtr は文字に関する束縛箱の情報で満たされる｡もし *xPtr か *yPtr か *widthPtr か *heightPtr かのどれかが NULL,であると対応する値は計算されないか保存されない｡ 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 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 は与えられた点(x, y)から layout 内の文字迄の最短距離を画素で計算する｡整列文書内の個別の行末に現れる行送り/改行文字と非表示空白文字は重複検査の目的では無視されるが､タブ文字は無視されない｡点が実際この layout.と重複する場合は返り値は 0 である｡もし点が layout と重複しない場合は､返り値は点から layout 迄の画素単位の距離の値である｡ 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 did not hit the layout then the return value is the distance in pixels from the point to the layout.

Tk_IntersectTextLayout は layout が与えられた矩形の完全な内側か､完全な外側か､重なるかを定める｡ layout 内の行末に生じる行送り/改行文字と非表示空白文字は交差の計算では無視される｡返り値は､もし layout が完全に矩形の外の場合は -1､重なっている場合は 0 ､完全に矩形の内側の場合は 1 である｡ 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 は layout.内の個別の行を表現する文字列のPostscript 配列を構成する命令譜を出力する｡文字列のPostscript 配列を取り､配列上の何かのPostscript 函数操作をそれぞれの描写すべき行に追加することは呼出し側の責務である｡文字列のPostscript 配列を表現する命令譜は解釈実行機能の結果に追記される｡ 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 interpreter interp's 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_ComputeTextLayout は常に､各行に最低１語を置くように試みる｡もしwrapLength が過少の為にそれができない場合､語は分解され可能な限り嵌る様にその行と残りを次の行に置く｡もしwrapLength が過少の為与えられた行に１文字さえ適合できなくなると､その行についてはwrapLength は無視されどの行も１文字が置かれる｡折畳みが断になった時は､行送り/改行､だけが行の終わりを引起す｡ 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.

下線を引かれた tkfont を使って文書整列が生成された時､個別の行末に発生するのどのような空白文字もTk_DrawTextLayout が呼ばれた時は､行送り/改行､タブは下線を引かずに表示される､理由は､このような文字は実際は決して - を描かれることは無く､単に layout 内で場所を保持しているだけであるから｡ 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
Copyright © 1996 Sun Microsystems, Inc.