Tk Source Code

typedef struct {
    const char *\fIname\fR;
    Tk_ImageCreateProc *\fIcreateProc\fR;
    Tk_ImageGetProc *\fIgetProc\fR;
    Tk_ImageDisplayProc *\fIdisplayProc\fR;
    Tk_ImageFreeProc *\fIfreeProc\fR;
    Tk_ImageDeleteProc *\fIdeleteProc\fR;
    struct Tk_ImageType *\fInextPtr\fR;
    Tk_ImageHandlerProc *\fIhandlerProc\fR;
} \fBTk_ImageType\fR;
.CE
The fields of this structure will be described in later subsections
of this entry.
.PP
The second major data structure manipulated by an image manager
is called an \fIimage model\fR;  it contains overall information

        void *\fImodelData\fR);
.CE
The \fImodelData\fR argument will be the same as the value
stored in \fI*modelDataPtr\fR by \fIcreateProc\fR when the
image was created.
\fIdeleteProc\fR should release any resources associated with
the image.
.SS NEXTPTR
.PP
This field will be filled out by Tk and is ignored.
.SS HANDLERPROC
.PP
\fItypePtr->handlerProc\fR is a procedure that Tk invokes when the command \fBimage handler\fR \fItype\fR is invoked.
The parameters to the command are passed as arguments.
The command result is set by the called procedure.
\fItypePtr->handlerProc\fR must match the following prototype:
.CS
typedef int \fBTk_ImageCreateProc\fR(
        Tcl_Interp *\fIinterp\fR,
        int \fIobjc\fR,
        Tcl_Obj *const \fIobjv\fR[],
.CE
The \fIinterp\fR argument is the interpreter in which the \fBimage\fR
command was invoked.
The \fIobjc\fR and \fIobjv\fR arguments describe all the options of the command (everything after the type argument to \fBimage driver\fR).
\fIobjc\fR is 0, if no options are passed.
The called routine is responsible for any error checking.
Set \fItypePtr->handlerProc\fR to NULL to deactivate the \fBimage handler\fR subcommand for this handler.
.SH TK_GETIMAGEMODELDATA
.PP
The procedure \fBTk_GetImageModelData\fR 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 \fIname\fR
in the interpreter given by \fIinterp\fR, then \fI*typePtrPtr\fR is

one named option (this list will be identical to the corresponding
sublist of the value returned if no \fIoption\fR is specified).  If
one or more \fIoption\-value\fR pairs are specified, then the command
modifies the given option(s) to have the given value(s);  in
this case the command returns an empty string.
\fIOption\fR may have any of the values accepted by the
\fBimage create\fR \fBbitmap\fR command.
.SH "HANDLER DRIVER SUBOPTIONS"
.PP
There are currently no suboptions available for the \fBimage handler bitmap\fR command.
.SH KEYWORDS
bitmap, image
'\" Local Variables:
'\" mode: nroff
'\" End:

manager will be dropped.
Existing instances will retain their sizes but redisplay as
empty areas.
If a deleted image is recreated with another call to \fBimage create\fR,
the existing instances will use the new image.
.\" METHOD: height
.TP
\fBimage handler\fR \fItype\fR \fIsubcommand\fR ?\fIargs ...\fR?
.
The handler command of the image type \fItype\fR is invoked.
The distinct functionality is described in the image type man page of the chosen image type.
.TP
\fBimage height \fIname\fR
.
Returns a decimal string giving the height of image \fIname\fR
in pixels.
.\" METHOD: inuse
.TP
\fBimage inuse \fIname\fR

.PP
.VE 8.7
.SH CREDITS
.PP
The photo image type was designed and implemented by Paul Mackerras,
based on his earlier photo widget and some suggestions from
John Ousterhout.
.SH "PHOTO HANDLER SUBOPTIONS"
.PP
The following commands are available:
.TP
\fBimage handler photo formats\fR
.
List the available formats in the order they are checked, if no \fI-format\fR option is given on image creation.
.SH EXAMPLE
.PP
Load an image from a file and tile it to the size of a window, which
is useful for producing a tiled background:
.PP
.CS
# These lines should be called once

typedef void (Tk_ImageFreeProc) (void *clientData, Display *display);
typedef void (Tk_ImageDeleteProc) (void *clientData);
typedef void (Tk_ImageChangedProc) (void *clientData, int x, int y,
	int width, int height, int imageWidth, int imageHeight);
typedef int (Tk_ImagePostscriptProc) (void *clientData,
	Tcl_Interp *interp, Tk_Window tkwin, Tk_PostscriptInfo psinfo,
	int x, int y, int width, int height, int prepass);
typedef int (Tk_ImageHandlerProc) (Tcl_Interp *interp,
	Tcl_Size objc, Tcl_Obj *const objv[]);

/*
 * The following structure represents a particular type of image (bitmap, xpm
 * image, etc.). It provides information common to all images of that type,
 * such as the type name and a collection of procedures in the image manager
 * that respond to various events. Each image manager is represented by one of
 * these structures.

    Tk_ImagePostscriptProc *postscriptProc;
				/* Procedure to call to produce postscript
				 * output for the image. */
    struct Tk_ImageType *nextPtr;
				/* Next in list of all image types currently
				 * known. Filled in by Tk, not by image
				 * manager. */
    char *reserved;		/* reserved for future expansion */
    Tk_ImageHandlerProc *handlerProc;
				/* Procedure to call for the image handler
				 * interface. */
};

