NAME¶

Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs - define new kind of image

SYNOPSIS¶

#include <tk.h>

Tk_CreateImageType(typePtr)

ClientData
Tk_GetImageMasterData(interp, name, typePtrPtr)

Tk_InitImageArgs(interp, argc, argvPtr)

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.

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

int argc (in)

Number of arguments

char ***argvPtr (in/out)

Pointer to argument list

DESCRIPTION¶

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

The following subsections describe the fields of a Tk_ImageType in more detail.

typedef int Tk_ImageCreateProc(


    Tcl_Interp *interp,


    char *name,


    int objc,


    Tcl_Obj *const objv[],


    Tk_ImageType *typePtr,


    Tk_ImageMaster master,


    ClientData *masterDataPtr);

typedef ClientData Tk_ImageGetProc(


    Tk_Window tkwin,


    ClientData masterData);

typedef void Tk_ImageDisplayProc(


    ClientData instanceData,


    Display *display,


    Drawable drawable,


    int imageX,


    int imageY,


    int width,


    int height,


    int drawableX,


    int drawableY);

typedef void Tk_ImageFreeProc(


    ClientData instanceData,


    Display *display);

typedef void Tk_ImageDeleteProc(


    ClientData masterData);

TK_GETIMAGEMASTERDATA¶

The procedure Tk_GetImageMasterData may be invoked to retrieve information about an image. For example, an image manager can use this procedure to locate its image master data for an image. If there exists an image named name in the interpreter given by interp, then *typePtrPtr is filled in with type information for the image (the typePtr value passed to Tk_CreateImageType when the image type was registered) and the return value is the ClientData value returned by the createProc when the image was created (this is typically a pointer to the image master data structure). If no such image exists then NULL is returned and NULL is stored at *typePtrPtr.

LEGACY INTERFACE SUPPORT¶

In Tk 8.2 and earlier, the definition of Tk_ImageCreateProc was incompatibly different, with the following prototype:

typedef int Tk_ImageCreateProc(


    Tcl_Interp *interp,


    char *name,


    int argc,


    char **argv,


    Tk_ImageType *typePtr,


    Tk_ImageMaster master,


    ClientData *masterDataPtr);

When the USE_OLD_IMAGE legacy support is enabled, you may see the routine Tk_InitImageArgs in use. This was a migration tool used to create stub-enabled extensions that could be loaded into interps containing all versions of Tk 8.1 and later. Tk 8.5 no longer provides this routine, but uses a macro to convert any attempted calls of this routine into an empty comment. Any stub-enabled extension providing an extended image type via the legacy interface that is compiled against Tk 8.5 headers and linked against the Tk 8.5 stub library will produce a file that can be loaded only into interps with Tk 8.5 or later; that is, the normal stub-compatibility rules. If a developer needs to generate from such code a file that is loadable into interps with Tk 8.4 or earlier, they must use Tk 8.4 headers and stub libraries to do so.

Any new code written today should not make use of the legacy interfaces. Expect their support to go away in Tk 9.

SEE ALSO¶

Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage

KEYWORDS¶

image manager, image type, instance, master