Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

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

Tk_CreateItemType(3)		      Tk Library Procedures		     Tk_CreateItemType(3)

_________________________________________________________________________________________________

NAME
       Tk_CreateItemType, Tk_GetItemTypes - define new kind of canvas item

SYNOPSIS
       #include <tk.h>

       Tk_CreateItemType(typePtr)

       Tk_ItemType *
       Tk_GetItemTypes()

ARGUMENTS
       Tk_ItemType *typePtr (in)	  Structure that defines the new type of canvas item.
_________________________________________________________________

INTRODUCTION
       Tk_CreateItemType  is invoked to define a new kind of canvas item described by the typePtr
       argument.  An item type corresponds to a particular value of the type argument to the cre-
       ate widget command for canvases, and the code that implements a canvas item type is called
       a type manager.	Tk defines several built-in item types, such as rectangle  and	text  and
       image,  but  Tk_CreateItemType  allows  additional item types to be defined.  Once Tk_Cre-
       ateItemType returns, the new item type may be used in new or existing canvas widgets  just
       like the built-in item types.

       Tk_GetItemTypes	returns  a  pointer  to the first in the list of all item types currently
       defined for canvases.  The entries in the list are linked together through  their  nextPtr
       fields, with the end of the list marked by a NULL nextPtr.

       You  may find it easier to understand the rest of this manual entry by looking at the code
       for an existing canvas item type such as  bitmap  (file	tkCanvBmap.c)  or  text  (tkCanv-
       Text.c).  The easiest way to create a new type manager is to copy the code for an existing
       type and modify it for the new type.

       Tk provides a number of utility procedures for the use of canvas type  managers,  such  as
       Tk_CanvasCoords and Tk_CanvasPsColor; these are described in separate manual entries.

