manpagez: man pages & more
man Tk_CreateItemType(3)
Home | html | info | man
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

       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  par-
       ticular  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 rectan-
       gle and text and image, but Tk_CreateItemType  allows  additional  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 manual  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 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  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_CreateItemType  is  called,  its
       typePtr  argument must point to a structure with all of the fields ini-
       tialized except nextPtr, which Tk sets to link all the  types  together
       into  a list.  The structure must be in permanent memory (either stati-
       cally 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 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-coordi-
       nate  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 man-
       agers 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  pro-
       cedures 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 structure in detail.  The name field provides a string name
       for  the  item type.  Once Tk_CreateImageType 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 fol-
       lowing 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-allo-
       cated  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 configu-
       ration  options,  in  a  form suitable for use with Tk_ConfigureWidget.
       This table will normally  be  used  by  typePtr->createProc  and  type-
       Ptr->configProc, but Tk also uses it directly to retrieve option infor-
       mation in  the  itemcget  and  itemconfigure  widget  commands.   type-
       Ptr->configSpecs  must  point to the configuration table for this type.
       Note: Tk provides a custom option type tk_CanvasTagsOption  for  imple-
       menting  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 following 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 wid-
       get,  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_ConfigureWidget; currently 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 com-
       mand  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 coordi-
       nate 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  mean-
       ing.   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 win-
       dow 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.  displayProc should call Tk_Canvas-
       DrawableCoords 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 displayed.  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 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 coordi-
       nates of a point.  pointProc must return a real value giving  the  dis-
       tance  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 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 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 prototype: 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  postscript-
       Proc.   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 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  Post-
       script, 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  generates  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_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 command.  The procedure must match  the  following  proto-
       type: 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 fac-
       tors.  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  +  sca-
       leY*(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 dur-
       ing  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  speci-
       fication  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 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 position of the insertion cursor in a textual item.   It  is
       only  relevant  for  item types that support an insertion cursor; type-
       Ptr->icursorProc may be specified as NULL for item types  that  do  not
       support  an  insertion  cursor.  The procedure must match the following
       prototype: 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->selec-
       tionProc may be specified as NULL for non-textual item types.  The pro-
       cedure  must  match  the following prototype: typedef int Tk_ItemSelec-
       tionProc(
           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 charac-
       ters 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; typePtr->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; typePtr->dCharsProc may be  specified  as
       NULL  for non-textual item types.  The procedure must match the follow-
       ing 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(3), Tk_CanvasTextInfo(3), Tk_CanvasTkwin(3)


KEYWORDS

       canvas, focus, item type, selection, type manager



Tk                                    4.0                 Tk_CreateItemType(3)

CrtItemType 8.5.4 - Generated Sat Aug 23 06:28:44 CDT 2008
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.