Tk_CreateImageType - Man Page

#include <tk.h>

Tk_CreateImageType(typePtr)

ClientData
Tk_GetImageMasterData(interp, name, typePtrPtr)

ClientData
Tk_GetImageModelData(interp, name, typePtrPtr)

Tk_InitImageArgs(interp, argc, argvPtr)

const Tk_ImageType *typePtr (in)

Structure that defines the new type of image. For Tk 8.4 and earlier this must be static: a pointer to this structure is retained by the image code. In Tk 8.5, this limitation was relaxed.

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

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 {
    const 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 model;  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,
        const char *name,
        int objc,
        Tcl_Obj *const objv[],
        const Tk_ImageType *typePtr,
        Tk_ImageMaster model,
        ClientData *modelDataPtr);

typedef ClientData Tk_ImageGetProc(
        Tk_Window tkwin,
        ClientData modelData);

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 modelData);

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 model 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 model data structure).  If no such image exists then NULL is returned and NULL is stored at *typePtrPtr.

Tk_GetImageModelData is synonym for Tk_GetImageMasterData

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 model,
        ClientData *modelDataPtr);

Legacy programs and libraries dating from those days may still contain code that defines extended Tk image types using the old interface.  The Tk header file will still support this legacy interface if the code is compiled with the macro USE_OLD_IMAGE defined.

Tk_ImageModel is synonym for Tk_ImageMaster

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.

Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage

image manager, image type, instance, model

The man pages Tk_GetImageMasterData(3), Tk_GetImageModelData(3) and Tk_InitImageArgs(3) are aliases of Tk_CreateImageType(3).