通讯编程

开发平台：
Visual C++

CrtItemType.3：源码内容
							'"
'" Copyright (c) 1994-1995 Sun Microsystems, Inc.
'"
'" See the file "license.terms" for information on usage and redistribution
'" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'" 
'" RCS: @(#) $Id: CrtItemType.3,v 1.6 2000/07/25 21:14:34 jenglish Exp $
'" 
.so man.macros
.TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CreateItemType, Tk_GetItemTypes - define new kind of canvas item
.SH SYNOPSIS
.nf
fB#include <tk.h>fR
.sp
fBTk_CreateItemTypefR(fItypePtrfR)
.sp
Tk_ItemType *
fBTk_GetItemTypesfR()
.SH ARGUMENTS
.AS Tk_ItemType *typePtr
.AP Tk_ItemType *typePtr in
Structure that defines the new type of canvas item.
.BE
.SH INTRODUCTION
.PP
fBTk_CreateItemTypefR is invoked to define a new kind of canvas item
described by the fItypePtrfR argument.
An item type corresponds to a particular value of the fItypefR
argument to the fBcreatefR widget command for canvases, and
the code that implements a canvas item type is called a fItype managerfR.
Tk defines several built-in item types, such as fBrectanglefR
and fBtextfR and fBimagefR, but fBTk_CreateItemTypefR
allows additional item types to be defined.
Once fBTk_CreateItemTypefR returns, the new item type may be used
in new or existing canvas widgets just like the built-in item
types.
.PP
fBTk_GetItemTypesfR 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
fInextPtrfR fields, with the end of the list marked by a
NULL fInextPtrfR.
.PP
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.
.PP
Tk provides a number of utility procedures for the use of canvas
type managers, such as fBTk_CanvasCoordsfR and fBTk_CanvasPsColorfR;
these are described in separate manual entries.
.SH "DATA STRUCTURES"
.PP
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:
.CS
typedef struct Tk_ItemType {
	char *fInamefR;
	int fIitemSizefR;
	Tk_ItemCreateProc *fIcreateProcfR;
	Tk_ConfigSpec *fIconfigSpecsfR;
	Tk_ItemConfigureProc *fIconfigProcfR;
	Tk_ItemCoordProc *fIcoordProcfR;
	Tk_ItemDeleteProc *fIdeleteProcfR;
	Tk_ItemDisplayProc *fIdisplayProcfR;
	int fIalwaysRedrawfR;
	Tk_ItemPointProc *fIpointProcfR;
	Tk_ItemAreaProc *fIareaProcfR;
	Tk_ItemPostscriptProc *fIpostscriptProcfR;
	Tk_ItemScaleProc *fIscaleProcfR;
	Tk_ItemTranslateProc *fItranslateProcfR;
	Tk_ItemIndexProc *fIindexProcfR;
	Tk_ItemCursorProc *fIicursorProcfR;
	Tk_ItemSelectionProc *fIselectionProcfR;
	Tk_ItemInsertProc *fIinsertProcfR;
	Tk_ItemDCharsProc *fIdCharsProcfR;
	Tk_ItemType *fInextPtrfR;
} Tk_ItemType;
.CE
.PP
The fields of a Tk_ItemType structure are described in more detail
later in this manual entry.
When fBTk_CreateItemTypefR is called, its fItypePtrfR
argument must point to a structure with all of the fields initialized
except fInextPtrfR, 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.
.PP
The second data structure manipulated by a type manager is an
fIitem recordfR.
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:
.CS
typedef struct BitmapItem {
	Tk_Item fIheaderfR;
	double fIxfR, fIyfR;
	Tk_Anchor fIanchorfR;
	Pixmap fIbitmapfR;
	XColor *fIfgColorfR;
	XColor *fIbgColorfR;
	GC fIgcfR;
} BitmapItem;
.CE
The fIheaderfR 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 fIxfR 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 fIx1fR, fIy1fR, fIx2fR, and fIy2fR.
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 fIx1fR or y-coordinate
lower than fIy1fR, nor should it cover any pixels with
x-coordinate greater than or equal to fIx2fR or y-coordinate
greater than or equal to fIy2fR.
It is up to the type manager to keep the bounding box up to
date as the item is moved and reconfigured.
.PP
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.
.PP
The third data structure used by type managers has type
Tk_Canvas;  it serves as an opaque handle for the canvas widget
as a whole.
Type managers need not know anything about the contents of this
structure.
A Tk_Canvas handle is typically passed in to the
procedures of a type manager, and the type manager can pass the
handle back to library procedures such as Tk_CanvasTkwin
to fetch information about the canvas.
.SH NAME
.PP
This section and the ones that follow describe each of the fields
in a Tk_ItemType structure in detail.
The fInamefR field provides a string name for the item type.
Once fBTk_CreateImageTypefR returns, this name may be used
in fBcreatefR 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.
.SH ITEMSIZE
fItypePtr->itemSizefR 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.
.SH CREATEPROC
.PP
fItypePtr->createProcfR points to a procedure for
Tk to call whenever a new item of this type is created.
fItypePtr->createProcfR must match the following prototype:
.CS
typedef int Tk_ItemCreateProc(
	Tcl_Interp *fIinterpfR,
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	int fIobjcfR,
	Tcl_Obj* CONST fIobjvfR);
