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

1 files changed, 45 insertions, 13 deletions

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