diff options
Diffstat (limited to 'doc/CrtPhImgFmt.3')
| -rw-r--r-- | doc/CrtPhImgFmt.3 | 135 |
1 files changed, 83 insertions, 52 deletions
diff --git a/doc/CrtPhImgFmt.3 b/doc/CrtPhImgFmt.3 index fa50d86..0575d40 100644 --- a/doc/CrtPhImgFmt.3 +++ b/doc/CrtPhImgFmt.3 @@ -10,7 +10,7 @@ '\" Australian National University. '\" .so man.macros -.TH Tk_CreatePhotoImageFormat 3 8.3 Tk "Tk Library Procedures" +.TH Tk_CreatePhotoImageFormat 3 8.5 Tk "Tk Library Procedures" .BS .SH NAME Tk_CreatePhotoImageFormat \- define new file format for photo images @@ -46,13 +46,13 @@ handler to deal with files and strings in this format. The Tk_PhotoImageFormat structure contains the following fields: .CS typedef struct Tk_PhotoImageFormat { - char *\fIname\fR; - Tk_ImageFileMatchProc *\fIfileMatchProc\fR; - Tk_ImageStringMatchProc *\fIstringMatchProc\fR; - Tk_ImageFileReadProc *\fIfileReadProc\fR; - Tk_ImageStringReadProc *\fIstringReadProc\fR; - Tk_ImageFileWriteProc *\fIfileWriteProc\fR; - Tk_ImageStringWriteProc *\fIstringWriteProc\fR; + char *\fIname\fR; + Tk_ImageFileMatchProc *\fIfileMatchProc\fR; + Tk_ImageStringMatchProc *\fIstringMatchProc\fR; + Tk_ImageFileReadProc *\fIfileReadProc\fR; + Tk_ImageStringReadProc *\fIstringReadProc\fR; + Tk_ImageFileWriteProc *\fIfileWriteProc\fR; + Tk_ImageStringWriteProc *\fIstringWriteProc\fR; } Tk_PhotoImageFormat; .CE .PP @@ -66,14 +66,6 @@ structure should be set to NULL. The handler must provide the procedure, and the \fIstringMatchProc\fR procedure if it provides the \fIstringReadProc\fR procedure. -.SH PORTABILITY -.PP -In Tk 8.2 and earlier, a different interface was used. Tk 8.3 will -still support the old format handlers if the format name is in upper -case. If you still want to compile old format handlers with Tk8.3, -use the flag -DUSE_OLD_IMAGE. This will restore all function prototypes -to match the pre-8.3 situation. - .SH NAME .PP \fIformatPtr->name\fR provides a name for the image type. @@ -81,9 +73,10 @@ Once \fBTk_CreatePhotoImageFormat\fR returns, this name may be used in the \fB\-format\fR photo image configuration and subcommand option. The manual page for the photo image (photo(n)) describes how image file formats are chosen based on their names and the value given to -the \fB\-format\fR option. For new format handlers, the name should -be in lower case. Pre-8.3 format handlers are assumed to be in -upper case. +the \fB\-format\fR option. The first character of \fIformatPtr->name\fR +must not be an uppercase character from the ASCII character set +(that is, one of the characters \fBA\fR-\fBZ\fR). Such names are used +only for legacy interface support (see below). .SH FILEMATCHPROC \fIformatPtr->fileMatchProc\fR provides the address of a procedure for @@ -92,12 +85,12 @@ suitable for reading data in a given file. \fIformatPtr->fileMatchProc\fR must match the following prototype: .CS typedef int Tk_ImageFileMatchProc( - Tcl_Channel \fIchan\fR, - CONST char *\fIfileName\fR, - Tcl_Obj *\fIformat\fR, - int *\fIwidthPtr\fR, - int *\fIheightPtr\fR, - Tcl_Interp *\fIinterp\fR); + Tcl_Channel \fIchan\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + int *\fIwidthPtr\fR, + int *\fIheightPtr\fR, + Tcl_Interp *\fIinterp\fR); .CE The \fIfileName\fR argument is the name of the file containing the image data, which is open for reading as \fIchan\fR. The @@ -115,11 +108,11 @@ suitable for reading data from a given string. \fIformatPtr->stringMatchProc\fR must match the following prototype: .CS typedef int Tk_ImageStringMatchProc( - Tcl_Obj *\fIdata\fR, - Tcl_Obj *\fIformat\fR, - int *\fIwidthPtr\fR, - int *\fIheightPtr\fR, - Tcl_Interp *\fIinterp\fR); + Tcl_Obj *\fIdata\fR, + Tcl_Obj *\fIformat\fR, + int *\fIwidthPtr\fR, + int *\fIheightPtr\fR, + Tcl_Interp *\fIinterp\fR); .CE The \fIdata\fR argument points to the object containing the image data. The \fIformat\fR argument contains the value given for @@ -136,14 +129,14 @@ Tk to call to read data from an image file into a photo image. \fIformatPtr->fileReadProc\fR must match the following prototype: .CS typedef int Tk_ImageFileReadProc( - Tcl_Interp *\fIinterp\fR, - Tcl_Channel \fIchan\fR, - CONST char *\fIfileName\fR, - Tcl_Obj *\fIformat\fR, - PhotoHandle \fIimageHandle\fR, - int \fIdestX\fR, int \fIdestY\fR, - int \fIwidth\fR, int \fIheight\fR, - int \fIsrcX\fR, int \fIsrcY\fR); + Tcl_Interp *\fIinterp\fR, + Tcl_Channel \fIchan\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + PhotoHandle \fIimageHandle\fR, + int \fIdestX\fR, int \fIdestY\fR, + int \fIwidth\fR, int \fIheight\fR, + int \fIsrcX\fR, int \fIsrcY\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to read the image; it should be used for reporting errors. @@ -165,13 +158,13 @@ Tk to call to read data from a string into a photo image. \fIformatPtr->stringReadProc\fR must match the following prototype: .CS typedef int Tk_ImageStringReadProc( - Tcl_Interp *\fIinterp\fR, - Tcl_Obj *\fIdata\fR, - Tcl_Obj *\fIformat\fR, - PhotoHandle \fIimageHandle\fR, - int \fIdestX\fR, int \fIdestY\fR, - int \fIwidth\fR, int \fIheight\fR, - int \fIsrcX\fR, int \fIsrcY\fR); + Tcl_Interp *\fIinterp\fR, + Tcl_Obj *\fIdata\fR, + Tcl_Obj *\fIformat\fR, + PhotoHandle \fIimageHandle\fR, + int \fIdestX\fR, int \fIdestY\fR, + int \fIwidth\fR, int \fIheight\fR, + int \fIsrcX\fR, int \fIsrcY\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to read the image; it should be used for reporting errors. @@ -193,10 +186,10 @@ Tk to call to write data from a photo image to a file. \fIformatPtr->fileWriteProc\fR must match the following prototype: .CS typedef int Tk_ImageFileWriteProc( - Tcl_Interp *\fIinterp\fR, - CONST char *\fIfileName\fR, - Tcl_Obj *\fIformat\fR, - Tk_PhotoImageBlock *\fIblockPtr\fR); + Tcl_Interp *\fIinterp\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + Tk_PhotoImageBlock *\fIblockPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to write the image; it should be used for reporting errors. @@ -218,9 +211,9 @@ Tk to call to translate image data from a photo image into a string. \fIformatPtr->stringWriteProc\fR must match the following prototype: .CS typedef int Tk_ImageStringWriteProc( - Tcl_Interp *\fIinterp\fR, - Tcl_Obj *\fIformat\fR, - Tk_PhotoImageBlock *\fIblockPtr\fR); + Tcl_Interp *\fIinterp\fR, + Tcl_Obj *\fIformat\fR, + Tk_PhotoImageBlock *\fIblockPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to convert the image; it should be used for reporting errors. @@ -236,6 +229,44 @@ after the name of the format. If appropriate, the characters to specify further details about the image file. The return value is a standard Tcl return value. +.SH "LEGACY INTERFACE SUPPORT" +In Tk 8.2 and earlier, the definition of all the function pointer +types stored in fields of a \fBTk_PhotoImageFormat\fR struct were +incompatibly different. Legacy programs and libraries dating from +those days may still contain code that defines extended Tk photo image +formats 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. Alternatively, the legacy interfaces +are used if the first character of \fIformatPtr->name\fR is an +uppercase ASCII character (\fBA\fR-\fBZ\fR), and explicit casts +are used to forgive the type mismatch. For example, +.CS +static Tk_PhotoImageFormat myFormat = { + "MyFormat", + (Tk_ImageFileMatchProc *) FileMatch, + NULL, + (Tk_ImageFileReadProc *) FileRead, + NULL, + NULL, + NULL +}; +.CE +would define a minimal \fBTk_PhotoImageFormat\fR that operates provide +only file reading capability, where \fBFileMatch\fR and \fBFileRead\fR +are written according to the legacy interfaces of Tk 8.2 or earlier. +.PP +Any stub-enabled extension providing an extended photo image format +via the legacy interface enabled by the \fBUSE_OLD_IMAGE\fR macro +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 +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_FindPhoto, Tk_PhotoPutBlock |