Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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
       const Tk_PhotoImageFormat *formatPtr (in)	  Structure  that  de-
							  fines	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  im-
       age  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 {
		  const	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  im-
       plemented,  the corresponding pointer in	the Tk_PhotoImageFormat	struc-
       ture should be set to NULL.  The	handler	must provide the fileMatchProc
       procedure  if  it  provides the fileReadProc procedure, and the string-
       MatchProc procedure if it provides the stringReadProc procedure.

   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 im-
       age  (photo(n))	describes  how	image file formats are chosen based on
       their names and the value given to the -format option. The first	 char-
       acter  of  formatPtr-_name  must	not be an uppercase character from the
       ASCII character set (that is, one of the	characters A-Z).   Such	 names
       are used	only for legacy	interface support (see below).

   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 re-
       spectively, 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 ap-
       pears 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 im-
       age data	to be converted	are in memory and are described	by the Tk_Pho-
       toImageBlock  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  specified.
       The  format  string  can	contain	extra characters after the name	of the
       format.	If appropriate,	the formatPtr-_stringWriteProc	procedure  may
       interpret  these	 characters to specify further details about the image
       file.  The return value is a standard Tcl return	value.

LEGACY INTERFACE SUPPORT
       In Tk 8.2 and earlier, the definition of	all the	function pointer types
       stored in fields	of a Tk_PhotoImageFormat struct	were incompatibly dif-
       ferent.	Legacy programs	and libraries dating from those	days may still
       contain code that defines extended Tk photo image formats 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.  Alterna-
       tively, the legacy interfaces are used if the first character  of  for-
       matPtr-_name  is	an uppercase ASCII character (A-Z), and	explicit casts
       are used	to forgive the type mismatch.  For example,
	      static Tk_PhotoImageFormat myFormat = {
		  "MyFormat",
		  (Tk_ImageFileMatchProc *) FileMatch,
		  NULL,
		  (Tk_ImageFileReadProc	*) FileRead,
		  NULL,
		  NULL,
		  NULL
	      };
       would define a minimal Tk_PhotoImageFormat that operates	 provide  only
       file  reading  capability, where	FileMatch and FileRead are written ac-
       cording to the legacy interfaces	of Tk 8.2 or earlier.

       Any stub-enabled	extension providing an extended	photo image format via
       the  legacy  interface  enabled by the USE_OLD_IMAGE macro that is com-
       piled 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	inter-
       faces.  Expect their support to go away in Tk 9.

SEE ALSO
       Tk_FindPhoto, Tk_PhotoPutBlock

KEYWORDS
       photo image, image file

Tk				      8.5	  Tk_CreatePhotoImageFormat(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | LEGACY INTERFACE SUPPORT | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk_CreatePhotoImageFormat.tk86&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help