util/src/TclTk/tk8.6.12/doc/GetImage.3

   1 '\"
   2 '\" Copyright (c) 1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 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 .TH Tk_GetImage 3 4.0 Tk "Tk Library Procedures"
   9 .so man.macros
  10 .BS
  11 .SH NAME
  12 Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage \- use an image in a widget
  13 .SH SYNOPSIS
  14 .nf
  15 \fB#include <tk.h>\fR
  16 .sp
  17 Tk_Image
  18 \fBTk_GetImage\fR(\fIinterp, tkwin, name, changeProc, clientData\fR)
  19 .sp
  20 \fBTk_RedrawImage\fR(\fIimage, imageX, imageY, width, height, drawable, drawableX, drawableY\fR)
  21 .sp
  22 \fBTk_SizeOfImage\fR(\fIimage, widthPtr, heightPtr\fR)
  23 .sp
  24 \fBTk_FreeImage\fR(\fIimage\fR)
  25 .SH ARGUMENTS
  26 .AS Tk_ImageChangedProc *changeProc
  27 .AP Tcl_Interp *interp in
  28 Place to leave error message.
  29 .AP Tk_Window tkwin in
  30 Window in which image will be used.
  31 .AP "const char" *name in
  32 Name of image.
  33 .AP Tk_ImageChangedProc *changeProc in
  34 Procedure for Tk to invoke whenever image content or size changes.
  35 .AP ClientData clientData in
  36 One-word value for Tk to pass to \fIchangeProc\fR.
  37 .AP Tk_Image image in
  38 Token for image instance;  must have been returned by a previous
  39 call to \fBTk_GetImage\fR.
  40 .AP int imageX in
  41 X-coordinate of upper-left corner of region of image to redisplay
  42 (measured in pixels from the image's upper-left corner).
  43 .AP int imageY in
  44 Y-coordinate of upper-left corner of region of image to redisplay
  45 (measured in pixels from the image's upper-left corner).
  46 .AP "int" width (in)
  47 Width of region of image to redisplay.
  48 .AP "int" height (in)
  49 Height of region of image to redisplay.
  50 .AP Drawable drawable in
  51 Where to display image.  Must either be window specified to
  52 \fBTk_GetImage\fR or a pixmap compatible with that window.
  53 .AP int drawableX in
  54 Where to display image in \fIdrawable\fR: this is the x-coordinate
  55 in \fIdrawable\fR where x-coordinate \fIimageX\fR of the image
  56 should be displayed.
  57 .AP int drawableY in
  58 Where to display image in \fIdrawable\fR: this is the y-coordinate
  59 in \fIdrawable\fR where y-coordinate \fIimageY\fR of the image
  60 should be displayed.
  61 .AP "int" widthPtr out
  62 Store width of \fIimage\fR (in pixels) here.
  63 .AP "int" heightPtr out
  64 Store height of \fIimage\fR (in pixels) here.
  65 .BE
  66 .SH DESCRIPTION
  67 .PP
  68 These procedures are invoked by widgets that wish to display images.
  69 \fBTk_GetImage\fR is invoked by a widget when it first decides to
  70 display an image.
  71 \fIname\fR gives the name of the desired image and \fItkwin\fR
  72 identifies the window where the image will be displayed.
  73 \fBTk_GetImage\fR looks up the image in the table of existing
  74 images and returns a token for a new instance of the image.
  75 If the image does not exist then \fBTk_GetImage\fR returns NULL
  76 and leaves an error message in interpreter \fIinterp\fR's result.
  77 .PP
  78 When a widget wishes to actually display an image it must
  79 call \fBTk_RedrawImage\fR, identifying the image (\fIimage\fR),
  80 a region within the image to redisplay (\fIimageX\fR, \fIimageY\fR,
  81 \fIwidth\fR, and \fIheight\fR), and a place to display the
  82 image (\fIdrawable\fR, \fIdrawableX\fR, and \fIdrawableY\fR).
  83 Tk will then invoke the appropriate image manager, which will
  84 display the requested portion of the image before returning.
  85 .PP
  86 A widget can find out the dimensions of an image by calling
  87 \fBTk_SizeOfImage\fR:  the width and height will be stored
  88 in the locations given by \fIwidthPtr\fR and \fIheightPtr\fR,
  89 respectively.
  90 .PP
  91 When a widget is finished with an image (e.g., the widget is
  92 being deleted or it is going to use a different image instead
  93 of the current one), it must call \fBTk_FreeImage\fR to
  94 release the image instance.
  95 The widget should never again use the image token after passing
  96 it to \fBTk_FreeImage\fR.
  97 There must be exactly one call to \fBTk_FreeImage\fR for each
  98 call to \fBTk_GetImage\fR.
  99 .PP
 100 If the contents or size of an image changes, then any widgets
 101 using the image will need to find out about the changes so that
 102 they can redisplay themselves.
 103 The \fIchangeProc\fR and \fIclientData\fR arguments to
 104 \fBTk_GetImage\fR are used for this purpose.
 105 \fIchangeProc\fR will be called by Tk whenever a change occurs
 106 in the image;  it must match the following prototype:
 107 .CS
 108 typedef void \fBTk_ImageChangedProc\fR(
 109         ClientData \fIclientData\fR,
 110         int \fIx\fR,
 111         int \fIy\fR,
 112         int \fIwidth\fR,
 113         int \fIheight\fR,
 114         int \fIimageWidth\fR,
 115         int \fIimageHeight\fR);
 116 .CE
 117 The \fIclientData\fR argument to \fIchangeProc\fR is the same as the
 118 \fIclientData\fR argument to \fBTk_GetImage\fR.
 119 It is usually a pointer to the widget record for the widget or
 120 some other data structure managed by the widget.
 121 The arguments \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR
 122 identify a region within the image that must be redisplayed;
 123 they are specified in pixels measured from the upper-left
 124 corner of the image.
 125 The arguments \fIimageWidth\fR and \fIimageHeight\fR give
 126 the image's (new) size.
 127 .SH "SEE ALSO"
 128 Tk_CreateImageType
 129 .SH KEYWORDS
 130 images, redisplay