.CE
The fIinterpfR argument is the interpreter in which the canvas's
fBcreatefR widget command was invoked, and fIcanvasfR is a
handle for the canvas widget.
fIitemPtrfR is a pointer to a newly-allocated item of
size fItypePtr->itemSizefR.
Tk has already initialized the item's header (the first
fBsizeof(Tk_ItemType)fR bytes).
The fIobjcfR and fIobjvfR arguments describe all of the
arguments to the fBcreatefR command after the fItypefR
argument.
For example, in the widget command
.CS
fB&.c create rectangle 10 20 50 50 -fill blackfR
.CE
fIobjcfR will be fB6fR and fIobjvfR[0] will contain the
integer object fB10fR.
.PP
fIcreateProcfR should use fIobjcfR and fIobjvfR 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 fIinterp->resultfR if an error occurs.
If an error occurs Tk will free the item record, so fIcreateProcfR
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).
.SH CONFIGSPECS
.PP
Each type manager must provide a standard table describing its
configuration options, in a form suitable for use with
fBTk_ConfigureWidgetfR.
This table will normally be used by fItypePtr->createProcfR
and fItypePtr->configProcfR, but Tk also uses it directly
to retrieve option information in the fBitemcgetfR and
fBitemconfigurefR widget commands.
fItypePtr->configSpecsfR must point to the configuration table
for this type.
Note: Tk provides a custom option type fBtk_CanvasTagsOptionfR
for implementing the fB-tagsfR option;  see an existing type
manager for an example of how to use it in fIconfigSpecsfR.
.SH CONFIGPROC
.PP
fItypePtr->configProcfR is called by Tk whenever the
fBitemconfigurefR widget command is invoked to change the
configuration options for a canvas item.
This procedure must match the following prototype:
.CS
typedef int Tk_ItemConfigureProc(
	Tcl_Interp *fIinterpfR,
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	int fIobjcfR,
	Tcl_Obj* CONST fIobjvfR,
	int fIflagsfR);
.CE
The fIinterpfR objument identifies the interpreter in which the
widget command was invoked,  fIcanvasfR is a handle for the canvas
widget, and fIitemPtrfR is a pointer to the item being configured.
fIobjcfR and fIobjvfR contain the configuration options.  For
example, if the following command is invoked:
.CS
fB&.c itemconfigure 2 -fill red -outline blackfR
.CE
fIobjcfR is fB4fR and fIobjvfR contains the string objects fB-fillfR
through fBblackfR.
fIobjcfR will always be an even value.
The  fIflagsfR argument contains flags to pass to fBTk_ConfigureWidgetfR;
currently this value is always TK_CONFIG_ARGV_ONLY when Tk
invokes fItypePtr->configProcfR, but the type manager's fIcreateProcfR
procedure will usually invoke fIconfigProcfR with different flag values.
.PP
fItypePtr->configProcfR returns a standard Tcl completion code and
leaves an error message in fIinterp->resultfR if an error occurs.
It must update the item's bounding box to reflect the new configuration
options.
.SH COORDPROC
.PP
fItypePtr->coordProcfR is invoked by Tk to implement the fBcoordsfR
widget command for an item.
It must match the following prototype:
.CS
typedef int Tk_ItemCoordProc(
	Tcl_Interp *fIinterpfR,
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	int fIobjcfR,
	Tcl_Obj* CONST fIobjvfR);
