crtitemtype.3

linux系统下的音频通信

\fIdeleteProc\fR should not actually free the item record;  this will
be done by Tk when \fIdeleteProc\fR returns.

.SH "DISPLAYPROC AND ALWAYSREDRAW"
.PP
\fItypePtr->displayProc\fR is invoked by Tk to redraw an item
on the screen.
It must match the following prototype:
.CS
typedef void Tk_ItemDisplayProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	Display *\fIdisplay\fR,
	Drawable \fIdst\fR,
	int \fIx\fR,
	int \fIy\fR,
	int \fIwidth\fR,
	int \fIheight\fR);
.CE
The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning.
\fIdisplay\fR identifies the display containing the canvas, and
\fIdst\fR 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.
\fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR 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 \fIdisplayProc\fR 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 \fIdst\fR
will not necessarily be the same as those in the canvas.
\fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR
to transform coordinates from those of the canvas to those
of \fIdst\fR.
.PP
Normally an item's \fIdisplayProc\fR is only invoked if the item
overlaps the area being displayed.
However, if \fItypePtr->alwaysRedraw\fR has a non-zero value, then
\fIdisplayProc\fR is invoked during every redisplay operation,
even if the item doesn't overlap the area of redisplay.
\fIalwaysRedraw\fR 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->pointProc\fR 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 \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	double *\fIpointPtr\fR);
.CE
\fIcanvas\fR and \fIitemPtr\fR have the usual meaning.
\fIpointPtr\fR points to an array of two numbers giving
the x and y coordinates of a point.
\fIpointProc\fR 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->areaProc\fR 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 \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	double *\fIrectPtr\fR);
.CE
\fIcanvas\fR and \fIitemPtr\fR have the usual meaning.
\fIrectPtr\fR 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.
\fIareaProc\fR 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->postscriptProc\fR is invoked by Tk to generate
Postcript for an item during the \fBpostscript\fR widget command.
If the type manager is not capable of generating Postscript then
\fItypePtr->postscriptProc\fR should be NULL.
The procedure must match the following prototype:
.CS
typedef int Tk_ItemPostscriptProc(
	Tcl_Interp *\fIinterp\fR,
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIprepass\fR);
.CE
The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have
standard meanings;  \fIprepass\fR will be described below.
If \fIpostscriptProc\fR completes successfully, it should append
Postscript for the item to the information in \fIinterp->result\fR
(e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR)
and return TCL_OK.
If an error occurs, \fIpostscriptProc\fR 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
\fIpostscriptProc\fR.
For example, \fBTk_CanvasPsColor\fR will generate Postscript to set
the current color to a given Tk color and \fBTk_CanvasPsFont\fR 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
\fBgsave\fR and \fBgrestore\fR commands around the Postscript for
the item.
The type manager can use canvas x coordinates directly in its Postscript,
but it must call \fBTk_CanvasPsY\fR 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 \fIpostscriptProc\fR in each pass.
The only purpose of the first pass is to collect font information
(which is done by \fBTk_CanvPsFont\fR);  the actual Postscript is
discarded.
Tk sets the \fIprepass\fR argument to \fIpostscriptProc\fR to 1
during the first pass;  the type manager can use \fIprepass\fR to skip
all Postscript generation except for calls to \fBTk_CanvasPsFont\fR.
During the second pass \fIprepass\fR will be 0, so the type manager
must generate complete Postscript.

.SH SCALEPROC
\fItypePtr->scaleProc\fR is invoked by Tk to rescale a canvas item
during the \fBscale\fR widget command.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemScaleProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	double \fIoriginX\fR,
	double \fIoriginY\fR,
	double \fIscaleX\fR,
	double \fIscaleY\fR);
.CE
The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning.
\fIoriginX\fR and \fIoriginY\fR specify an origin relative to which
the item is to be scaled, and \fIscaleX\fR and \fIscaleY\fR 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 \fIx\fR and \fIy\fR will have new
coordinates \fIx'\fR and \fIy'\fR, where
.CS
\fIx' = originX  + scaleX*(x-originX)
y' = originY + scaleY*(y-originY)\fR
.CE
\fIscaleProc\fR must also update the bounding box in the item's
header.

.SH TRANSLATEPROC
\fItypePtr->translateProc\fR is invoked by Tk to translate a canvas item
during the \fBmove\fR widget command.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemTranslateProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	double \fIdeltaX\fR,
	double \fIdeltaY\fR);
.CE
The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning,
and \fIdeltaX\fR and \fIdeltaY\fR 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->indexProc\fR is invoked by Tk to translate a string
index specification into a numerical index, for example during the
\fBindex\fR widget command.
It is only relevant for item types that support indexable text;
\fItypePtr->indexProc\fR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef int Tk_ItemIndexProc(
	Tcl_Interp *\fIinterp\fR,
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	char \fIindexString\fR,
	int *\fIindexPtr\fR);
.CE
The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all
have the usual meaning.
\fIindexString\fR contains a textual description of an index,
and \fIindexPtr\fR 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, \fBinsert\fR,  \fBsel.first\fR,
\fBend\fR, etc.).
\fIindexProc\fR should return a Tcl completion code and set
\fIinterp->result\fR in the event of an error.

.SH ICURSORPROC
.PP
\fItypePtr->icursorProc\fR is invoked by Tk during
the \fBicursor\fR 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->icursorProc\fR 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_ItemIndexProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIindex\fR);
.CE
\fIcanvas\fR and \fIitemPtr\fR have the usual meanings, and
\fIindex\fR is an index into the item's text, as returned by a
previous call to \fItypePtr->insertProc\fR.
The type manager should position the insertion cursor in the
item just before the character given by \fIindex\fR.
Whether or not to actually display the insertion cursor is
determined by other information provided by \fBTk_CanvasGetTextInfo\fR.

.SH SELECTIONPROC
.PP
\fItypePtr->selectionProc\fR 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->selectionProc\fR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef int Tk_ItemSelectionProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIoffset\fR,
	char *\fIbuffer\fR,
	int \fImaxBytes\fR);
.CE
\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
\fIoffset\fR 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.
\fIbuffer\fR points to an area of memory in which to store the
requested bytes, and \fImaxBytes\fR specifies the maximum number
of bytes to return.
\fIselectionProc\fR should extract up to \fImaxBytes\fR characters
from the selection and copy them to \fImaxBytes\fR;  it should
return a count of the number of bytes actually copied, which may
be less than \fImaxBytes\fR if there aren't \fIoffset+maxBytes\fR bytes
in the selection.

.SH INSERTPROC
.PP
\fItypePtr->insertProc\fR is invoked by Tk during
the \fBinsert\fR widget command to insert new text into a
canvas item.
It is only relevant for item types that support text;
\fItypePtr->insertProc\fR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemInsertProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIindex\fR,
	char *\fIstring\fR);
.CE
\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
\fIindex\fR is an index into the item's text, as returned by a
previous call to \fItypePtr->insertProc\fR, and \fIstring\fR
contains new text to insert just before the character given
by \fIindex\fR.
The type manager should insert the text and recompute the bounding
box in the item's header.

.SH DCHARSPROC
.PP
\fItypePtr->dCharsProc\fR is invoked by Tk during the \fBdchars\fR
widget command to delete a range of text from a canvas item.
It is only relevant for item types that support text;
\fItypePtr->dCharsProc\fR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemDCharsProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIfirst\fR,
	int \fIlast\fR);
.CE
\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
\fIfirst\fR and \fIlast\fR give the indices of the first and last bytes
to be deleted, as returned by previous calls to \fItypePtr->indexProc\fR.
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