Tk_GetImage(3) Tk Library Procedures Tk_GetImage(3)

____________________________________________________________________________

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

Tk 4.0 Tk_GetImage(3)