---
name: "Tk_FreeImage"
section: "3"
platform: "linux"
package: "tk"
version: "8.6.16-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Tk_FreeImage"
---

# Tk\_FreeImage(3)

use an image in a widget

```

```

## NAME

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

## 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

- 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.

- ClientData *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

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(
        ClientData 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) size.

## SEE ALSO

Tk\_CreateImageType

## KEYWORDS

images, redisplay