Tk_InitImageArgs man page on Minix

Man page or keyword search:  
man Server   6208 pages
apropos Keyword Search (all sections)
Output format
Minix 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								       │
       Tk_ImageType   *typePtr	    (in)				       │
					      Structure that defines  the  new │
					      type  of image.  Must be static: │
					      a pointer to this	 structure  is │
					      retained by the image code.      │

       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 {
		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.

PORTABILITY
       In Tk 8.2 and earlier, the createProc below had a different  signature.
       If  you	want  to  compile  an image type using the old interface which
       should still run on all Tcl/Tk  versions,  compile  it  with  the  flag
       -DUSE_OLD_IMAGE.	 Further  on, if you are using Stubs, you need to call
       the function Tk_InitImageArgs(interp, argc, &argv) first in  your  cre‐
       ateProc. See below for a description of this function.

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,
		char *name,
		int objc,
		Tcl_Obj *CONST objv[],
		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
       interp->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.

TK_INITIMAGEARGS
       The  function Tk_InitImageArgs converts the arguments of the createProc │
       from objects to strings when necessary. When not using stubs, not using │
       the old interface, or running under an older (pre-8.3) Tk version, this │
       function has no effect. This function makes porting  older  image  han‐ │
       dlers  to  the new interface a lot easier: After running this function, │
       the arguments are guaranteed to be in string format, no matter  how  Tk │
       deliverd them.							       │

SEE ALSO								       │
       Tk_ImageChanged,	 Tk_GetImage,  Tk_FreeImage,  Tk_RedrawImage, Tk_Size‐ │
       OfImage								       │

KEYWORDS								       │
       image manager, image type, instance, master			       │

Tk				      8.3		 Tk_CreateImageType(3)
[top]

List of man pages available for Minix

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