summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorhobbs <hobbs>2000-02-08 11:31:28 (GMT)
committerhobbs <hobbs>2000-02-08 11:31:28 (GMT)
commitacfa815d400ff9f351e628c2dd24089170b2bfe3 (patch)
treeaaba98591be690b73fe87702aaa4023a89457083 /doc
parent4a0d1284957db786ed4b02c4a426b3681212565f (diff)
downloadtk-acfa815d400ff9f351e628c2dd24089170b2bfe3.zip
tk-acfa815d400ff9f351e628c2dd24089170b2bfe3.tar.gz
tk-acfa815d400ff9f351e628c2dd24089170b2bfe3.tar.bz2
* 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]
Diffstat (limited to 'doc')
-rw-r--r--doc/CrtImgType.334
-rw-r--r--doc/CrtPhImgFmt.333
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