Tk_CreateImageType 804.027

Tk_CreateImageType is a Perl module to define new kind of image.

SYNOPSIS

#include < tk.h >

Tk_CreateImageType(typePtr) ClientData

Tk_GetImageMasterData(interp, name, typePtrPtr)

ARGUMENTS

Tk_ImageType *typePtr (in)

Structure that defines the new type of image. Must be static: a pointer to this structure is retained by the image code.

Tcl_Interp *interp (in)

Interpreter in which image was created.

char *name (in)

Name of existing image.

Tk_ImageType **typePtrPtr (out)

Points to word in which to store a pointer to type information for the given image, if it exists.

Tk_CreateImageType is invoked to define a new kind of image. An image type corresponds to a particular value of the type argument for the image create command. There may exist any number of different image types, and new types may be defined dynamically by calling Tk_CreateImageType. For example, there might be one type for 2-color bitmaps, another for multi-color images, another for dithered images, another for video, and so on.

The code that implements a new image type is called an image manager. It consists of a collection of procedures plus three different kinds of data structures. The first data structure is a Tk_ImageType structure, which contains the name of the image type and pointers to five procedures provided by the image manager to deal with images of this type:

typedef struct Tk_ImageType {
char *name;
Tk_ImageCreateProc *createProc;
Tk_ImageGetProc *getProc;
Tk_ImageDisplayProc *displayProc;
Tk_ImageFreeProc *freeProc;
Tk_ImageDeleteProc *deleteProc;
} Tk_ImageType;

The fields of this structure will be described in later subsections of this entry.
The second major data structure manipulated by an image manager is called an image master; it contains overall information about a particular image, such as the values of the configuration options specified in an image create command. There will usually be one of these structures for each invocation of the image create command.

The third data structure related to images is an image instance. There will usually be one of these structures for each usage of an image in a particular widget. It is possible for a single image to appear simultaneously in multiple widgets, or even multiple times in the same widget. Furthermore, different instances may be on different screens or displays. The image instance data structure describes things that may vary from instance to instance, such as colors and graphics contexts for redisplay. There is usually one instance structure for each -image option specified for a widget or canvas item.