Tk_CreatePhotoImageFormat man page on OpenServer

Man page or keyword search:  
man Server   5388 pages
apropos Keyword Search (all sections)
Output format
OpenServer logo
[printable version]

Tk_CreatePhotoImageFormat(3) Tk Library ProceduresTk_CreatePhotoImageFormat(3)

______________________________________________________________________________

NAME
       Tk_CreatePhotoImageFormat - define new file format for photo images

SYNOPSIS
       #include <tk.h>

       Tk_CreatePhotoImageFormat(formatPtr)

ARGUMENTS
       Tk_PhotoImageFormat   *formatPtr	  (in)	    Structure that defines the
						    new file format.
_________________________________________________________________

DESCRIPTION
       Tk_CreatePhotoImageFormat is invoked to define a new  file  format  for
       image  data  for	 use  with  photo images.  The code that implements an
       image file format is called an image file format	 handler,  or  handler
       for  short.  The photo image code maintains a list of handlers that can
       be used to read and write data to or from a file.   Some	 handlers  may
       also  support reading image data from a string or converting image data
       to a string format.  The user can specify which handler to use with the
       -format	image  configuration  option or the -format option to the read
       and write photo image subcommands.

       An image file format handler consists of	 a  collection	of  procedures
       plus  a	Tk_PhotoImageFormat  structure, which contains the name of the
       image file format and pointers to six procedures provided by  the  han-
       dler to deal with files and strings in this format.  The Tk_PhotoImage-
       Format structure contains the following fields:
	      typedef struct Tk_PhotoImageFormat {
		char *name;
		Tk_ImageFileMatchProc *fileMatchProc;
		Tk_ImageStringMatchProc *stringMatchProc;
		Tk_ImageFileReadProc *fileReadProc;
		Tk_ImageStringReadProc *stringReadProc;
		Tk_ImageFileWriteProc *fileWriteProc;
		Tk_ImageStringWriteProc *stringWriteProc;
	      } Tk_PhotoImageFormat;

       The handler need not provide implementations  of	 all  six  procedures.
       For  example,  the procedures that handle string data would not be pro-
       vided for a format in which the image data are stored  in  binary,  and
       could  therefore	 contain  null	characters.   If  any procedure is not
       implemented,  the  corresponding	 pointer  in  the  Tk_PhotoImageFormat
       structure  should  be  set  to  NULL.   The  handler  must  provide the
       fileMatchProc procedure if it provides the fileReadProc procedure,  and
       the  stringMatchProc procedure if it provides the stringReadProc proce-
       dure.

PORTABILITY
       In Tk 8.2 and earlier, a different interface  was  used.	 Tk  8.3  will
       still  support  the  old format handlers if the format name is in upper
       case. If you still want to compile old format handlers with Tk8.3,  use
       the  flag -DUSE_OLD_IMAGE. This will restore all function prototypes to
       match the pre-8.3 situation.

NAME
       formatPtr->name provides a name for the image type.  Once Tk_CreatePho-
       toImageFormat returns, this name may be used in the -format photo image
       configuration and subcommand option.  The manual	 page  for  the	 photo
       image  (photo(n))  describes how image file formats are chosen based on
       their names and the value given to the -format option. For  new	format
       handlers, the name should be in lower case. Pre-8.3 format handlers are
       assumed to be in upper case.

FILEMATCHPROC
       formatPtr->fileMatchProc provides the address of a procedure for Tk  to
       call when it is searching for an image file format handler suitable for
       reading data in a given file.  formatPtr->fileMatchProc must match  the
       following prototype:
	      typedef int Tk_ImageFileMatchProc(
		Tcl_Channel chan,
		CONST char *fileName,
		Tcl_Obj *format,
		int *widthPtr,
		int *heightPtr,
		Tcl_Interp *interp);
       The  fileName  argument	is  the	 name of the file containing the image
       data, which is open for reading as chan.	 The format argument  contains
       the  value  given for the -format option, or NULL if the option was not
       specified.  If the data in the file appears to be in  the  format  sup-
       ported  by  this handler, the formatPtr->fileMatchProc procedure should
       store the width and height of the image	in  *widthPtr  and  *heightPtr
       respectively, and return 1.  Otherwise it should return 0.

STRINGMATCHPROC
       formatPtr->stringMatchProc  provides  the address of a procedure for Tk
       to call when it is searching for an image file format handler for suit-
       able  for reading data from a given string.  formatPtr->stringMatchProc
       must match the following prototype:
	      typedef int Tk_ImageStringMatchProc(
		Tcl_Obj *data,
		Tcl_Obj *format,
		int *widthPtr,
		int *heightPtr,
		Tcl_Interp *interp);
       The data argument points to the object containing the image data.   The
       format  argument	 contains  the	value given for the -format option, or
       NULL if the option was not  specified.	If  the	 data  in  the	string
       appears	to  be	in  the	 format	 supported  by	this handler, the for-
       matPtr->stringMatchProc procedure should store the width and height  of
       the image in *widthPtr and *heightPtr respectively, and return 1.  Oth-
       erwise it should return 0.

