* generic/tkDecls.h:

	* generic/tk.decls:
	* generic/tk.h: moved new public functions created in dash patch
	to the stubs interface [Bug: 4062]

	* generic/tk.h:
	* doc/CrtImgType.3:
	* doc/CrtPhImgFmt.3:
	* generic/tk.h:
	* generic/tkImgGIF.c:
	* generic/tkImgPhoto.c:
	* generic/tkStubImg.c (new file):
	* generic/tkTest.c:
	* unix/Makefile.in:
	* win/Makefile.in:
	* win/makefile.vc: improved support for moving from the old style
	image C API to the new obj'ified one with new Tk_InitImageArgs
	command and stub'ing of image code.  See docs for how to make the
	transition. [Bug: 4060]

1 files changed, 21 insertions, 12 deletions

diff --git a/doc/CrtPhImgFmt.3 b/doc/CrtPhImgFmt.3
index 94b1404..fba525df 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.3 1999/10/29 03:57:40 hobbs Exp $
+'\" RCS: @(#) $Id: CrtPhImgFmt.3,v 1.4 2000/02/08 11:31:30 hobbs Exp $
 '\"
 .so man.macros
-.TH Tk_CreatePhotoImageFormat 3 4.0 Tk "Tk Library Procedures"
+.TH Tk_CreatePhotoImageFormat 3 8.3 Tk "Tk Library Procedures"
 .BS
 .SH NAME
 Tk_CreatePhotoImageFormat \- define new file format for photo images
@@ -69,6 +69,14 @@ 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.
@@ -76,7 +84,9 @@ 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.
+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.
 
 .SH FILEMATCHPROC
 \fIformatPtr->fileMatchProc\fR provides the address of a procedure for
@@ -86,7 +96,7 @@ suitable for reading data in a given file.
 .CS
 typedef int Tk_ImageFileMatchProc(
 	Tcl_Channel \fIchan\fR,
-	char *\fIfileName\fR,
+	CONST char *\fIfileName\fR,
 	Tcl_Obj *\fIformat\fR,
 	int *\fIwidthPtr\fR,
 	int *\fIheightPtr\fR,
@@ -108,13 +118,13 @@ suitable for reading data from a given string.
 \fIformatPtr->stringMatchProc\fR must match the following prototype:
 .CS
 typedef int Tk_ImageStringMatchProc(
-	char *\fIstring\fR,
+	Tcl_Obj *\fIdata\fR,
 	Tcl_Obj *\fIformat\fR,
 	int *\fIwidthPtr\fR,
 	int *\fIheightPtr\fR,
 	Tcl_Interp *\fIinterp\fR);
 .CE
-The \fIstring\fR argument points to the string containing the image
+The \fIdata\fR argument points to the object containing the image
 data.  The \fIformat\fR argument contains the value given for
 the \fB\-format\fR option, or NULL if the option was not specified.
 If the data in the string appears to be in the format supported by
@@ -131,7 +141,7 @@ Tk to call to read data from an image file into a photo image.
 typedef int Tk_ImageFileReadProc(
 	Tcl_Interp *\fIinterp\fR,
 	Tcl_Channel \fIchan\fR,
-	char *\fIfileName\fR,
+	CONST char *\fIfileName\fR,
 	Tcl_Obj *\fIformat\fR,
 	PhotoHandle \fIimageHandle\fR,
 	int \fIdestX\fR, int \fIdestY\fR,
@@ -159,7 +169,7 @@ Tk to call to read data from a string into a photo image.
 .CS
 typedef int Tk_ImageStringReadProc(
 	Tcl_Interp *\fIinterp\fR,
-	char *\fIstring\fR,
+	Tcl_Obj *\fIdata\fR,
 	Tcl_Obj *\fIformat\fR,
 	PhotoHandle \fIimageHandle\fR,
 	int \fIdestX\fR, int \fIdestY\fR,
@@ -168,7 +178,7 @@ typedef int Tk_ImageStringReadProc(
 .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.
-The \fIstring\fR argument points to the image data in string form.
+The \fIdata\fR argument points to the image data in object form.
 The \fIformat\fR argument contains the
 value given for the \fB\-format\fR option, or NULL if the option was
 not specified.  The image data in the string, or a subimage of it, is to
@@ -187,7 +197,7 @@ Tk to call to write data from a photo image to a file.
 .CS
 typedef int Tk_ImageFileWriteProc(
 	Tcl_Interp *\fIinterp\fR,
-	char *\fIfileName\fR,
+	CONST char *\fIfileName\fR,
 	Tcl_Obj *\fIformat\fR,
 	Tk_PhotoImageBlock *\fIblockPtr\fR);
 .CE
@@ -212,7 +222,6 @@ Tk to call to translate image data from a photo image into a string.
 .CS
 typedef int Tk_ImageStringWriteProc(
 	Tcl_Interp *\fIinterp\fR,
-	Tcl_DString *\fIdataPtr\fR,
 	Tcl_Obj *\fIformat\fR,
 	Tk_PhotoImageBlock *\fIblockPtr\fR);
 .CE
@@ -221,7 +230,7 @@ invoked to convert the image; it should be used for reporting errors.
 The image data to be converted are in memory and are described by the
 Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the
 manual page FindPhoto(3) for details.  The data for the string
-should be appended to the dynamic string given by \fIdataPtr\fR.
+should be put in the interpreter \fIinterp\fR result.
 The \fIformat\fR argument contains the
 value given for the \fB\-format\fR option, or NULL if the option was
 not specified.  The format string can contain extra characters