util/X86LINUX64/man/man3/Tk_SizeOfBitmap.3

   1 '\"
   2 '\" Copyright (c) 1990 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH Tk_AllocBitmapFromObj 3 8.1 Tk "Tk Library Procedures"
   9 .\" The -*- nroff -*- definitions below are for supplemental macros used
  10 .\" in Tcl/Tk manual entries.
  11 .\"
  12 .\" .AP type name in/out ?indent?
  13 .\"     Start paragraph describing an argument to a library procedure.
  14 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  15 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  16 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  17 .\"     needed;  use .AS below instead)
  18 .\"
  19 .\" .AS ?type? ?name?
  20 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  21 .\"     name are examples of largest possible arguments that will be passed
  22 .\"     to .AP later.  If args are omitted, default tab stops are used.
  23 .\"
  24 .\" .BS
  25 .\"     Start box enclosure.  From here until next .BE, everything will be
  26 .\"     enclosed in one large box.
  27 .\"
  28 .\" .BE
  29 .\"     End of box enclosure.
  30 .\"
  31 .\" .CS
  32 .\"     Begin code excerpt.
  33 .\"
  34 .\" .CE
  35 .\"     End code excerpt.
  36 .\"
  37 .\" .VS ?version? ?br?
  38 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  39 .\"     of man pages.  The first argument is ignored and used for recording
  40 .\"     the version when the .VS was added, so that the sidebars can be
  41 .\"     found and removed when they reach a certain age.  If another argument
  42 .\"     is present, then a line break is forced before starting the sidebar.
  43 .\"
  44 .\" .VE
  45 .\"     End of vertical sidebar.
  46 .\"
  47 .\" .DS
  48 .\"     Begin an indented unfilled display.
  49 .\"
  50 .\" .DE
  51 .\"     End of indented unfilled display.
  52 .\"
  53 .\" .SO ?manpage?
  54 .\"     Start of list of standard options for a Tk widget. The manpage
  55 .\"     argument defines where to look up the standard options; if
  56 .\"     omitted, defaults to "options". The options follow on successive
  57 .\"     lines, in three columns separated by tabs.
  58 .\"
  59 .\" .SE
  60 .\"     End of list of standard options for a Tk widget.
  61 .\"
  62 .\" .OP cmdName dbName dbClass
  63 .\"     Start of description of a specific option.  cmdName gives the
  64 .\"     option's name as specified in the class command, dbName gives
  65 .\"     the option's name in the option database, and dbClass gives
  66 .\"     the option's class in the option database.
  67 .\"
  68 .\" .UL arg1 arg2
  69 .\"     Print arg1 underlined, then print arg2 normally.
  70 .\"
  71 .\" .QW arg1 ?arg2?
  72 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  73 .\"
  74 .\" .PQ arg1 ?arg2?
  75 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  76 .\"     (for trailing punctuation) and then a closing parenthesis.
  77 .\"
  78 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  79 .if t .wh -1.3i ^B
  80 .nr ^l \n(.l
  81 .ad b
  82 .\"     # Start an argument description
  83 .de AP
  84 .ie !"\\$4"" .TP \\$4
  85 .el \{\
  86 .   ie !"\\$2"" .TP \\n()Cu
  87 .   el          .TP 15
  88 .\}
  89 .ta \\n()Au \\n()Bu
  90 .ie !"\\$3"" \{\
  91 \&\\$1 \\fI\\$2\\fP (\\$3)
  92 .\".b
  93 .\}
  94 .el \{\
  95 .br
  96 .ie !"\\$2"" \{\
  97 \&\\$1  \\fI\\$2\\fP
  98 .\}
  99 .el \{\
 100 \&\\fI\\$1\\fP
 101 .\}
 102 .\}
 103 ..
 104 .\"     # define tabbing values for .AP
 105 .de AS
 106 .nr )A 10n
 107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 108 .nr )B \\n()Au+15n
 109 .\"
 110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 112 ..
 113 .AS Tcl_Interp Tcl_CreateInterp in/out
 114 .\"     # BS - start boxed text
 115 .\"     # ^y = starting y location
 116 .\"     # ^b = 1
 117 .de BS
 118 .br
 119 .mk ^y
 120 .nr ^b 1u
 121 .if n .nf
 122 .if n .ti 0
 123 .if n \l'\\n(.lu\(ul'
 124 .if n .fi
 125 ..
 126 .\"     # BE - end boxed text (draw box now)
 127 .de BE
 128 .nf
 129 .ti 0
 130 .mk ^t
 131 .ie n \l'\\n(^lu\(ul'
 132 .el \{\
 133 .\"     Draw four-sided box normally, but don't draw top of
 134 .\"     box if the box started on an earlier page.
 135 .ie !\\n(^b-1 \{\
 136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 137 .\}
 138 .el \}\
 139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 140 .\}
 141 .\}
 142 .fi
 143 .br
 144 .nr ^b 0
 145 ..
 146 .\"     # VS - start vertical sidebar
 147 .\"     # ^Y = starting y location
 148 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 149 .de VS
 150 .if !"\\$2"" .br
 151 .mk ^Y
 152 .ie n 'mc \s12\(br\s0
 153 .el .nr ^v 1u
 154 ..
 155 .\"     # VE - end of vertical sidebar
 156 .de VE
 157 .ie n 'mc
 158 .el \{\
 159 .ev 2
 160 .nf
 161 .ti 0
 162 .mk ^t
 163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 164 .sp -1
 165 .fi
 166 .ev
 167 .\}
 168 .nr ^v 0
 169 ..
 170 .\"     # Special macro to handle page bottom:  finish off current
 171 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 172 .\"     # page bottom macro.
 173 .de ^B
 174 .ev 2
 175 'ti 0
 176 'nf
 177 .mk ^t
 178 .if \\n(^b \{\
 179 .\"     Draw three-sided box if this is the box's first page,
 180 .\"     draw two sides but no top otherwise.
 181 .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
 182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 183 .\}
 184 .if \\n(^v \{\
 185 .nr ^x \\n(^tu+1v-\\n(^Yu
 186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 187 .\}
 188 .bp
 189 'fi
 190 .ev
 191 .if \\n(^b \{\
 192 .mk ^y
 193 .nr ^b 2
 194 .\}
 195 .if \\n(^v \{\
 196 .mk ^Y
 197 .\}
 198 ..
 199 .\"     # DS - begin display
 200 .de DS
 201 .RS
 202 .nf
 203 .sp
 204 ..
 205 .\"     # DE - end display
 206 .de DE
 207 .fi
 208 .RE
 209 .sp
 210 ..
 211 .\"     # SO - start of list of standard options
 212 .de SO
 213 'ie '\\$1'' .ds So \\fBoptions\\fR
 214 'el .ds So \\fB\\$1\\fR
 215 .SH "STANDARD OPTIONS"
 216 .LP
 217 .nf
 218 .ta 5.5c 11c
 219 .ft B
 220 ..
 221 .\"     # SE - end of list of standard options
 222 .de SE
 223 .fi
 224 .ft R
 225 .LP
 226 See the \\*(So manual entry for details on the standard options.
 227 ..
 228 .\"     # OP - start of full description for a single option
 229 .de OP
 230 .LP
 231 .nf
 232 .ta 4c
 233 Command-Line Name:      \\fB\\$1\\fR
 234 Database Name:  \\fB\\$2\\fR
 235 Database Class: \\fB\\$3\\fR
 236 .fi
 237 .IP
 238 ..
 239 .\"     # CS - begin code excerpt
 240 .de CS
 241 .RS
 242 .nf
 243 .ta .25i .5i .75i 1i
 244 ..
 245 .\"     # CE - end code excerpt
 246 .de CE
 247 .fi
 248 .RE
 249 ..
 250 .\"     # UL - underline word
 251 .de UL
 252 \\$1\l'|0\(ul'\\$2
 253 ..
 254 .\"     # QW - apply quotation marks to word
 255 .de QW
 256 .ie '\\*(lq'"' ``\\$1''\\$2
 257 .\"" fix emacs highlighting
 258 .el \\*(lq\\$1\\*(rq\\$2
 259 ..
 260 .\"     # PQ - apply parens and quotation marks to word
 261 .de PQ
 262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 263 .\"" fix emacs highlighting
 264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 265 ..
 266 .\"     # QR - quoted range
 267 .de QR
 268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 269 .\"" fix emacs highlighting
 270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 271 ..
 272 .\"     # MT - "empty" string
 273 .de MT
 274 .QW ""
 275 ..
 276 .BS
 277 .SH NAME
 278 Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap \- maintain database of single-plane pixmaps
 279 .SH SYNOPSIS
 280 .nf
 281 \fB#include <tk.h>\fR
 282 .sp
 283 Pixmap
 284 \fBTk_AllocBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR
 285 .sp
 286 Pixmap
 287 \fBTk_GetBitmap(\fIinterp, tkwin, info\fB)\fR
 288 .sp
 289 Pixmap
 290 \fBTk_GetBitmapFromObj(\fItkwin, objPtr\fB)\fR
 291 .sp
 292 int
 293 \fBTk_DefineBitmap(\fIinterp, name, source, width, height\fB)\fR
 294 .sp
 295 const char *
 296 \fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR
 297 .sp
 298 \fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR
 299 .sp
 300 \fBTk_FreeBitmapFromObj(\fItkwin, objPtr\fB)\fR
 301 .sp
 302 \fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR
 303 .SH ARGUMENTS
 304 .AS "unsigned long" *pixelPtr
 305 .AP Tcl_Interp *interp in
 306 Interpreter to use for error reporting; if NULL then no error message
 307 is left after errors.
 308 .AP Tk_Window tkwin in
 309 Token for window in which the bitmap will be used.
 310 .AP Tcl_Obj *objPtr in/out
 311 String value describes desired bitmap; internal rep will be
 312 modified to cache pointer to corresponding Pixmap.
 313 .AP "const char" *info in
 314 Same as \fIobjPtr\fR except description of bitmap is passed as a string and
 315 resulting Pixmap is not cached.
 316 .AP "const char" *name in
 317 Name for new bitmap to be defined.
 318 .AP "const void" *source in
 319 Data for bitmap, in standard bitmap format.
 320 Must be stored in static memory whose value will never change.
 321 .AP "int" width in
 322 Width of bitmap.
 323 .AP "int" height in
 324 Height of bitmap.
 325 .AP "int" *widthPtr out
 326 Pointer to word to fill in with \fIbitmap\fR's width.
 327 .AP "int" *heightPtr out
 328 Pointer to word to fill in with \fIbitmap\fR's height.
 329 .AP Display *display in
 330 Display for which \fIbitmap\fR was allocated.
 331 .AP Pixmap bitmap in
 332 Identifier for a bitmap allocated by \fBTk_AllocBitmapFromObj\fR or
 333 \fBTk_GetBitmap\fR.
 334 .BE
 335 .SH DESCRIPTION
 336 .PP
 337 These procedures manage a collection of bitmaps (one-plane pixmaps)
 338 being used by an application.  The procedures allow bitmaps to be
 339 re-used efficiently, thereby avoiding server overhead, and also
 340 allow bitmaps to be named with character strings.
 341 .PP
 342 \fBTk_AllocBitmapFromObj\fR returns a Pixmap identifier for a bitmap
 343 that matches the description in \fIobjPtr\fR and is suitable for use
 344 in \fItkwin\fR.  It re-uses an existing bitmap, if possible, and
 345 creates a new one otherwise.  \fIObjPtr\fR's value must have one
 346 of the following forms:
 347 .TP 20
 348 \fB@\fIfileName\fR
 349 \fIFileName\fR must be the name of a file containing a bitmap
 350 description in the standard X11 format.
 351 .TP 20
 352 \fIname\fR
 353 \fIName\fR must be the name of a bitmap defined previously with
 354 a call to \fBTk_DefineBitmap\fR.  The following names are pre-defined
 355 by Tk:
 356 .RS
 357 .TP 12
 358 \fBerror\fR
 359 The international
 360 .QW don't
 361 symbol:  a circle with a diagonal line across it.
 362 .TP 12
 363 \fBgray75\fR
 364 75% gray: a checkerboard pattern where three out of four bits are on.
 365 .TP 12
 366 \fBgray50\fR
 367 50% gray: a checkerboard pattern where every other bit is on.
 368 .TP 12
 369 \fBgray25\fR
 370 25% gray: a checkerboard pattern where one out of every four bits is on.
 371 .TP 12
 372 \fBgray12\fR
 373 12.5% gray: a pattern where one-eighth of the bits are on, consisting of
 374 every fourth pixel in every other row.
 375 .TP 12
 376 \fBhourglass\fR
 377 An hourglass symbol.
 378 .TP 12
 379 \fBinfo\fR
 380 A large letter
 381 .QW i .
 382 .TP 12
 383 \fBquesthead\fR
 384 The silhouette of a human head, with a question mark in it.
 385 .TP 12
 386 \fBquestion\fR
 387 A large question-mark.
 388 .TP 12
 389 \fBwarning\fR
 390 A large exclamation point.
 391 .PP
 392 In addition, the following pre-defined names are available only on the
 393 \fBMacintosh\fR platform:
 394 .TP 12
 395 \fBdocument\fR
 396 A generic document.
 397 .TP 12
 398 \fBstationery\fR
 399 Document stationery.
 400 .TP 12
 401 \fBedition\fR
 402 The \fIedition\fR symbol.
 403 .TP 12
 404 \fBapplication\fR
 405 Generic application icon.
 406 .TP 12
 407 \fBaccessory\fR
 408 A desk accessory.
 409 .TP 12
 410 \fBfolder\fR
 411 Generic folder icon.
 412 .TP 12
 413 \fBpfolder\fR
 414 A locked folder.
 415 .TP 12
 416 \fBtrash\fR
 417 A trash can.
 418 .TP 12
 419 \fBfloppy\fR
 420 A floppy disk.
 421 .TP 12
 422 \fBramdisk\fR
 423 A floppy disk with chip.
 424 .TP 12
 425 \fBcdrom\fR
 426 A cd disk icon.
 427 .TP 12
 428 \fBpreferences\fR
 429 A folder with prefs symbol.
 430 .TP 12
 431 \fBquerydoc\fR
 432 A database document icon.
 433 .TP 12
 434 \fBstop\fR
 435 A stop sign.
 436 .TP 12
 437 \fBnote\fR
 438 A face with balloon words.
 439 .TP 12
 440 \fBcaution\fR
 441 A triangle with an exclamation point.
 442 .RE
 443 .LP
 444 Under normal conditions, \fBTk_AllocBitmapFromObj\fR
 445 returns an identifier for the requested bitmap.  If an error
 446 occurs in creating the bitmap, such as when \fIobjPtr\fR refers
 447 to a non-existent file, then \fBNone\fR is returned and an error
 448 message is left in \fIinterp\fR's result if \fIinterp\fR is not
 449 NULL. \fBTk_AllocBitmapFromObj\fR caches information about the return
 450 value in \fIobjPtr\fR, which speeds up future calls to procedures
 451 such as \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmapFromObj\fR.
 452 .PP
 453 \fBTk_GetBitmap\fR is identical to \fBTk_AllocBitmapFromObj\fR except
 454 that the description of the bitmap is specified with a string instead
 455 of an object.  This prevents \fBTk_GetBitmap\fR from caching the
 456 return value, so \fBTk_GetBitmap\fR is less efficient than
 457 \fBTk_AllocBitmapFromObj\fR.
 458 .PP
 459 \fBTk_GetBitmapFromObj\fR returns the token for an existing bitmap, given
 460 the window and description used to create the bitmap.
 461 \fBTk_GetBitmapFromObj\fR does not actually create the bitmap; the bitmap
 462 must already have been created with a previous call to
 463 \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.  The return
 464 value is cached in \fIobjPtr\fR, which speeds up
 465 future calls to \fBTk_GetBitmapFromObj\fR with the same \fIobjPtr\fR
 466 and \fItkwin\fR.
 467 .PP
 468 \fBTk_DefineBitmap\fR associates a name with
 469 in-memory bitmap data so that the name can be used in later
 470 calls to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.  The \fInameId\fR
 471 argument gives a name for the bitmap;  it must not previously
 472 have been used in a call to \fBTk_DefineBitmap\fR.
 473 The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR
 474 describe the bitmap.
 475 \fBTk_DefineBitmap\fR normally returns \fBTCL_OK\fR; if an error occurs
 476 (e.g. a bitmap named \fInameId\fR has already been defined) then
 477 \fBTCL_ERROR\fR is returned and an error message is left in
 478 interpreter \fIinterp\fR's result.
 479 Note:  \fBTk_DefineBitmap\fR expects the memory pointed to by
 480 \fIsource\fR to be static:  \fBTk_DefineBitmap\fR does not make
 481 a private copy of this memory, but uses the bytes pointed to
 482 by \fIsource\fR later in calls to \fBTk_AllocBitmapFromObj\fR or
 483 \fBTk_GetBitmap\fR.
 484 .PP
 485 Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a
 486 bitmap file directly into a C program and then referencing
 487 the variables defined by the file.
 488 For example, suppose there exists a file \fBstip.bitmap\fR,
 489 which was created by the \fBbitmap\fR program and contains
 490 a stipple pattern.
 491 The following code uses \fBTk_DefineBitmap\fR to define a
 492 new bitmap named \fBfoo\fR:
 493 .CS
 494 Pixmap bitmap;
 495 #include "stip.bitmap"
 496 Tk_DefineBitmap(interp, "foo", stip_bits,
 497     stip_width, stip_height);
 498 \&...
 499 bitmap = Tk_GetBitmap(interp, tkwin, "foo");
 500 .CE
 501 This code causes the bitmap file to be read
 502 at compile-time and incorporates the bitmap information into
 503 the program's executable image.  The same bitmap file could be
 504 read at run-time using \fBTk_GetBitmap\fR:
 505 .CS
 506 Pixmap bitmap;
 507 bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap");
 508 .CE
 509 The second form is a bit more flexible (the file could be modified
 510 after the program has been compiled, or a different string could be
 511 provided to read a different file), but it is a little slower and
 512 requires the bitmap file to exist separately from the program.
 513 .PP
 514 Tk maintains a database of all the bitmaps that are currently in use.
 515 Whenever possible, it will return an existing bitmap rather
 516 than creating a new one.
 517 When a bitmap is no longer used, Tk will release it automatically.
 518 This approach can substantially reduce server overhead, so
 519 \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR should generally
 520 be used in preference to Xlib procedures like \fBXReadBitmapFile\fR.
 521 .PP
 522 The bitmaps returned by \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR
 523 are shared, so callers should never modify them.
 524 If a bitmap must be modified dynamically, then it should be
 525 created by calling Xlib procedures such as \fBXReadBitmapFile\fR
 526 or \fBXCreatePixmap\fR directly.
 527 .PP
 528 The procedure \fBTk_NameOfBitmap\fR is roughly the inverse of
 529 \fBTk_GetBitmap\fR.
 530 Given an X Pixmap argument, it returns the textual description that was
 531 passed to \fBTk_GetBitmap\fR when the bitmap was created.
 532 \fIBitmap\fR must have been the return value from a previous
 533 call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.
 534 .PP
 535 \fBTk_SizeOfBitmap\fR returns the dimensions of its \fIbitmap\fR
 536 argument in the words pointed to by the \fIwidthPtr\fR and
 537 \fIheightPtr\fR arguments.  As with \fBTk_NameOfBitmap\fR,
 538 \fIbitmap\fR must have been created by \fBTk_AllocBitmapFromObj\fR or
 539 \fBTk_GetBitmap\fR.
 540 .PP
 541 When a bitmap is no longer needed, \fBTk_FreeBitmapFromObj\fR or
 542 \fBTk_FreeBitmap\fR should be called to release it.
 543 For \fBTk_FreeBitmapFromObj\fR the bitmap to release is specified
 544 with the same information used to create it; for
 545 \fBTk_FreeBitmap\fR the bitmap to release is specified
 546 with its Pixmap token.
 547 There should be exactly one call to \fBTk_FreeBitmapFromObj\fR
 548 or \fBTk_FreeBitmap\fR for each call to \fBTk_AllocBitmapFromObj\fR or
 549 \fBTk_GetBitmap\fR.
 550 .SH BUGS
 551 .PP
 552 In determining whether an existing bitmap can be used to satisfy
 553 a new request, \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR
 554 consider only the immediate value of the string description.  For
 555 example, when a file name is passed to \fBTk_GetBitmap\fR,
 556 \fBTk_GetBitmap\fR will assume it is safe to re-use an existing
 557 bitmap created from the same file name:  it will not check to
 558 see whether the file itself has changed, or whether the current
 559 directory has changed, thereby causing the name to refer to
 560 a different file.
 561 .SH KEYWORDS
 562 bitmap, pixmap