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

       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;
                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
       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 objc,
                Tcl_Obj* CONST objv);
       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 objc and  objv  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
       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
       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(
                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 configured.  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_ConfigureWid­
       get; currently this value  is  always  TK_CONFIG_ARGV_ONLY
       when  Tk  invokes  typePtr->configProc,  but the type man­
       ager'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 fol­
       lowing 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 coordi­
       nate arguments.  For example, if the following widget com­
       mand 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  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
              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.

       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

       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_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_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

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