/*
 *----------------------------------------------------------------------
 *
 * Additional definitions used to manage images of type "photo".
 *

    }
    copyPtr = (Tk_ImageType *)ckalloc(sizeof(Tk_ImageType));
    *copyPtr = *typePtr;
    copyPtr->nextPtr = tsdPtr->imageTypeList;
    tsdPtr->imageTypeList = copyPtr;
}


/*
 *----------------------------------------------------------------------
 *
 * Tk_ImageObjCmd --
 *
 *	This function is invoked to process the "image" Tcl command. See the
 *	user documentation for details on what it does.

Tk_ImageObjCmd(
    void *clientData,	/* Main window associated with interpreter. */
    Tcl_Interp *interp,		/* Current interpreter. */
    int objc,			/* Number of arguments. */
    Tcl_Obj *const objv[])	/* Argument strings. */
{
    static const char *const imageOptions[] = {
	"create", "delete", "height", "inuse", "names", "type", "types",
	"width", NULL
	"create", "delete", "handler", "height", "inuse", "names", "type",
	"types", "width", NULL
    };
    enum options {
	IMAGE_CREATE, IMAGE_DELETE, IMAGE_HEIGHT, IMAGE_INUSE, IMAGE_NAMES,
	IMAGE_TYPE, IMAGE_TYPES, IMAGE_WIDTH
	IMAGE_CREATE, IMAGE_DELETE, IMAGE_HANDLER, IMAGE_HEIGHT, IMAGE_INUSE,
	IMAGE_NAMES, IMAGE_TYPE, IMAGE_TYPES, IMAGE_WIDTH
    };
    TkWindow *winPtr = (TkWindow *)clientData;
    int i, isNew, firstOption, index;
    Tk_ImageType *typePtr;
    ImageModel *modelPtr;
    Image *imagePtr;
    Tcl_HashEntry *hPtr;

	return TCL_ERROR;
    }

    if (Tcl_GetIndexFromObjStruct(interp, objv[1], imageOptions,
	    sizeof(char *), "option", 0, &index) != TCL_OK) {
	return TCL_ERROR;
    }
    
    /*
     * First parse the image type for create and handler options
     */

    switch ((enum options) index) {
    case IMAGE_CREATE: {
	Tcl_Obj **args;

    case IMAGE_CREATE:
    case IMAGE_HANDLER:

	/*
	 * Check if image type argument is given
	 */
	
	if (objc < 3) {
	    Tcl_WrongNumArgs(interp, 2, objv,
		    (index == IMAGE_CREATE ?
		    "type ?name? ?-option value ...?");
		    "type ?name? ?-option value ...?" :
		    "type command ?arguments ...?") );
	    return TCL_ERROR;
	}

	/*
	 * Look up the image type.
	 */

	arg = Tcl_GetString(objv[2]);
	for (typePtr = tsdPtr->imageTypeList; typePtr != NULL;
		typePtr = typePtr->nextPtr) {
	    if ((*arg == typePtr->name[0])
		    && (strcmp(arg, typePtr->name) == 0)) {
		break;
	    }
	}
	if (typePtr == NULL) {
	    Tcl_SetObjResult(interp, Tcl_ObjPrintf(
		    "image type \"%s\" does not exist", arg));
	    Tcl_SetErrorCode(interp, "TK", "LOOKUP", "IMAGE_TYPE", arg, (char *)NULL);
	    Tcl_SetErrorCode(interp, "TK", "LOOKUP", "IMAGE_TYPE", arg,
		    (char *)NULL);
	    return TCL_ERROR;
	}

    }
    
    /*
     * Process the command options
     */
    
    switch ((enum options) index) {
    case IMAGE_CREATE: {
	Tcl_Obj **args;

	/*
	 * Figure out a name to use for the new image.
	 */

	if ((objc == 3) || (*(arg = Tcl_GetString(objv[3])) == '-')) {
	    do {
		dispPtr->imageId++;

	    imagePtr->instanceData = typePtr->getProc(imagePtr->tkwin,
		    modelPtr->modelData);
	}
	Tcl_SetObjResult(interp, Tcl_NewStringObj(
		(const char *)Tcl_GetHashKey(&winPtr->mainPtr->imageTable, hPtr), TCL_INDEX_NONE));
	break;
    }
    case IMAGE_HANDLER:

	/*
	 * Check, if a handler proc is registered.
	 * With Tk 9.1, a former reserved value was used for this pointer.
	 * Old calls of Tk_CreateImageType may not pass a function but NULL
	 * to indicate, that this is not supported.
	 */

	if (typePtr->handlerProc == NULL) {
	    Tcl_SetObjResult(interp, Tcl_NewStringObj(
		    "handler operation not supported by this image type",
		    -1));
	    Tcl_SetErrorCode(interp, "TK", "IMAGE", "HANDLER_NOT_SUPPORTED",
		    (char *)NULL);
	    return TCL_ERROR;
	}

	/*
	 * Call the handler image type command.
	 * Note: there might be even no more arguments (objc-3=0).
	 * Let the type handler handle this.
	 */
	
	i = typePtr->handlerProc(interp, objc-3, objv+3);

	/*
	 * Pass the handler proc result to the caller
	 */

	return i;

    case IMAGE_DELETE:
	for (i = 2; i < objc; i++) {
	    arg = Tcl_GetString(objv[i]);
	    hPtr = Tcl_FindHashEntry(&winPtr->mainPtr->imageTable, arg);
	    if (hPtr == NULL) {
		goto alreadyDeleted;
	    }

			    int drawableX, int drawableY);
static void		ImgBmapFree(void *clientData, Display *display);
static void		ImgBmapDelete(void *clientData);
static int		ImgBmapPostscript(void *clientData,
			    Tcl_Interp *interp, Tk_Window tkwin,
			    Tk_PostscriptInfo psinfo, int x, int y,
			    int width, int height, int prepass);
static int		ImgBmapHandler(Tcl_Interp *interp,
			    Tcl_Size objc, Tcl_Obj *const objv[]);

Tk_ImageType tkBitmapImageType = {
    "bitmap",			/* name */
    ImgBmapCreate,		/* createProc */
    ImgBmapGet,			/* getProc */
    ImgBmapDisplay,		/* displayProc */
    ImgBmapFree,		/* freeProc */
    ImgBmapDelete,		/* deleteProc */
    ImgBmapPostscript,		/* postscriptProc */
    NULL,			/* nextPtr */
    NULL
    ImgBmapHandler		/* handlerProc */
};

/*
 * Information used for parsing configuration specs:
 */

static const Tk_ConfigSpec configSpecs[] = {

    return TCL_OK;

  error:
    Tcl_DiscardInterpState(interpState);
    Tcl_DecrRefCount(psObj);
    return TCL_ERROR;
}

/*
 *--------------------------------------------------------------
 *
 * ImgBmapHandler --
 *
 *	The "image handler bitmap args" command is passed to this procedure.
 *
 * Results:
 *	Returns a standard Tcl return value.
 *
 * Side effects:
 *	None.
 *
 *--------------------------------------------------------------
 */

static int
ImgBmapHandler(
    Tcl_Interp *interp,		/* Interpreter for application containing
				 * image. */
    Tcl_Size objc,		/* Number of arguments, may be zero. */
    Tcl_Obj *const objv[])	/* Argument objects (doesn't include option
				 * and image type). */
{
    /*
     * There is currently no operation.
     */
    
    static const char *const handlerOptions[] = {
	NULL
    };
    int index;

    if (objc < 1) {
	Tcl_WrongNumArgs(interp, 0, objv, "suboption ?args?");
	return TCL_ERROR;
    }

    if (Tcl_GetIndexFromObjStruct(interp, objv[0], handlerOptions,
	    sizeof(char *), "suboption", 0, &index) != TCL_OK) {
	return TCL_ERROR;
    }
 
    return TCL_OK;
}

/*
 * Local Variables:
 * mode: c
 * c-basic-offset: 4
 * fill-column: 78
 * End:
 */

			    const Tk_ImageType *typePtr, Tk_ImageModel model,
			    void **clientDataPtr);
static void		ImgPhotoDelete(void *clientData);
static int		ImgPhotoPostscript(void *clientData,
			    Tcl_Interp *interp, Tk_Window tkwin,
			    Tk_PostscriptInfo psInfo, int x, int y, int width,
			    int height, int prepass);
static int		ImgPhotoHandler(Tcl_Interp *interp,
			    Tcl_Size objc, Tcl_Obj *const objv[]);

/*
 * The type record itself for photo images:
 */

Tk_ImageType tkPhotoImageType = {
    "photo",			/* name */
    ImgPhotoCreate,		/* createProc */
    TkImgPhotoGet,		/* getProc */
    TkImgPhotoDisplay,		/* displayProc */
    TkImgPhotoFree,		/* freeProc */
    ImgPhotoDelete,		/* deleteProc */
    ImgPhotoPostscript,		/* postscriptProc */
    NULL,			/* nextPtr */
    NULL
    ImgPhotoHandler		/* handlerProc */
};

typedef struct {
    Tk_PhotoImageFormat *formatList;
				/* Pointer to the first in the list of known
				 * photo image formats.*/
    Tk_PhotoImageFormatVersion3 *formatListVersion3;

    Tk_PhotoImageBlock block;

    Tk_PhotoGetImage(clientData, &block);
    block.pixelPtr += y * block.pitch + x * block.pixelSize;

    return Tk_PostscriptPhoto(interp, &block, psInfo, width, height);
}

/*
 *--------------------------------------------------------------
 *
 * ImgPhotoHandler --
 *
 *	The "image handler photo args" command is passed to this procedure.
 *
 * Results:
 *	Returns a standard Tcl return value.
 *
 * Side effects:
 *	None.
 *
 *--------------------------------------------------------------
 */

static int
ImgPhotoHandler(
    Tcl_Interp *interp,		/* Interpreter for application containing
				 * image. */
    Tcl_Size objc,		/* Number of arguments, may be zero. */
    Tcl_Obj *const objv[])	/* Argument objects (doesn't include option
				 * and image type). */
{
    static const char *const handlerOptions[] = {
	"formats", NULL
    };
    enum options {
	HANDLER_FORMATS
    };
    int index;
    Tcl_Obj *resultObj;
    Tk_PhotoImageFormat *formatPtr;
    Tk_PhotoImageFormatVersion3 *formatVersion3Ptr;
    char * defaultFormatName = NULL;
    ThreadSpecificData *tsdPtr = (ThreadSpecificData *)
	    Tcl_GetThreadData(&dataKey, sizeof(ThreadSpecificData));

    if (objc < 1) {
	Tcl_WrongNumArgs(interp, 0, objv, "suboption ?args?");
	return TCL_ERROR;
    }

    if (Tcl_GetIndexFromObjStruct(interp, objv[0], handlerOptions,
	    sizeof(char *), "suboption", 0, &index) != TCL_OK) {
	return TCL_ERROR;
    }
    
    switch ( (enum options) index) {
    case HANDLER_FORMATS:
	resultObj = Tcl_NewObj();
	

	/*
	 * Scan through the table of file format handlers and collect the
	 * name field.
	 */

	for (formatPtr = tsdPtr->formatList; formatPtr != NULL;
		formatPtr = formatPtr->nextPtr) {
	    
	    /*
	     * Default will be evaluated last, so put it at the end of the
	     * evaluation list
	     */

	    if (strncasecmp("default", formatPtr->name,
		    strlen(formatPtr->name)) == 0) {
		defaultFormatName = formatPtr->name;
	    } else {
		Tcl_ListObjAppendElement(interp, resultObj,
			Tcl_NewStringObj(formatPtr->name,-1));
	    }
	}
	
	/*
	 * Version 3 image format handlers
	 */

	for (formatVersion3Ptr = tsdPtr->formatListVersion3;
		formatVersion3Ptr != NULL;
		formatVersion3Ptr = formatVersion3Ptr->nextPtr) {
	    Tcl_ListObjAppendElement(interp, resultObj,
		    Tcl_NewStringObj(formatVersion3Ptr->name,-1)); 
	}
	
	if (NULL != defaultFormatName) {
	    Tcl_ListObjAppendElement(interp, resultObj,
		    Tcl_NewStringObj(defaultFormatName,-1));
	}

	Tcl_SetObjResult(interp, resultObj);
	break;
    }

    return TCL_OK;
}

/*
 * Local Variables:
 * mode: c
 * c-basic-offset: 4
 * fill-column: 78
 * tab-width: 8
 * End:
 */

test image-1.1 {Tk_ImageCmd procedure, "create" option} -body {
    image
} -returnCodes error -result {wrong # args: should be "image option ?args?"}
test image-1.2 {Tk_ImageCmd procedure, "create" option} -body {
    image gorp
} -returnCodes error -result {bad option "gorp": must be create, delete, height, inuse, names, type, types, or width}
} -returnCodes error -result {bad option "gorp": must be create, delete, handler, height, inuse, names, type, types, or width}
test image-1.3 {Tk_ImageCmd procedure, "create" option} -body {
    image create
} -returnCodes error -result {wrong # args: should be "image create type ?name? ?-option value ...?"}
test image-1.4 {Tk_ImageCmd procedure, "create" option} -body {
    image c bad_type
} -returnCodes error -result {image type "bad_type" does not exist}
test image-1.5 {Tk_ImageCmd procedure, "create" option} -constraints {

} -returnCodes error -result {image "foo" does not exist}
test image-3.4 {Tk_ImageCmd procedure, "height" option} -constraints {
    testImageType
} -setup {
    imageCleanup
} -body {
    image create test myimage
    set x [image h myimage]
    set x [image he myimage]
    myimage changed 0 0 0 0 60 50
    list $x [image height myimage]
} -cleanup {
    imageCleanup
} -result {15 50}

    lappend x [imageNames]
    image create photo foo -width 20 -height 20
    lappend x [.c bbox i1] [imageNames]
} -cleanup {
    .c delete all
    imageCleanup
} -result {10 10 20 20 foo {} {10 10 30 30} foo}

# 16.x command "image handler"

test image-16.1 {Tk_ImageCmd procedure, "handler" no type} -body {
    image handler
} -returnCodes error -result {wrong # args: should be "image handler type command ?arguments ...?"}

test image-16.2 {Tk_ImageCmd procedure, "handler" bad type} -body {
    image ha bad_type
} -returnCodes error -result {image type "bad_type" does not exist}


destroy .c
imageFinish

# cleanup
cleanupTests
return

# Local variables:
# mode: tcl
# End:

test imageBmap-12.1 {ImgBmapCmdDeletedProc procedure} -body {
    image create bitmap i2 -file foo.bm -maskfile foo2.bm
    rename i2 {}
    list [expr {"i2" in [imageNames]}] [catch {i2 foo} msg] $msg
} -result {0 1 {invalid command name "i2"}}

# test 26.x: ImgPhotoHandler, command "image handler bitmap"

test image-13.1 {ImgBmapDriver/image handler bitmap: no option} -body {
    image handler bitmap
} -returnCodes error -result {wrong # args: should be "suboption ?args?"}

test image-13.2 {ImgBmapDriver/image handler bitmap: bad option} -body {
    image handler bitmap bad_option
} -returnCodes error -result {bad suboption "bad_option": no valid options}


removeFile foo.bm
removeFile foo2.bm
imageFinish

# cleanup
cleanupTests

# Tk_PhotoSetSize:                      no tests
# TkGetPhotoValidRegion:                no tests
# ImgGetPhoto:                          no tests
# Tk_PhotoGetImage                      no tests
# ImgPostscriptPhoto                    no tests
# Tk_PhotoGetMetadata:                  imgPhoto-21.*
# Tk_PhotoSetMetadata:                  imgPhoto-22.*
# ImgPhotoDriver                        imgPhoto-26.*
#--------------------------------------------------------------------------
#

#
# Some tests are not specific to a function in tkImgPhoto.c. They are:
#

    catch {png1 read $ousterPhotoFile -from 102 62 2000 1000} msg
    list $msg [image width png1] [image height png1]
} -cleanup {
    catch {image delete png1}
} -result {{coordinates for -from option extend outside source image} 0 0}
unset ousterPhotoFile

# test 26.x: ImgPhotoHandler, command "image handler photo"

test image-26.1 {ImgPhotoDriver/image handler photo: no option} -body {
    image handler photo
} -returnCodes error -result {wrong # args: should be "suboption ?args?"}

test image-26.2 {ImgPhotoDriver/image handler photo: bad option} -body {
    image handler photo bad_option
} -returnCodes error -result {bad suboption "bad_option": must be formats}

test image-26.3 {ImgPhotoDriver/image handler photo: formats option} -body {
    image handler photo formats
} -match glob -result {svg ppm png gif *default}
# take into account, that the list of formats may extend
# Any new format may be inserted between our own ones and the default format.

catch {rename foreachPixel {}}
catch {rename checkImgTrans {}}
catch {rename checkImgTransLoop {}}
imageFinish

# cleanup
removeFile README-imgPhoto
cleanupTests
return

# Local variables:
# mode: tcl
# End: