Tk\_GetImage(3) Tk Library Procedures Tk\_GetImage(3)

```

```

# [NAME](#NAME)

Tk\_GetImage, Tk\_RedrawImage, Tk\_SizeOfImage, Tk\_FreeImage - use an image in a widget

# [SYNOPSIS](#SYNOPSIS)

```
#include <tk.h>

Tk_Image
Tk_GetImage(interp, tkwin, name, changeProc, clientData)

Tk_RedrawImage(image, imageX, imageY, width, height, drawable, drawableX, drawableY)

Tk_SizeOfImage(image, widthPtr, heightPtr)

Tk_FreeImage(image)
```

# [ARGUMENTS](#ARGUMENTS)

Tcl\_Interp *\*interp* (in)

Place to leave error message.

Tk\_Window *tkwin* (in)

Window in which image will be used.

const char *\*name* (in)

Name of image.

Tk\_ImageChangedProc *\*changeProc* (in)

Procedure for Tk to invoke whenever image content or size changes.

void *\*clientData* (in)

One-word value for Tk to pass to *changeProc*.

Tk\_Image *image* (in)

Token for image instance; must have been returned by a previous call to **Tk\_GetImage**.

int *imageX* (in)

X-coordinate of upper-left corner of region of image to redisplay (measured in pixels from the image's upper-left corner).

int *imageY* (in)

Y-coordinate of upper-left corner of region of image to redisplay (measured in pixels from the image's upper-left corner).

int *width* ((in))

Width of region of image to redisplay.

int *height* ((in))

Height of region of image to redisplay.

Drawable *drawable* (in)

Where to display image. Must either be window specified to **Tk\_GetImage** or a pixmap compatible with that window.

int *drawableX* (in)

Where to display image in *drawable*: this is the x-coordinate in *drawable* where x-coordinate *imageX* of the image should be displayed.

int *drawableY* (in)

Where to display image in *drawable*: this is the y-coordinate in *drawable* where y-coordinate *imageY* of the image should be displayed.

int *widthPtr* (out)

Store width of *image* (in pixels) here.

int *heightPtr* (out)

Store height of *image* (in pixels) here.

```
    
```

# [DESCRIPTION](#DESCRIPTION)

These procedures are invoked by widgets that wish to display images. **Tk\_GetImage** is invoked by a widget when it first decides to display an image. *name* gives the name of the desired image and *tkwin* identifies the window where the image will be displayed. **Tk\_GetImage** looks up the image in the table of existing images and returns a token for a new instance of the image. If the image does not exist then **Tk\_GetImage** returns NULL and leaves an error message in interpreter *interp*'s result.

When a widget wishes to actually display an image it must call **Tk\_RedrawImage**, identifying the image (*image*), a region within the image to redisplay (*imageX*, *imageY*, *width*, and *height*), and a place to display the image (*drawable*, *drawableX*, and *drawableY*). Tk will then invoke the appropriate image manager, which will display the requested portion of the image before returning.

A widget can find out the dimensions of an image by calling **Tk\_SizeOfImage**: the width and height will be stored in the locations given by *widthPtr* and *heightPtr*, respectively.

When a widget is finished with an image (e.g., the widget is being deleted or it is going to use a different image instead of the current one), it must call **Tk\_FreeImage** to release the image instance. The widget should never again use the image token after passing it to **Tk\_FreeImage**. There must be exactly one call to **Tk\_FreeImage** for each call to **Tk\_GetImage**.

If the contents or size of an image changes, then any widgets using the image will need to find out about the changes so that they can redisplay themselves. The *changeProc* and *clientData* arguments to **Tk\_GetImage** are used for this purpose. *changeProc* will be called by Tk whenever a change occurs in the image; it must match the following prototype:

```
typedef void Tk_ImageChangedProc(


        void *clientData,


        int x,


        int y,


        int width,


        int height,


        int imageWidth,


        int imageHeight);
```

The *clientData* argument to *changeProc* is the same as the *clientData* argument to **Tk\_GetImage**. It is usually a pointer to the widget record for the widget or some other data structure managed by the widget. The arguments *x*, *y*, *width*, and *height* identify a region within the image that must be redisplayed; they are specified in pixels measured from the upper-left corner of the image. The arguments *imageWidth* and *imageHeight* give the image'[s (new)](/man/os/tk/s.new) size.

# [SEE ALSO](#SEE_ALSO)

Tk\_CreateImageType

# [KEYWORDS](#KEYWORDS)

images, redisplay

4.0 Tk

---

Document: Tk_FreeImage(3) from tk 9.0.4-r2 (Chainguard OS)
Source: https://downloads.sourceforge.net/sourceforge/tcl/tk9.0.4-src.tar.gz