util/X86LINUX64/man/man3/Tk_TextWidth.3

   1 '\"
   2 '\" Copyright (c) 1996 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH Tk_MeasureChars 3 8.1 Tk "Tk Library Procedures"
   8 .\" The -*- nroff -*- definitions below are for supplemental macros used
   9 .\" in Tcl/Tk manual entries.
  10 .\"
  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)
  17 .\"
  18 .\" .AS ?type? ?name?
  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.
  22 .\"
  23 .\" .BS
  24 .\"     Start box enclosure.  From here until next .BE, everything will be
  25 .\"     enclosed in one large box.
  26 .\"
  27 .\" .BE
  28 .\"     End of box enclosure.
  29 .\"
  30 .\" .CS
  31 .\"     Begin code excerpt.
  32 .\"
  33 .\" .CE
  34 .\"     End code excerpt.
  35 .\"
  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.
  42 .\"
  43 .\" .VE
  44 .\"     End of vertical sidebar.
  45 .\"
  46 .\" .DS
  47 .\"     Begin an indented unfilled display.
  48 .\"
  49 .\" .DE
  50 .\"     End of indented unfilled display.
  51 .\"
  52 .\" .SO ?manpage?
  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.
  57 .\"
  58 .\" .SE
  59 .\"     End of list of standard options for a Tk widget.
  60 .\"
  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.
  66 .\"
  67 .\" .UL arg1 arg2
  68 .\"     Print arg1 underlined, then print arg2 normally.
  69 .\"
  70 .\" .QW arg1 ?arg2?
  71 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  72 .\"
  73 .\" .PQ arg1 ?arg2?
  74 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  75 .\"     (for trailing punctuation) and then a closing parenthesis.
  76 .\"
  77 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  78 .if t .wh -1.3i ^B
  79 .nr ^l \n(.l
  80 .ad b
  81 .\"     # Start an argument description
  82 .de AP
  83 .ie !"\\$4"" .TP \\$4
  84 .el \{\
  85 .   ie !"\\$2"" .TP \\n()Cu
  86 .   el          .TP 15
  87 .\}
  88 .ta \\n()Au \\n()Bu
  89 .ie !"\\$3"" \{\
  90 \&\\$1 \\fI\\$2\\fP (\\$3)
  91 .\".b
  92 .\}
  93 .el \{\
  94 .br
  95 .ie !"\\$2"" \{\
  96 \&\\$1  \\fI\\$2\\fP
  97 .\}
  98 .el \{\
  99 \&\\fI\\$1\\fP
 100 .\}
 101 .\}
 102 ..
 103 .\"     # define tabbing values for .AP
 104 .de AS
 105 .nr )A 10n
 106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 107 .nr )B \\n()Au+15n
 108 .\"
 109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 111 ..
 112 .AS Tcl_Interp Tcl_CreateInterp in/out
 113 .\"     # BS - start boxed text
 114 .\"     # ^y = starting y location
 115 .\"     # ^b = 1
 116 .de BS
 117 .br
 118 .mk ^y
 119 .nr ^b 1u
 120 .if n .nf
 121 .if n .ti 0
 122 .if n \l'\\n(.lu\(ul'
 123 .if n .fi
 124 ..
 125 .\"     # BE - end boxed text (draw box now)
 126 .de BE
 127 .nf
 128 .ti 0
 129 .mk ^t
 130 .ie n \l'\\n(^lu\(ul'
 131 .el \{\
 132 .\"     Draw four-sided box normally, but don't draw top of
 133 .\"     box if the box started on an earlier page.
 134 .ie !\\n(^b-1 \{\
 135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 136 .\}
 137 .el \}\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .\}
 141 .fi
 142 .br
 143 .nr ^b 0
 144 ..
 145 .\"     # VS - start vertical sidebar
 146 .\"     # ^Y = starting y location
 147 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 148 .de VS
 149 .if !"\\$2"" .br
 150 .mk ^Y
 151 .ie n 'mc \s12\(br\s0
 152 .el .nr ^v 1u
 153 ..
 154 .\"     # VE - end of vertical sidebar
 155 .de VE
 156 .ie n 'mc
 157 .el \{\
 158 .ev 2
 159 .nf
 160 .ti 0
 161 .mk ^t
 162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 163 .sp -1
 164 .fi
 165 .ev
 166 .\}
 167 .nr ^v 0
 168 ..
 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.
 172 .de ^B
 173 .ev 2
 174 'ti 0
 175 'nf
 176 .mk ^t
 177 .if \\n(^b \{\
 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
 182 .\}
 183 .if \\n(^v \{\
 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
 186 .\}
 187 .bp
 188 'fi
 189 .ev
 190 .if \\n(^b \{\
 191 .mk ^y
 192 .nr ^b 2
 193 .\}
 194 .if \\n(^v \{\
 195 .mk ^Y
 196 .\}
 197 ..
 198 .\"     # DS - begin display
 199 .de DS
 200 .RS
 201 .nf
 202 .sp
 203 ..
 204 .\"     # DE - end display
 205 .de DE
 206 .fi
 207 .RE
 208 .sp
 209 ..
 210 .\"     # SO - start of list of standard options
 211 .de SO
 212 'ie '\\$1'' .ds So \\fBoptions\\fR
 213 'el .ds So \\fB\\$1\\fR
 214 .SH "STANDARD OPTIONS"
 215 .LP
 216 .nf
 217 .ta 5.5c 11c
 218 .ft B
 219 ..
 220 .\"     # SE - end of list of standard options
 221 .de SE
 222 .fi
 223 .ft R
 224 .LP
 225 See the \\*(So manual entry for details on the standard options.
 226 ..
 227 .\"     # OP - start of full description for a single option
 228 .de OP
 229 .LP
 230 .nf
 231 .ta 4c
 232 Command-Line Name:      \\fB\\$1\\fR
 233 Database Name:  \\fB\\$2\\fR
 234 Database Class: \\fB\\$3\\fR
 235 .fi
 236 .IP
 237 ..
 238 .\"     # CS - begin code excerpt
 239 .de CS
 240 .RS
 241 .nf
 242 .ta .25i .5i .75i 1i
 243 ..
 244 .\"     # CE - end code excerpt
 245 .de CE
 246 .fi
 247 .RE
 248 ..
 249 .\"     # UL - underline word
 250 .de UL
 251 \\$1\l'|0\(ul'\\$2
 252 ..
 253 .\"     # QW - apply quotation marks to word
 254 .de QW
 255 .ie '\\*(lq'"' ``\\$1''\\$2
 256 .\"" fix emacs highlighting
 257 .el \\*(lq\\$1\\*(rq\\$2
 258 ..
 259 .\"     # PQ - apply parens and quotation marks to word
 260 .de PQ
 261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 262 .\"" fix emacs highlighting
 263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 264 ..
 265 .\"     # QR - quoted range
 266 .de QR
 267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 268 .\"" fix emacs highlighting
 269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 270 ..
 271 .\"     # MT - "empty" string
 272 .de MT
 273 .QW ""
 274 ..
 275 .BS
 276 .SH NAME
 277 Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to measure and display simple single-line strings.
 278 .SH SYNOPSIS
 279 .nf
 280 \fB#include <tk.h>\fR
 281 .sp
 282 int
 283 \fBTk_MeasureChars(\fItkfont, string, numBytes, maxPixels, flags, lengthPtr\fB)\fR
 284 .sp
 285 int
 286 \fBTk_TextWidth(\fItkfont, string, numBytes\fB)\fR
 287 .sp
 288 \fBTk_DrawChars(\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y\fB)\fR
 289 .sp
 290 \fBTk_UnderlineChars(\fIdisplay, drawable, gc, tkfont, string, x, y, firstByte, lastByte\fB)\fR
 291 .sp
 292 .SH ARGUMENTS
 293 .AS "const char" firstChar
 294 .AP Tk_Font tkfont in
 295 Token for font in which text is to be drawn or measured.  Must have been
 296 returned by a previous call to \fBTk_GetFont\fR.
 297 .AP "const char" *string in
 298 Text to be measured or displayed.  Need not be null terminated.  Any
 299 non-printing meta-characters in the string (such as tabs, newlines, and
 300 other control characters) will be measured or displayed in a
 301 platform-dependent manner.
 302 .AP int numBytes in
 303 The maximum number of bytes to consider when measuring or drawing
 304 \fIstring\fR.  Must be greater than or equal to 0.
 305 .AP int maxPixels in
 306 If \fImaxPixels\fR is >= 0, it specifies the longest permissible
 307 line length in pixels.  Characters from \fIstring\fR are processed only
 308 until this many pixels have been covered.  If \fImaxPixels\fR is < 0, then
 309 the line length is unbounded and the \fIflags\fR argument is ignored.
 310 .AP int flags in
 311 Various flag bits OR-ed together: \fBTK_PARTIAL_OK\fR means include a character
 312 as long as any part of it fits in the length given by \fImaxPixels\fR;
 313 otherwise, a character must fit completely to be considered.
 314 \fBTK_WHOLE_WORDS\fR means stop on a word boundary, if possible.  If
 315 \fBTK_AT_LEAST_ONE\fR is set, it means return at least one character even if no
 316 characters could fit in the length given by \fImaxPixels\fR.  If
 317 \fBTK_AT_LEAST_ONE\fR is set and \fBTK_WHOLE_WORDS\fR is also set, it means that if
 318 not even one word fits on the line, return the first few letters of the
 319 word that did fit; if not even one letter of the word fit, then the first
 320 letter will still be returned.
 321 .AP int *lengthPtr out
 322 Filled with the number of pixels occupied by the number of characters
 323 returned as the result of \fBTk_MeasureChars\fR.
 324 .AP Display *display in
 325 Display on which to draw.
 326 .AP Drawable drawable in
 327 Window or pixmap in which to draw.
 328 .AP GC gc in
 329 Graphics context for drawing characters.  The font selected into this GC
 330 must be the same as the \fItkfont\fR.
 331 .AP int "x, y" in
 332 Coordinates at which to place the left edge of the baseline when displaying
 333 \fIstring\fR.
 334 .AP int firstByte in
 335 The index of the first byte of the first character to underline in the
 336 \fIstring\fR.  Underlining begins at the left edge of this character.
 337 .AP int lastByte in
 338 The index of the first byte of the last character up to which the
 339 underline will be drawn.  The character specified by \fIlastByte\fR
 340 will not itself be underlined.
 341 .BE
 342 .SH DESCRIPTION
 343 .PP
 344 These routines are for measuring and displaying simple single-font,
 345 single-line strings.  To measure and display single-font, multi-line,
 346 justified text, refer to the documentation for \fBTk_ComputeTextLayout\fR.
 347 There is no programming interface in the core of Tk that supports
 348 multi-font, multi-line text; support for that behavior must be built on
 349 top of simpler layers.
 350 Note that the interfaces described here are
 351 byte-oriented not character-oriented, so index values coming from Tcl
 352 scripts need to be converted to byte offsets using the
 353 \fBTcl_UtfAtIndex\fR and related routines.
 354 .PP
 355 A glyph is the displayable picture of a letter, number, or some other
 356 symbol.  Not all character codes in a given font have a glyph.
 357 Characters such as tabs, newlines/returns, and control characters that
 358 have no glyph are measured and displayed by these procedures in a
 359 platform-dependent manner; under X, they are replaced with backslashed
 360 escape sequences, while under Windows and Macintosh hollow or solid boxes
 361 may be substituted.  Refer to the documentation for
 362 \fBTk_ComputeTextLayout\fR for a programming interface that supports the
 363 platform-independent expansion of tab characters into columns and
 364 newlines/returns into multi-line text.
 365 .PP
 366 \fBTk_MeasureChars\fR is used both to compute the length of a given
 367 string and to compute how many characters from a string fit in a given
 368 amount of space.  The return value is the number of bytes from
 369 \fIstring\fR that fit in the space specified by \fImaxPixels\fR subject to
 370 the conditions described by \fIflags\fR.  If all characters fit, the return
 371 value will be \fInumBytes\fR.  \fI*lengthPtr\fR is filled with the computed
 372 width, in pixels, of the portion of the string that was measured.  For
 373 example, if the return value is 5, then \fI*lengthPtr\fR is filled with the
 374 distance between the left edge of \fIstring\fR[0] and the right edge of
 375 \fIstring\fR[4].
 376 .PP
 377 \fBTk_TextWidth\fR is a wrapper function that provides a simpler interface
 378 to the \fBTk_MeasureChars\fR function.  The return value is how much
 379 space in pixels the given \fIstring\fR needs.
 380 .PP
 381 \fBTk_DrawChars\fR draws the \fIstring\fR at the given location in the
 382 given \fIdrawable\fR.
 383 .PP
 384 \fBTk_UnderlineChars\fR underlines the given range of characters in the
 385 given \fIstring\fR.  It does not draw the characters (which are assumed to
 386 have been displayed previously by \fBTk_DrawChars\fR); it just draws the
 387 underline.  This procedure is used to underline a few characters without
 388 having to construct an underlined font.  To produce natively underlined
 389 text, the appropriate underlined font should be constructed and used.
 390 .SH "SEE ALSO"
 391 font(n), FontId(3)
 392 .SH KEYWORDS
 393 font, measurement