crtitemtype.3

linux系统下的音频通信

'\"
'\" 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.
'\" 
'\" SCCS: @(#) CrtItemType.3 1.7 96/02/16 10:30:28
'\" 
.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_CreateItemType\fR(\fItypePtr\fR)
.sp
Tk_ItemType *
\fBTk_GetItemTypes\fR()
.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_CreateItemType\fR is invoked to define a new kind of canvas item
described by the \fItypePtr\fR argument.
An item type corresponds to a particular value of the \fItype\fR
argument to the \fBcreate\fR widget command for canvases, and
the code that implements a canvas item type is called a \fItype manager\fR.
Tk defines several built-in item types, such as \fBrectangle\fR
and \fBtext\fR and \fBimage\fR, but \fBTk_CreateItemType\fR
allows additional item types to be defined.
Once \fBTk_CreateItemType\fR returns, the new item type may be used
in new or existing canvas widgets just like the built-in item
types.
.PP
\fBTk_GetItemTypes\fR 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
\fInextPtr\fR fields, with the end of the list marked by a
NULL \fInextPtr\fR.
.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_CanvasCoords\fR and \fBTk_CanvasPsColor\fR;
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 *\fIname\fR;
	int \fIitemSize\fR;
	Tk_ItemCreateProc *\fIcreateProc\fR;
	Tk_ConfigSpec *\fIconfigSpecs\fR;
	Tk_ItemConfigureProc *\fIconfigProc\fR;
	Tk_ItemCoordProc *\fIcoordProc\fR;
	Tk_ItemDeleteProc *\fIdeleteProc\fR;
	Tk_ItemDisplayProc *\fIdisplayProc\fR;
	int \fIalwaysRedraw\fR;
	Tk_ItemPointProc *\fIpointProc\fR;
	Tk_ItemAreaProc *\fIareaProc\fR;
	Tk_ItemPostscriptProc *\fIpostscriptProc\fR;
	Tk_ItemScaleProc *\fIscaleProc\fR;
	Tk_ItemTranslateProc *\fItranslateProc\fR;
	Tk_ItemIndexProc *\fIindexProc\fR;
	Tk_ItemCursorProc *\fIicursorProc\fR;
	Tk_ItemSelectionProc *\fIselectionProc\fR;
	Tk_ItemInsertProc *\fIinsertProc\fR;
	Tk_ItemDCharsProc *\fIdCharsProc\fR;
	Tk_ItemType *\fInextPtr\fR;
} Tk_ItemType;
.CE
.PP
The fields of a Tk_ItemType structure are described in more detail
later in this manual entry.
When \fBTk_CreateItemType\fR is called, its \fItypePtr\fR
argument must point to a structure with all of the fields initialized
except \fInextPtr\fR, 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 record\fR.
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 \fIheader\fR;
	double \fIx\fR, \fIy\fR;
	Tk_Anchor \fIanchor\fR;
	Pixmap \fIbitmap\fR;
	XColor *\fIfgColor\fR;
	XColor *\fIbgColor\fR;
	GC \fIgc\fR;
} BitmapItem;
.CE
The \fIheader\fR 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 \fIx\fR 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 \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR.
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 \fIx1\fR or y-coordinate
lower than \fIy1\fR, nor should it cover any pixels with
x-coordinate greater than or equal to \fIx2\fR or y-coordinate
greater than or equal to \fIy2\fR.
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 \fIname\fR field provides a string name for the item type.
Once \fBTk_CreateImageType\fR returns, this name may be used
in \fBcreate\fR 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->itemSize\fR 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->createProc\fR points to a procedure for
Tk to call whenever a new item of this type is created.
\fItypePtr->createProc\fR must match the following prototype:
.CS
typedef int Tk_ItemCreateProc(
	Tcl_Interp *\fIinterp\fR,
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIargc\fR,
	char **\fIargv\fR);
