Provided by: tk8.5-doc_8.5.19-3_all bug

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
       configuration 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
       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_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
       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 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.
       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  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
       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 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
       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 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
       prototype:
              typedef void Tk_ImageDeleteProc(
                  ClientData masterData);
       The masterData argument will be  the  same  as  the  value  stored  in  *masterDataPtr  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 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
       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.

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
       provides  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