tk/doc/CrtImgType.3

   1 '\"
   2 '\" Copyright (c) 1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH Tk_CreateImageType 3 8.3 Tk "Tk Library Procedures"
  12 .BS
  13 .SH NAME
  14 Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs \- define new kind of image
  15 .SH SYNOPSIS
  16 .nf
  17 \fB#include <tk.h>\fR
  18 .sp
  19 \fBTk_CreateImageType\fR(\fItypePtr\fR)
  20 ClientData
  21 .sp
  22 .VS
  23 \fBTk_GetImageMasterData\fR(\fIinterp, name, typePtrPtr\fR)
  24 .sp
  25 \fBTk_InitImageArgs\fR(\fIinterp, argc, argvPtr\fR)
  26 .SH ARGUMENTS
  27 .AS Tk_ImageType *typePtrPtr
  28 .AP Tk_ImageType *typePtr in
  29 Structure that defines the new type of image.
  30 Must be static: a
  31 pointer to this structure is retained by the image code.
  32 .AP Tcl_Interp *interp in
  33 Interpreter in which image was created.
  34 .AP "CONST char" *name in
  35 Name of existing image.
  36 .AP Tk_ImageType **typePtrPtr out
  37 Points to word in which to store a pointer to type information for
  38 the given image, if it exists.
  39 .AP int argc in
  40 Number of arguments
  41 .AP char ***argvPtr in/out
  42 Pointer to argument list
  43 .VE
  44 .BE
  45
  46 .SH DESCRIPTION
  47 .PP
  48 \fBTk_CreateImageType\fR is invoked to define a new kind of image.
  49 An image type corresponds to a particular value of the \fItype\fR
  50 argument for the \fBimage create\fR command.  There may exist
  51 any number of different image types, and new types may be defined
  52 dynamically by calling \fBTk_CreateImageType\fR.
  53 For example, there might be one type for 2-color bitmaps,
  54 another for multi-color images, another for dithered images,
  55 another for video, and so on.
  56 .PP
  57 The code that implements a new image type is called an
  58 \fIimage manager\fR.
  59 It consists of a collection of procedures plus three different
  60 kinds of data structures.
  61 The first data structure is a Tk_ImageType structure, which contains
  62 the name of the image type and pointers to five procedures provided
  63 by the image manager to deal with images of this type:
  64 .CS
  65 typedef struct Tk_ImageType {
  66         char *\fIname\fR;
  67         Tk_ImageCreateProc *\fIcreateProc\fR;
  68         Tk_ImageGetProc *\fIgetProc\fR;
  69         Tk_ImageDisplayProc *\fIdisplayProc\fR;
  70         Tk_ImageFreeProc *\fIfreeProc\fR;
  71         Tk_ImageDeleteProc *\fIdeleteProc\fR;
  72 } Tk_ImageType;
  73 .CE
  74 The fields of this structure will be described in later subsections
  75 of this entry.
  76 .PP
  77 The second major data structure manipulated by an image manager
  78 is called an \fIimage master\fR;  it contains overall information
  79 about a particular image, such as the values of the configuration
  80 options specified in an \fBimage create\fR command.
  81 There will usually be one of these structures for each
  82 invocation of the \fBimage create\fR command.
  83 .PP
  84 The third data structure related to images is an \fIimage instance\fR.
  85 There will usually be one of these structures for each usage of an
  86 image in a particular widget.
  87 It is possible for a single image to appear simultaneously
  88 in multiple widgets, or even multiple times in the same widget.
  89 Furthermore, different instances may be on different screens
  90 or displays.
  91 The image instance data structure describes things that may
  92 vary from instance to instance, such as colors and graphics
  93 contexts for redisplay.
  94 There is usually one instance structure for each \fB\-image\fR
  95 option specified for a widget or canvas item.
  96 .PP
  97 The following subsections describe the fields of a Tk_ImageType
  98 in more detail.
  99
 100 .SH NAME
 101 .PP
 102 \fItypePtr->name\fR provides a name for the image type.
 103 Once \fBTk_CreateImageType\fR returns, this name may be used
 104 in \fBimage create\fR commands to create images of the new
 105 type.
 106 If there already existed an image type by this name then
 107 the new image type replaces the old one.
 108
 109 .SH PORTABILITY
 110 .PP
 111 In Tk 8.2 and earlier, the createProc below had a different
 112 signature. If you want to compile an image type using the
 113 old interface which should still run on all Tcl/Tk versions,
 114 compile it with the flag -DUSE_OLD_IMAGE. Further on, if
 115 you are using Stubs, you need to call the function
 116 Tk_InitImageArgs(interp, argc, &argv) first in your
 117 createProc. See below for a description of this function.
 118
 119 .SH CREATEPROC
 120 \fItypePtr->createProc\fR provides the address of a procedure for
 121 Tk to call whenever \fBimage create\fR is invoked to create
 122 an image of the new type.
 123 \fItypePtr->createProc\fR must match the following prototype:
 124 .CS
 125 typedef int Tk_ImageCreateProc(
 126         Tcl_Interp *\fIinterp\fR,
 127         char *\fIname\fR,
 128         int \fIobjc\fR,
 129         Tcl_Obj *CONST \fIobjv\fR[],
 130         Tk_ImageType *\fItypePtr\fR,
 131         Tk_ImageMaster \fImaster\fR,
 132         ClientData *\fImasterDataPtr\fR);
 133 .CE
 134 The \fIinterp\fR argument is the interpreter in which the \fBimage\fR
 135 command was invoked, and \fIname\fR is the name for the new image,
 136 which was either specified explicitly in the \fBimage\fR command
 137 or generated automatically by the \fBimage\fR command.
 138 The \fIobjc\fR and \fIobjv\fR arguments describe all the configuration
 139 options for the new image (everything after the name argument to
 140 \fBimage\fR).
 141 The \fImaster\fR argument is a token that refers to Tk's information
 142 about this image;  the image manager must return this token to
 143 Tk when invoking the \fBTk_ImageChanged\fR procedure.
 144 Typically \fIcreateProc\fR will parse \fIobjc\fR and \fIobjv\fR
 145 and create an image master data structure for the new image.
 146 \fIcreateProc\fR may store an arbitrary one-word value at
 147 *\fImasterDataPtr\fR, which will be passed back to the
 148 image manager when other callbacks are invoked.
 149 Typically the value is a pointer to the master data
 150 structure for the image.
 151 .PP
 152 If \fIcreateProc\fR encounters an error, it should leave an error
 153 message in \fIinterp->result\fR and return \fBTCL_ERROR\fR;  otherwise
 154 it should return \fBTCL_OK\fR.
 155 .PP
 156 \fIcreateProc\fR should call \fBTk_ImageChanged\fR in order to set the
 157 size of the image and request an initial redisplay.
 158
 159 .SH GETPROC
 160 .PP
 161 \fItypePtr->getProc\fR is invoked by Tk whenever a widget
 162 calls \fBTk_GetImage\fR to use a particular image.
 163 This procedure must match the following prototype:
 164 .CS
 165 typedef ClientData Tk_ImageGetProc(
 166         Tk_Window \fItkwin\fR,
 167         ClientData \fImasterData\fR);
 168 .CE
 169 The \fItkwin\fR argument identifies the window in which the
 170 image will be used and \fImasterData\fR is the value
 171 returned by \fIcreateProc\fR when the image master was created.
 172 \fIgetProc\fR will usually create a data structure for the new
 173 instance, including such things as the resources needed to
 174 display the image in the given window.
 175 \fIgetProc\fR returns a one-word token for the instance, which
 176 is typically the address of the instance data structure.
 177 Tk will pass this value back to the image manager when invoking
 178 its \fIdisplayProc\fR and \fIfreeProc\fR procedures.
 179
 180 .SH DISPLAYPROC
 181 .PP
 182 \fItypePtr->displayProc\fR is invoked by Tk whenever an image needs
 183 to be displayed (i.e., whenever a widget calls \fBTk_RedrawImage\fR).
 184 \fIdisplayProc\fR must match the following prototype:
 185 .CS
 186 typedef void Tk_ImageDisplayProc(
 187         ClientData \fIinstanceData\fR,
 188         Display *\fIdisplay\fR,
 189         Drawable \fIdrawable\fR,
 190         int \fIimageX\fR,
 191         int \fIimageY\fR,
 192         int \fIwidth\fR,
 193         int \fIheight\fR,
 194         int \fIdrawableX\fR,
 195         int \fIdrawableY\fR);
 196 .CE
 197 The \fIinstanceData\fR will be the same as the value returned by
 198 \fIgetProc\fR when the instance was created.
 199 \fIdisplay\fR and \fIdrawable\fR indicate where to display the
 200 image;  \fIdrawable\fR may be a pixmap rather than
 201 the window specified to \fIgetProc\fR (this is usually the case,
 202 since most widgets double-buffer their redisplay to get smoother
 203 visual effects).
 204 \fIimageX\fR, \fIimageY\fR, \fIwidth\fR, and \fIheight\fR
 205 identify the region of the image that must be redisplayed.
 206 This region will always be within the size of the image
 207 as specified in the most recent call to \fBTk_ImageChanged\fR.
 208 \fIdrawableX\fR and \fIdrawableY\fR indicate where in \fIdrawable\fR
 209 the image should be displayed;  \fIdisplayProc\fR should display
 210 the given region of the image so that point (\fIimageX\fR, \fIimageY\fR)
 211 in the image appears at (\fIdrawableX\fR, \fIdrawableY\fR) in \fIdrawable\fR.
 212
 213 .SH FREEPROC
 214 .PP
 215 \fItypePtr->freeProc\fR contains the address of a procedure that
 216 Tk will invoke when an image instance is released (i.e., when
 217 \fBTk_FreeImage\fR is invoked).
 218 This can happen, for example, when a widget is deleted or a image item
 219 in a canvas is deleted, or when the image displayed in a widget or
 220 canvas item is changed.
 221 \fIfreeProc\fR must match the following prototype:
 222 .CS
 223 typedef void Tk_ImageFreeProc(
 224         ClientData \fIinstanceData\fR,
 225         Display *\fIdisplay\fR);
 226 .CE
 227 The \fIinstanceData\fR will be the same as the value returned by
 228 \fIgetProc\fR when the instance was created, and \fIdisplay\fR
 229 is the display containing the window for the instance.
 230 \fIfreeProc\fR should release any resources associated with the
 231 image instance, since the instance will never be used again.
 232
 233 .SH DELETEPROC
 234 .PP
 235 \fItypePtr->deleteProc\fR is a procedure that Tk invokes when an
 236 image is being deleted (i.e. when the \fBimage delete\fR command
 237 is invoked).
 238 Before invoking \fIdeleteProc\fR Tk will invoke \fIfreeProc\fR for
 239 each of the image's instances.
 240 \fIdeleteProc\fR must match the following prototype:
 241 .CS
 242 typedef void Tk_ImageDeleteProc(
 243         ClientData \fImasterData\fR);
 244 .CE
 245 The \fImasterData\fR argument will be the same as the value
 246 stored in \fI*masterDataPtr\fR by \fIcreateProc\fR when the
 247 image was created.
 248 \fIdeleteProc\fR should release any resources associated with
 249 the image.
 250
 251 .SH TK_GETIMAGEMASTERDATA
 252 .VS
 253 .PP
 254 The procedure \fBTk_GetImageMasterData\fR may be invoked to retrieve
 255 information about an image.  For example, an image manager can use this
 256 procedure to locate its image master data for an image.
 257 If there exists an image named \fIname\fR
 258 in the interpreter given by \fIinterp\fR, then \fI*typePtrPtr\fR is
 259 filled in with type information for the image (the \fItypePtr\fR value
 260 passed to \fBTk_CreateImageType\fR when the image type was registered)
 261 and the return value is the ClientData value returned by the
 262 \fIcreateProc\fR when the image was created (this is typically a
 263 pointer to the image master data structure).  If no such image exists
 264 then NULL is returned and NULL is stored at \fI*typePtrPtr\fR.
 265 .VE
 266
 267 .SH TK_INITIMAGEARGS
 268 .VS
 269 .PP
 270 The function \fBTk_InitImageArgs\fR converts the arguments of the
 271 \fBcreateProc\fR from objects to strings when necessary. When
 272 not using stubs, not using the old interface, or running
 273 under an older (pre-8.3) Tk version, this function has no
 274 effect. This function makes porting older image handlers to
 275 the new interface a lot easier: After running this function,
 276 the arguments are guaranteed to be in string format, no
 277 matter how Tk deliverd them.
 278
 279 .SH "SEE ALSO"
 280 Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage
 281
 282 .SH KEYWORDS
 283 image manager, image type, instance, master