'\" 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.6 2002/08/05 04:30:38 dgp Exp $
-'\"
-'\" The definitions below are for supplemental macros used in Tcl/Tk
-'\" manual entries.
-'\"
-'\" .AP type name in/out ?indent?
-'\" Start paragraph describing an argument to a library procedure.
-'\" type is type of argument (int, etc.), in/out is either "in", "out",
-'\" or "in/out" to describe whether procedure reads or modifies arg,
-'\" and indent is equivalent to second arg of .IP (shouldn't ever be
-'\" needed; use .AS below instead)
-'\"
-'\" .AS ?type? ?name?
-'\" Give maximum sizes of arguments for setting tab stops. Type and
-'\" name are examples of largest possible arguments that will be passed
-'\" to .AP later. If args are omitted, default tab stops are used.
-'\"
-'\" .BS
-'\" Start box enclosure. From here until next .BE, everything will be
-'\" enclosed in one large box.
-'\"
-'\" .BE
-'\" End of box enclosure.
-'\"
-'\" .CS
-'\" Begin code excerpt.
-'\"
-'\" .CE
-'\" End code excerpt.
-'\"
-'\" .VS ?version? ?br?
-'\" Begin vertical sidebar, for use in marking newly-changed parts
-'\" of man pages. The first argument is ignored and used for recording
-'\" the version when the .VS was added, so that the sidebars can be
-'\" found and removed when they reach a certain age. If another argument
-'\" is present, then a line break is forced before starting the sidebar.
-'\"
-'\" .VE
-'\" End of vertical sidebar.
-'\"
-'\" .DS
-'\" Begin an indented unfilled display.
-'\"
-'\" .DE
-'\" End of indented unfilled display.
-'\"
-'\" .SO
-'\" Start of list of standard options for a Tk widget. The
-'\" options follow on successive lines, in four columns separated
-'\" by tabs.
-'\"
-'\" .SE
-'\" End of list of standard options for a Tk widget.
-'\"
-'\" .OP cmdName dbName dbClass
-'\" Start of description of a specific option. cmdName gives the
-'\" option's name as specified in the class command, dbName gives
-'\" the option's name in the option database, and dbClass gives
-'\" the option's class in the option database.
-'\"
-'\" .UL arg1 arg2
-'\" Print arg1 underlined, then print arg2 normally.
-'\"
-'\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
-'\"
-'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
+.TH Tk_CreateImageType 3 8.5 Tk "Tk Library Procedures"
+.\" The -*- nroff -*- definitions below are for supplemental macros used
+.\" in Tcl/Tk manual entries.
+.\"
+.\" .AP type name in/out ?indent?
+.\" Start paragraph describing an argument to a library procedure.
+.\" type is type of argument (int, etc.), in/out is either "in", "out",
+.\" or "in/out" to describe whether procedure reads or modifies arg,
+.\" and indent is equivalent to second arg of .IP (shouldn't ever be
+.\" needed; use .AS below instead)
+.\"
+.\" .AS ?type? ?name?
+.\" Give maximum sizes of arguments for setting tab stops. Type and
+.\" name are examples of largest possible arguments that will be passed
+.\" to .AP later. If args are omitted, default tab stops are used.
+.\"
+.\" .BS
+.\" Start box enclosure. From here until next .BE, everything will be
+.\" enclosed in one large box.
+.\"
+.\" .BE
+.\" End of box enclosure.
+.\"
+.\" .CS
+.\" Begin code excerpt.
+.\"
+.\" .CE
+.\" End code excerpt.
+.\"
+.\" .VS ?version? ?br?
+.\" Begin vertical sidebar, for use in marking newly-changed parts
+.\" of man pages. The first argument is ignored and used for recording
+.\" the version when the .VS was added, so that the sidebars can be
+.\" found and removed when they reach a certain age. If another argument
+.\" is present, then a line break is forced before starting the sidebar.
+.\"
+.\" .VE
+.\" End of vertical sidebar.
+.\"
+.\" .DS
+.\" Begin an indented unfilled display.
+.\"
+.\" .DE
+.\" End of indented unfilled display.
+.\"
+.\" .SO ?manpage?
+.\" Start of list of standard options for a Tk widget. The manpage
+.\" argument defines where to look up the standard options; if
+.\" omitted, defaults to "options". The options follow on successive
+.\" lines, in three columns separated by tabs.
+.\"
+.\" .SE
+.\" End of list of standard options for a Tk widget.
+.\"
+.\" .OP cmdName dbName dbClass
+.\" Start of description of a specific option. cmdName gives the
+.\" option's name as specified in the class command, dbName gives
+.\" the option's name in the option database, and dbClass gives
+.\" the option's class in the option database.
+.\"
+.\" .UL arg1 arg2
+.\" Print arg1 underlined, then print arg2 normally.
+.\"
+.\" .QW arg1 ?arg2?
+.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
+.\"
+.\" .PQ arg1 ?arg2?
+.\" Print an open parenthesis, arg1 in quotes, then arg2 normally
+.\" (for trailing punctuation) and then a closing parenthesis.
+.\"
+.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
-'\" # Start an argument description
+.\" # Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
-\&\\$1 \\fI\\$2\\fP (\\$3)
+\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.\}
.\}
..
-'\" # define tabbing values for .AP
+.\" # define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
-'\" # BS - start boxed text
-'\" # ^y = starting y location
-'\" # ^b = 1
+.\" # BS - start boxed text
+.\" # ^y = starting y location
+.\" # ^b = 1
.de BS
.br
.mk ^y
.if n \l'\\n(.lu\(ul'
.if n .fi
..
-'\" # BE - end boxed text (draw box now)
+.\" # BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.br
.nr ^b 0
..
-'\" # VS - start vertical sidebar
-'\" # ^Y = starting y location
-'\" # ^v = 1 (for troff; for nroff this doesn't matter)
+.\" # VS - start vertical sidebar
+.\" # ^Y = starting y location
+.\" # ^v = 1 (for troff; for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
-'\" # VE - end of vertical sidebar
+.\" # VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.\}
.nr ^v 0
..
-'\" # Special macro to handle page bottom: finish off current
-'\" # box/sidebar if in box/sidebar mode, then invoked standard
-'\" # page bottom macro.
+.\" # Special macro to handle page bottom: finish off current
+.\" # box/sidebar if in box/sidebar mode, then invoked standard
+.\" # page bottom macro.
.de ^B
.ev 2
'ti 0
.mk ^Y
.\}
..
-'\" # DS - begin display
+.\" # DS - begin display
.de DS
.RS
.nf
.sp
..
-'\" # DE - end display
+.\" # DE - end display
.de DE
.fi
.RE
.sp
..
-'\" # SO - start of list of standard options
+.\" # SO - start of list of standard options
.de SO
+'ie '\\$1'' .ds So \\fBoptions\\fR
+'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
-'\" # SE - end of list of standard options
+.\" # SE - end of list of standard options
.de SE
.fi
.ft R
.LP
-See the \\fBoptions\\fR manual entry for details on the standard options.
+See the \\*(So manual entry for details on the standard options.
..
-'\" # OP - start of full description for a single option
+.\" # OP - start of full description for a single option
.de OP
.LP
.nf
.fi
.IP
..
-'\" # CS - begin code excerpt
+.\" # CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
-'\" # CE - end code excerpt
+.\" # CE - end code excerpt
.de CE
.fi
.RE
..
+.\" # UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
-.TH Tk_CreateImageType 3 8.3 Tk "Tk Library Procedures"
+.\" # QW - apply quotation marks to word
+.de QW
+.ie '\\*(lq'"' ``\\$1''\\$2
+.\"" fix emacs highlighting
+.el \\*(lq\\$1\\*(rq\\$2
+..
+.\" # PQ - apply parens and quotation marks to word
+.de PQ
+.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
+.\"" fix emacs highlighting
+.el (\\*(lq\\$1\\*(rq\\$2)\\$3
+..
+.\" # QR - quoted range
+.de QR
+.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
+.\"" fix emacs highlighting
+.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
+..
+.\" # MT - "empty" string
+.de MT
+.QW ""
+..
.BS
.SH NAME
Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs \- define new kind of image
\fB#include <tk.h>\fR
.sp
\fBTk_CreateImageType\fR(\fItypePtr\fR)
-ClientData
.sp
-.VS
+ClientData
\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
+.AS "const Tk_ImageType" *typePtrPtr
+.AP "const Tk_ImageType" *typePtr in
Structure that defines the new type of image.
-Must be static: a
+For Tk 8.4 and earlier this must be static: a
pointer to this structure is retained by the image code.
+In Tk 8.5, this limitation was relaxed.
.AP Tcl_Interp *interp in
Interpreter in which image was created.
-.AP "CONST char" *name in
+.AP "const char" *name in
Name of existing image.
.AP Tk_ImageType **typePtrPtr out
Points to word in which to store a pointer to type information for
Number of arguments
.AP char ***argvPtr in/out
Pointer to argument list
-.VE
.BE
-
.SH DESCRIPTION
.PP
\fBTk_CreateImageType\fR is invoked to define a new kind of image.
by the image manager to deal with images of this type:
.CS
typedef struct Tk_ImageType {
- char *\fIname\fR;
- Tk_ImageCreateProc *\fIcreateProc\fR;
- Tk_ImageGetProc *\fIgetProc\fR;
- Tk_ImageDisplayProc *\fIdisplayProc\fR;
- Tk_ImageFreeProc *\fIfreeProc\fR;
- Tk_ImageDeleteProc *\fIdeleteProc\fR;
-} Tk_ImageType;
+ const char *\fIname\fR;
+ Tk_ImageCreateProc *\fIcreateProc\fR;
+ Tk_ImageGetProc *\fIgetProc\fR;
+ Tk_ImageDisplayProc *\fIdisplayProc\fR;
+ Tk_ImageFreeProc *\fIfreeProc\fR;
+ Tk_ImageDeleteProc *\fIdeleteProc\fR;
+} \fBTk_ImageType\fR;
.CE
The fields of this structure will be described in later subsections
of this entry.
.PP
The following subsections describe the fields of a Tk_ImageType
in more detail.
-
-.SH NAME
+.SS NAME
.PP
\fItypePtr->name\fR provides a name for the image type.
Once \fBTk_CreateImageType\fR returns, this name may be used
type.
If there already existed an image type by this name then
the new image type replaces the old one.
-
-.SH PORTABILITY
+.SS CREATEPROC
.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
an image of the new type.
\fItypePtr->createProc\fR must match the following prototype:
.CS
-typedef int Tk_ImageCreateProc(
- Tcl_Interp *\fIinterp\fR,
- char *\fIname\fR,
- int \fIobjc\fR,
- Tcl_Obj *CONST \fIobjv\fR[],
- Tk_ImageType *\fItypePtr\fR,
- Tk_ImageMaster \fImaster\fR,
- ClientData *\fImasterDataPtr\fR);
+typedef int \fBTk_ImageCreateProc\fR(
+ Tcl_Interp *\fIinterp\fR,
+ const char *\fIname\fR,
+ int \fIobjc\fR,
+ Tcl_Obj *const \fIobjv\fR[],
+ const Tk_ImageType *\fItypePtr\fR,
+ Tk_ImageMaster \fImaster\fR,
+ ClientData *\fImasterDataPtr\fR);
.CE
The \fIinterp\fR argument is the interpreter in which the \fBimage\fR
command was invoked, and \fIname\fR is the name for the new image,
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
size of the image and request an initial redisplay.
-
-.SH GETPROC
+.SS GETPROC
.PP
\fItypePtr->getProc\fR is invoked by Tk whenever a widget
calls \fBTk_GetImage\fR to use a particular image.
This procedure must match the following prototype:
.CS
-typedef ClientData Tk_ImageGetProc(
- Tk_Window \fItkwin\fR,
- ClientData \fImasterData\fR);
+typedef ClientData \fBTk_ImageGetProc\fR(
+ Tk_Window \fItkwin\fR,
+ ClientData \fImasterData\fR);
.CE
The \fItkwin\fR argument identifies the window in which the
image will be used and \fImasterData\fR is the value
is typically the address of the instance data structure.
Tk will pass this value back to the image manager when invoking
its \fIdisplayProc\fR and \fIfreeProc\fR procedures.
-
-.SH DISPLAYPROC
+.SS DISPLAYPROC
.PP
\fItypePtr->displayProc\fR is invoked by Tk whenever an image needs
to be displayed (i.e., whenever a widget calls \fBTk_RedrawImage\fR).
\fIdisplayProc\fR must match the following prototype:
.CS
-typedef void Tk_ImageDisplayProc(
- ClientData \fIinstanceData\fR,
- Display *\fIdisplay\fR,
- Drawable \fIdrawable\fR,
- int \fIimageX\fR,
- int \fIimageY\fR,
- int \fIwidth\fR,
- int \fIheight\fR,
- int \fIdrawableX\fR,
- int \fIdrawableY\fR);
+typedef void \fBTk_ImageDisplayProc\fR(
+ ClientData \fIinstanceData\fR,
+ Display *\fIdisplay\fR,
+ Drawable \fIdrawable\fR,
+ int \fIimageX\fR,
+ int \fIimageY\fR,
+ int \fIwidth\fR,
+ int \fIheight\fR,
+ int \fIdrawableX\fR,
+ int \fIdrawableY\fR);
.CE
The \fIinstanceData\fR will be the same as the value returned by
\fIgetProc\fR when the instance was created.
the image should be displayed; \fIdisplayProc\fR should display
the given region of the image so that point (\fIimageX\fR, \fIimageY\fR)
in the image appears at (\fIdrawableX\fR, \fIdrawableY\fR) in \fIdrawable\fR.
-
-.SH FREEPROC
+.SS FREEPROC
.PP
\fItypePtr->freeProc\fR contains the address of a procedure that
Tk will invoke when an image instance is released (i.e., when
canvas item is changed.
\fIfreeProc\fR must match the following prototype:
.CS
-typedef void Tk_ImageFreeProc(
- ClientData \fIinstanceData\fR,
- Display *\fIdisplay\fR);
+typedef void \fBTk_ImageFreeProc\fR(
+ ClientData \fIinstanceData\fR,
+ Display *\fIdisplay\fR);
.CE
The \fIinstanceData\fR will be the same as the value returned by
\fIgetProc\fR when the instance was created, and \fIdisplay\fR
is the display containing the window for the instance.
\fIfreeProc\fR should release any resources associated with the
image instance, since the instance will never be used again.
-
-.SH DELETEPROC
+.SS DELETEPROC
.PP
\fItypePtr->deleteProc\fR is a procedure that Tk invokes when an
image is being deleted (i.e. when the \fBimage delete\fR command
each of the image's instances.
\fIdeleteProc\fR must match the following prototype:
.CS
-typedef void Tk_ImageDeleteProc(
- ClientData \fImasterData\fR);
+typedef void \fBTk_ImageDeleteProc\fR(
+ ClientData \fImasterData\fR);
.CE
The \fImasterData\fR argument will be the same as the value
stored in \fI*masterDataPtr\fR by \fIcreateProc\fR when the
image was created.
\fIdeleteProc\fR should release any resources associated with
the image.
-
.SH TK_GETIMAGEMASTERDATA
-.VS
.PP
The procedure \fBTk_GetImageMasterData\fR may be invoked to retrieve
information about an image. For example, an image manager can use this
\fIcreateProc\fR when the image was created (this is typically a
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
+.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 \fBTk_ImageCreateProc\fR(
+ 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
-
.SH KEYWORDS
image manager, image type, instance, master
OSDN Git Service
