[Tk Bug 1712081]

        * unix/Makefile.in:     Updates to account for new and deleted files
        * win/Makefile.in:      tkStubImg.c and tkOldTest.c.
        * win/makefile.bc:
        * win/makefile.vc:

        * generic/tkOldTest.c (new):    New file used to create testing
        * generic/tkTest.c:             commands for testing various Tk
        * tests/constraints.tcl:        legacy interfaces where a separate
        * tests/image.test:             compilation unit is needed in order
        to #define suitable macros during compilation.  Only the effect of
        USE_OLD_IMAGE on Tk_CreateImageType() is currently tested, but more
        similar testing commands can be added to this same file.  New
        constraint defined to detect presence of the image type provided by
        the new testing code, and a few tests added to exercise it.  Having
        USE_OLD_IMAGE support tested by the default test suite should reduce
        chance of a recurrence of this bug.

        * doc/CrtImgType.3:     Revised docs to better indicate the legacy
        * doc/CrtPhImgFmt.3:    nature of the interfaces supported by
        USE_OLD_IMAGE.

        * generic/tkDecls.h:    make genstubs
        * generic/tkStubInit.c:

        * generic/tk.decls:             Reworked USE_OLD_IMAGE support to use
        * generic/tk.h:                 the same support mechanisms both with
        * generic/tkStubImg.c (deleted):and without a stub-enabled build.  In
        each case, route the legacy calls to Tk_CreateImageType and
        Tk_CreatePhotoImageFormat through the Tk_CreateOldImageType and
        Tk_CreateOldPhotoImageFormat routines.  Add those routines to the
        public stub table so they're available to a stub-enabled extension.
        Remove the definition of Tk_InitImageArgs() and use a macro to
        convert any calls to it in source code into a comment.

        * generic/tkImage.c:    Removed the MODULE_SCOPE declarations that
        * generic/tkImgPhoto.c: broke USE_OLD_IMAGE support.

2 files changed, 83 insertions, 35 deletions

diff --git a/doc/CrtImgType.3 b/doc/CrtImgType.3
index 77fc6c8..88b9b82 100644
--- a/doc/CrtImgType.3
+++ b/doc/CrtImgType.3
@@ -5,10 +5,10 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CrtImgType.3,v 1.10 2007/01/05 00:00:48 nijtmans Exp $
+'\" RCS: @(#) $Id: CrtImgType.3,v 1.11 2007/05/14 20:58:25 dgp Exp $
 '\" 
 .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
@@ -104,16 +104,6 @@ type.
 If there already existed an image type by this name then
 the new image type replaces the old one.
 
-.SS 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.
-
 .SS CREATEPROC
 \fItypePtr->createProc\fR provides the address of a procedure for
 Tk to call whenever \fBimage create\fR is invoked to create
@@ -148,7 +138,7 @@ 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
@@ -260,16 +250,42 @@ and the return value is the ClientData value returned by the
 pointer to the image master data structure).  If no such image exists
 then NULL is returned and NULL is stored at \fI*typePtrPtr\fR.
 
-.SH TK_INITIMAGEARGS
+.SH LEGACY INTERFACE SUPPORT
+.PP
+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
diff --git a/doc/CrtPhImgFmt.3 b/doc/CrtPhImgFmt.3
index a0c972b..d640315 100644
--- a/doc/CrtPhImgFmt.3
+++ b/doc/CrtPhImgFmt.3
@@ -9,10 +9,10 @@
 '\"	    Department of Computer Science,
 '\"	    Australian National University.
 '\"
-'\" RCS: @(#) $Id: CrtPhImgFmt.3,v 1.7 2007/01/05 00:00:49 nijtmans Exp $
+'\" RCS: @(#) $Id: CrtPhImgFmt.3,v 1.8 2007/05/14 20:58:25 dgp Exp $
 '\"
 .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
@@ -68,14 +68,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.
@@ -83,9 +75,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
@@ -238,6 +231,45 @@ 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
+.PP
+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