Unix/Linux Go Back    


CentOS 7.0 - man page for tk_initimageargs (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Tk_CreateImageType(3)		      Tk Library Procedures		    Tk_CreateImageType(3)

_________________________________________________________________________________________________

NAME
       Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs - define new kind of image

SYNOPSIS
       #include <tk.h>

       Tk_CreateImageType(typePtr)

       ClientData
       Tk_GetImageMasterData(interp, name, typePtrPtr)

       Tk_InitImageArgs(interp, argc, argvPtr)

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.

       const 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.

       int argc (in)			      Number of arguments

       char ***argvPtr (in/out) 	      Pointer to argument list
_________________________________________________________________

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_CreateImageType.  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  procedures  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 particular image, such as the values of the con-
       figuration options specified 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 simultaneously in multiple widgets, or even multiple times in
       the same widget.  Furthermore, different instances may be on  different	screens  or  dis-
       plays.	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_CreateImageType returns, this
       name may be used in image create commands to create 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 cre-
       ate 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 objc,
		  Tcl_Obj *const objv[],
		  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 specified explicitly in the image command  or
       generated  automatically  by  the image command.  The objc and objv arguments describe all
       the configuration 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 objc and objv and create an image master data structure
       for the new image.  createProc may store an arbitrary one-word  value  at  *masterDataPtr,
       which  will  be	passed back to the image manager when other callbacks are invoked.  Typi-
       cally 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  the  interpreter
       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 display 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  proce-
       dures.

   DISPLAYPROC
       typePtr->displayProc is invoked by Tk whenever an image needs to be displayed (i.e., when-
       ever 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 display the image;	drawable may be a
       pixmap rather than the window specified 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  dis-
       played  in  a  widget or canvas item is changed.  freeProc must match the following proto-
       type:
	      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 associated 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 proto-
       type:
	      typedef void Tk_ImageDeleteProc(
		  ClientData masterData);
       The masterData argument will be the same as the value stored  in  *masterDataPtr  by  cre-
       ateProc	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 information about an image.
       For  example,  an image manager can use this procedure 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 Client-
       Data  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.

LEGACY INTERFACE SUPPORT
       In  Tk  8.2  and earlier, the definition of Tk_ImageCreateProc was incompatibly different,
       with the following prototype:
	      typedef int Tk_ImageCreateProc(
		  Tcl_Interp *interp,
		  char *name,
		  int argc,
		  char **argv,
		  Tk_ImageType *typePtr,
		  Tk_ImageMaster master,
		  ClientData *masterDataPtr);
       Legacy programs and libraries dating from those days may still contain code  that  defines
       extended  Tk  image  types using the old interface.  The Tk header file will still support
       this legacy interface if the code is compiled with the macro USE_OLD_IMAGE defined.

       When the USE_OLD_IMAGE legacy support is enabled, you may see the routine Tk_InitImageArgs
       in  use.   This	was a migration tool used to create stub-enabled extensions that could be
       loaded into interps containing all versions of Tk 8.1 and later.  Tk 8.5  no  longer  pro-
       vides  this  routine, but uses a macro to convert any attempted calls of this routine into
       an empty comment.  Any stub-enabled extension providing an extended  image  type  via  the
       legacy  interface  that	is  compiled against Tk 8.5 headers and linked against the Tk 8.5
       stub library will produce a file that can be loaded only  into  interps	with  Tk  8.5  or
       later;  that  is,  the  normal stub-compatibility rules.  If a developer needs to generate
       from such code a file that is loadable into interps with Tk 8.4 or earlier, they must  use
       Tk 8.4 headers and stub libraries to do so.

       Any  new  code  written	today should not make use of the legacy interfaces.  Expect their
       support to go away in Tk 9.

SEE ALSO
       Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage

KEYWORDS
       image manager, image type, instance, master

Tk					       8.5			    Tk_CreateImageType(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:23 PM.