Tk_CreateImageType(3) Tk Library Procedures Tk_CreateImageType(3)



     Tk_CreateImageType, Tk_GetImageMasterData,  Tk_InitImageArgs
     - define new kind of image


     #include <tk.h>


     Tk_GetImageMasterData(interp, name, typePtrPtr)

     Tk_InitImageArgs(interp, argc, argvPtr)


     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

     Tcl_Interp *interp (in)                Interpreter in  which
                                            image was created.

     const char *name (in)                  Name   of    existing

     Tk_ImageType **typePtrPtr (out)        Points  to  word   in
                                            which   to   store  a
                                            pointer    to    type
                                            information  for  the
                                            given  image,  if  it

     int argc (in)                          Number of arguments

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


     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,

Tk                      Last change: 8.5                        1

Tk_CreateImageType(3) Tk Library Procedures Tk_CreateImageType(3)

     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.

     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.

Tk                      Last change: 8.5                        2

Tk_CreateImageType(3) Tk Library Procedures Tk_CreateImageType(3)

     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  pro-
     cedure.   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 *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  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.

     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

Tk                      Last change: 8.5                        3

Tk_CreateImageType(3) Tk Library Procedures Tk_CreateImageType(3)

     the image manager when invoking its displayProc and freeProc

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

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

Tk                      Last change: 8.5                        4

Tk_CreateImageType(3) Tk Library Procedures Tk_CreateImageType(3)

     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


     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.


     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 sup-
     port  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 migra-
     tion 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

Tk                      Last change: 8.5                        5

Tk_CreateImageType(3) Tk Library Procedures Tk_CreateImageType(3)

     empty comment.   Any  stub-enabled  extension  providing  an
     extended  image  type  via the legacy interface that is com-
     piled 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.


     Tk_ImageChanged, Tk_GetImage, Tk_FreeImage,  Tk_RedrawImage,


     image manager, image type, instance, master

Tk                      Last change: 8.5                        6

Man(1) output converted with man2html