GetBitmap man page on BSDOS

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDOS logo
[printable version]



Tk_GetBitmap(3)	      Tk Library Procedures	  Tk_GetBitmap(3)

_________________________________________________________________

NAME
       Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOf-
       Bitmap,	Tk_FreeBitmap,	Tk_GetBitmapFromData  -	 maintain
       database of single-plane pixmaps

SYNOPSIS
       #include <tk.h>

       Pixmap
       Tk_GetBitmap(interp, tkwin, id)

       int
       Tk_DefineBitmap(interp, nameId, source, width, height)

       Tk_Uid
       Tk_NameOfBitmap(display, bitmap)

       Tk_SizeOfBitmap(display, bitmap, widthPtr, heightPtr)

       Tk_FreeBitmap(display, bitmap)

ARGUMENTS
       Tcl_Interp      *interp	   (in)	     Interpreter  to  use
					     for error reporting.

       Tk_Window       tkwin	   (in)	     Token  for window in
					     which   the   bitmap
					     will be used.

       Tk_Uid	       id	   (in)	     Description       of
					     bitmap;   see  below
					     for possible values.

       Tk_Uid	       nameId	   (in)	     Name for new  bitmap
					     to be defined.

       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

Tk			       4.1				1

Tk_GetBitmap(3)	      Tk Library Procedures	  Tk_GetBitmap(3)

					     fill     in     with
					     bitmap's height.

       Display	       *display	   (in)	     Display  for   which
					     bitmap   was   allo-
					     cated.

       Pixmap	       bitmap	   (in)	     Identifier	  for	a
					     bitmap  allocated by
					     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_GetBitmap takes  as  argument	 a  Tk_Uid  describing	a
       bitmap.	 It returns a Pixmap identifier for a bitmap cor-
       responding to the description.	It  re-uses  an	 existing
       bitmap,	if possible, and creates a new one otherwise.  At
       present, id must have one of the following forms:

       @fileName	   FileName must be the name  of  a  file
			   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.

			   gray50      50%  gray:  a checkerboard
				       pattern where every  other
				       bit 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

Tk			       4.1				2

Tk_GetBitmap(3)	      Tk Library Procedures	  Tk_GetBitmap(3)

				       head, with a question mark
				       in it.

			   question    A large question-mark.

			   warning     A large exclamation point.

       Under normal conditions, Tk_GetBitmap returns  an  identi-
       fier for the requested bitmap.  If an error occurs in cre-
       ating the bitmap, such as when id refers to a non-existent
       file,  then  None is returned and an error message is left
       in interp->result.

       Tk_DefineBitmap associates a name  with	in-memory  bitmap
       data  so	 that  the  name  can  be  used in later calls to
       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  pri-
       vate copy of this memory, but uses the bytes pointed to by
       source later in calls to 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, Tk_GetUid("foo"), stip_bits,
		stip_width, stip_height);
	      ...
	      bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo"));
       This code causes the bitmap file to be  read  at	 compile-
       time and incorporates the bitmap information into the pro-
       gram's executable image.	 The same bitmap  file	could  be
       read at run-time using Tk_GetBitmap:
	      Pixmap bitmap;
	      bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.bitmap"));
       The  second form is a bit more flexible (the file could be
       modified after the program has been compiled, or a differ-
       ent  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_GetBitmap  maintains a database of all the bitmaps that
       are currently in use.  Whenever possible, it  will  return

Tk			       4.1				3

Tk_GetBitmap(3)	      Tk Library Procedures	  Tk_GetBitmap(3)

       an  existing  bitmap rather than creating a new one.  This
       approach can  substantially  reduce  server  overhead,  so
       Tk_GetBitmap  should  generally	be  used in preference to
       Xlib procedures like XReadBitmapFile.

       The  bitmaps  returned  by  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 XReadBitmapFile or XCreatePixmap
       directly.

       The procedure Tk_NameOfBitmap is roughly	 the  inverse  of
       Tk_GetBitmap.   Given an X Pixmap argument, it returns the
       id that was passed to Tk_GetBitmap  when	 the  bitmap  was
       created.	  Bitmap  must	have been the return value from a
       previous call to 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_GetBitmap.

       When  a	bitmap	returned  by  Tk_GetBitmap  is	no longer
       needed, Tk_FreeBitmap should  be	 called	 to  release  it.
       There should be exactly one call to Tk_FreeBitmap for each
       call to Tk_GetBitmap.  When a bitmap is no longer  in  use
       anywhere	 (i.e.	it has been freed as many times as it has
       been gotten) Tk_FreeBitmap will release it to the X server
       and delete it from the database.

BUGS
       In  determining	whether an existing bitmap can be used to
       satisfy a new request,  Tk_GetBitmap  considers	only  the
       immediate  value	 of its id argument.  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 direc-
       tory has changed, thereby causing the name to refer  to	a
       different file.

KEYWORDS
       bitmap, pixmap

Tk			       4.1				4

[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server BSDOS

List of man pages available for BSDOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net