Tk_CreateImageType,  Tk_GetImageMasterData,  Tk_InitImageArgs  - define
       new kind of image


       #include <tk.h>


       ClientData                                                              |
       Tk_GetImageMasterData(interp, name, typePtrPtr)                         |

       Tk_InitImageArgs(interp, argc, argvPtr)                                 |


       Tk_ImageType   *type-                                                   |
       Ptr      (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   **typeP-                                                 |
       trPtr  (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


       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


       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.


       In Tk 8.2 and earlier, the createProc below had a different  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.  Further  on, if you are using Stubs, you need to call
       the function Tk_InitImageArgs(interp, argc, &argv) first in  your  cre-
       ateProc. See below for a description of this function.


       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 spec-
       ified explicitly in the image command or generated automatically by the
       image command.  The objc and objv 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  objc  and objv 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

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


       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


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


       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.


       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.


       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 running under an older (pre-8.3) Tk version, this |
       function has no effect. This function makes porting  older  image  han- |
       dlers  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_RedrawImage, Tk_Size- |
       OfImage                                                                 |


       image manager, image type, instance, master                             |

Tk                                    8.3                Tk_CreateImageType(3)

Man(1) output converted with man2html