Tk_CreateImageType man page on OpenMandriva

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

Tk_CreateImageType(3)	     Tk Library Procedures	 Tk_CreateImageType(3)

______________________________________________________________________________

NAME
       Tk_CreateImageType,  Tk_GetImageMasterData,  Tk_InitImageArgs  - define
       new kind of image

SYNOPSIS
       #include <tk.h>

       Tk_CreateImageType(typePtr)

       ClientData
       Tk_GetImageMasterData(interp, name, typePtrPtr)

       Tk_InitImageArgs(interp, argc, argvPtr)

ARGUMENTS
       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
_________________________________________________________________

DESCRIPTION
       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_CreateIm‐
       ageType.	  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	proce‐
       dures 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 master;  it contains overall information about a par‐
       ticular image, such as the values of the configuration  options	speci‐
       fied  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	simul‐
       taneously  in multiple widgets, or even multiple times in the same wid‐
       get.  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.

   NAME
       typePtr->name  provides	a  name for the image type.  Once Tk_CreateIm‐
       ageType returns, this name may be used in image create commands to cre‐
       ate  images of the new type.  If there already existed an image type by
       this name then the new image type replaces the old one.

   CREATEPROC
       typePtr->createProc provides the address of a procedure for Tk to  call
       whenever	 image	create	is invoked to create an image of the new type.
       typePtr->createProc must match the following prototype:
	      typedef int Tk_ImageCreateProc(
		      Tcl_Interp *interp,
		      const char *name,
		      int objc,
		      Tcl_Obj *const objv[],
		      const Tk_ImageType *typePtr,
		      Tk_ImageMaster master,
		      ClientData *masterDataPtr);
       The interp argument is the interpreter in which the image  command  was
       invoked, and name is the name for the new image, which was either spec‐
       ified explicitly in the image command or generated automatically by the
       image command.  The objc and objv arguments describe all the configura‐
       tion options for the new image (everything after the name  argument  to
       image).	The master argument is a token that refers to Tk's information
       about this image;  the image manager must return this token to Tk  when
       invoking	 the  Tk_ImageChanged  procedure.   Typically  createProc will
       parse objc and objv and create an image master data structure  for  the
       new  image.   createProc may store an arbitrary one-word value at *mas‐
       terDataPtr, which will be passed back to the image manager  when	 other
       callbacks  are invoked.	Typically the value is a pointer to the master
       data structure for the image.

       If createProc encounters an error, it should leave an error message  in
       the  interpreter	 result	 and  return  TCL_ERROR;   otherwise it should
       return TCL_OK.

       createProc should call Tk_ImageChanged in order to set the size of  the
       image and request an initial redisplay.

   GETPROC
       typePtr->getProc	 is  invoked by Tk whenever a widget calls Tk_GetImage
       to use a particular image.  This procedure  must	 match	the  following
       prototype:
	      typedef ClientData Tk_ImageGetProc(
		      Tk_Window tkwin,
		      ClientData masterData);
       The  tkwin  argument  identifies	 the window in which the image will be
       used and masterData is the value returned by createProc when the	 image
       master  was  created.  getProc will usually create a data structure for
       the new instance, including such things as the resources needed to dis‐
       play  the  image in the given window.  getProc returns a one-word token
       for the instance, which is typically the address of the	instance  data
       structure.   Tk	will  pass  this  value back to the image manager when
       invoking its displayProc and freeProc procedures.

   DISPLAYPROC
       typePtr->displayProc is invoked by Tk whenever an  image	 needs	to  be
       displayed  (i.e., whenever a widget calls Tk_RedrawImage).  displayProc
       must match the following prototype:
	      typedef void Tk_ImageDisplayProc(
		      ClientData instanceData,
		      Display *display,
		      Drawable drawable,
		      int imageX,
		      int imageY,
		      int width,
		      int height,
		      int drawableX,
		      int drawableY);
       The instanceData will be the same as the value returned by getProc when
       the  instance was created.  display and drawable indicate where to dis‐
       play the image;	drawable may be a pixmap rather than the window speci‐
       fied  to	 getProc (this is usually the case, since most widgets double-
       buffer their  redisplay	to  get	 smoother  visual  effects).   imageX,
       imageY, width, and height identify the region of the image that must be
       redisplayed.  This region will always be within the size of  the	 image
       as specified in the most recent call to Tk_ImageChanged.	 drawableX and
       drawableY indicate where in drawable the	 image	should	be  displayed;
       displayProc  should display the given region of the image so that point
       (imageX, imageY) in the image  appears  at  (drawableX,	drawableY)  in
       drawable.

   FREEPROC
       typePtr->freeProc  contains  the	 address  of  a procedure that Tk will
       invoke when an image instance is released (i.e., when  Tk_FreeImage  is
       invoked).   This can happen, for example, when a widget is deleted or a
       image item in a canvas is deleted, or when the  image  displayed	 in  a
       widget  or  canvas  item is changed.  freeProc must match the following
       prototype:
	      typedef void Tk_ImageFreeProc(
		      ClientData instanceData,
		      Display *display);
       The instanceData will be the same as the value returned by getProc when
       the  instance  was  created,  and display is the display containing the
       window for the instance.	 freeProc should release any resources associ‐
       ated  with  the	image  instance, since the instance will never be used
       again.

   DELETEPROC
       typePtr->deleteProc is a procedure that Tk invokes  when	 an  image  is
       being  deleted (i.e. when the image delete command is invoked).	Before
       invoking deleteProc Tk will invoke freeProc for	each  of  the  image's
       instances.  deleteProc must match the following prototype:
	      typedef void Tk_ImageDeleteProc(
		      ClientData masterData);
       The  masterData	argument will be the same as the value stored in *mas‐
       terDataPtr by createProc when the image was created.  deleteProc should
       release any resources associated with the image.

TK_GETIMAGEMASTERDATA
       The procedure Tk_GetImageMasterData may be invoked to retrieve informa‐
       tion about an image.  For example, an image manager can use this proce‐
       dure  to locate its image master 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
       master  data structure).	 If no such image exists then NULL is returned
       and NULL is stored at *typePtrPtr.

LEGACY INTERFACE SUPPORT
       In Tk 8.2 and earlier, the definition of Tk_ImageCreateProc was	incom‐
       patibly different, with the following prototype:
	      typedef int Tk_ImageCreateProc(
		      Tcl_Interp *interp,
		      char *name,
		      int argc,
		      char **argv,
		      Tk_ImageType *typePtr,
		      Tk_ImageMaster master,
		      ClientData *masterDataPtr);
       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.

       When the USE_OLD_IMAGE legacy support is enabled, you may see the  rou‐
       tine 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 rou‐
       tine, 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 gen‐
       erate 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_ImageChanged, Tk_GetImage,  Tk_FreeImage,  Tk_RedrawImage,  Tk_Size‐
       OfImage

KEYWORDS
       image manager, image type, instance, master

Tk				      8.5		 Tk_CreateImageType(3)
[top]

List of man pages available for OpenMandriva

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