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

FreeBSD Manual Pages

  
 
  

home | help
Tk_GetImage(3)		     Tk	Library	Procedures		Tk_GetImage(3)

______________________________________________________________________________

NAME
       Tk_GetImage,  Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage - use	an im-
       age in a	widget

SYNOPSIS
       #include	<tk.h>

       Tk_Image
       Tk_GetImage(interp, tkwin, name,	changeProc, clientData)

       Tk_RedrawImage(image, imageX, imageY, width, height, drawable, drawableX, drawableY)

       Tk_SizeOfImage(image, widthPtr, heightPtr)

       Tk_FreeImage(image)

ARGUMENTS
       Tcl_Interp *interp (in)			     Place to leave error mes-
						     sage.

       Tk_Window tkwin (in)			     Window   in  which	 image
						     will be used.

       const char *name	(in)			     Name of image.

       Tk_ImageChangedProc *changeProc (in)	     Procedure for Tk  to  in-
						     voke  whenever image con-
						     tent or size changes.

       ClientData clientData (in)		     One-word value for	Tk  to
						     pass to changeProc.

       Tk_Image	image (in)			     Token for image instance;
						     must have	been  returned
						     by	 a  previous  call  to
						     Tk_GetImage.

       int imageX (in)				     X-coordinate  of	upper-
						     left  corner of region of
						     image to redisplay	 (mea-
						     sured  in pixels from the
						     image's  upper-left  cor-
						     ner).

       int imageY (in)				     Y-coordinate   of	upper-
						     left corner of region  of
						     image  to redisplay (mea-
						     sured in pixels from  the
						     image's  upper-left  cor-
						     ner).

       int width ((in))				     Width of region of	 image
						     to	redisplay.

       int height ((in))			     Height of region of image
						     to	redisplay.

       Drawable	drawable (in)			     Where to  display	image.
						     Must   either  be	window
						     specified to  Tk_GetImage
						     or	 a  pixmap  compatible
						     with that window.

       int drawableX (in)			     Where to display image in
						     drawable:	this is	the x-
						     coordinate	 in   drawable
						     where x-coordinate	imageX
						     of	the  image  should  be
						     displayed.

       int drawableY (in)			     Where to display image in
						     drawable: this is the  y-
						     coordinate	  in  drawable
						     where y-coordinate	imageY
						     of	 the  image  should be
						     displayed.

       int widthPtr (out)			     Store width of image  (in
						     pixels) here.

       int heightPtr (out)			     Store height of image (in
						     pixels) here.
______________________________________________________________________________

DESCRIPTION
       These procedures	are invoked by widgets that wish  to  display  images.
       Tk_GetImage  is invoked by a widget when	it first decides to display an
       image.  name gives the name of the desired image	and  tkwin  identifies
       the window where	the image will be displayed.  Tk_GetImage looks	up the
       image in	the table of existing images and returns a token for a new in-
       stance  of the image.  If the image does	not exist then Tk_GetImage re-
       turns NULL and leaves an	error message in interp-_result.

       When a widget wishes to actually	display	an image it must  call	Tk_Re-
       drawImage,  identifying the image (image), a region within the image to
       redisplay (imageX, imageY, width, and height), and a place  to  display
       the  image  (drawable,  drawableX, and drawableY).  Tk will then	invoke
       the appropriate image manager, which will display the requested portion
       of the image before returning.

       A  widget  can  find out	the dimensions of an image by calling Tk_Size-
       OfImage:	 the width and height will be stored in	the locations given by
       widthPtr	and heightPtr, respectively.

       When  a	widget	is  finished  with an image (e.g., the widget is being
       deleted or it is	going to use a different image instead of the  current
       one),  it  must	call  Tk_FreeImage to release the image	instance.  The
       widget should never again use the  image	 token	after  passing	it  to
       Tk_FreeImage.   There must be exactly one call to Tk_FreeImage for each
       call to Tk_GetImage.

       If the contents or size of an image changes, then any widgets using the
       image  will  need to find out about the changes so that they can	redis-
       play themselves.	 The changeProc	and clientData arguments to  Tk_GetIm-
       age  are	 used for this purpose.	 changeProc will be called by Tk when-
       ever a change occurs in the image;  it must match the following	proto-
       type:
	      typedef void Tk_ImageChangedProc(
		  ClientData clientData,
		  int x,
		  int y,
		  int width,
		  int height,
		  int imageWidth,
		  int imageHeight);
       The clientData argument to changeProc is	the same as the	clientData ar-
       gument to Tk_GetImage.  It is usually a pointer to  the	widget	record
       for the widget or some other data structure managed by the widget.  The
       arguments x, y, width, and height identify a region  within  the	 image
       that  must  be  redisplayed; they are specified in pixels measured from
       the upper-left corner of	the image.  The	arguments imageWidth  and  im-
       ageHeight give the image's (new)	size.

SEE ALSO
       Tk_CreateImageType

KEYWORDS
       images, redisplay

Tk				      4.0			Tk_GetImage(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO | KEYWORDS

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

home | help