.CE
The \fIinterp\fR argument is the interpreter in which the canvas's
\fBcreate\fR widget command was invoked, and \fIcanvas\fR is a
handle for the canvas widget.
\fIitemPtr\fR is a pointer to a newly-allocated item of
size \fItypePtr->itemSize\fR.
Tk has already initialized the item's header (the first
\fBsizeof(Tk_ItemType)\fR bytes).
The \fIargc\fR and \fIargv\fR arguments describe all of the
arguments to the \fBcreate\fR command after the \fItype\fR
argument.
For example, in the widget command
.CS
\fB\&.c create rectangle 10 20 50 50 \-fill black\fR
.CE
\fIargc\fR will be \fB6\fR and \fIargv\fR[0] will contain the
string \fB10\fR.
.PP
\fIcreateProc\fR should use \fIargc\fR and \fIargv\fR 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->result\fR if an error occurs.
If an error occurs Tk will free the item record, so \fIcreateProc\fR
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_ConfigureWidget\fR.
This table will normally be used by \fItypePtr->createProc\fR
and \fItypePtr->configProc\fR, but Tk also uses it directly
to retrieve option information in the \fBitemcget\fR and
\fBitemconfigure\fR widget commands.
\fItypePtr->configSpecs\fR must point to the configuration table
for this type.
Note: Tk provides a custom option type \fBtk_CanvasTagsOption\fR
for implementing the \fB\-tags\fR option;  see an existing type
manager for an example of how to use it in \fIconfigSpecs\fR.

.SH CONFIGPROC
.PP
\fItypePtr->configProc\fR is called by Tk whenever the
\fBitemconfigure\fR 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 *\fIinterp\fR,
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIargc\fR,
	char **\fIargv\fR,
	int \fIflags\fR);
.CE
The \fIinterp\fR argument identifies the interpreter in which the
widget command was invoked,  \fIcanvas\fR is a handle for the canvas
widget, and \fIitemPtr\fR is a pointer to the item being configured.
\fIargc\fR and \fIargv\fR contain the configuration options.  For
example, if the following command is invoked:
.CS
\fB\&.c itemconfigure 2 \-fill red \-outline black\fR
.CE
\fIargc\fR is \fB4\fR and \fIargv\fR contains the strings \fB\-fill\fR
through \fBblack\fR.
\fIargc\fR will always be an even value.
The  \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR;
currently this value is always TK_CONFIG_ARGV_ONLY when Tk
invokes \fItypePtr->configProc\fR, but the type manager's \fIcreateProc\fR
procedure will usually invoke \fIconfigProc\fR with different flag values.
.PP
\fItypePtr->configProc\fR returns a standard Tcl completion code and
leaves an error message in \fIinterp->result\fR if an error occurs.
It must update the item's bounding box to reflect the new configuration
options.

.SH COORDPROC
.PP
\fItypePtr->coordProc\fR is invoked by Tk to implement the \fBcoords\fR
widget command for an item.
It must match the following prototype:
.CS
typedef int Tk_ItemCoordProc(
	Tcl_Interp *\fIinterp\fR,
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIargc\fR,
	char **\fIargv\fR);
.CE
The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR
all have the standard meanings, and \fIargc\fR and \fIargv\fR
describe the coordinate arguments.
For example, if the following widget command is invoked:
.CS
\fB\&.c coords 2 30 90\fR
.CE
\fIargc\fR will be \fB2\fR and \fBargv\fR will contain the string values
\fB30\fR and \fB90\fR.
.PP
The \fIcoordProc\fR 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, \fIcoordProc\fR must leave an error message in
\fIinterp->result\fR.

.SH DELETEPROC
.PP
\fItypePtr->deleteProc\fR 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 \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	Display *\fIdisplay\fR);
.CE
The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual
interpretations, and \fIdisplay\fR identifies the X display containing
the canvas.
\fIdeleteProc\fR must free up any resources allocated for the item,
so that Tk can free the item record.