Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

CentOS 7.0 - man page for tk_createphotoimageformat (centos section 3)

Tk_CreatePhotoImageFormat(3)	      Tk Library Procedures	     Tk_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  -for-
       mat option to the read and write photo image subcommands.

       An  image file format handler consists of a collection of procedures plus a Tk_PhotoImage-
       Format structure, which contains the name of the image file format  and	pointers  to  six
       procedures  provided  by  the  handler to deal with files and strings in this format.  The
       Tk_PhotoImageFormat 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 pro-
       cedures that handle string data would not be provided 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 fil-
       eReadProc  procedure,  and the stringMatchProc procedure if it provides the stringReadProc
       procedure.

NAME
       formatPtr->name provides a  name  for  the  image  type.   Once	Tk_CreatePhotoImageFormat
       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. 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 sup-
       port (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
       supported  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 suitable 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.  Otherwise 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.  formatPtr->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 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.

STRINGREADPROC
       formatPtr->stringReadProc  provides the address of a procedure for Tk to call to read data
       from a string into a photo image.  formatPtr->stringReadProc must match the following pro-
       totype:
	      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 imageHandle.  The subimage of the
       data in the string is of dimensions width x height and has its top-left corner at  coordi-
       nates  (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.  formatPtr->fileWriteProc must match  the	following  proto-
       type:
	      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_PhotoImageBlock structure pointed to by blockPtr; see the man-
       ual page FindPhoto(3) for details.  The fileName argument points to the string giving  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 specify further  details
       about the image file.  The return value is a standard 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.  formatPtr->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 mem-
       ory  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 inter-
       preter  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  different.   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.  Alternatively,
       the legacy interfaces are used if the first character of formatPtr->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  capa-
       bility,	where FileMatch and FileRead are written according to the legacy interfaces of Tk
       8.2 or earlier.

       Any stub-enabled extension providing an extended photo image format via the legacy  inter-
       face enabled by the USE_OLD_IMAGE macro 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_FindPhoto, Tk_PhotoPutBlock

KEYWORDS
       photo image, image file

Tk					       8.5		     Tk_CreatePhotoImageFormat(3)


All times are GMT -4. The time now is 10:53 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password