Tk_GetImage(3tk)
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
Tk Last change: 4.0 1
Tk_GetImage(3) Tk Library Procedures Tk_GetImage(3)
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 speci-
fied to
Tk_GetImage or
a pixmap com-
patible 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
Tk Last change: 4.0 2
Tk_GetImage(3) Tk Library Procedures Tk_GetImage(3)
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 pix-
els) 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
interp->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.
Tk Last change: 4.0 3
Tk_GetImage(3) Tk Library Procedures Tk_GetImage(3)
If the contents or size of an image changes, then any widg-
ets 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 pur-
pose. 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 Last change: 4.0 4
Man(1) output converted with
man2html