DATA STRUCTURES
       A type manager consists of a collection of procedures that provide a standard set of oper-
       ations on items of that type.  The type manager deals with three kinds of data structures.
       The first data structure is a Tk_ItemType; it contains information such as the name of the
       type and pointers to the standard procedures implemented by the type manager:
	      typedef struct Tk_ItemType {
		  char *name;
		  int itemSize;
		  Tk_ItemCreateProc *createProc;
		  Tk_ConfigSpec *configSpecs;
		  Tk_ItemConfigureProc *configProc;
		  Tk_ItemCoordProc *coordProc;
		  Tk_ItemDeleteProc *deleteProc;
		  Tk_ItemDisplayProc *displayProc;
		  int alwaysRedraw;
		  Tk_ItemPointProc *pointProc;
		  Tk_ItemAreaProc *areaProc;
		  Tk_ItemPostscriptProc *postscriptProc;
		  Tk_ItemScaleProc *scaleProc;
		  Tk_ItemTranslateProc *translateProc;
		  Tk_ItemIndexProc *indexProc;
		  Tk_ItemCursorProc *icursorProc;
		  Tk_ItemSelectionProc *selectionProc;
		  Tk_ItemInsertProc *insertProc;
		  Tk_ItemDCharsProc *dCharsProc;
		  Tk_ItemType *nextPtr;
	      } Tk_ItemType;

       The fields of a Tk_ItemType structure are described in more detail later  in  this  manual
       entry.	When  Tk_CreateItemType is called, its typePtr argument must point to a structure
       with all of the fields initialized except nextPtr, which Tk sets to  link  all  the  types
       together  into a list.  The structure must be in permanent memory (either statically allo-
       cated or dynamically allocated but never freed);  Tk retains a pointer to this structure.

       The second data structure manipulated by a type manager is an item record.  For each  item
       in a canvas there exists one item record.  All of the items of a given type generally have
       item records with the same structure, but different types usually have  different  formats
       for  their  item  records.  The first part of each item record is a header with a standard
       structure defined by Tk via the type Tk_Item;  the rest of the item record is  defined  by
       the type manager.  A type manager must define its item records with a Tk_Item as the first
       field.  For example, the item record for bitmap items is defined as follows:
	      typedef struct BitmapItem {
		  Tk_Item header;
		  double x, y;
		  Tk_Anchor anchor;
		  Pixmap bitmap;
		  XColor *fgColor;
		  XColor *bgColor;
		  GC gc;
	      } BitmapItem;
       The header substructure contains information used by Tk to manage the item,  such  as  its
       identifier,  its  tags, its type, and its bounding box.	The fields starting with x belong
       to the type manager: Tk will never read or write them.  The type manager should	not  need
       to  read  or  write any of the fields in the header except for four fields whose names are
       x1, y1, x2, and y2.  These fields give a bounding box for the items using  integer  canvas
       coordinates:   the  item should not cover any pixels with x-coordinate lower than x1 or y-
       coordinate lower than y1, nor should it cover any pixels with x-coordinate greater than or
       equal  to x2 or y-coordinate greater than or equal to y2.  It is up to the type manager to
       keep the bounding box up to date as the item is moved and reconfigured.

       Whenever Tk calls a procedure in a type manager it passes in a pointer to an item  record.
       The  argument is always passed as a pointer to a Tk_Item;  the type manager will typically
       cast this into a pointer to its own specific type, such as BitmapItem.

       The third data structure used by type managers has type Tk_Canvas;  it serves as an opaque
       handle  for  the canvas widget as a whole.  Type managers need not know anything about the
       contents of this structure.  A Tk_Canvas handle is typically passed in to  the  procedures
       of  a  type  manager,  and the type manager can pass the handle back to library procedures
       such as Tk_CanvasTkwin to fetch information about the canvas.

   NAME
       This section and the ones that follow describe each of the fields in a Tk_ItemType  struc-
       ture  in  detail.   The name field provides a string name for the item type.  Once Tk_Cre-
       ateImageType returns, this name may be used in create widget commands to create	items  of
       the  new  type.	If there already existed an item type by this name then the new item type
       replaces the old one.

   ITEMSIZE
       typePtr->itemSize gives the size in bytes of item records  of  this  type,  including  the
       Tk_Item header.	Tk uses this size to allocate memory space for items of the type.  All of
       the item records for a given type must have the same size.  If variable length fields  are
       needed for an item (such as a list of points for a polygon), the type manager can allocate
       a separate object of variable length and keep a pointer to it in the item record.

   CREATEPROC
       typePtr->createProc points to a procedure for Tk to call whenever a new item of this  type
       is created.  typePtr->createProc must match the following prototype:
	      typedef int Tk_ItemCreateProc(
		  Tcl_Interp *interp,
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  int objc,
		  Tcl_Obj* const objv[]);
       The  interp  argument  is  the interpreter in which the canvas's create widget command was
       invoked, and canvas is a handle for the canvas widget.  itemPtr is a pointer to	a  newly-
       allocated  item	of  size typePtr->itemSize.  Tk has already initialized the item's header
       (the first sizeof(Tk_ItemType) bytes).  The objc and objv arguments describe  all  of  the
       arguments  to the create command after the type argument.  For example, in the widget com-
       mand
	      .c create rectangle 10 20 50 50 -fill black
       objc will be 6 and objv[0] will contain the integer object 10.

       createProc should use objc and objv to initialize the  type-specific  parts  of	the  item
       record  and  set  an  initial  value for the bounding box in the item's header.	It should
       return a standard Tcl completion code and leave an error message in interp->result  if  an
       error occurs.  If an error occurs Tk will free the item record, so createProc must be sure
       to leave the item record in a clean state if it returns an error (e.g., it must	free  any
       additional memory that it allocated for the item).

   CONFIGSPECS
       Each type manager must provide a standard table describing its configuration options, in a
       form suitable for use with Tk_ConfigureWidget.  This table will normally be used by  type-
       Ptr->createProc	and  typePtr->configProc, but Tk also uses it directly to retrieve option
       information in the itemcget and itemconfigure widget commands.  typePtr->configSpecs  must
       point  to  the  configuration table for this type.  Note: Tk provides a custom option type
       tk_CanvasTagsOption for implementing the -tags option;  see an existing type  manager  for
       an example of how to use it in configSpecs.

   CONFIGPROC
       typePtr->configProc  is	called by Tk whenever the itemconfigure widget command is invoked
       to change the configuration options for a canvas item.  This procedure must match the fol-
       lowing prototype:
	      typedef int Tk_ItemConfigureProc(
		  Tcl_Interp *interp,
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  int objc,
		  Tcl_Obj* const objv[],
		  int flags);
       The  interp  objument  identifies the interpreter in which the widget command was invoked,
       canvas is a handle for the canvas widget, and itemPtr is a pointer to the item being  con-
       figured.   objc and objv contain the configuration options.  For example, if the following
       command is invoked:
	      .c itemconfigure 2 -fill red -outline black
       objc is 4 and objv contains the string objects -fill through black.  objc will  always  be
       an  even  value.   The	flags argument contains flags to pass to Tk_ConfigureWidget; cur-
       rently this value is always TK_CONFIG_ARGV_ONLY when Tk invokes	typePtr->configProc,  but
       the type manager's createProc procedure will usually invoke configProc with different flag
       values.

       typePtr->configProc returns a standard Tcl completion code and leaves an error message  in
       interp->result  if an error occurs.  It must update the item's bounding box to reflect the
       new configuration options.

   COORDPROC
       typePtr->coordProc is invoked by Tk to implement the coords widget command  for	an  item.
       It must match the following prototype:
	      typedef int Tk_ItemCoordProc(
		  Tcl_Interp *interp,
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  int objc,
		  Tcl_Obj* const objv[]);
       The  arguments  interp,	canvas,  and itemPtr all have the standard meanings, and objc and
       objv describe the coordinate arguments.	For example, if the following widget  command  is
       invoked:
	      .c coords 2 30 90
       objc will be 2 and objv will contain the integer objects 30 and 90.

       The  coordProc procedure should process the new coordinates, update the item appropriately
       (e.g., it must reset the bounding box in the item's header), and  return  a  standard  Tcl
       completion  code.   If  an  error  occurs,  coordProc  must  leave  an  error  message  in
       interp->result.

   DELETEPROC
       typePtr->deleteProc is invoked by Tk to delete an item and free any resources allocated to
       it.  It must match the following prototype:
	      typedef void Tk_ItemDeleteProc(
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  Display *display);
       The  canvas  and  itemPtr arguments have the usual interpretations, and display identifies
       the X display containing the canvas.  deleteProc must free up any resources allocated  for
       the  item,  so  that Tk can free the item record.  deleteProc should not actually free the
       item record;  this will be done by Tk when deleteProc returns.

   DISPLAYPROC AND ALWAYSREDRAW
       typePtr->displayProc is invoked by Tk to redraw an item on the screen.  It must match  the
       following prototype:
	      typedef void Tk_ItemDisplayProc(
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  Display *display,
		  Drawable dst,
		  int x,
		  int y,
		  int width,
		  int height);
       The  canvas  and itemPtr arguments have the usual meaning.  display identifies the display
       containing the canvas, and dst specifies a drawable in which the item should be	rendered;
       typically  this	is an off-screen pixmap, which Tk will copy into the canvas's window once
       all relevant items have been drawn.  x, y, width, and height specify a rectangular  region
       in  canvas  coordinates,  which	is the area to be redrawn; only information that overlaps
       this area needs to be redrawn.  Tk will not call displayProc unless  the  item's  bounding
       box  overlaps  the  redraw  area,  but the type manager may wish to use the redraw area to
       optimize the redisplay of the item.

       Because of scrolling and the use of off-screen pixmaps for double-buffered redisplay,  the
       item's  coordinates  in dst will not necessarily be the same as those in the canvas.  dis-
       playProc should call Tk_CanvasDrawableCoords to transform coordinates from  those  of  the
       canvas to those of dst.

       Normally  an  item's  displayProc is only invoked if the item overlaps the area being dis-
       played.	However, if typePtr->alwaysRedraw has  a  non-zero  value,  then  displayProc  is
       invoked	during	every  redisplay operation, even if the item does not overlap the area of
       redisplay.  alwaysRedraw should normally be set to 0;  it is only  set  to  1  in  special
       cases such as window items that need to be unmapped when they are off-screen.

   POINTPROC
       typePtr->pointProc  is  invoked	by  Tk to find out how close a given point is to a canvas
       item.  Tk uses this procedure for purposes such as locating the item under  the	mouse  or
       finding	the closest item to a given point.  The procedure must match the following proto-
       type:
	      typedef double Tk_ItemPointProc(
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  double *pointPtr);
       canvas and itemPtr have the usual meaning.  pointPtr points to an  array  of  two  numbers
       giving  the x and y coordinates of a point.  pointProc must return a real value giving the
       distance from the point to the item, or 0 if the point lies inside the item.

   AREAPROC
       typePtr->areaProc is invoked by Tk to find out the relationship between an item and a rec-
       tangular area.  It must match the following prototype:
	      typedef int Tk_ItemAreaProc(
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  double *rectPtr);
       canvas  and  itemPtr have the usual meaning.  rectPtr points to an array of four real num-
       bers; the first two give the x and y coordinates of the upper left corner of a  rectangle,
       and  the second two give the x and y coordinates of the lower right corner.  areaProc must
       return -1 if the item lies entirely outside the given area, 0 if it lies partially  inside
       and partially outside the area, and 1 if it lies entirely inside the area.

   POSTSCRIPTPROC
       typePtr->postscriptProc	is  invoked  by  Tk to generate Postscript for an item during the
       postscript widget command.  If the type manager is not capable  of  generating  Postscript
       then  typePtr->postscriptProc should be NULL.  The procedure must match the following pro-
       totype:
	      typedef int Tk_ItemPostscriptProc(
		  Tcl_Interp *interp,
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  int prepass);
       The interp, canvas, and itemPtr arguments all have standard  meanings;	prepass  will  be
       described  below.   If  postscriptProc completes successfully, it should append Postscript
       for the item to the information in interp->result (e.g. by calling  Tcl_AppendResult,  not
       Tcl_SetResult)  and  return  TCL_OK.   If an error occurs, postscriptProc should clear the
       result and replace its contents with an error message;  then it should return TCL_ERROR.

       Tk provides a collection of utility procedures to simplify postscriptProc.   For  example,
       Tk_CanvasPsColor will generate Postscript to set the current color to a given Tk color and
       Tk_CanvasPsFont will set up font information.  When generating Postscript, the  type  man-
       ager  is  free to change the graphics state of the Postscript interpreter, since Tk places
       gsave and grestore commands around the Postscript for the item.	The type manager can  use
       canvas  x coordinates directly in its Postscript, but it must call Tk_CanvasPsY to convert
       y coordinates from the space of the canvas (where the origin is at the upper left) to  the
       space of Postscript (where the origin is at the lower left).

       In  order to generate Postscript that complies with the Adobe Document Structuring Conven-
       tions, Tk actually generates Postscript in two passes.  It calls each  item's  postscript-
       Proc  in  each  pass.   The  only purpose of the first pass is to collect font information
       (which is done by Tk_CanvasPsFont);  the actual Postscript  is  discarded.   Tk	sets  the
       prepass	argument  to postscriptProc to 1 during the first pass;  the type manager can use
       prepass to skip all Postscript generation except for calls to Tk_CanvasPsFont.  During the
       second pass prepass will be 0, so the type manager must generate complete Postscript.

   SCALEPROC
       typePtr->scaleProc  is invoked by Tk to rescale a canvas item during the scale widget com-
       mand.  The procedure must match the following prototype:
	      typedef void Tk_ItemScaleProc(
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  double originX,
		  double originY,
		  double scaleX,
		  double scaleY);
       The canvas and itemPtr arguments have the usual meaning.  originX and originY  specify  an
       origin  relative to which the item is to be scaled, and scaleX and scaleY give the x and y
       scale factors.  The item should adjust its coordinates so that a point in  the  item  that
       used to have coordinates x and y will have new coordinates x' and y', where
	      x' = originX  + scaleX*(x-originX)
	      y' = originY + scaleY*(y-originY)
       scaleProc must also update the bounding box in the item's header.

   TRANSLATEPROC
       typePtr->translateProc  is invoked by Tk to translate a canvas item during the move widget
       command.  The procedure must match the following prototype:
	      typedef void Tk_ItemTranslateProc(
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  double deltaX,
		  double deltaY);
       The canvas and itemPtr arguments have the usual meaning, and deltaX and	deltaY	give  the
       amounts that should be added to each x and y coordinate within the item.  The type manager
       should adjust the item's coordinates and update the bounding box in the item's header.

   INDEXPROC
       typePtr->indexProc is invoked by Tk to translate  a  string  index  specification  into	a
       numerical  index,  for  example	during the index widget command.  It is only relevant for
       item types that support indexable text; typePtr->indexProc may be specified  as	NULL  for
       non-textual item types.	The procedure must match the following prototype:
	      typedef int Tk_ItemIndexProc(
		  Tcl_Interp *interp,
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  char indexString,
		  int *indexPtr);
       The  interp,  canvas,  and itemPtr arguments all have the usual meaning.  indexString con-
       tains a textual description of an index, and indexPtr points  to  an  integer  value  that
       should  be  filled in with a numerical index.  It is up to the type manager to decide what
       forms of index are supported (e.g., numbers, insert,  sel.first,  end,  etc.).	indexProc
       should return a Tcl completion code and set interp->result in the event of an error.

   ICURSORPROC
       typePtr->icursorProc  is  invoked by Tk during the icursor widget command to set the posi-
       tion of the insertion cursor in a textual item.	It is only relevant for item  types  that
       support	an insertion cursor; typePtr->icursorProc may be specified as NULL for item types
       that do not support an insertion cursor.  The procedure must match  the	following  proto-
       type:
	      typedef void Tk_ItemCursorProc(
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  int index);
       canvas and itemPtr have the usual meanings, and index is an index into the item's text, as
       returned by a previous call to typePtr->insertProc.  The type manager should position  the
       insertion  cursor in the item just before the character given by index.	Whether or not to
       actually display the insertion cursor is  determined  by  other	information  provided  by
       Tk_CanvasGetTextInfo.

   SELECTIONPROC
       typePtr->selectionProc  is invoked by Tk during selection retrievals;  it must return part
       or all of the selected text in the item (if any).  It is only relevant for item types that
       support	text; typePtr->selectionProc may be specified as NULL for non-textual item types.
       The procedure must match the following prototype:
	      typedef int Tk_ItemSelectionProc(
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  int offset,
		  char *buffer,
		  int maxBytes);
       canvas and itemPtr have the usual meanings.  offset is an offset in bytes into the  selec-
       tion where 0 refers to the first byte of the selection;	it identifies the first character
       that is to be returned in this call.  buffer points to an area of memory in which to store
       the requested bytes, and maxBytes specifies the maximum number of bytes to return.  selec-
       tionProc should extract up to maxBytes characters from the  selection  and  copy  them  to
       maxBytes;   it  should return a count of the number of bytes actually copied, which may be
       less than maxBytes if there are not offset+maxBytes bytes in the selection.

   INSERTPROC
       typePtr->insertProc is invoked by Tk during the insert widget command to insert	new  text
       into  a	canvas	item.	It  is	only  relevant	for  item  types that support text; type-
       Ptr->insertProc may be specified as NULL for non-textual item types.  The  procedure  must
       match the following prototype:
	      typedef void Tk_ItemInsertProc(
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  int index,
		  char *string);
       canvas  and  itemPtr  have the usual meanings.  index is an index into the item's text, as
       returned by a previous call to typePtr->insertProc, and string contains new text to insert
       just  before  the  character  given by index.  The type manager should insert the text and
       recompute the bounding box in the item's header.

   DCHARSPROC
       typePtr->dCharsProc is invoked by Tk during the dchars widget command to delete a range of
       text  from  a  canvas  item.   It is only relevant for item types that support text; type-
       Ptr->dCharsProc may be specified as NULL for non-textual item types.  The  procedure  must
       match the following prototype:
	      typedef void Tk_ItemDCharsProc(
		  Tk_Canvas canvas,
		  Tk_Item *itemPtr,
		  int first,
		  int last);
       canvas  and itemPtr have the usual meanings.  first and last give the indices of the first
       and last bytes to be deleted, as returned by previous calls  to	typePtr->indexProc.   The
       type  manager  should  delete  the specified characters and update the bounding box in the
       item's header.

SEE ALSO
       Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin

KEYWORDS
       canvas, focus, item type, selection, type manager

Tk					       4.0			     Tk_CreateItemType(3)


All times are GMT -4. The time now is 01:38 AM.

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