diff options
Diffstat (limited to 'doc/FindPhoto.3')
| -rw-r--r-- | doc/FindPhoto.3 | 36 |
1 files changed, 16 insertions, 20 deletions
diff --git a/doc/FindPhoto.3 b/doc/FindPhoto.3 index 30df3a2..e4d83f0 100644 --- a/doc/FindPhoto.3 +++ b/doc/FindPhoto.3 @@ -21,7 +21,6 @@ Tk_FindPhoto, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetImage, Tk_Pho Tk_PhotoHandle \fBTk_FindPhoto\fR(\fIinterp, imageName\fR) .sp -.VS 8.5 int \fBTk_PhotoPutBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\ compRule\fR) @@ -29,7 +28,6 @@ compRule\fR) int \fBTk_PhotoPutZoomedBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\ zoomX, zoomY, subsampleX, subsampleY, compRule\fR) -.VE 8.5 .sp int \fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR) @@ -37,18 +35,14 @@ int void \fBTk_PhotoBlank\fR(\fIhandle\fR) .sp -.VS 8.5 int \fBTk_PhotoExpand\fR(\fIinterp, handle, width, height\fR) -.VE 8.5 .sp void \fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR) .sp -.VS 8.5 int \fBTk_PhotoSetSize\fR(\fIinterp. handle, width, height\fR) -.VE 8.5 .SH ARGUMENTS .AS Tk_PhotoImageBlock window_path .AP Tcl_Interp *interp in @@ -99,13 +93,14 @@ being written to the photo image. Specifies the zoom factor to be applied in the Y direction to pixels being written to the photo image. .BE - .SH DESCRIPTION .PP \fBTk_FindPhoto\fR returns an opaque handle that is used to identify a particular photo image to the other procedures. The parameter is the name of the image, that is, the name specified to the \fBimage create photo\fR command, or assigned by that command if no name was specified. +If \fIimageName\fR does not exist or is not a photo image, +\fBTk_FindPhoto\fR returns NULL. .PP \fBTk_PhotoPutBlock\fR is used to supply blocks of image data to be displayed. The call affects an area of the image of size @@ -128,8 +123,8 @@ typedef struct { int \fIheight\fR; int \fIpitch\fR; int \fIpixelSize\fR; - int \fIoffset[4]\fR; -} Tk_PhotoImageBlock; + int \fIoffset\fR[4]; +} \fBTk_PhotoImageBlock\fR; .CE The \fIpixelPtr\fR field points to the first pixel, that is, the top-left pixel in the block. @@ -161,12 +156,10 @@ given are replicated (in a tiled fashion) to fill the specified area. These rules operate independently in the horizontal and vertical directions. .PP -.VS 8.5 \fBTk_PhotoPutBlock\fR normally returns \fBTCL_OK\fR, though if it cannot allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is returned instead and, if the \fIinterp\fR argument is non-NULL, an error message is placed in the interpreter's result. -.VE 8.5 .PP \fBTk_PhotoPutZoomedBlock\fR works like \fBTk_PhotoPutBlock\fR except that the image can be reduced or enlarged for display. The @@ -190,6 +183,18 @@ in the structure pointed to by the \fIblockPtr\fR parameter with values that describe the address and layout of the image data that the photo image has stored internally. The values are valid until the image is destroyed or its size is changed. +.PP +It is possible to modify an image by writing directly to the data +the \fIpixelPtr\fR field points to. The size of the image cannot be +changed this way, though. +Also, changes made by writing directly to \fIpixelPtr\fR will not be +immediately visible, but only after a call to +\fBTk_ImageChanged\fR or after an event that causes the interested +widgets to redraw themselves. +For these reasons usually it is preferable to make changes to +a copy of the image data and write it back with +\fBTk_PhotoPutBlock\fR or \fBTk_PhotoPutZoomedBlock\fR. +.PP \fBTk_PhotoGetImage\fR returns 1 for compatibility with the corresponding procedure in the old photo widget. .PP @@ -207,12 +212,10 @@ are being supplied in many small blocks, it is more efficient to use allowing the image to expand in many small increments as image blocks are supplied. .PP -.VS 8.5 \fBTk_PhotoExpand\fR normally returns \fBTCL_OK\fR, though if it cannot allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is returned instead and, if the \fIinterp\fR argument is non-NULL, an error message is placed in the interpreter's result. -.VE 8.5 .PP \fBTk_PhotoSetSize\fR specifies the size of the image, as if the user had specified the given \fIwidth\fR and \fIheight\fR values to the @@ -222,16 +225,13 @@ or height, but allows the width or height to be changed by subsequent calls to \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR or \fBTk_PhotoExpand\fR. .PP -.VS 8.5 \fBTk_PhotoSetSize\fR normally returns \fBTCL_OK\fR, though if it cannot allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is returned instead and, if the \fIinterp\fR argument is non-NULL, an error message is placed in the interpreter's result. -.VE 8.5 .PP \fBTk_PhotoGetSize\fR returns the dimensions of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR. - .SH PORTABILITY .PP In Tk 8.3 and earlier, \fBTk_PhotoPutBlock\fR and @@ -241,7 +241,6 @@ your code, compile it with the flag -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK. Code linked using Stubs against older versions of Tk will continue to work. .PP -.VS 8.5 In Tk 8.4, \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR, \fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR did not take an \fIinterp\fR argument or return any result code. If insufficient @@ -249,12 +248,9 @@ memory was available for an image, Tk would panic. This behaviour is still supported if you compile your extension with the additional flag -DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE. Code linked using Stubs against older versions of Tk will continue to work. -.VE 8.5 - .SH CREDITS .PP The code for the photo image type was developed by Paul Mackerras, based on his earlier photo widget code. - .SH KEYWORDS photo, image |