FILEREADPROC
       formatPtr->fileReadProc provides the address of a procedure for	Tk  to
       call  to	 read  data  from  an  image  file  into  a photo image.  for-
       matPtr->fileReadProc must match the following prototype:
	      typedef int Tk_ImageFileReadProc(
		Tcl_Interp *interp,
		Tcl_Channel chan,
		CONST char *fileName,
		Tcl_Obj *format,
		PhotoHandle imageHandle,
		int destX, int destY,
		int width, int height,
		int srcX, int srcY);
       The interp argument is the interpreter in which the command was invoked
       to  read	 the image; it should be used for reporting errors.  The image
       data is in the file named fileName, which is open for reading as	 chan.
       The format argument contains the value given for the -format option, or
       NULL if the option was not specified.  The image data in the file, or a
       subimage	 of  it,  is to be read into the photo image identified by the
       handle imageHandle.  The subimage of the data in the file is of	dimen-
       sions  width  x	height	and  has  its  top-left	 corner at coordinates
       (srcX,srcY).  It is to be stored in the photo image with	 its  top-left
       corner  at  coordinates (destX,destY) using the Tk_PhotoPutBlock proce-
       dure.  The return value is a standard Tcl return value.

STRINGREADPROC
       formatPtr->stringReadProc provides the address of a procedure for Tk to
       call   to   read	  data	from  a	 string	 into  a  photo	 image.	  for-
       matPtr->stringReadProc must match the following prototype:
	      typedef int Tk_ImageStringReadProc(
		Tcl_Interp *interp,
		Tcl_Obj *data,
		Tcl_Obj *format,
		PhotoHandle imageHandle,
		int destX, int destY,
		int width, int height,
		int srcX, int srcY);
       The interp argument is the interpreter in which the command was invoked
       to  read	 the  image; it should be used for reporting errors.  The data
       argument points to the image data in object form.  The format  argument
       contains	 the value given for the -format option, or NULL if the option
       was not specified.  The image data in the string, or a subimage of  it,
       is  to  be read into the photo image identified by the handle imageHan-
       dle.  The subimage of the data in the string is of dimensions  width  x
       height  and  has its top-left corner at coordinates (srcX,srcY).	 It is
       to be stored in the photo image with its top-left corner at coordinates
       (destX,destY)  using  the Tk_PhotoPutBlock procedure.  The return value
       is a standard Tcl return value.

FILEWRITEPROC
       formatPtr->fileWriteProc provides the address of a procedure for Tk  to
       call   to   write   data	  from	 a   photo  image  to  a  file.	  for-
       matPtr->fileWriteProc must match the following prototype:
	      typedef int Tk_ImageFileWriteProc(
		Tcl_Interp *interp,
		CONST char *fileName,
		Tcl_Obj *format,
		Tk_PhotoImageBlock *blockPtr);
       The interp argument is the interpreter in which the command was invoked
       to  write the image; it should be used for reporting errors.  The image
       data to be written are in memory and are described by  the  Tk_PhotoIm-
       ageBlock	 structure  pointed  to by blockPtr; see the manual page Find-
       Photo(3) for details.  The fileName argument points to the string  giv-
       ing  the name of the file in which to write the image data.  The format
       argument contains the value given for the -format option,  or  NULL  if
       the  option  was	 not  specified.   The format string can contain extra
       characters after the name of the	 format.   If  appropriate,  the  for-
       matPtr->fileWriteProc procedure may interpret these characters to spec-
       ify further details about the image file.  The return value is a	 stan-
       dard Tcl return value.

STRINGWRITEPROC
       formatPtr->stringWriteProc  provides  the address of a procedure for Tk
       to call to translate image data from a photo image into a string.  for-
       matPtr->stringWriteProc must match the following prototype:
	      typedef int Tk_ImageStringWriteProc(
		Tcl_Interp *interp,
		Tcl_Obj *format,
		Tk_PhotoImageBlock *blockPtr);
       The interp argument is the interpreter in which the command was invoked
       to convert the image; it should be  used	 for  reporting	 errors.   The
       image  data  to	be  converted  are  in memory and are described by the
       Tk_PhotoImageBlock structure pointed to by  blockPtr;  see  the	manual
       page  FindPhoto(3)  for details.	 The data for the string should be put
       in the interpreter interp result.  The  format  argument	 contains  the
       value given for the -format option, or NULL if the option was not spec-
       ified.  The format string can contain extra characters after  the  name
       of  the	format.	 If appropriate, the formatPtr->stringWriteProc proce-
       dure may interpret these characters to specify  further	details	 about
       the image file.	The return value is a standard Tcl return value.

SEE ALSO
       Tk_FindPhoto, Tk_PhotoPutBlock

KEYWORDS
       photo image, image file

Tk				      8.3	  Tk_CreatePhotoImageFormat(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OpenServer

List of man pages available for OpenServer

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net