Windows PowerShell command on Get-command Tk

Manual Pages for UNIX Operating System command usage for man Tk_NameOfBitmap

Tk Library Procedures Tk_AllocBitmapFromObj(3TK)

_________________________________________________________________

NAME

Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj,

Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap,

Tk_FreeBitmapFromObj, Tk_FreeBitmap - maintain database of

single-plane pixmaps

SYNOPSIS

#include

Pixmap |

Tk_AllocBitmapFromObj(interp, tkwin, objPtr) |

Pixmap |

Tk_GetBitmap(interp, tkwin, info) |

Pixmap |

Tk_GetBitmapFromObj(tkwin, objPtr) |

int

Tk_DefineBitmap(interp, name, source, width, height)

CONST char *

Tk_NameOfBitmap(display, bitmap)

Tk_SizeOfBitmap(display, bitmap, widthPtr, heightPtr)

Tk_FreeBitmapFromObj(tkwin, objPtr) |

Tk_FreeBitmap(display, bitmap)

ARGUMENTS

Tcl_Interp *interp (in) Interpreter to use for

error reporting; if NULL then no error message is left after errors.

Tk_Window tkwin (in) Token for window in

which the bitmap will be used.

Tcl_Obj *objPtr (in/out) ||

String value describes |

desired bitmap; inter- |

nal rep will be modi- |

fied to cache pointer |

to corresponding Pix- |

map. | CONST char *info (in) || Tk Last change: 8.1 1

Tk Library Procedures Tk_AllocBitmapFromObj(3TK)

Same as objPtr except | description of bitmap | is passed as a string | and resulting Pixmap | isn't cached. CONST char *name (in) Name for new bitmap to be defined. CONST char *source (in) Data for bitmap, in

standard bitmap for-

mat. Must be stored in static memory whose value will never change. int width (in) Width of bitmap. int height (in) Height of bitmap. int *widthPtr (out) Pointer to word to fill in with bitmap's width. int *heightPtr (out) Pointer to word to fill in with bitmap's height.

Display *display (in) Display for which bit-

map was allocated.

Pixmap bitmap (in) Identifier for a bit-

map allocated by

Tk_AllocBitmapFromObj

or Tk_GetBitmap.

_________________________________________________________________

DESCRIPTION

These procedures manage a collection of bitmaps (one-plane

pixmaps) being used by an application. The procedures allow

bitmaps to be re-used efficiently, thereby avoiding server

overhead, and also allow bitmaps to be named with character strings.

Tk_AllocBitmapFromObj returns a Pixmap identifier for a bit- |

map that matches the description in objPtr and is suitable |

for use in tkwin. It re-uses an existing bitmap, if possi- |

ble, and creates a new one otherwise. ObjPtr's value must | have one of the following forms: @fileName FileName must be the name of a file Tk Last change: 8.1 2

Tk Library Procedures Tk_AllocBitmapFromObj(3TK)

containing a bitmap description in the standard X11 or X10 format. name Name must be the name of a bitmap defined previously with a call to

Tk_DefineBitmap. The following names

are pre-defined by Tk:

error The international "don't" symbol: a circle with a diagonal line across it. gray75 ||

75% gray: a checkerboard |

pattern where three out of | four bits are on.

gray50 50% gray: a checkerboard

pattern where every other bit is on. gray25 ||

25% gray: a checkerboard |

pattern where one out of | every four bits is on.

gray12 12.5% gray: a pattern where

one-eighth of the bits are

on, consisting of every fourth pixel in every other row. hourglass An hourglass symbol. info A large letter ``i''. questhead The silhouette of a human head, with a question mark in it.

question A large question-mark.

warning A large exclamation point.

In addition, the following pre-defined

names are available only on the Macin-

tosh platform: document A generic document. stationery Document stationery. Tk Last change: 8.1 3

Tk Library Procedures Tk_AllocBitmapFromObj(3TK)

edition The edition symbol. application Generic application icon. accessory A desk accessory. folder Generic folder icon. pfolder A locked folder. trash A trash can. floppy A floppy disk. ramdisk A floppy disk with chip. cdrom A cd disk icon. preferences A folder with prefs symbol. querydoc A database document icon. stop A stop sign. note A face with ballon words.

caution A triangle with an exclama-

tion point.

Under normal conditions, Tk_AllocBitmapFromObj returns an |

identifier for the requested bitmap. If an error occurs in |

creating the bitmap, such as when objPtr refers to a non- |

existent file, then None is returned and an error message is | left in interp's result if interp isn't NULL. |

Tk_AllocBitmapFromObj caches information about the return |

value in objPtr, which speeds up future calls to procedures |

such as Tk_AllocBitmapFromObj and Tk_GetBitmapFromObj. |

Tk_GetBitmap is identical to Tk_AllocBitmapFromObj except |

that the description of the bitmap is specified with a |

string instead of an object. This prevents Tk_GetBitmap |

from caching the return value, so Tk_GetBitmap is less effi- |

cient than Tk_AllocBitmapFromObj. |

Tk_GetBitmapFromObj returns the token for an existing bit- |

map, given the window and description used to create the |

bitmap. Tk_GetBitmapFromObj doesn't actually create the |

bitmap; the bitmap must already have been created with a |

previous call to Tk_AllocBitmapFromObj or Tk_GetBitmap. The |

return value is cached in objPtr, which speeds up future |

calls to Tk_GetBitmapFromObj with the same objPtr and tkwin.

Tk Last change: 8.1 4

Tk Library Procedures Tk_AllocBitmapFromObj(3TK)

Tk_DefineBitmap associates a name with in-memory bitmap data

so that the name can be used in later calls to

Tk_AllocBitmapFromObj or Tk_GetBitmap. The nameId argument

gives a name for the bitmap; it must not previously have

been used in a call to Tk_DefineBitmap. The arguments

source, width, and height describe the bitmap.

Tk_DefineBitmap normally returns TCL_OK; if an error occurs

(e.g. a bitmap named nameId has already been defined) then

TCL_ERROR is returned and an error message is left in

interp->result. Note: Tk_DefineBitmap expects the memory

pointed to by source to be static: Tk_DefineBitmap doesn't

make a private copy of this memory, but uses the bytes

pointed to by source later in calls to Tk_AllocBitmapFromObj

or Tk_GetBitmap.

Typically Tk_DefineBitmap is used by #include-ing a bitmap

file directly into a C program and then referencing the variables defined by the file. For example, suppose there exists a file stip.bitmap, which was created by the bitmap program and contains a stipple pattern. The following code

uses Tk_DefineBitmap to define a new bitmap named foo: |

Pixmap bitmap; |

#include "stip.bitmap" |

Tk_DefineBitmap(interp, "foo", stip_bits, |

stip_width, stip_height); |

... |

bitmap = Tk_GetBitmap(interp, tkwin, "foo"); |

This code causes the bitmap file to be read at compile-time

and incorporates the bitmap information into the program's executable image. The same bitmap file could be read at

run-time using Tk_GetBitmap: |

Pixmap bitmap; |

bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap"); |

The second form is a bit more flexible (the file could be modified after the program has been compiled, or a different string could be provided to read a different file), but it is a little slower and requires the bitmap file to exist separately from the program. Tk maintains a database of all the bitmaps that are currently in use. Whenever possible, it will return an

existing bitmap rather than creating a new one. When a bit-

map is no longer used, Tk will release it automatically. This approach can substantially reduce server overhead, so

Tk_AllocBitmapFromObj and Tk_GetBitmap should generally be

used in preference to Xlib procedures like XReadBitmapFile.

The bitmaps returned by Tk_AllocBitmapFromObj and

Tk_GetBitmap are shared, so callers should never modify

them. If a bitmap must be modified dynamically, then it

should be created by calling Xlib procedures such as XRead-

BitmapFile or XCreatePixmap directly. Tk Last change: 8.1 5

Tk Library Procedures Tk_AllocBitmapFromObj(3TK)

The procedure Tk_NameOfBitmap is roughly the inverse of

Tk_GetBitmap. Given an X Pixmap argument, it returns the

textual description that was passed to Tk_GetBitmap when the

bitmap was created. Bitmap must have been the return value

from a previous call to Tk_AllocBitmapFromObj or

Tk_GetBitmap.

Tk_SizeOfBitmap returns the dimensions of its bitmap argu-

ment in the words pointed to by the widthPtr and heightPtr

arguments. As with Tk_NameOfBitmap, bitmap must have been

created by Tk_AllocBitmapFromObj or Tk_GetBitmap.

When a bitmap is no longer needed, Tk_FreeBitmapFromObj or |

Tk_FreeBitmap should be called to release it. For |

Tk_FreeBitmapFromObj the bitmap to release is specified with |

the same information used to create it; for Tk_FreeBitmap |

the bitmap to release is specified with its Pixmap token. |

There should be exactly one call to Tk_FreeBitmapFromObj or |

Tk_FreeBitmap for each call to Tk_AllocBitmapFromObj or |

Tk_GetBitmap.

BUGS

In determining whether an existing bitmap can be used to

satisfy a new request, Tk_AllocBitmapFromObj and

Tk_GetBitmap consider only the immediate value of the string

description. For example, when a file name is passed to

Tk_GetBitmap, Tk_GetBitmap will assume it is safe to re-use

an existing bitmap created from the same file name: it will not check to see whether the file itself has changed, or whether the current directory has changed, thereby causing the name to refer to a different file. KEYWORDS bitmap, pixmap

ATTRIBUTES

See attributes(5) for descriptions of the following attri-

butes: Tk Last change: 8.1 6

Tk Library Procedures Tk_AllocBitmapFromObj(3TK)

_______________________________________

| ATTRIBUTE TYPE | ATTRIBUTE VALUE|

|____________________|__________________|_

| Availability | runtime/tk-8 |

|____________________|__________________|_

| Interface Stability| Uncommitted |

|____________________|_________________|

NOTES Source for Tk is available on http://opensolaris.org. Tk Last change: 8.1 7