Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | '\" |
2 | '\" Copyright (c) 1994 The Regents of the University of California. | |
3 | '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. | |
4 | '\" | |
5 | '\" See the file "license.terms" for information on usage and redistribution | |
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
7 | '\" | |
8 | '\" RCS: @(#) $Id: CrtImgType.3,v 1.6.2.1 2003/12/10 09:40:43 dkf Exp $ | |
9 | '\" | |
10 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
11 | '\" manual entries. | |
12 | '\" | |
13 | '\" .AP type name in/out ?indent? | |
14 | '\" Start paragraph describing an argument to a library procedure. | |
15 | '\" type is type of argument (int, etc.), in/out is either "in", "out", | |
16 | '\" or "in/out" to describe whether procedure reads or modifies arg, | |
17 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be | |
18 | '\" needed; use .AS below instead) | |
19 | '\" | |
20 | '\" .AS ?type? ?name? | |
21 | '\" Give maximum sizes of arguments for setting tab stops. Type and | |
22 | '\" name are examples of largest possible arguments that will be passed | |
23 | '\" to .AP later. If args are omitted, default tab stops are used. | |
24 | '\" | |
25 | '\" .BS | |
26 | '\" Start box enclosure. From here until next .BE, everything will be | |
27 | '\" enclosed in one large box. | |
28 | '\" | |
29 | '\" .BE | |
30 | '\" End of box enclosure. | |
31 | '\" | |
32 | '\" .CS | |
33 | '\" Begin code excerpt. | |
34 | '\" | |
35 | '\" .CE | |
36 | '\" End code excerpt. | |
37 | '\" | |
38 | '\" .VS ?version? ?br? | |
39 | '\" Begin vertical sidebar, for use in marking newly-changed parts | |
40 | '\" of man pages. The first argument is ignored and used for recording | |
41 | '\" the version when the .VS was added, so that the sidebars can be | |
42 | '\" found and removed when they reach a certain age. If another argument | |
43 | '\" is present, then a line break is forced before starting the sidebar. | |
44 | '\" | |
45 | '\" .VE | |
46 | '\" End of vertical sidebar. | |
47 | '\" | |
48 | '\" .DS | |
49 | '\" Begin an indented unfilled display. | |
50 | '\" | |
51 | '\" .DE | |
52 | '\" End of indented unfilled display. | |
53 | '\" | |
54 | '\" .SO | |
55 | '\" Start of list of standard options for a Tk widget. The | |
56 | '\" options follow on successive lines, in four columns separated | |
57 | '\" by tabs. | |
58 | '\" | |
59 | '\" .SE | |
60 | '\" End of list of standard options for a Tk widget. | |
61 | '\" | |
62 | '\" .OP cmdName dbName dbClass | |
63 | '\" Start of description of a specific option. cmdName gives the | |
64 | '\" option's name as specified in the class command, dbName gives | |
65 | '\" the option's name in the option database, and dbClass gives | |
66 | '\" the option's class in the option database. | |
67 | '\" | |
68 | '\" .UL arg1 arg2 | |
69 | '\" Print arg1 underlined, then print arg2 normally. | |
70 | '\" | |
71 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
72 | '\" | |
73 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
74 | .if t .wh -1.3i ^B | |
75 | .nr ^l \n(.l | |
76 | .ad b | |
77 | '\" # Start an argument description | |
78 | .de AP | |
79 | .ie !"\\$4"" .TP \\$4 | |
80 | .el \{\ | |
81 | . ie !"\\$2"" .TP \\n()Cu | |
82 | . el .TP 15 | |
83 | .\} | |
84 | .ta \\n()Au \\n()Bu | |
85 | .ie !"\\$3"" \{\ | |
86 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
87 | .\".b | |
88 | .\} | |
89 | .el \{\ | |
90 | .br | |
91 | .ie !"\\$2"" \{\ | |
92 | \&\\$1 \\fI\\$2\\fP | |
93 | .\} | |
94 | .el \{\ | |
95 | \&\\fI\\$1\\fP | |
96 | .\} | |
97 | .\} | |
98 | .. | |
99 | '\" # define tabbing values for .AP | |
100 | .de AS | |
101 | .nr )A 10n | |
102 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
103 | .nr )B \\n()Au+15n | |
104 | .\" | |
105 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
106 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
107 | .. | |
108 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
109 | '\" # BS - start boxed text | |
110 | '\" # ^y = starting y location | |
111 | '\" # ^b = 1 | |
112 | .de BS | |
113 | .br | |
114 | .mk ^y | |
115 | .nr ^b 1u | |
116 | .if n .nf | |
117 | .if n .ti 0 | |
118 | .if n \l'\\n(.lu\(ul' | |
119 | .if n .fi | |
120 | .. | |
121 | '\" # BE - end boxed text (draw box now) | |
122 | .de BE | |
123 | .nf | |
124 | .ti 0 | |
125 | .mk ^t | |
126 | .ie n \l'\\n(^lu\(ul' | |
127 | .el \{\ | |
128 | .\" Draw four-sided box normally, but don't draw top of | |
129 | .\" box if the box started on an earlier page. | |
130 | .ie !\\n(^b-1 \{\ | |
131 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
132 | .\} | |
133 | .el \}\ | |
134 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
135 | .\} | |
136 | .\} | |
137 | .fi | |
138 | .br | |
139 | .nr ^b 0 | |
140 | .. | |
141 | '\" # VS - start vertical sidebar | |
142 | '\" # ^Y = starting y location | |
143 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
144 | .de VS | |
145 | .if !"\\$2"" .br | |
146 | .mk ^Y | |
147 | .ie n 'mc \s12\(br\s0 | |
148 | .el .nr ^v 1u | |
149 | .. | |
150 | '\" # VE - end of vertical sidebar | |
151 | .de VE | |
152 | .ie n 'mc | |
153 | .el \{\ | |
154 | .ev 2 | |
155 | .nf | |
156 | .ti 0 | |
157 | .mk ^t | |
158 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
159 | .sp -1 | |
160 | .fi | |
161 | .ev | |
162 | .\} | |
163 | .nr ^v 0 | |
164 | .. | |
165 | '\" # Special macro to handle page bottom: finish off current | |
166 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
167 | '\" # page bottom macro. | |
168 | .de ^B | |
169 | .ev 2 | |
170 | 'ti 0 | |
171 | 'nf | |
172 | .mk ^t | |
173 | .if \\n(^b \{\ | |
174 | .\" Draw three-sided box if this is the box's first page, | |
175 | .\" draw two sides but no top otherwise. | |
176 | .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 | |
177 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
178 | .\} | |
179 | .if \\n(^v \{\ | |
180 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
181 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
182 | .\} | |
183 | .bp | |
184 | 'fi | |
185 | .ev | |
186 | .if \\n(^b \{\ | |
187 | .mk ^y | |
188 | .nr ^b 2 | |
189 | .\} | |
190 | .if \\n(^v \{\ | |
191 | .mk ^Y | |
192 | .\} | |
193 | .. | |
194 | '\" # DS - begin display | |
195 | .de DS | |
196 | .RS | |
197 | .nf | |
198 | .sp | |
199 | .. | |
200 | '\" # DE - end display | |
201 | .de DE | |
202 | .fi | |
203 | .RE | |
204 | .sp | |
205 | .. | |
206 | '\" # SO - start of list of standard options | |
207 | .de SO | |
208 | .SH "STANDARD OPTIONS" | |
209 | .LP | |
210 | .nf | |
211 | .ta 5.5c 11c | |
212 | .ft B | |
213 | .. | |
214 | '\" # SE - end of list of standard options | |
215 | .de SE | |
216 | .fi | |
217 | .ft R | |
218 | .LP | |
219 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
220 | .. | |
221 | '\" # OP - start of full description for a single option | |
222 | .de OP | |
223 | .LP | |
224 | .nf | |
225 | .ta 4c | |
226 | Command-Line Name: \\fB\\$1\\fR | |
227 | Database Name: \\fB\\$2\\fR | |
228 | Database Class: \\fB\\$3\\fR | |
229 | .fi | |
230 | .IP | |
231 | .. | |
232 | '\" # CS - begin code excerpt | |
233 | .de CS | |
234 | .RS | |
235 | .nf | |
236 | .ta .25i .5i .75i 1i | |
237 | .. | |
238 | '\" # CE - end code excerpt | |
239 | .de CE | |
240 | .fi | |
241 | .RE | |
242 | .. | |
243 | .de UL | |
244 | \\$1\l'|0\(ul'\\$2 | |
245 | .. | |
246 | .TH Tk_CreateImageType 3 8.3 Tk "Tk Library Procedures" | |
247 | .BS | |
248 | .SH NAME | |
249 | Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs \- define new kind of image | |
250 | .SH SYNOPSIS | |
251 | .nf | |
252 | \fB#include <tk.h>\fR | |
253 | .sp | |
254 | \fBTk_CreateImageType\fR(\fItypePtr\fR) | |
255 | .sp | |
256 | .VS | |
257 | ClientData | |
258 | \fBTk_GetImageMasterData\fR(\fIinterp, name, typePtrPtr\fR) | |
259 | .sp | |
260 | \fBTk_InitImageArgs\fR(\fIinterp, argc, argvPtr\fR) | |
261 | .SH ARGUMENTS | |
262 | .AS Tk_ImageType *typePtrPtr | |
263 | .AP Tk_ImageType *typePtr in | |
264 | Structure that defines the new type of image. | |
265 | Must be static: a | |
266 | pointer to this structure is retained by the image code. | |
267 | .AP Tcl_Interp *interp in | |
268 | Interpreter in which image was created. | |
269 | .AP "CONST char" *name in | |
270 | Name of existing image. | |
271 | .AP Tk_ImageType **typePtrPtr out | |
272 | Points to word in which to store a pointer to type information for | |
273 | the given image, if it exists. | |
274 | .AP int argc in | |
275 | Number of arguments | |
276 | .AP char ***argvPtr in/out | |
277 | Pointer to argument list | |
278 | .VE | |
279 | .BE | |
280 | ||
281 | .SH DESCRIPTION | |
282 | .PP | |
283 | \fBTk_CreateImageType\fR is invoked to define a new kind of image. | |
284 | An image type corresponds to a particular value of the \fItype\fR | |
285 | argument for the \fBimage create\fR command. There may exist | |
286 | any number of different image types, and new types may be defined | |
287 | dynamically by calling \fBTk_CreateImageType\fR. | |
288 | For example, there might be one type for 2-color bitmaps, | |
289 | another for multi-color images, another for dithered images, | |
290 | another for video, and so on. | |
291 | .PP | |
292 | The code that implements a new image type is called an | |
293 | \fIimage manager\fR. | |
294 | It consists of a collection of procedures plus three different | |
295 | kinds of data structures. | |
296 | The first data structure is a Tk_ImageType structure, which contains | |
297 | the name of the image type and pointers to five procedures provided | |
298 | by the image manager to deal with images of this type: | |
299 | .CS | |
300 | typedef struct Tk_ImageType { | |
301 | char *\fIname\fR; | |
302 | Tk_ImageCreateProc *\fIcreateProc\fR; | |
303 | Tk_ImageGetProc *\fIgetProc\fR; | |
304 | Tk_ImageDisplayProc *\fIdisplayProc\fR; | |
305 | Tk_ImageFreeProc *\fIfreeProc\fR; | |
306 | Tk_ImageDeleteProc *\fIdeleteProc\fR; | |
307 | } Tk_ImageType; | |
308 | .CE | |
309 | The fields of this structure will be described in later subsections | |
310 | of this entry. | |
311 | .PP | |
312 | The second major data structure manipulated by an image manager | |
313 | is called an \fIimage master\fR; it contains overall information | |
314 | about a particular image, such as the values of the configuration | |
315 | options specified in an \fBimage create\fR command. | |
316 | There will usually be one of these structures for each | |
317 | invocation of the \fBimage create\fR command. | |
318 | .PP | |
319 | The third data structure related to images is an \fIimage instance\fR. | |
320 | There will usually be one of these structures for each usage of an | |
321 | image in a particular widget. | |
322 | It is possible for a single image to appear simultaneously | |
323 | in multiple widgets, or even multiple times in the same widget. | |
324 | Furthermore, different instances may be on different screens | |
325 | or displays. | |
326 | The image instance data structure describes things that may | |
327 | vary from instance to instance, such as colors and graphics | |
328 | contexts for redisplay. | |
329 | There is usually one instance structure for each \fB\-image\fR | |
330 | option specified for a widget or canvas item. | |
331 | .PP | |
332 | The following subsections describe the fields of a Tk_ImageType | |
333 | in more detail. | |
334 | ||
335 | .SH NAME | |
336 | .PP | |
337 | \fItypePtr->name\fR provides a name for the image type. | |
338 | Once \fBTk_CreateImageType\fR returns, this name may be used | |
339 | in \fBimage create\fR commands to create images of the new | |
340 | type. | |
341 | If there already existed an image type by this name then | |
342 | the new image type replaces the old one. | |
343 | ||
344 | .SH PORTABILITY | |
345 | .PP | |
346 | In Tk 8.2 and earlier, the createProc below had a different | |
347 | signature. If you want to compile an image type using the | |
348 | old interface which should still run on all Tcl/Tk versions, | |
349 | compile it with the flag -DUSE_OLD_IMAGE. Further on, if | |
350 | you are using Stubs, you need to call the function | |
351 | Tk_InitImageArgs(interp, argc, &argv) first in your | |
352 | createProc. See below for a description of this function. | |
353 | ||
354 | .SH CREATEPROC | |
355 | \fItypePtr->createProc\fR provides the address of a procedure for | |
356 | Tk to call whenever \fBimage create\fR is invoked to create | |
357 | an image of the new type. | |
358 | \fItypePtr->createProc\fR must match the following prototype: | |
359 | .CS | |
360 | typedef int Tk_ImageCreateProc( | |
361 | Tcl_Interp *\fIinterp\fR, | |
362 | char *\fIname\fR, | |
363 | int \fIobjc\fR, | |
364 | Tcl_Obj *CONST \fIobjv\fR[], | |
365 | Tk_ImageType *\fItypePtr\fR, | |
366 | Tk_ImageMaster \fImaster\fR, | |
367 | ClientData *\fImasterDataPtr\fR); | |
368 | .CE | |
369 | The \fIinterp\fR argument is the interpreter in which the \fBimage\fR | |
370 | command was invoked, and \fIname\fR is the name for the new image, | |
371 | which was either specified explicitly in the \fBimage\fR command | |
372 | or generated automatically by the \fBimage\fR command. | |
373 | The \fIobjc\fR and \fIobjv\fR arguments describe all the configuration | |
374 | options for the new image (everything after the name argument to | |
375 | \fBimage\fR). | |
376 | The \fImaster\fR argument is a token that refers to Tk's information | |
377 | about this image; the image manager must return this token to | |
378 | Tk when invoking the \fBTk_ImageChanged\fR procedure. | |
379 | Typically \fIcreateProc\fR will parse \fIobjc\fR and \fIobjv\fR | |
380 | and create an image master data structure for the new image. | |
381 | \fIcreateProc\fR may store an arbitrary one-word value at | |
382 | *\fImasterDataPtr\fR, which will be passed back to the | |
383 | image manager when other callbacks are invoked. | |
384 | Typically the value is a pointer to the master data | |
385 | structure for the image. | |
386 | .PP | |
387 | If \fIcreateProc\fR encounters an error, it should leave an error | |
388 | message in \fIinterp->result\fR and return \fBTCL_ERROR\fR; otherwise | |
389 | it should return \fBTCL_OK\fR. | |
390 | .PP | |
391 | \fIcreateProc\fR should call \fBTk_ImageChanged\fR in order to set the | |
392 | size of the image and request an initial redisplay. | |
393 | ||
394 | .SH GETPROC | |
395 | .PP | |
396 | \fItypePtr->getProc\fR is invoked by Tk whenever a widget | |
397 | calls \fBTk_GetImage\fR to use a particular image. | |
398 | This procedure must match the following prototype: | |
399 | .CS | |
400 | typedef ClientData Tk_ImageGetProc( | |
401 | Tk_Window \fItkwin\fR, | |
402 | ClientData \fImasterData\fR); | |
403 | .CE | |
404 | The \fItkwin\fR argument identifies the window in which the | |
405 | image will be used and \fImasterData\fR is the value | |
406 | returned by \fIcreateProc\fR when the image master was created. | |
407 | \fIgetProc\fR will usually create a data structure for the new | |
408 | instance, including such things as the resources needed to | |
409 | display the image in the given window. | |
410 | \fIgetProc\fR returns a one-word token for the instance, which | |
411 | is typically the address of the instance data structure. | |
412 | Tk will pass this value back to the image manager when invoking | |
413 | its \fIdisplayProc\fR and \fIfreeProc\fR procedures. | |
414 | ||
415 | .SH DISPLAYPROC | |
416 | .PP | |
417 | \fItypePtr->displayProc\fR is invoked by Tk whenever an image needs | |
418 | to be displayed (i.e., whenever a widget calls \fBTk_RedrawImage\fR). | |
419 | \fIdisplayProc\fR must match the following prototype: | |
420 | .CS | |
421 | typedef void Tk_ImageDisplayProc( | |
422 | ClientData \fIinstanceData\fR, | |
423 | Display *\fIdisplay\fR, | |
424 | Drawable \fIdrawable\fR, | |
425 | int \fIimageX\fR, | |
426 | int \fIimageY\fR, | |
427 | int \fIwidth\fR, | |
428 | int \fIheight\fR, | |
429 | int \fIdrawableX\fR, | |
430 | int \fIdrawableY\fR); | |
431 | .CE | |
432 | The \fIinstanceData\fR will be the same as the value returned by | |
433 | \fIgetProc\fR when the instance was created. | |
434 | \fIdisplay\fR and \fIdrawable\fR indicate where to display the | |
435 | image; \fIdrawable\fR may be a pixmap rather than | |
436 | the window specified to \fIgetProc\fR (this is usually the case, | |
437 | since most widgets double-buffer their redisplay to get smoother | |
438 | visual effects). | |
439 | \fIimageX\fR, \fIimageY\fR, \fIwidth\fR, and \fIheight\fR | |
440 | identify the region of the image that must be redisplayed. | |
441 | This region will always be within the size of the image | |
442 | as specified in the most recent call to \fBTk_ImageChanged\fR. | |
443 | \fIdrawableX\fR and \fIdrawableY\fR indicate where in \fIdrawable\fR | |
444 | the image should be displayed; \fIdisplayProc\fR should display | |
445 | the given region of the image so that point (\fIimageX\fR, \fIimageY\fR) | |
446 | in the image appears at (\fIdrawableX\fR, \fIdrawableY\fR) in \fIdrawable\fR. | |
447 | ||
448 | .SH FREEPROC | |
449 | .PP | |
450 | \fItypePtr->freeProc\fR contains the address of a procedure that | |
451 | Tk will invoke when an image instance is released (i.e., when | |
452 | \fBTk_FreeImage\fR is invoked). | |
453 | This can happen, for example, when a widget is deleted or a image item | |
454 | in a canvas is deleted, or when the image displayed in a widget or | |
455 | canvas item is changed. | |
456 | \fIfreeProc\fR must match the following prototype: | |
457 | .CS | |
458 | typedef void Tk_ImageFreeProc( | |
459 | ClientData \fIinstanceData\fR, | |
460 | Display *\fIdisplay\fR); | |
461 | .CE | |
462 | The \fIinstanceData\fR will be the same as the value returned by | |
463 | \fIgetProc\fR when the instance was created, and \fIdisplay\fR | |
464 | is the display containing the window for the instance. | |
465 | \fIfreeProc\fR should release any resources associated with the | |
466 | image instance, since the instance will never be used again. | |
467 | ||
468 | .SH DELETEPROC | |
469 | .PP | |
470 | \fItypePtr->deleteProc\fR is a procedure that Tk invokes when an | |
471 | image is being deleted (i.e. when the \fBimage delete\fR command | |
472 | is invoked). | |
473 | Before invoking \fIdeleteProc\fR Tk will invoke \fIfreeProc\fR for | |
474 | each of the image's instances. | |
475 | \fIdeleteProc\fR must match the following prototype: | |
476 | .CS | |
477 | typedef void Tk_ImageDeleteProc( | |
478 | ClientData \fImasterData\fR); | |
479 | .CE | |
480 | The \fImasterData\fR argument will be the same as the value | |
481 | stored in \fI*masterDataPtr\fR by \fIcreateProc\fR when the | |
482 | image was created. | |
483 | \fIdeleteProc\fR should release any resources associated with | |
484 | the image. | |
485 | ||
486 | .SH TK_GETIMAGEMASTERDATA | |
487 | .VS | |
488 | .PP | |
489 | The procedure \fBTk_GetImageMasterData\fR may be invoked to retrieve | |
490 | information about an image. For example, an image manager can use this | |
491 | procedure to locate its image master data for an image. | |
492 | If there exists an image named \fIname\fR | |
493 | in the interpreter given by \fIinterp\fR, then \fI*typePtrPtr\fR is | |
494 | filled in with type information for the image (the \fItypePtr\fR value | |
495 | passed to \fBTk_CreateImageType\fR when the image type was registered) | |
496 | and the return value is the ClientData value returned by the | |
497 | \fIcreateProc\fR when the image was created (this is typically a | |
498 | pointer to the image master data structure). If no such image exists | |
499 | then NULL is returned and NULL is stored at \fI*typePtrPtr\fR. | |
500 | .VE | |
501 | ||
502 | .SH TK_INITIMAGEARGS | |
503 | .VS | |
504 | .PP | |
505 | The function \fBTk_InitImageArgs\fR converts the arguments of the | |
506 | \fBcreateProc\fR from objects to strings when necessary. When | |
507 | not using stubs, not using the old interface, or running | |
508 | under an older (pre-8.3) Tk version, this function has no | |
509 | effect. This function makes porting older image handlers to | |
510 | the new interface a lot easier: After running this function, | |
511 | the arguments are guaranteed to be in string format, no | |
512 | matter how Tk deliverd them. | |
513 | ||
514 | .SH "SEE ALSO" | |
515 | Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage | |
516 | ||
517 | .SH KEYWORDS | |
518 | image manager, image type, instance, master |