.CE
The arguments fIinterpfR, fIcanvasfR, and fIitemPtrfR
all have the standard meanings, and fIobjcfR and fIobjvfR
describe the coordinate arguments.
For example, if the following widget command is invoked:
.CS
fB&.c coords 2 30 90fR
.CE
fIobjcfR will be fB2fR and fBobjvfR will contain the integer objects
fB30fR and fB90fR.
.PP
The fIcoordProcfR 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, fIcoordProcfR must leave an error message in
fIinterp->resultfR.
.SH DELETEPROC
.PP
fItypePtr->deleteProcfR is invoked by Tk to delete an item
and free any resources allocated to it.
It must match the following prototype:
.CS
typedef void Tk_ItemDeleteProc(
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	Display *fIdisplayfR);
.CE
The fIcanvasfR and fIitemPtrfR arguments have the usual
interpretations, and fIdisplayfR identifies the X display containing
the canvas.
fIdeleteProcfR must free up any resources allocated for the item,
so that Tk can free the item record.
fIdeleteProcfR should not actually free the item record;  this will
be done by Tk when fIdeleteProcfR returns.
.SH "DISPLAYPROC AND ALWAYSREDRAW"
.PP
fItypePtr->displayProcfR is invoked by Tk to redraw an item
on the screen.
It must match the following prototype:
.CS
typedef void Tk_ItemDisplayProc(
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	Display *fIdisplayfR,
	Drawable fIdstfR,
	int fIxfR,
	int fIyfR,
	int fIwidthfR,
	int fIheightfR);
.CE
The fIcanvasfR and fIitemPtrfR arguments have the usual meaning.
fIdisplayfR identifies the display containing the canvas, and
fIdstfR 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.
fIxfR, fIyfR, fIwidthfR, and fIheightfR 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 fIdisplayProcfR 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.
.PP
Because of scrolling and the use of off-screen pixmaps for
double-buffered redisplay, the item's coordinates in fIdstfR
will not necessarily be the same as those in the canvas.
fIdisplayProcfR should call fBTk_CanvasDrawableCoordsfR
to transform coordinates from those of the canvas to those
of fIdstfR.
.PP
Normally an item's fIdisplayProcfR is only invoked if the item
overlaps the area being displayed.
However, if fItypePtr->alwaysRedrawfR has a non-zero value, then
fIdisplayProcfR is invoked during every redisplay operation,
even if the item doesn't overlap the area of redisplay.
fIalwaysRedrawfR 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.
.SH POINTPROC
.PP
fItypePtr->pointProcfR 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:
.CS
typedef double Tk_ItemPointProc(
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	double *fIpointPtrfR);
.CE
fIcanvasfR and fIitemPtrfR have the usual meaning.
fIpointPtrfR points to an array of two numbers giving
the x and y coordinates of a point.
fIpointProcfR must return a real value giving the distance
from the point to the item, or 0 if the point lies inside
the item.
.SH AREAPROC
.PP
fItypePtr->areaProcfR is invoked by Tk to find out the relationship
between an item and a rectangular area.
It must match the following prototype:
.CS
typedef int Tk_ItemAreaProc(
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	double *fIrectPtrfR);
.CE
fIcanvasfR and fIitemPtrfR have the usual meaning.
fIrectPtrfR 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.
fIareaProcfR 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.
.SH POSTSCRIPTPROC
.PP
fItypePtr->postscriptProcfR is invoked by Tk to generate
Postcript for an item during the fBpostscriptfR widget command.
If the type manager is not capable of generating Postscript then
fItypePtr->postscriptProcfR should be NULL.
The procedure must match the following prototype:
.CS
typedef int Tk_ItemPostscriptProc(
	Tcl_Interp *fIinterpfR,
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	int fIprepassfR);
.CE
The fIinterpfR, fIcanvasfR, and fIitemPtrfR arguments all have
standard meanings;  fIprepassfR will be described below.
If fIpostscriptProcfR completes successfully, it should append
Postscript for the item to the information in fIinterp->resultfR
(e.g. by calling fBTcl_AppendResultfR, not fBTcl_SetResultfR)
and return TCL_OK.
If an error occurs, fIpostscriptProcfR should clear the result
and replace its contents with an error message;  then it should
return TCL_ERROR.
.PP
Tk provides a collection of utility procedures to simplify
fIpostscriptProcfR.
For example, fBTk_CanvasPsColorfR will generate Postscript to set
the current color to a given Tk color and fBTk_CanvasPsFontfR 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
fBgsavefR and fBgrestorefR commands around the Postscript for
the item.
The type manager can use canvas x coordinates directly in its Postscript,
but it must call fBTk_CanvasPsYfR 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).
.PP
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 fIpostscriptProcfR in each pass.
The only purpose of the first pass is to collect font information
(which is done by fBTk_CanvasPsFontfR);  the actual Postscript is
discarded.
Tk sets the fIprepassfR argument to fIpostscriptProcfR to 1
during the first pass;  the type manager can use fIprepassfR to skip
all Postscript generation except for calls to fBTk_CanvasPsFontfR.
During the second pass fIprepassfR will be 0, so the type manager
must generate complete Postscript.
.SH SCALEPROC
fItypePtr->scaleProcfR is invoked by Tk to rescale a canvas item
during the fBscalefR widget command.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemScaleProc(
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	double fIoriginXfR,
	double fIoriginYfR,
	double fIscaleXfR,
	double fIscaleYfR);
