2 '\" Copyright (c) 1996 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 .TH Tk_ComputeTextLayout 3 8.1 Tk "Tk Library Procedures"
8 .\" The -*- nroff -*- definitions below are for supplemental macros used
9 .\" in Tcl/Tk manual entries.
11 .\" .AP type name in/out ?indent?
12 .\" Start paragraph describing an argument to a library procedure.
13 .\" type is type of argument (int, etc.), in/out is either "in", "out",
14 .\" or "in/out" to describe whether procedure reads or modifies arg,
15 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
16 .\" needed; use .AS below instead)
19 .\" Give maximum sizes of arguments for setting tab stops. Type and
20 .\" name are examples of largest possible arguments that will be passed
21 .\" to .AP later. If args are omitted, default tab stops are used.
24 .\" Start box enclosure. From here until next .BE, everything will be
25 .\" enclosed in one large box.
28 .\" End of box enclosure.
31 .\" Begin code excerpt.
36 .\" .VS ?version? ?br?
37 .\" Begin vertical sidebar, for use in marking newly-changed parts
38 .\" of man pages. The first argument is ignored and used for recording
39 .\" the version when the .VS was added, so that the sidebars can be
40 .\" found and removed when they reach a certain age. If another argument
41 .\" is present, then a line break is forced before starting the sidebar.
44 .\" End of vertical sidebar.
47 .\" Begin an indented unfilled display.
50 .\" End of indented unfilled display.
53 .\" Start of list of standard options for a Tk widget. The manpage
54 .\" argument defines where to look up the standard options; if
55 .\" omitted, defaults to "options". The options follow on successive
56 .\" lines, in three columns separated by tabs.
59 .\" End of list of standard options for a Tk widget.
61 .\" .OP cmdName dbName dbClass
62 .\" Start of description of a specific option. cmdName gives the
63 .\" option's name as specified in the class command, dbName gives
64 .\" the option's name in the option database, and dbClass gives
65 .\" the option's class in the option database.
68 .\" Print arg1 underlined, then print arg2 normally.
71 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
74 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
75 .\" (for trailing punctuation) and then a closing parenthesis.
77 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 .\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 .\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 .\" # BS - start boxed text
114 .\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 .\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 .\" # VS - start vertical sidebar
146 .\" # ^Y = starting y location
147 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 .\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
169 .\" # Special macro to handle page bottom: finish off current
170 .\" # box/sidebar if in box/sidebar mode, then invoked standard
171 .\" # page bottom macro.
178 .\" Draw three-sided box if this is the box's first page,
179 .\" draw two sides but no top otherwise.
180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
184 .nr ^x \\n(^tu+1v-\\n(^Yu
185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
198 .\" # DS - begin display
204 .\" # DE - end display
210 .\" # SO - start of list of standard options
212 'ie '\\$1'' .ds So \\fBoptions\\fR
213 'el .ds So \\fB\\$1\\fR
214 .SH "STANDARD OPTIONS"
220 .\" # SE - end of list of standard options
225 See the \\*(So manual entry for details on the standard options.
227 .\" # OP - start of full description for a single option
232 Command-Line Name: \\fB\\$1\\fR
233 Database Name: \\fB\\$2\\fR
234 Database Class: \\fB\\$3\\fR
238 .\" # CS - begin code excerpt
244 .\" # CE - end code excerpt
249 .\" # UL - underline word
253 .\" # QW - apply quotation marks to word
255 .ie '\\*(lq'"' ``\\$1''\\$2
256 .\"" fix emacs highlighting
257 .el \\*(lq\\$1\\*(rq\\$2
259 .\" # PQ - apply parens and quotation marks to word
261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
262 .\"" fix emacs highlighting
263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
265 .\" # QR - quoted range
267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
268 .\"" fix emacs highlighting
269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
271 .\" # MT - "empty" string
277 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.
280 \fB#include <tk.h>\fR
283 \fBTk_ComputeTextLayout(\fItkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr\fB)\fR
286 \fBTk_FreeTextLayout(\fIlayout\fB)\fR
289 \fBTk_DrawTextLayout(\fIdisplay, drawable, gc, layout, x, y, firstChar, lastChar\fB)\fR
292 \fBTk_UnderlineTextLayout(\fIdisplay, drawable, gc, layout, x, y, underline\fB)\fR
295 \fBTk_PointToChar(\fIlayout, x, y\fB)\fR
298 \fBTk_CharBbox(\fIlayout, index, xPtr, yPtr, widthPtr, heightPtr\fB)\fR
301 \fBTk_DistanceToTextLayout(\fIlayout, x, y\fB)\fR
304 \fBTk_IntersectTextLayout(\fIlayout, x, y, width, height\fB)\fR
307 \fBTk_TextLayoutToPostscript(\fIinterp, layout\fB)\fR
309 .AS Tk_TextLayout "*xPtr, *yPtr"
310 .AP Tk_Font tkfont in
311 Font to use when constructing and displaying a text layout. The
312 \fItkfont\fR must remain valid for the lifetime of the text layout. Must
313 have been returned by a previous call to \fBTk_GetFont\fR.
314 .AP "const char" *string in
315 Potentially multi-line string whose dimensions are to be computed and
316 stored in the text layout. The \fIstring\fR must remain valid for the
317 lifetime of the text layout.
319 The number of characters to consider from \fIstring\fR. If
320 \fInumChars\fR is less than 0, then assumes \fIstring\fR is null
321 terminated and uses \fBTcl_NumUtfChars\fR to determine the length of
323 .AP int wrapLength in
324 Longest permissible line length, in pixels. Lines in \fIstring\fR will
325 automatically be broken at word boundaries and wrapped when they reach
326 this length. If \fIwrapLength\fR is too small for even a single
327 character to fit on a line, it will be expanded to allow one character to
328 fit on each line. If \fIwrapLength\fR is <= 0, there is no automatic
329 wrapping; lines will get as long as they need to be and only wrap if a
330 newline/return character is encountered.
331 .AP Tk_Justify justify in
332 How to justify the lines in a multi-line text layout. Possible values
333 are \fBTK_JUSTIFY_LEFT\fR, \fBTK_JUSTIFY_CENTER\fR, or
334 \fBTK_JUSTIFY_RIGHT\fR. If the text layout only occupies a single
335 line, then \fIjustify\fR is irrelevant.
337 Various flag bits OR-ed together. \fBTK_IGNORE_TABS\fR means that tab
338 characters should not be expanded to the next tab stop.
339 \fBTK_IGNORE_NEWLINES\fR means that newline/return characters should
340 not cause a line break. If either tabs or newlines/returns are
341 ignored, then they will be treated as regular characters, being
342 measured and displayed in a platform-dependent manner as described in
343 \fBTk_MeasureChars\fR, and will not have any special behaviors.
344 .AP int *widthPtr out
345 If non-NULL, filled with either the width, in pixels, of the widest
346 line in the text layout, or the width, in pixels, of the bounding box for the
347 character specified by \fIindex\fR.
348 .AP int *heightPtr out
349 If non-NULL, filled with either the total height, in pixels, of all
350 the lines in the text layout, or the height, in pixels, of the bounding
351 box for the character specified by \fIindex\fR.
352 .AP Tk_TextLayout layout in
353 A token that represents the cached layout information about the single-font,
354 multi-line, justified piece of text. This token is returned by
355 \fBTk_ComputeTextLayout\fR.
356 .AP Display *display in
357 Display on which to draw.
358 .AP Drawable drawable in
359 Window or pixmap in which to draw.
361 Graphics context to use for drawing text layout. The font selected in
362 this GC must correspond to the \fItkfont\fR used when constructing the
365 Point, in pixels, at which to place the upper-left hand corner of the
366 text layout when it is being drawn, or the coordinates of a point (with
367 respect to the upper-left hand corner of the text layout) to check
368 against the text layout.
370 The index of the first character to draw from the given text layout.
371 The number 0 means to draw from the beginning.
373 The index of the last character up to which to draw. The character
374 specified by \fIlastChar\fR itself will not be drawn. A number less
375 than 0 means to draw all characters in the text layout.
377 Index of the single character to underline in the text layout, or a number
378 less than 0 for no underline.
380 The index of the character whose bounding box is desired. The bounding
381 box is computed with respect to the upper-left hand corner of the text layout.
382 .AP int "*xPtr, *yPtr" out
383 Filled with the upper-left hand corner, in pixels, of the bounding box
384 for the character specified by \fIindex\fR. Either or both \fIxPtr\fR
385 and \fIyPtr\fR may be NULL, in which case the corresponding value
387 .AP int "width, height" in
388 Specifies the width and height, in pixels, of the rectangular area to
389 compare for intersection against the text layout.
390 .AP Tcl_Interp *interp out
391 Postscript code that will print the text layout is appended to
392 the result of interpreter \fIinterp\fR.
396 These routines are for measuring and displaying single-font, multi-line,
397 justified text. To measure and display simple single-font, single-line
398 strings, refer to the documentation for \fBTk_MeasureChars\fR. There is
399 no programming interface in the core of Tk that supports multi-font,
400 multi-line text; support for that behavior must be built on top of
402 Note that unlike the lower level text display routines, the functions
403 described here all operate on character-oriented lengths and indices
404 rather than byte-oriented values. See the description of
405 \fBTcl_UtfAtIndex\fR for more details on converting between character
408 The routines described here are built on top of the programming interface
409 described in the \fBTk_MeasureChars\fR documentation. Tab characters and
410 newline/return characters may be treated specially by these procedures,
411 but all other characters are passed through to the lower level.
413 \fBTk_ComputeTextLayout\fR computes the layout information needed to
414 display a single-font, multi-line, justified \fIstring\fR of text and
415 returns a Tk_TextLayout token that holds this information. This token is
416 used in subsequent calls to procedures such as \fBTk_DrawTextLayout\fR,
417 \fBTk_DistanceToTextLayout\fR, and \fBTk_FreeTextLayout\fR. The
418 \fIstring\fR and \fItkfont\fR used when computing the layout must remain
419 valid for the lifetime of this token.
421 \fBTk_FreeTextLayout\fR is called to release the storage associated with
422 \fIlayout\fR when it is no longer needed. A \fIlayout\fR should not be used
423 in any other text layout procedures once it has been released.
425 \fBTk_DrawTextLayout\fR uses the information in \fIlayout\fR to display a
426 single-font, multi-line, justified string of text at the specified location.
428 \fBTk_UnderlineTextLayout\fR uses the information in \fIlayout\fR to
429 display an underline below an individual character. This procedure does
430 not draw the text, just the underline. To produce natively underlined
431 text, an underlined font should be constructed and used. All characters,
432 including tabs, newline/return characters, and spaces at the ends of
433 lines, can be underlined using this method. However, the underline will
434 never be drawn outside of the computed width of \fIlayout\fR; the
435 underline will stop at the edge for any character that would extend
436 partially outside of \fIlayout\fR, and the underline will not be visible
437 at all for any character that would be located completely outside of the
440 \fBTk_PointToChar\fR uses the information in \fIlayout\fR to determine the
441 character closest to the given point. The point is specified with respect
442 to the upper-left hand corner of the \fIlayout\fR, which is considered to be
443 located at (0, 0). Any point whose \fIy\fR-value is less that 0 will be
444 considered closest to the first character in the text layout; any point
445 whose \fIy\fR-value is greater than the height of the text layout will be
446 considered closest to the last character in the text layout. Any point
447 whose \fIx\fR-value is less than 0 will be considered closest to the first
448 character on that line; any point whose \fIx\fR-value is greater than the
449 width of the text layout will be considered closest to the last character on
450 that line. The return value is the index of the character that was closest
451 to the point, or one more than the index of any character (to indicate that
452 the point was after the end of the string and that the corresponding caret
453 would be at the end of the string). Given a \fIlayout\fR with no characters,
454 the value 0 will always be returned, referring to a hypothetical zero-width
455 placeholder character.
457 \fBTk_CharBbox\fR uses the information in \fIlayout\fR to return the
458 bounding box for the character specified by \fIindex\fR. The width of the
459 bounding box is the advance width of the character, and does not include any
460 left or right bearing. Any character that extends partially outside of
461 \fIlayout\fR is considered to be truncated at the edge. Any character
462 that would be located completely outside of \fIlayout\fR is considered to
463 be zero-width and pegged against the edge. The height of the bounding
464 box is the line height for this font, extending from the top of the
465 ascent to the bottom of the descent; information about the actual height
466 of individual letters is not available. For measurement purposes, a
467 \fIlayout\fR that contains no characters is considered to contain a
468 single zero-width placeholder character at index 0. If \fIindex\fR was
469 not a valid character index, the return value is 0 and \fI*xPtr\fR,
470 \fI*yPtr\fR, \fI*widthPtr\fR, and \fI*heightPtr\fR are unmodified.
471 Otherwise, if \fIindex\fR did specify a valid, the return value is
472 non-zero, and \fI*xPtr\fR, \fI*yPtr\fR, \fI*widthPtr\fR, and
473 \fI*heightPtr\fR are filled with the bounding box information for the
474 character. If any of \fIxPtr\fR, \fIyPtr\fR, \fIwidthPtr\fR, or
475 \fIheightPtr\fR are NULL, the corresponding value is not calculated or
478 \fBTk_DistanceToTextLayout\fR computes the shortest distance in pixels from
479 the given point (\fIx, y\fR) to the characters in \fIlayout\fR.
480 Newline/return characters and non-displaying space characters that occur at
481 the end of individual lines in the text layout are ignored for hit detection
482 purposes, but tab characters are not. The return value is 0 if the point
483 actually hits the \fIlayout\fR. If the point did not hit the \fIlayout\fR
484 then the return value is the distance in pixels from the point to the
487 \fBTk_IntersectTextLayout\fR determines whether a \fIlayout\fR lies
488 entirely inside, entirely outside, or overlaps a given rectangle.
489 Newline/return characters and non-displaying space characters that occur
490 at the end of individual lines in the \fIlayout\fR are ignored for
491 intersection calculations. The return value is \-1 if the \fIlayout\fR is
492 entirely outside of the rectangle, 0 if it overlaps, and 1 if it is
493 entirely inside of the rectangle.
495 \fBTk_TextLayoutToPostscript\fR outputs code consisting of a Postscript
496 array of strings that represent the individual lines in \fIlayout\fR. It
497 is the responsibility of the caller to take the Postscript array of
498 strings and add some Postscript function operate on the array to render
499 each of the lines. The code that represents the Postscript array of
500 strings is appended to interpreter \fIinterp\fR's result.
503 When measuring a text layout, space characters that occur at the end of a
504 line are ignored. The space characters still exist and the insertion point
505 can be positioned amongst them, but their additional width is ignored when
506 justifying lines or returning the total width of a text layout. All
507 end-of-line space characters are considered to be attached to the right edge
508 of the line; this behavior is logical for left-justified text and reasonable
509 for center-justified text, but not very useful when editing right-justified
510 text. Spaces are considered variable width characters; the first space that
511 extends past the edge of the text layout is clipped to the edge, and any
512 subsequent spaces on the line are considered zero width and pegged against
513 the edge. Space characters that occur in the middle of a line of text are
514 not suppressed and occupy their normal space width.
516 Tab characters are not ignored for measurement calculations. If wrapping
517 is turned on and there are enough tabs on a line, the next tab will wrap
518 to the beginning of the next line. There are some possible strange
519 interactions between tabs and justification; tab positions are calculated
520 and the line length computed in a left-justified world, and then the
521 whole resulting line is shifted so it is centered or right-justified,
522 causing the tab columns not to align any more.
524 When wrapping is turned on, lines may wrap at word breaks (space or tab
525 characters) or newline/returns. A dash or hyphen character in the middle
526 of a word is not considered a word break. \fBTk_ComputeTextLayout\fR
527 always attempts to place at least one word on each line. If it cannot
528 because the \fIwrapLength\fR is too small, the word will be broken and as
529 much as fits placed on the line and the rest on subsequent line(s). If
530 \fIwrapLength\fR is so small that not even one character can fit on a
531 given line, the \fIwrapLength\fR is ignored for that line and one
532 character will be placed on the line anyhow. When wrapping is turned
533 off, only newline/return characters may cause a line break.
535 When a text layout has been created using an underlined \fItkfont\fR,
536 then any space characters that occur at the end of individual lines,
537 newlines/returns, and tabs will not be displayed underlined when
538 \fBTk_DrawTextLayout\fR is called, because those characters are never
539 actually drawn \- they are merely placeholders maintained in the
OSDN Git Service
