2 '\" Copyright (c) 1994 The Regents of the University of California.
3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 '\" RCS: @(#) $Id: CrtImgType.3,v 1.6 2002/08/05 04:30:38 dgp Exp $
10 '\" The definitions below are for supplemental macros used in Tcl/Tk
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)
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.
26 '\" Start box enclosure. From here until next .BE, everything will be
27 '\" enclosed in one large box.
30 '\" End of box enclosure.
33 '\" Begin code excerpt.
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.
46 '\" End of vertical sidebar.
49 '\" Begin an indented unfilled display.
52 '\" End of indented unfilled display.
55 '\" Start of list of standard options for a Tk widget. The
56 '\" options follow on successive lines, in four columns separated
60 '\" End of list of standard options for a Tk widget.
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.
69 '\" Print arg1 underlined, then print arg2 normally.
71 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
73 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
77 '\" # Start an argument description
81 . ie !"\\$2"" .TP \\n()Cu
86 \&\\$1 \\fI\\$2\\fP (\\$3)
99 '\" # define tabbing values for .AP
102 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
105 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
106 .nr )C \\n()Bu+\\w'(in/out)'u+2n
108 .AS Tcl_Interp Tcl_CreateInterp in/out
109 '\" # BS - start boxed text
110 '\" # ^y = starting y location
118 .if n \l'\\n(.lu\(ul'
121 '\" # BE - end boxed text (draw box now)
126 .ie n \l'\\n(^lu\(ul'
128 .\" Draw four-sided box normally, but don't draw top of
129 .\" box if the box started on an earlier page.
131 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
134 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
141 '\" # VS - start vertical sidebar
142 '\" # ^Y = starting y location
143 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
147 .ie n 'mc \s12\(br\s0
150 '\" # VE - end of vertical sidebar
158 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
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.
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
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
194 '\" # DS - begin display
200 '\" # DE - end display
206 '\" # SO - start of list of standard options
208 .SH "STANDARD OPTIONS"
214 '\" # SE - end of list of standard options
219 See the \\fBoptions\\fR manual entry for details on the standard options.
221 '\" # OP - start of full description for a single option
226 Command-Line Name: \\fB\\$1\\fR
227 Database Name: \\fB\\$2\\fR
228 Database Class: \\fB\\$3\\fR
232 '\" # CS - begin code excerpt
238 '\" # CE - end code excerpt
246 .TH Tk_CreateImageType 3 8.3 Tk "Tk Library Procedures"
249 Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs \- define new kind of image
252 \fB#include <tk.h>\fR
254 \fBTk_CreateImageType\fR(\fItypePtr\fR)
258 \fBTk_GetImageMasterData\fR(\fIinterp, name, typePtrPtr\fR)
260 \fBTk_InitImageArgs\fR(\fIinterp, argc, argvPtr\fR)
262 .AS Tk_ImageType *typePtrPtr
263 .AP Tk_ImageType *typePtr in
264 Structure that defines the new type of image.
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.
276 .AP char ***argvPtr in/out
277 Pointer to argument list
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.
292 The code that implements a new image type is called an
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:
300 typedef struct Tk_ImageType {
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;
309 The fields of this structure will be described in later subsections
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.
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
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.
332 The following subsections describe the fields of a Tk_ImageType
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
341 If there already existed an image type by this name then
342 the new image type replaces the old one.
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.
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:
360 typedef int Tk_ImageCreateProc(
361 Tcl_Interp *\fIinterp\fR,
364 Tcl_Obj *CONST \fIobjv\fR[],
365 Tk_ImageType *\fItypePtr\fR,
366 Tk_ImageMaster \fImaster\fR,
367 ClientData *\fImasterDataPtr\fR);
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
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.
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.
391 \fIcreateProc\fR should call \fBTk_ImageChanged\fR in order to set the
392 size of the image and request an initial redisplay.
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:
400 typedef ClientData Tk_ImageGetProc(
401 Tk_Window \fItkwin\fR,
402 ClientData \fImasterData\fR);
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.
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:
421 typedef void Tk_ImageDisplayProc(
422 ClientData \fIinstanceData\fR,
423 Display *\fIdisplay\fR,
424 Drawable \fIdrawable\fR,
430 int \fIdrawableY\fR);
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
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.
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:
458 typedef void Tk_ImageFreeProc(
459 ClientData \fIinstanceData\fR,
460 Display *\fIdisplay\fR);
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.
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
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:
477 typedef void Tk_ImageDeleteProc(
478 ClientData \fImasterData\fR);
480 The \fImasterData\fR argument will be the same as the value
481 stored in \fI*masterDataPtr\fR by \fIcreateProc\fR when the
483 \fIdeleteProc\fR should release any resources associated with
486 .SH TK_GETIMAGEMASTERDATA
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.
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.
515 Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage
518 image manager, image type, instance, master