1Tk_FindPhoto(3) Tk Library Procedures Tk_FindPhoto(3)
2______________________________________________________________________________
6
8 Tk_FindPhoto, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetIm‐
9 age, Tk_PhotoBlank, Tk_PhotoExpand, Tk_PhotoGetSize, Tk_PhotoSetSize -
10 manipulate the image data stored in a photo image.
11
13 #include <tk.h>
14 #include <tkPhoto.h>
15 Tk_PhotoHandle
17 Tk_FindPhoto(interp, imageName) │
18 void
20 Tk_PhotoPutBlock(handle, blockPtr, x, y, width, height, compRule)
21 void
23 Tk_PhotoPutZoomedBlock(handle, blockPtr, x, y, width, height,zoomX, zoomY, subsampleX, subsampleY, compRule)
24 int
26 Tk_PhotoGetImage(handle, blockPtr)
27 void
29 Tk_PhotoBlank(handle)
30 void
32 Tk_PhotoExpand(handle, width, height)
33 void
35 Tk_PhotoGetSize(handle, widthPtr, heightPtr)
36 void
38 Tk_PhotoSetSize(handle, width, height)
39
41 Tcl_Interp *interp (in) Interpreter in which image │
42 was created.
43 CONST char *imageName (in) Name of the photo image.
45 Tk_PhotoHandle handle (in) Opaque handle identifying
47 the photo image to be
48 affected.
49 Tk_PhotoImageBlock *blockPtr (in) Specifies the address and
51 storage layout of image
52 data.
53 int x (in) Specifies the X coordinate
55 where the top-left corner
56 of the block is to be
57 placed within the image.
58 int y (in) Specifies the Y coordinate
60 where the top-left corner
61 of the block is to be
62 placed within the image.
63 int width (in) Specifies the width of the
65 image area to be affected
66 (for Tk_PhotoPutBlock) or
67 the desired image width
68 (for Tk_PhotoExpand and
69 Tk_PhotoSetSize). │
70 int compRule (in) │
72 Specifies the compositing │
73 rule used when combining │
74 transparent pixels in a │
75 block of data with a photo │
76 image. Must be one of │
77 TK_PHOTO_COMPOSITE_OVERLAY │
78 (which puts the block of │
79 data over the top of the │
80 existing photo image, with │
81 the previous contents │
82 showing through in the │
83 transparent bits) or │
84 TK_PHOTO_COMPOSITE_SET │
85 (which discards the exist‐ │
86 ing photo image contents │
87 in the rectangle covered │
88 by the data block.)
89 int height (in) Specifies the height of
91 the image area to be
92 affected (for Tk_PhotoPut‐
93 Block) or the desired
94 image height (for Tk_Pho‐
95 toExpand and Tk_PhotoSet‐
96 Size).
97 int *widthPtr (out) Pointer to location in
99 which to store the image
100 width.
101 int *heightPtr (out) Pointer to location in
103 which to store the image
104 height.
105 int subsampleX (in) Specifies the subsampling
107 factor in the X direction
108 for input image data.
109 int subsampleY (in) Specifies the subsampling
111 factor in the Y direction
112 for input image data.
113 int zoomX (in) Specifies the zoom factor
115 to be applied in the X
116 direction to pixels being
117 written to the photo
118 image.
119 int zoomY (in) Specifies the zoom factor
121 to be applied in the Y
122 direction to pixels being
123 written to the photo
124 image.
125_________________________________________________________________
126
129 Tk_FindPhoto returns an opaque handle that is used to identify a par‐
130 ticular photo image to the other procedures. The parameter is the name
131 of the image, that is, the name specified to the image create photo
132 command, or assigned by that command if no name was specified.
133 Tk_PhotoPutBlock is used to supply blocks of image data to be dis‐
135 played. The call affects an area of the image of size width x height
136 pixels, with its top-left corner at coordinates (x,y). All of width,
137 height, x, and y must be non-negative. If part of this area lies out‐
138 side the current bounds of the image, the image will be expanded to
139 include the area, unless the user has specified an explicit image size
140 with the -width and/or -height widget configuration options (see
141 photo(n)); in that case the area is silently clipped to the image
142 boundaries.
143 The block parameter is a pointer to a Tk_PhotoImageBlock structure,
145 defined as follows:
146 typedef struct {
147 unsigned char *pixelPtr;
148 int width;
149 int height;
150 int pitch;
151 int pixelSize;
152 int offset[4];
153 } Tk_PhotoImageBlock;
154 The pixelPtr field points to the first pixel, that is, the top-left
155 pixel in the block. The width and height fields specify the dimensions
156 of the block of pixels. The pixelSize field specifies the address dif‐
157 ference between two horizontally adjacent pixels. Often it is 3 or 4,
158 but it can have any value. The pitch field specifies the address dif‐
159 ference between two vertically adjacent pixels. The offset array con‐
160 tains the offsets from the address of a pixel to the addresses of the
161 bytes containing the red, green, blue and alpha (transparency) compo‐
162 nents. These are normally 0, 1, 2 and 3, but can have other values,
163 e.g., for images that are stored as separate red, green and blue
164 planes.
165 The compRule parameter to Tk_PhotoPutBlock specifies a compositing rule │
167 that says what to do with transparent pixels. The value TK_PHOTO_COM‐ │
168 POSITE_OVERLAY says that the previous contents of the photo image │
169 should show through, and the value TK_PHOTO_COMPOSITE_SET says that the │
170 previous contents of the photo image should be completely ignored, and │
171 the values from the block be copied directly across. The behavior in │
172 Tk8.3 and earlier was equivalent to having TK_PHOTO_COMPOSITE_OVERLAY │
173 as a compositing rule.
174 The value given for the width and height parameters to Tk_PhotoPutBlock
176 do not have to correspond to the values specified in block. If they
177 are smaller, Tk_PhotoPutBlock extracts a sub-block from the image data
178 supplied. If they are larger, the data given are replicated (in a
179 tiled fashion) to fill the specified area. These rules operate inde‐
180 pendently in the horizontal and vertical directions.
181 Tk_PhotoPutZoomedBlock works like Tk_PhotoPutBlock except that the
183 image can be reduced or enlarged for display. The subsampleX and sub‐
184 sampleY parameters allow the size of the image to be reduced by subsam‐
185 pling. Tk_PhotoPutZoomedBlock will use only pixels from the input
186 image whose X coordinates are multiples of subsampleX, and whose Y
187 coordinates are multiples of subsampleY. For example, an image of
188 512x512 pixels can be reduced to 256x256 by setting subsampleX and sub‐
189 sampleY to 2.
190 The zoomX and zoomY parameters allow the image to be enlarged by pixel
192 replication. Each pixel of the (possibly subsampled) input image will
193 be written to a block zoomX pixels wide and zoomY pixels high of the
194 displayed image. Subsampling and zooming can be used together for spe‐
195 cial effects.
196 Tk_PhotoGetImage can be used to retrieve image data from a photo image.
198 Tk_PhotoGetImage fills in the structure pointed to by the blockPtr
199 parameter with values that describe the address and layout of the image
200 data that the photo image has stored internally. The values are valid
201 until the image is destroyed or its size is changed. Tk_PhotoGetImage
202 returns 1 for compatibility with the corresponding procedure in the old
203 photo widget.
204 Tk_PhotoBlank blanks the entire area of the photo image. Blank areas
206 of a photo image are transparent.
207 Tk_PhotoExpand requests that the widget's image be expanded to be at
209 least width x height pixels in size. The width and/or height are
210 unchanged if the user has specified an explicit image width or height
211 with the -width and/or -height configuration options, respectively. If
212 the image data are being supplied in many small blocks, it is more
213 efficient to use Tk_PhotoExpand or Tk_PhotoSetSize at the beginning
214 rather than allowing the image to expand in many small increments as
215 image blocks are supplied.
216 Tk_PhotoSetSize specifies the size of the image, as if the user had
218 specified the given width and height values to the -width and -height
219 configuration options. A value of zero for width or height does not
220 change the image's width or height, but allows the width or height to
221 be changed by subsequent calls to Tk_PhotoPutBlock, Tk_PhotoPutZoomed‐
222 Block or Tk_PhotoExpand.
223 Tk_PhotoGetSize returns the dimensions of the image in *widthPtr and
225 *heightPtr.
226
229 In Tk 8.3 and earlier, Tk_PhotoPutBlock and Tk_PhotoPutZoomedBlock had │
230 different signatures. If you want to compile code that uses the old │
231 interface against 8.4 without updating your code, compile it with the │
232 flag -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK. Code linked using Stubs │
233 against older versions of Tk will continue to work.
234
237 The code for the photo image type was developed by Paul Mackerras,
238 based on his earlier photo widget code.
239
242 photo, image
243Tk 8.0 Tk_FindPhoto(3)