NAME

       Tk_CreateImageType,    Tk_GetImageMasterData,   Tk_InitIm­
       ageArgs - 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.            |

       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                                               ||
                                              Number of arguments |

       char           ***argvPtr                                         ||
                                              Pointer to argument |
                                              list
_________________________________________________________________


       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  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
       there already existed an image type by this name then  the
       new image type replaces the old one.



PORTABILITY

       In  Tk 8.2 and earlier, the createProc below had a differ­
       ent signature. If you want to compile an image type  using
       the  old  interface  which  should still run on all Tcl/Tk
       versions, compile it with the flag  -DUSE_OLD_IMAGE.  Fur­
       ther  on,  if  you  are  using Stubs, you need to call the
       function Tk_InitImageArgs(interp, argc,  &argv)  first  in
       your createProc. See below for a description of this func­
       tion.



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 argu­
       ment  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 struc­
       ture 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  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.

       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  draw­
       able 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.,
       canvas is deleted, or when the image displayed in a widget
       or  canvas  item is changed.  freeProc must match the fol­
       lowing 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  associ­
       ated 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.



TK_INITIMAGEARGS

       The function Tk_InitImageArgs converts  the  arguments  of |
       the  createProc  from  objects  to strings when necessary. |
       When not using stubs, not using the old interface, or run­ |
       ning  under  an  older (pre-8.3) Tk version, this function |
       has no effect. This function  makes  porting  older  image |
       handlers  to the new interface a lot easier: After running |
       this function, the  arguments  are  guaranteed  to  be  in |
       string format, no matter how Tk deliverd them.             |

       Tk_ImageChanged,  Tk_GetImage,  Tk_FreeImage, Tk_RedrawIm­ |
       age, Tk_SizeOfImage                                        |



KEYWORDS |

       image manager, image type, instance, master                |