CrtItemType man page on BSDOS

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



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  can-
       vas  item described by the typePtr argument.  An item type
       corresponds to a particular value of the type argument  to
       the  create 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  addi-
       tional  item  types to be defined.  Once Tk_CreateItemType
       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 man-
       ual entry by looking at the code for  an	 existing  canvas
       item  type  such	 as  bitmap  (file  tkCanvBmap.c) or text
       (tkCanvText.c).	The easiest way to create a new type man-
       ager  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_Can-
       vasPsColor;  these  are	described  in	separate   manual
       entries.

DATA STRUCTURES
       A type manager consists of a collection of procedures that

Tk			       4.0				1

Tk_CreateItemType(3)  Tk Library Procedures  Tk_CreateItemType(3)

       provide a standard set of  operations  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_CreateIt-
       emType  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  allocated  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  gener-
       ally  have  item records with the same structure, but dif-
       ferent 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;

Tk			       4.0				2

Tk_CreateItemType(3)  Tk Library Procedures  Tk_CreateItemType(3)

		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 coordi-
       nates:  the item should not cover any pixels with  x-coor-
       dinate  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 man-
       ager, and the type manager can pass  the	 handle	 back  to
       library	procedures such as Tk_CanvasTkwin to fetch infor-
       mation about the canvas.

NAME
       This section and the ones that follow describe each of the
       fields  in  a  Tk_ItemType  structure in detail.	 The name
       field provides a string name  for  the  item  type.   Once
       Tk_CreateImageType  returns, this name may be used in cre-
       ate 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.

Tk			       4.0				3

Tk_CreateItemType(3)  Tk Library Procedures  Tk_CreateItemType(3)

