diff options
Diffstat (limited to 'doc/CrtImgType.3')
| -rw-r--r-- | doc/CrtImgType.3 | 130 |
1 files changed, 70 insertions, 60 deletions
diff --git a/doc/CrtImgType.3 b/doc/CrtImgType.3 index 65061b3..da083e0 100644 --- a/doc/CrtImgType.3 +++ b/doc/CrtImgType.3 @@ -6,7 +6,7 @@ '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .so man.macros -.TH Tk_CreateImageType 3 8.3 Tk "Tk Library Procedures" +.TH Tk_CreateImageType 3 8.5 Tk "Tk Library Procedures" .BS .SH NAME Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs \- define new kind of image @@ -16,7 +16,6 @@ Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs \- define new kind o .sp \fBTk_CreateImageType\fR(\fItypePtr\fR) .sp -.VS ClientData \fBTk_GetImageMasterData\fR(\fIinterp, name, typePtrPtr\fR) .sp @@ -29,7 +28,7 @@ Must be static: a pointer to this structure is retained by the image code. .AP Tcl_Interp *interp in Interpreter in which image was created. -.AP "CONST char" *name in +.AP "const char" *name in Name of existing image. .AP Tk_ImageType **typePtrPtr out Points to word in which to store a pointer to type information for @@ -38,7 +37,6 @@ the given image, if it exists. Number of arguments .AP char ***argvPtr in/out Pointer to argument list -.VE .BE .SH DESCRIPTION @@ -61,12 +59,12 @@ the name of the image type and pointers to five procedures provided by the image manager to deal with images of this type: .CS typedef struct Tk_ImageType { - char *\fIname\fR; - Tk_ImageCreateProc *\fIcreateProc\fR; - Tk_ImageGetProc *\fIgetProc\fR; - Tk_ImageDisplayProc *\fIdisplayProc\fR; - Tk_ImageFreeProc *\fIfreeProc\fR; - Tk_ImageDeleteProc *\fIdeleteProc\fR; + char *\fIname\fR; + Tk_ImageCreateProc *\fIcreateProc\fR; + Tk_ImageGetProc *\fIgetProc\fR; + Tk_ImageDisplayProc *\fIdisplayProc\fR; + Tk_ImageFreeProc *\fIfreeProc\fR; + Tk_ImageDeleteProc *\fIdeleteProc\fR; } Tk_ImageType; .CE The fields of this structure will be described in later subsections @@ -95,7 +93,7 @@ option specified for a widget or canvas item. The following subsections describe the fields of a Tk_ImageType in more detail. -.SH NAME +.SS NAME .PP \fItypePtr->name\fR provides a name for the image type. Once \fBTk_CreateImageType\fR returns, this name may be used @@ -104,30 +102,20 @@ type. If there already existed an image type by this name then the new image type replaces the old one. -.SH PORTABILITY -.PP -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 -createProc. See below for a description of this function. - -.SH CREATEPROC +.SS CREATEPROC \fItypePtr->createProc\fR provides the address of a procedure for Tk to call whenever \fBimage create\fR is invoked to create an image of the new type. \fItypePtr->createProc\fR must match the following prototype: .CS typedef int Tk_ImageCreateProc( - Tcl_Interp *\fIinterp\fR, - char *\fIname\fR, - int \fIobjc\fR, - Tcl_Obj *CONST \fIobjv\fR[], - Tk_ImageType *\fItypePtr\fR, - Tk_ImageMaster \fImaster\fR, - ClientData *\fImasterDataPtr\fR); + Tcl_Interp *\fIinterp\fR, + char *\fIname\fR, + int \fIobjc\fR, + Tcl_Obj *const \fIobjv\fR[], + Tk_ImageType *\fItypePtr\fR, + Tk_ImageMaster \fImaster\fR, + ClientData *\fImasterDataPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the \fBimage\fR command was invoked, and \fIname\fR is the name for the new image, @@ -148,21 +136,21 @@ Typically the value is a pointer to the master data structure for the image. .PP If \fIcreateProc\fR encounters an error, it should leave an error -message in \fIinterp->result\fR and return \fBTCL_ERROR\fR; otherwise +message in the interpreter result and return \fBTCL_ERROR\fR; otherwise it should return \fBTCL_OK\fR. .PP \fIcreateProc\fR should call \fBTk_ImageChanged\fR in order to set the size of the image and request an initial redisplay. -.SH GETPROC +.SS GETPROC .PP \fItypePtr->getProc\fR is invoked by Tk whenever a widget calls \fBTk_GetImage\fR to use a particular image. This procedure must match the following prototype: .CS typedef ClientData Tk_ImageGetProc( - Tk_Window \fItkwin\fR, - ClientData \fImasterData\fR); + Tk_Window \fItkwin\fR, + ClientData \fImasterData\fR); .CE The \fItkwin\fR argument identifies the window in which the image will be used and \fImasterData\fR is the value @@ -175,22 +163,22 @@ is typically the address of the instance data structure. Tk will pass this value back to the image manager when invoking its \fIdisplayProc\fR and \fIfreeProc\fR procedures. -.SH DISPLAYPROC +.SS DISPLAYPROC .PP \fItypePtr->displayProc\fR is invoked by Tk whenever an image needs to be displayed (i.e., whenever a widget calls \fBTk_RedrawImage\fR). \fIdisplayProc\fR must match the following prototype: .CS typedef void Tk_ImageDisplayProc( - ClientData \fIinstanceData\fR, - Display *\fIdisplay\fR, - Drawable \fIdrawable\fR, - int \fIimageX\fR, - int \fIimageY\fR, - int \fIwidth\fR, - int \fIheight\fR, - int \fIdrawableX\fR, - int \fIdrawableY\fR); + ClientData \fIinstanceData\fR, + Display *\fIdisplay\fR, + Drawable \fIdrawable\fR, + int \fIimageX\fR, + int \fIimageY\fR, + int \fIwidth\fR, + int \fIheight\fR, + int \fIdrawableX\fR, + int \fIdrawableY\fR); .CE The \fIinstanceData\fR will be the same as the value returned by \fIgetProc\fR when the instance was created. @@ -208,7 +196,7 @@ the image should be displayed; \fIdisplayProc\fR should display the given region of the image so that point (\fIimageX\fR, \fIimageY\fR) in the image appears at (\fIdrawableX\fR, \fIdrawableY\fR) in \fIdrawable\fR. -.SH FREEPROC +.SS FREEPROC .PP \fItypePtr->freeProc\fR contains the address of a procedure that Tk will invoke when an image instance is released (i.e., when @@ -219,8 +207,8 @@ canvas item is changed. \fIfreeProc\fR must match the following prototype: .CS typedef void Tk_ImageFreeProc( - ClientData \fIinstanceData\fR, - Display *\fIdisplay\fR); + ClientData \fIinstanceData\fR, + Display *\fIdisplay\fR); .CE The \fIinstanceData\fR will be the same as the value returned by \fIgetProc\fR when the instance was created, and \fIdisplay\fR @@ -228,7 +216,7 @@ is the display containing the window for the instance. \fIfreeProc\fR should release any resources associated with the image instance, since the instance will never be used again. -.SH DELETEPROC +.SS DELETEPROC .PP \fItypePtr->deleteProc\fR is a procedure that Tk invokes when an image is being deleted (i.e. when the \fBimage delete\fR command @@ -238,7 +226,7 @@ each of the image's instances. \fIdeleteProc\fR must match the following prototype: .CS typedef void Tk_ImageDeleteProc( - ClientData \fImasterData\fR); + ClientData \fImasterData\fR); .CE The \fImasterData\fR argument will be the same as the value stored in \fI*masterDataPtr\fR by \fIcreateProc\fR when the @@ -247,7 +235,6 @@ image was created. the image. .SH TK_GETIMAGEMASTERDATA -.VS .PP The procedure \fBTk_GetImageMasterData\fR may be invoked to retrieve information about an image. For example, an image manager can use this @@ -260,19 +247,42 @@ and the return value is the ClientData value returned by the \fIcreateProc\fR 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 \fI*typePtrPtr\fR. -.VE -.SH TK_INITIMAGEARGS -.VS +.SH "LEGACY INTERFACE SUPPORT" +In Tk 8.2 and earlier, the definition of \fBTk_ImageCreateProc\fR +was incompatibly different, with the following prototype: +.CS +typedef int Tk_ImageCreateProc( + Tcl_Interp *\fIinterp\fR, + char *\fIname\fR, + int \fIargc\fR, + char **\fIargv\fR, + Tk_ImageType *\fItypePtr\fR, + Tk_ImageMaster \fImaster\fR, + ClientData *\fImasterDataPtr\fR); +.CE +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 support this legacy +interface if the code is compiled with the macro \fBUSE_OLD_IMAGE\fR +defined. +.PP +When the \fBUSE_OLD_IMAGE\fR legacy support is enabled, you may +see the routine \fBTk_InitImageArgs\fR in use. This was a migration +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 empty comment. Any stub-enabled +extension providing an extended image type via the legacy interface +that is compiled 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. .PP -The function \fBTk_InitImageArgs\fR converts the arguments of the -\fBcreateProc\fR 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 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. +Any new code written today should not make use of the legacy +interfaces. Expect their support to go away in Tk 9. .SH "SEE ALSO" Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage |