* 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]


FossilOrigin-Name: dbe34fe5efcb725442acc347dcb728ad8e30493c

2 files changed, 52 insertions, 15 deletions

diff --git a/doc/CrtImgType.3 b/doc/CrtImgType.3
index 918e0cc..ce97863 100644
--- a/doc/CrtImgType.3
+++ b/doc/CrtImgType.3
@@ -5,13 +5,13 @@
 '\" 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.3 1999/10/29 03:57:40 hobbs Exp $
+'\" RCS: @(#) $Id: CrtImgType.3,v 1.4 2000/02/08 11:31:30 hobbs Exp $
 '\" 
 .so man.macros
-.TH Tk_CreateImageType 3 8.0 Tk "Tk Library Procedures"
+.TH Tk_CreateImageType 3 8.3 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_CreateImageType, Tk_GetImageMasterData \- define new kind of image
+Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs \- define new kind of image
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
@@ -21,6 +21,8 @@ ClientData
 .sp
 .VS
 \fBTk_GetImageMasterData\fR(\fIinterp, name, typePtrPtr\fR)
+.sp
+\fBTk_InitImageArgs\fR(\fIinterp, argc, argvPtr\fR)
 .SH ARGUMENTS
 .AS Tk_ImageType *typePtrPtr
 .AP Tk_ImageType *typePtr in
@@ -34,6 +36,10 @@ Name of existing image.
 .AP Tk_ImageType **typePtrPtr out
 Points to word in which to store a pointer to type information for
 the given image, if it exists.
+.AP int argc
+Number of arguments
+.AP char ***argvPtr
+Pointer to argument list
 .VE
 .BE
 
@@ -100,6 +106,16 @@ 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
 \fItypePtr->createProc\fR provides the address of a procedure for
 Tk to call whenever \fBimage create\fR is invoked to create
@@ -248,6 +264,18 @@ 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
+.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.
+
 .SH "SEE ALSO"
 Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage
 
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