CREATEPROC
       typePtr->createProc  points  to a procedure for Tk to call
       whenever a new  item  of	 this  type  is	 created.   type-
       Ptr->createProc must match the following prototype:
	      typedef int Tk_ItemCreateProc(
		Tcl_Interp *interp,
		Tk_Canvas canvas,
		Tk_Item *itemPtr,
		int argc,
		char **argv);
       The  interp  argument is the interpreter in which the can-
       vas'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 argc and  argv	arguments
       describe	 all of the arguments to the create command after
       the type argument.  For example, in the widget command
	      .c create rectangle 10 20 50 50 -fill black
       argc will be 6 and argv[0] will contain the string 10.

       createProc should use argc  and	argv  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
       typePtr->createProc  and	 typePtr->configProc, but Tk also
       uses it directly to retrieve  option  information  in  the
       itemcget and itemconfigure widget commands.  typePtr->con-
       figSpecs must point to the configuration	 table	for  this
       type.   Note:  Tk  provides  a  custom option type tk_Can-
       vasTagsOption 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	 itemcon-
       figure  widget command is invoked to change the configura-
       tion options for a canvas item.	This procedure must match
       the following prototype:
	      typedef int Tk_ItemConfigureProc(
		Tcl_Interp *interp,
		Tk_Canvas canvas,

Tk			       4.0				4

Tk_CreateItemType(3)  Tk Library Procedures  Tk_CreateItemType(3)

		Tk_Item *itemPtr,
		int argc,
		char **argv,
		int flags);
       The  interp  argument  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 configured.  argc and argv contain the configuration
       options.	   For	example,  if  the  following  command  is
       invoked:
	      .c itemconfigure 2 -fill red -outline black
       argc is 4 and argv  contains  the  strings  -fill  through
       black.	argc  will  always  be an even value.  The  flags
       argument contains flags	to  pass  to  Tk_ConfigureWidget;
       currently this value is always TK_CONFIG_ARGV_ONLY when Tk
       invokes typePtr->configProc, but the type  manager's  cre-
       ateProc procedure will usually invoke configProc with dif-
       ferent 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 fol-
       lowing prototype:
	      typedef int Tk_ItemCoordProc(
		Tcl_Interp *interp,
		Tk_Canvas canvas,
		Tk_Item *itemPtr,
		int argc,
		char **argv);
       The  arguments  interp,	canvas,	 and itemPtr all have the
       standard meanings, and argc and argv describe the  coordi-
       nate arguments.	For example, if the following widget com-
       mand is invoked:
	      .c coords 2 30 90
       argc will be 2 and argv will contain the string values  30
       and 90.

       The  coordProc  procedure  should  process the new coordi-
       nates, update the item appropriately (e.g., it must  reset
       the bounding box in the item's header), and return a stan-
       dard 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:

Tk			       4.0				5

Tk_CreateItemType(3)  Tk Library Procedures  Tk_CreateItemType(3)

	      typedef void Tk_ItemDeleteProc(
		Tk_Canvas canvas,
		Tk_Item *itemPtr,
		Display *display);
       The  canvas and itemPtr arguments have the usual interpre-
       tations, and display identifies the X  display  containing
       the  canvas.   deleteProc must free up any resources allo-
       cated 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 ren-
       dered; 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  rect-
       angular 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.
       displayProc  should call Tk_CanvasDrawableCoords to trans-
       form 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	 displayed.   However,	if  type-
       Ptr->alwaysRedraw  has  a non-zero value, then displayProc
       is invoked during every redisplay operation, even  if  the
       item  doesn't overlap the area of redisplay.  alwaysRedraw
       should normally be set to 0;  it is only set to 1 in  spe-
       cial  cases  such as window items that need to be unmapped
       when they are off-screen.

Tk			       4.0				6

Tk_CreateItemType(3)  Tk Library Procedures  Tk_CreateItemType(3)

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 prototype:
	      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 coor-
       dinates 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  rela-
       tionship	 between an item and a rectangular 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 numbers; 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 par-
       tially inside and partially outside the area, and 1 if  it
       lies entirely inside the area.

POSTSCRIPTPROC
       typePtr->postscriptProc	is  invoked  by	 Tk  to	 generate
       Postcript for an item during the	 postscript  widget  com-
       mand.   If  the	type manager is not capable of generating
       Postscript then typePtr->postscriptProc	should	be  NULL.
       The procedure must match the following prototype:
	      typedef int Tk_ItemPostscriptProc(
		Tcl_Interp *interp,
		Tk_Canvas canvas,
		Tk_Item *itemPtr,
		int prepass);
       The  interp,  canvas, and itemPtr arguments all have stan-
       dard 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

Tk			       4.0				7

Tk_CreateItemType(3)  Tk Library Procedures  Tk_CreateItemType(3)

       TCL_ERROR.

       Tk provides a collection of utility procedures to simplify
       postscriptProc.	For example, Tk_CanvasPsColor will gener-
       ate  Postscript	to  set	 the  current color to a given Tk
       color and Tk_CanvasPsFont will set  up  font  information.
       When  generating	 Postscript,  the type manager 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 Conventions, Tk actually gener-
       ates  Postscript	 in  two  passes.   It	calls each item's
       postscriptProc in each pass.   The  only	 purpose  of  the
       first  pass  is to collect font information (which is done
       by Tk_CanvPsFont);  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_CanvasPs-
       Font.  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 command.  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  coordi-
       nates  so that a point in the item that used to have coor-
       dinates 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

Tk			       4.0				8

Tk_CreateItemType(3)  Tk Library Procedures  Tk_CreateItemType(3)

       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 contains 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 sup-
       ported (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 position 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 don't support  an
       insertion  cursor.  The procedure must match the following
       prototype:
	      typedef void Tk_ItemIndexProc(
		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

Tk			       4.0				9

Tk_CreateItemType(3)  Tk Library Procedures  Tk_CreateItemType(3)

       display the insertion cursor is determined by other infor-
       mation 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  proce-
       dure 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 selection 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.  selectionProc 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
       aren't 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 proto-
       type:
	      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

Tk			       4.0			       10

Tk_CreateItemType(3)  Tk Library Procedures  Tk_CreateItemType(3)

       text; typePtr->dCharsProc may be	 specified  as	NULL  for
       non-textual item types.	The procedure must match the fol-
       lowing 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->index-
       Proc.   The type manager should delete the specified char-
       acters 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			       11

[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server BSDOS

List of man pages available for BSDOS

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