.CE
The fIcanvasfR and fIitemPtrfR arguments have the usual meaning.
fIoriginXfR and fIoriginYfR specify an origin relative to which
the item is to be scaled, and fIscaleXfR and fIscaleYfR 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 fIxfR and fIyfR will have new
coordinates fIx'fR and fIy'fR, where
.CS
fIx' = originX  + scaleX*(x-originX)
y' = originY + scaleY*(y-originY)fR
.CE
fIscaleProcfR must also update the bounding box in the item's
header.
.SH TRANSLATEPROC
fItypePtr->translateProcfR is invoked by Tk to translate a canvas item
during the fBmovefR widget command.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemTranslateProc(
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	double fIdeltaXfR,
	double fIdeltaYfR);
.CE
The fIcanvasfR and fIitemPtrfR arguments have the usual meaning,
and fIdeltaXfR and fIdeltaYfR 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.
.SH INDEXPROC
fItypePtr->indexProcfR is invoked by Tk to translate a string
index specification into a numerical index, for example during the
fBindexfR widget command.
It is only relevant for item types that support indexable text;
fItypePtr->indexProcfR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef int Tk_ItemIndexProc(
	Tcl_Interp *fIinterpfR,
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	char fIindexStringfR,
	int *fIindexPtrfR);
.CE
The fIinterpfR, fIcanvasfR, and fIitemPtrfR arguments all
have the usual meaning.
fIindexStringfR contains a textual description of an index,
and fIindexPtrfR 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, fBinsertfR,  fBsel.firstfR,
fBendfR, etc.).
fIindexProcfR should return a Tcl completion code and set
fIinterp->resultfR in the event of an error.
.SH ICURSORPROC
.PP
fItypePtr->icursorProcfR is invoked by Tk during
the fBicursorfR 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;
fItypePtr->icursorProcfR may be specified as NULL for item types
that don't support an insertion cursor.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemCursorProc(
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	int fIindexfR);
.CE
fIcanvasfR and fIitemPtrfR have the usual meanings, and
fIindexfR is an index into the item's text, as returned by a
previous call to fItypePtr->insertProcfR.
The type manager should position the insertion cursor in the
item just before the character given by fIindexfR.
Whether or not to actually display the insertion cursor is
determined by other information provided by fBTk_CanvasGetTextInfofR.
.SH SELECTIONPROC
.PP
fItypePtr->selectionProcfR 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;
fItypePtr->selectionProcfR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef int Tk_ItemSelectionProc(
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	int fIoffsetfR,
	char *fIbufferfR,
	int fImaxBytesfR);
.CE
fIcanvasfR and fIitemPtrfR have the usual meanings.
fIoffsetfR 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.
fIbufferfR points to an area of memory in which to store the
requested bytes, and fImaxBytesfR specifies the maximum number
of bytes to return.
fIselectionProcfR should extract up to fImaxBytesfR characters
from the selection and copy them to fImaxBytesfR;  it should
return a count of the number of bytes actually copied, which may
be less than fImaxBytesfR if there aren't fIoffset+maxBytesfR bytes
in the selection.
.SH INSERTPROC
.PP
fItypePtr->insertProcfR is invoked by Tk during
the fBinsertfR widget command to insert new text into a
canvas item.
It is only relevant for item types that support text;
fItypePtr->insertProcfR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemInsertProc(
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	int fIindexfR,
	char *fIstringfR);
.CE
fIcanvasfR and fIitemPtrfR have the usual meanings.
fIindexfR is an index into the item's text, as returned by a
previous call to fItypePtr->insertProcfR, and fIstringfR
contains new text to insert just before the character given
by fIindexfR.
The type manager should insert the text and recompute the bounding
box in the item's header.
.SH DCHARSPROC
.PP
fItypePtr->dCharsProcfR is invoked by Tk during the fBdcharsfR
widget command to delete a range of text from a canvas item.
It is only relevant for item types that support text;
fItypePtr->dCharsProcfR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemDCharsProc(
	Tk_Canvas fIcanvasfR,
	Tk_Item *fIitemPtrfR,
	int fIfirstfR,
	int fIlastfR);
.CE
fIcanvasfR and fIitemPtrfR have the usual meanings.
fIfirstfR and fIlastfR give the indices of the first and last bytes
to be deleted, as returned by previous calls to fItypePtr->indexProcfR.
The type manager should delete the specified characters and update
the bounding box in the item's header.
.SH "SEE ALSO"
Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin
.SH KEYWORDS
canvas, focus, item type, selection, type manager

						