CrtItemType man page on AIX

Man page or keyword search:  
man Server   4752 pages
apropos Keyword Search (all sections)
Output format
AIX 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  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-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 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  wid‐
       get.   itemPtr  is  a  pointer  to a newly-allocated item of size type‐
       Ptr->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 com‐
       mand was invoked,  canvas is  a	handle	for  the  canvas  widget,  and
       itemPtr	is a pointer to the item being configured.  objc and objv con‐
       tain 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_CON‐
       FIG_ARGV_ONLY when Tk invokes typePtr->configProc, but  the  type  man‐
       ager's createProc procedure will usually invoke configProc with differ‐
       ent 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 mean‐
       ings, and objc and objv describe the coordinate arguments.   For	 exam‐
       ple, 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 iden‐
       tifies  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.  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 doesn't 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 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 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 Postcript 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 success‐
       fully, 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 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 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 don't
       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  dis‐
       play  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_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 selec‐
       tion;  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; 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 pre‐
       vious 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)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server AIX

List of man pages available for AIX

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