Tk_GetImageMasterData man page on UnixWare

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

Tk_CreateImageType(3)	     Tk Library Procedures	 Tk_CreateImageType(3)

______________________________________________________________________________

NAME
       Tk_CreateImageType, Tk_GetImageMasterData - define new kind of image

SYNOPSIS
       #include <tk.h>

       Tk_CreateImageType(typePtr)
       ClientData

       Tk_GetImageMasterData(interp, name, typePtrPtr)			       │

ARGUMENTS								       │
       Tk_ImageType   *typePtr	    (in)				       │
					      Structure	 that  defines the new │
					      type of image.  Must be  static: │
					      a	 pointer  to this structure is │
					      retained by the image code.      │

       Tcl_Interp     *interp	    (in)				       │
					      Interpreter in which  image  was │
					      created.			       │

       char	      *name	    (in)				       │
					      Name of existing image.	       │

       Tk_ImageType   **typePtrPtr  (out)				       │
					      Points to word in which to store │
					      a pointer	 to  type  information │
					      for   the	 given	image,	if  it │
					      exists.
_________________________________________________________________

DESCRIPTION
       Tk_CreateImageType is invoked to define a new kind of image.  An	 image
       type  corresponds  to  a	 particular value of the type argument for the
       image create command.  There may exist any number  of  different	 image
       types, and new types may be defined dynamically by calling Tk_CreateIm‐
       ageType.	 For example, there might be one  type	for  2-color  bitmaps,
       another	for  multi-color  images, another for dithered images, another
       for video, and so on.

       The code that implements a new image type is called an  image  manager.
       It consists of a collection of procedures plus three different kinds of
       data structures.	 The first data structure is a Tk_ImageType structure,
       which  contains	the name of the image type and pointers to five proce‐
       dures provided by the image manager to deal with images of this type:
	      typedef struct Tk_ImageType {
		char *name;
		Tk_ImageCreateProc *createProc;
		Tk_ImageGetProc *getProc;
		Tk_ImageDisplayProc *displayProc;
		Tk_ImageFreeProc *freeProc;
		Tk_ImageDeleteProc *deleteProc;
	      } Tk_ImageType;
       The fields of this structure will be described in later subsections  of
       this entry.

       The  second  major  data	 structure  manipulated by an image manager is
       called an image master;	it contains overall information about  a  par‐
       ticular	image,	such as the values of the configuration options speci‐
       fied in an image create command.	 There will usually be	one  of	 these
       structures for each invocation of the image create command.

       The third data structure related to images is an image instance.	 There
       will usually be one of these structures for each usage of an image in a
       particular  widget.  It is possible for a single image to appear simul‐
       taneously in multiple widgets, or even multiple times in the same  wid‐
       get.   Furthermore,  different instances may be on different screens or
       displays.  The image instance data structure describes things that  may
       vary  from  instance  to instance, such as colors and graphics contexts
       for redisplay.  There is usually one instance structure for each -image
       option specified for a widget or canvas item.

       The following subsections describe the fields of a Tk_ImageType in more
       detail.

NAME
       typePtr->name provides a name for the image  type.   Once  Tk_CreateIm‐
       ageType returns, this name may be used in image create commands to cre‐
       ate images of the new type.  If there already existed an image type  by
       this name then the new image type replaces the old one.

CREATEPROC
       typePtr->createProc  provides the address of a procedure for Tk to call
       whenever image create is invoked to create an image of  the  new	 type.
       typePtr->createProc must match the following prototype:
	      typedef int Tk_ImageCreateProc(
		Tcl_Interp *interp,
		char *name,
		int argc,
		char **argv,
		Tk_ImageType *typePtr,
		Tk_ImageMaster master,
		ClientData *masterDataPtr);
       The  interp  argument is the interpreter in which the image command was
       invoked, and name is the name for the new image, which was either spec‐
       ified explicitly in the image command or generated automatically by the
       image command.  The argc and argv arguments describe all the configura‐
       tion  options  for the new image (everything after the name argument to
       image).	The master argument is a token that refers to Tk's information
       about  this image;  the image manager must return this token to Tk when
       invoking the  Tk_ImageChanged  procedure.   Typically  createProc  will
       parse  argc  and argv and create an image master data structure for the
       new image.  createProc may store an arbitrary one-word value  at	 *mas‐
       terDataPtr,  which  will be passed back to the image manager when other
       callbacks are invoked.  Typically the value is a pointer to the	master
       data structure for the image.

       If  createProc encounters an error, it should leave an error message in
       interp->result  and  return  TCL_ERROR;	 otherwise  it	should	return
       TCL_OK.

       createProc  should call Tk_ImageChanged in order to set the size of the
       image and request an initial redisplay.

GETPROC
       typePtr->getProc is invoked by Tk whenever a widget  calls  Tk_GetImage
       to  use	a  particular  image.  This procedure must match the following
       prototype:
	      typedef ClientData Tk_ImageGetProc(
		Tk_Window tkwin,
		ClientData masterData);
       The tkwin argument identifies the window in which  the  image  will  be
       used  and masterData is the value returned by createProc when the image
       master was created.  getProc will usually create a data	structure  for
       the new instance, including such things as the resources needed to dis‐
       play the image in the given window.  getProc returns a  one-word	 token
       for  the	 instance, which is typically the address of the instance data
       structure.  Tk will pass this value back	 to  the  image	 manager  when
       invoking its displayProc and freeProc procedures.

DISPLAYPROC
       typePtr->displayProc  is	 invoked  by  Tk whenever an image needs to be
       displayed (i.e., whenever a widget calls Tk_RedrawImage).   displayProc
       must match the following prototype:
	      typedef void Tk_ImageDisplayProc(
		ClientData instanceData,
		Display *display,
		Drawable drawable,
		int imageX,
		int imageY,
		int width,
		int height,
		int drawableX,
		int drawableY);
       The instanceData will be the same as the value returned by getProc when
       the instance was created.  display and drawable indicate where to  dis‐
       play the image;	drawable may be a pixmap rather than the window speci‐
       fied to getProc (this is usually the case, since most  widgets  double-
       buffer  their  redisplay	 to  get  smoother  visual  effects).  imageX,
       imageY, width, and height identify the region of the image that must be
       redisplayed.   This  region will always be within the size of the image
       as specified in the most recent call to Tk_ImageChanged.	 drawableX and
       drawableY  indicate  where  in  drawable the image should be displayed;
       displayProc should display the given region of the image so that	 point
       (imageX,	 imageY)  in  the  image  appears at (drawableX, drawableY) in
       drawable.

FREEPROC
       typePtr->freeProc contains the address of  a  procedure	that  Tk  will
       invoke  when  an image instance is released (i.e., when Tk_FreeImage is
       invoked).  This can happen, for example, when a widget is deleted or  a
       image  item  in	a  canvas is deleted, or when the image displayed in a
       widget or canvas item is changed.  freeProc must	 match	the  following
       prototype:
	      typedef void Tk_ImageFreeProc(
		ClientData instanceData,
		Display *display);
       The instanceData will be the same as the value returned by getProc when
       the instance was created, and display is	 the  display  containing  the
       window for the instance.	 freeProc should release any resources associ‐
       ated with the image instance, since the instance	 will  never  be  used
       again.

DELETEPROC
       typePtr->deleteProc  is	a  procedure  that Tk invokes when an image is
       being deleted (i.e. when the image delete command is invoked).	Before
       invoking	 deleteProc  Tk	 will  invoke freeProc for each of the image's
       instances.  deleteProc must match the following prototype:
	      typedef void Tk_ImageDeleteProc(
		ClientData masterData);
       The masterData argument will be the same as the value stored  in	 *mas‐
       terDataPtr by createProc when the image was created.  deleteProc should
       release any resources associated with the image.

TK_GETIMAGEMASTERDATA
       The procedure Tk_GetImageMasterData may be invoked to retrieve informa‐ │
       tion about an image.  For example, an image manager can use this proce‐ │
       dure to locate its image master data for an image.  If there exists  an │
       image  named  name in the interpreter given by interp, then *typePtrPtr │
       is filled in with type information for the  image  (the	typePtr	 value │
       passed  to  Tk_CreateImageType  when the image type was registered) and │
       the return value is the ClientData value	 returned  by  the  createProc │
       when  the  image	 was created (this is typically a pointer to the image │
       master data structure).	If no such image exists then NULL is  returned │
       and NULL is stored at *typePtrPtr.

SEE ALSO
       Tk_ImageChanged,	 Tk_GetImage,  Tk_FreeImage,  Tk_RedrawImage, Tk_Size‐
       OfImage

KEYWORDS
       image manager, image type, instance, master

Tk				      8.0		 Tk_CreateImageType(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server UnixWare

List of man pages available for UnixWare

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