tk4.2 C API - CrtImgType






NAME

     Tk_CreateImageType - define new kind of image


SYNOPSIS

     #include <tk.h>

     Tk_CreateImageType(typePtr)


ARGUMENTS

     Tk_ImageType   *typePtr   (in)      Structure  that  defines
                                         the new type of image.





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  pro-
     vided 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 sub-
     sections 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 com-
     mand.  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 possi-
     ble  for a single image to appear simultaneously in multiple
     widgets, or even multiple times in the same widget.   Furth-
     ermore,  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  usu-
     ally 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 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 specified explicitly in the  image  command
     or  generated  automatically by the image command.  The argc
     and argv 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  pro-
     cedure.   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 *master-
     DataPtr, 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 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  pro-
     totype:
          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 pix-
     map  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  exam-
     ple, 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 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 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.



SEE ALSO

     Tk_ImageChanged, Tk_GetImage, Tk_FreeImage,  Tk_RedrawImage,
     Tk_SizeOfImage



KEYWORDS

     image manager, image type, instance, master