| '\" |
| '\" Copyright (c) 1994 The Regents of the University of California. |
| '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. |
| '\" |
| '\" 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. |
| .if t .wh -1.3i ^B |
| .nr ^l \n(.l |
| .ad b |
| '\" # Start an argument description |
| .de AP |
| .ie !"\\$4"" .TP \\$4 |
| .el \{\ |
| . ie !"\\$2"" .TP \\n()Cu |
| . el .TP 15 |
| .\} |
| .ta \\n()Au \\n()Bu |
| .ie !"\\$3"" \{\ |
| \&\\$1 \\fI\\$2\\fP (\\$3) |
| .\".b |
| .\} |
| .el \{\ |
| .br |
| .ie !"\\$2"" \{\ |
| \&\\$1 \\fI\\$2\\fP |
| .\} |
| .el \{\ |
| \&\\fI\\$1\\fP |
| .\} |
| .\} |
| .. |
| '\" # define tabbing values for .AP |
| .de AS |
| .nr )A 10n |
| .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| .nr )B \\n()Au+15n |
| .\" |
| .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+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 |
| .de BS |
| .br |
| .mk ^y |
| .nr ^b 1u |
| .if n .nf |
| .if n .ti 0 |
| .if n \l'\\n(.lu\(ul' |
| .if n .fi |
| .. |
| '\" # BE - end boxed text (draw box now) |
| .de BE |
| .nf |
| .ti 0 |
| .mk ^t |
| .ie n \l'\\n(^lu\(ul' |
| .el \{\ |
| .\" Draw four-sided box normally, but don't draw top of |
| .\" box if the box started on an earlier page. |
| .ie !\\n(^b-1 \{\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .el \}\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .\} |
| .fi |
| .br |
| .nr ^b 0 |
| .. |
| '\" # 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 |
| .de VE |
| .ie n 'mc |
| .el \{\ |
| .ev 2 |
| .nf |
| .ti 0 |
| .mk ^t |
| \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| .sp -1 |
| .fi |
| .ev |
| .\} |
| .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. |
| .de ^B |
| .ev 2 |
| 'ti 0 |
| 'nf |
| .mk ^t |
| .if \\n(^b \{\ |
| .\" Draw three-sided box if this is the box's first page, |
| .\" draw two sides but no top otherwise. |
| .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .\} |
| .if \\n(^v \{\ |
| .nr ^x \\n(^tu+1v-\\n(^Yu |
| \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| .\} |
| .bp |
| 'fi |
| .ev |
| .if \\n(^b \{\ |
| .mk ^y |
| .nr ^b 2 |
| .\} |
| .if \\n(^v \{\ |
| .mk ^Y |
| .\} |
| .. |
| '\" # DS - begin display |
| .de DS |
| .RS |
| .nf |
| .sp |
| .. |
| '\" # DE - end display |
| .de DE |
| .fi |
| .RE |
| .sp |
| .. |
| '\" # SO - start of list of standard options |
| .de SO |
| .SH "STANDARD OPTIONS" |
| .LP |
| .nf |
| .ta 5.5c 11c |
| .ft B |
| .. |
| '\" # 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. |
| .. |
| '\" # OP - start of full description for a single option |
| .de OP |
| .LP |
| .nf |
| .ta 4c |
| Command-Line Name: \\fB\\$1\\fR |
| Database Name: \\fB\\$2\\fR |
| Database Class: \\fB\\$3\\fR |
| .fi |
| .IP |
| .. |
| '\" # CS - begin code excerpt |
| .de CS |
| .RS |
| .nf |
| .ta .25i .5i .75i 1i |
| .. |
| '\" # CE - end code excerpt |
| .de CE |
| .fi |
| .RE |
| .. |
| .de UL |
| \\$1\l'|0\(ul'\\$2 |
| .. |
| .TH Tk_CreateImageType 3 8.3 Tk "Tk Library Procedures" |
| .BS |
| .SH NAME |
| Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs \- define new kind of image |
| .SH SYNOPSIS |
| .nf |
| \fB#include <tk.h>\fR |
| .sp |
| \fBTk_CreateImageType\fR(\fItypePtr\fR) |
| 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 |
| Structure that defines the new type of image. |
| Must be static: a |
| pointer to this structure is retained by the image code. |
| .AP Tcl_Interp *interp in |
| Interpreter in which image was created. |
| .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 |
| the given image, if it exists. |
| .AP int argc in |
| 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. |
| An image type corresponds to a particular value of the \fItype\fR |
| argument for the \fBimage create\fR command. There may exist |
| any number of different image types, and new types may be defined |
| dynamically by calling \fBTk_CreateImageType\fR. |
| For example, there might be one type for 2-color bitmaps, |
| another for multi-color images, another for dithered images, |
| another for video, and so on. |
| .PP |
| The code that implements a new image type is called an |
| \fIimage manager\fR. |
| It consists of a collection of procedures plus three different |
| kinds of data structures. |
| The first data structure is a Tk_ImageType structure, which contains |
| the name of the image type and pointers to five procedures provided |
| 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; |
| .CE |
| The fields of this structure will be described in later subsections |
| of this entry. |
| .PP |
| The second major data structure manipulated by an image manager |
| is called an \fIimage master\fR; it contains overall information |
| about a particular image, such as the values of the configuration |
| options specified in an \fBimage create\fR command. |
| There will usually be one of these structures for each |
| invocation of the \fBimage create\fR command. |
| .PP |
| The third data structure related to images is an \fIimage instance\fR. |
| There will usually be one of these structures for each usage of an |
| image in a particular widget. |
| It is possible for a single image to appear simultaneously |
| in multiple widgets, or even multiple times in the same widget. |
| Furthermore, different instances may be on different screens |
| or displays. |
| The image instance data structure describes things that may |
| vary from instance to instance, such as colors and graphics |
| contexts for redisplay. |
| There is usually one instance structure for each \fB\-image\fR |
| option specified for a widget or canvas item. |
| .PP |
| The following subsections describe the fields of a Tk_ImageType |
| in more detail. |
| |
| .SH NAME |
| .PP |
| \fItypePtr->name\fR provides a name for the image type. |
| Once \fBTk_CreateImageType\fR returns, this name may be used |
| in \fBimage create\fR commands to create images of the new |
| 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 |
| 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); |
| .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, |
| which was either specified explicitly in the \fBimage\fR command |
| or generated automatically by the \fBimage\fR command. |
| The \fIobjc\fR and \fIobjv\fR arguments describe all the configuration |
| options for the new image (everything after the name argument to |
| \fBimage\fR). |
| The \fImaster\fR argument is a token that refers to Tk's information |
| about this image; the image manager must return this token to |
| Tk when invoking the \fBTk_ImageChanged\fR procedure. |
| Typically \fIcreateProc\fR will parse \fIobjc\fR and \fIobjv\fR |
| and create an image master data structure for the new image. |
| \fIcreateProc\fR may store an arbitrary one-word value at |
| *\fImasterDataPtr\fR, which will be passed back to the |
| image manager when other callbacks are invoked. |
| Typically the value is a pointer to the master data |
| 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 |
| 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 |
| .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); |
| .CE |
| The \fItkwin\fR argument identifies the window in which the |
| image will be used and \fImasterData\fR is the value |
| returned by \fIcreateProc\fR when the image master was created. |
| \fIgetProc\fR will usually create a data structure for the new |
| instance, including such things as the resources needed to |
| display the image in the given window. |
| \fIgetProc\fR returns a one-word token for the instance, which |
| 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 |
| .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); |
| .CE |
| The \fIinstanceData\fR will be the same as the value returned by |
| \fIgetProc\fR when the instance was created. |
| \fIdisplay\fR and \fIdrawable\fR indicate where to display the |
| image; \fIdrawable\fR may be a pixmap rather than |
| the window specified to \fIgetProc\fR (this is usually the case, |
| since most widgets double-buffer their redisplay to get smoother |
| visual effects). |
| \fIimageX\fR, \fIimageY\fR, \fIwidth\fR, and \fIheight\fR |
| identify the region of the image that must be redisplayed. |
| This region will always be within the size of the image |
| as specified in the most recent call to \fBTk_ImageChanged\fR. |
| \fIdrawableX\fR and \fIdrawableY\fR indicate where in \fIdrawable\fR |
| 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 |
| .PP |
| \fItypePtr->freeProc\fR contains the address of a procedure that |
| Tk will invoke when an image instance is released (i.e., when |
| \fBTk_FreeImage\fR is invoked). |
| This can happen, for example, when a widget is deleted or a image item |
| in a canvas is deleted, or when the image displayed in a widget or |
| canvas item is changed. |
| \fIfreeProc\fR must match the following prototype: |
| .CS |
| typedef void Tk_ImageFreeProc( |
| 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 |
| .PP |
| \fItypePtr->deleteProc\fR is a procedure that Tk invokes when an |
| image is being deleted (i.e. when the \fBimage delete\fR command |
| is invoked). |
| Before invoking \fIdeleteProc\fR Tk will invoke \fIfreeProc\fR for |
| each of the image's instances. |
| \fIdeleteProc\fR must match the following prototype: |
| .CS |
| typedef void Tk_ImageDeleteProc( |
| 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 |
| procedure to locate its image master data for an image. |
| If there exists an image named \fIname\fR |
| in the interpreter given by \fIinterp\fR, then \fI*typePtrPtr\fR is |
| filled in with type information for the image (the \fItypePtr\fR value |
| passed to \fBTk_CreateImageType\fR when the image type was registered) |
| and the return value is the ClientData value returned by the |
| \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 |
| .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 |
| |
| .SH KEYWORDS |
| image manager, image type, instance, master |