## Tcl8.6.17/Tk8.6.17 Documentation > Tk C API > CrtItemType

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  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)
  INTRODUCTION
  データ構造 DATA STRUCTURES
  TK_ITEMTYPE FIELDS
  NAME
  FLAGS (IN ALWAYSREDRAW)
    1
    TK_CONFIG_OBJS
    TK_MOVABLE_POINTS
  ITEMSIZE
  CREATEPROC
  CONFIGSPECS
  CONFIGPROC
  COORDPROC
  DELETEPROC
  DISPLAYPROC
  POINTPROC
  AREAPROC
  POSTSCRIPTPROC
  SCALEPROC
  TRANSLATEPROC
  INDEXPROC
  ICURSORPROC
  SELECTIONPROC
  INSERTPROC
  DCHARSPROC
  SEE ALSO
  KEYWORDS

### 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 は typePtr 引数によって記述された画布品目の新しい種類を定義する為に起動される｡品目型は､画布の為の create 部品命令への type 引数の特定の値に相当し､画布品目型を実装する命令符号は型管理譜に呼出される｡ Tk は譬えば rectangle や text や image 等の､幾つかの組込み品目型を定義しているが､ Tk_CreateItemType は定義できる追加的品目型を許容している｡一たびTk_CreateItemType が帰ると､新しい品目型が､新しい又は既存の画布部品内で恰も組込み品目型の様に使える様になる｡ Tk_CreateItemType is invoked to define a new kind of canvas item described by the typePtr argument. An item type corresponds to a particular 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 rectangle 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 は画布の為に現在定義されている全ての品目型のリストの開始点へのポインターを返す｡そのリストの見出しはその nextPtr 欄を通して互いに連結されれいる､リストの末尾は NULL nextPtr.が記されている｡ 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.

点地図( tkCanvBmap.c ファイル内)や文書(tkCanvText.c)の様な既存の画布品目型の為の符号命令を見ることにより残りのこの取扱説明書の見出しの理解がより容易であることが判る｡新しい型管理譜を作成する容易な方法は既存の型の為の符号命令を複写し新しい型の為に修正することである｡ 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 (in the 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 は Tk_CanvasCoords や Tk_CanvasPsColor; の様な､画布型管理譜の使用の為の有益な手続函数の数を提供する; これらは別々の取扱説明書の見出しに記述されている｡ 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

型管理譜は標準的なその型の品目上の操作の組を提供する手続函数の集まりによって構成される｡型管理譜は三つの種類のデータ構造を扱う｡第１データ構造は Tk_ItemType;であり; 型の名前や､型管理譜によって実装された標準的手続函数へのポインターの様な情報を含む: 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 {
        const char *name;
        int itemSize;
        Tk_ItemCreateProc *createProc;
        const 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;

Tk_ItemType 構造の欄はこの取扱説明書の後の見出しで更に詳細に記述する｡ Tk_CreateItemType が呼ばれた時､その typePtr 引数はTk がリストに全ての型を一緒に連結する為に設定する nextPtr を除き､初期化された全ての欄を伴う構造を指さなければならない｡構造は永久的な記憶になければならない(静的に割当てられても動的に割当てられても好いが､解放されてはならない); Tk はこの構造へのポインターを保持する｡ 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 initialized except nextPtr, 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.

型管理譜により操作される第２のデータ構造は品目の記録である｡画布内の夫々の品目に一つの記録がある｡与えられた型の全ての品目は一般に同じ構造の品目記録を有するが､異なる型は通常その品目記録の為に異なる形式を有する｡夫々の品目の記録の初めの部分は型 Tk_Item;経由で Tk に定義された標準構造の冒頭情報である; 品目記録の残りの部分は型管理譜によって定義される｡型管理譜は最初の欄としてその品目記録の Tk_Item を定義しなくてはならない｡譬えば､点地図の品目の為の品目記録は次のように定義される: 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;

冒頭情報の仔構造は､その識別子､その貼り札､その型､その結合箱の様な､品目を管理する為に Tk によって使われる情報を含む｡ x によって始まる欄は型管理譜に属する: Tk がそれを読むことはない｡型管理譜は名前が x1, y1, x2, and y2.の四つの欄以外は冒頭情報のどの欄も読み書きする必要はない｡これ等の欄は整数画布座標を使う品目の為に結合箱を与える: その品目は x1 より下の x-座標や y1 より下の y-座標のどの画素も対象としないし､ x2 以上の x-座標や y2 以上の y-座標のどの画素も対象としない｡結合箱を品目が移動し又構成設定されるに従って更新することは型管理譜の責務である｡ 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.

何時であれ Tk が型管理譜内の手続函数を呼ぶ時､それはポインター内のものを品目記録に渡す｡引数は常に Tk_Item にポインターとして渡される; 型管理譜は典型的には､ それを､BitmapItem.の様な､自己の特別な型へのポインター内に仕舞う｡ 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.

型管理譜に使われる第３のデータ構造は型 Tk_Canvas を有す; それは全体としての画布部品の為の不透明な処理機能として働く｡型管理譜はこの構造の内容に関して何も知る必要はない｡Tk_Canvas 処理機能は典型的には型管理譜の手続函数に渡され､型管理譜は､画布に関する情報を取る為に Tk_CanvasTkwin の如く外部函数手続函数に処理機能を戻し渡すことができる｡ 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.

### TK_ITEMTYPE FIELDS

#### NAME

この項とそれに続く項では Tk_ItemType 構造内のそれぞれの欄について詳細に記述する｡ name 欄は夫々の品目型の文字列名前を提供する｡一たび Tk_CreateImageType から帰ると､この名前は create 部品命令内で新しい型の品目を作成する為に使われるかもしれない｡もしこの名前の品目型が既に実在する場合は新しい品目型が古い物に置換わる｡ 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.

#### FLAGS (IN ALWAYSREDRAW)

typePtr->alwaysRedraw 欄は(歴史的理由によってそう名付られた)､画布の中核が品目と如何に干渉するかを修正する旗印ビットの集まりを含む｡次のビットが定義されている: The typePtr->alwaysRedraw field (so named for historic reasons) contains a collection of flag bits that modify how the canvas core interacts with the item. The following bits are defined:

1
  品目の結合箱が再描画される領域が重なった時にのみではなく､画布のどこかの部分が再描写された時は常に品目が再描写されることを指し示す｡これは窓品目に使われる､譬えば､画面上になく対応解除する必要がある副窓｡ Indicates that the item should always be redrawn when any part of the canvas is redrawn, rather than only when the bounding box of the item overlaps the area being redrawn. This is used by window items, for example, which need to unmap subwindows that are not on the screen.

TK_CONFIG_OBJS
  文字列(又は文字列配列)以外を取る操作は実際は Tcl_Obj 参照(又はその様な参照の配列)をとることを指し示す｡これを適用する操作は configProc, the coordProc, the createProc, the indexProc and the insertProc である｡ Indicates that operations which would otherwise take a string (or array of strings) actually take a Tcl_Obj reference (or an array of such references). The operations to which this applies are the configProc, the coordProc, the createProc, the indexProc and the insertProc.

TK_MOVABLE_POINTS
  品目が Tk に組込まれている線や多角形型と同じ意味論で dCharsProc, indexProc and insertProc を運営していることを指し示す､又それで､個別の座標点が移動可能である｡上のどれかの手段が NULL.の場合は設定される事はない｡ Indicates that the item supports the dCharsProc, indexProc and insertProc with the same semantics as Tk's built-in line and polygon types, and that hence individual coordinate points can be moved. Must not be set if any of the above methods is NULL.

#### ITEMSIZE

typePtr->itemSize はTk_Item 冒頭情報を含むこの型の品目記録の寸法をバイト単位で与える｡ Tk はこの寸法を型の品目についての記憶空間の割付に使う｡与えられた型の全ての品目の記録は同じ寸法を有さなければならない｡もし変数長さ欄がどれかの品目に必要な場合(多角形の為の点のリストの如く)､型管理譜は変数長さの区切られた対象を割当てられ､その品目記録内にそれへのポインターを保有する｡ 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 は､何時であれこの型の新しい品目が作成される時､ Tk を呼ぶ為の手続函数を指示する｡typePtr->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 following prototype:

    typedef int Tk_ItemCreateProc(
            Tcl_Interp *interp,
            Tk_Canvas canvas,
            Tk_Item *itemPtr,
            int objc,
            Tcl_Obj *const objv[]);

interp 引数はその中で画布の create 部品命令が起動される解釈実行機能であり､ canvas は画布部品の為の処理機能である｡ itemPtr は新しく割付けられた寸法の型の品目 typePtr->itemSize を指す｡ Tk は既に品目の冒頭情報により初期化されている(初めの sizeof(Tk_ItemType) バイト)｡ objc と objv 引数は create 命令の type 引数の後の全ての引数を記述する｡註意すべきはもし､ TK_CONFIG_OBJS が typePtr->alwaysRedraw 欄に設定されていない場合､ 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-allocated 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. Note that if TK_CONFIG_OBJS is not set in the typePtr->alwaysRedraw field, the objv parameter will actually contain a pointer to an array of constant strings. For example, in the widget command:

    	.c create rectangle 10 20 50 50 -fill black

objc は 6 になり､ objv[0] は整数対象 10 を含む｡ objc will be 6 and objv[0] will contain the integer object 10.

createProc は objc and objv を品目記録の型固有の部分を初期化する為に使われ､品目の冒頭情報内の結合箱の為の初期値を設定する｡それは標準 Tcl 完成符号を返し､もし不都合が生じた場合､解釈実行機能内に不都合伝言文を残す｡もし不都合が生じると Tk は品目符号を解除するので､もしそれが不都合を返す場合､ createProc は品目記録を清浄な状態にして残す事を確かめなければならない(譬えば､その品目の為に割当てられたどんな追加的記憶も解除しなければならない)｡ 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 the interpreter 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

それぞれの画布管理譜は､ Tk_ConfigureWidget で使うのに適した形式で､その構成設定指示項目を記述する標準表を提供しなければならない｡この表は通常 typePtr->createProc と typePtr->configProc とによって使用されるが､ Tk は itemcget と itemconfigure 部品命令内で､それを指示項目の情報を取り返す為に直接利用する｡ typePtr->configSpecs はこの型の為の構成設定表を指さなければならない｡註意: Tk は -tags 指示項目を実装する為に誂えた指示項目型 tk_CanvasTagsOption を提供する; 譬えば､ configSpecs.内でそれを使用する方法の例については､既存の型管理譜を参照されたい｡ Each type manager must provide a standard table describing its configuration options, in a form suitable for use with Tk_ConfigureWidget. This table will normally be used by typePtr->createProc and typePtr->configProc, but Tk also uses it directly to retrieve option information in the itemcget and itemconfigure widget commands. typePtr->configSpecs must point to the configuration table for this type. Note: Tk provides a custom option type tk_CanvasTagsOption for implementing the -tags option; see an existing type manager for an example of how to use it in configSpecs.

#### CONFIGPROC

typePtr->configProc は､何時であれ itemconfigure 部品命令が画布品目について､構成設定指示項目を変更するために起動された時に呼出される｡この手続函数は次の原型に合致しなくてはならない: 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);

interp 引数は､その中で部品命令が起動された解釈実行機能を識別する｡canvas は画布部品の為の操作子であり､itemPtr は構成設定の品目への指示子である｡objc と objv は構成設定項目を含む｡註意すべきは､もし TK_CONFIG_OBJS が typePtr->alwaysRedraw 内で設定されてない場合､ objv 假引数は定数文字列の配列への指示子を実際上含む｡譬えば､もし次の命令が起動されると: The interp argument identifies the interpreter in which the widget command was invoked, canvas is a handle for the canvas widget, and itemPtr is a pointer to the item being configured. objc and objv contain the configuration options. Note that if TK_CONFIG_OBJS is not set in the typePtr->alwaysRedraw field, the objv parameter will actually contain a pointer to an array of constant strings. For example, if the following command is invoked:

    	.c itemconfigure 2 -fill red -outline black

objc は 4 ､ objv は文字列対象 -fill から black 迄を含む｡ objc は常に偶数になる｡ flags 引数は Tk_ConfigureWidget に渡す為の旗印を含む; 現在この値は Tk が typePtr->configProc を起動している時は､常に TK_CONFIG_ARGV_ONLY であるが､型管理譜の createProc 手続函数は通常 configProc を異なる旗印値で起動する｡ 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 は標準 Tcl 完成符号を返し､もし不都合が生じた場合､解釈実行機能内に不都合伝言文を残す｡新しい構成設定指示項目を参照している品目の結合箱を更新しなければならない｡ typePtr->configProc returns a standard Tcl completion code and leaves an error message in the interpreter result if an error occurs. It must update the item's bounding box to reflect the new configuration options.

#### COORDPROC

typePtr->coordProc は品目に関する coords 部品命令を実装する為に Tk によって起動される｡それは次の原型に合致しなくてはならない: typePtr->coordProc is invoked by Tk to implement the coords widget command 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[]);

interp, canvas, and itemPtr 引数は全て標準的意味を有する､又､ objc と objv は座標引数を記述する｡註意すべきは､ TK_CONFIG_OBJS が typePtr->alwaysRedraw 欄内に設定されてない場合､ objv 假引数は定数文字列の配列へのポインターを実際に含む｡譬えばもし次の部品命令が起動されると: The arguments interp, canvas, and itemPtr all have the standard meanings, and objc and objv describe the coordinate arguments. Note that if TK_CONFIG_OBJS is not set in the typePtr->alwaysRedraw field, the objv parameter will actually contain a pointer to an array of constant strings. For example, if the following widget command is invoked:

    	.c coords 2 30 90

objc は 2 そして objv は整数対象 30 と 90 を含む｡ objc will be 2 and objv will contain the integer objects 30 and 90.

coordProc 手続函数は新しい座標を処理し､品目を適切に更新し(譬えば､品目の冒頭情報内の結合箱の残りに違いない)､標準 Tcl 完成符号を返す｡もし不都合が生じると coordProc は不都合伝言文を解釈実行機能内に残すはずである｡ 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 the interpreter result.

#### DELETEPROC

typePtr->deleteProc は Tk により品目を除去しそれに割付けたどの原資も解放する為に起動される｡それは次の原型に合致しなければならない: 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);

canvas and itemPtr 引数は通常の解釈実行機能を有する､又 display は画布を含む X 表示装置を識別する｡ deleteProc はその品目の為に割当てたどの原資迄も解放しれなければならない､そこで Tk は品目記録を解放する｡ deleteProc は実際品目記録を解放しないであろう; これは deleteProc が帰った時に Tk により実行される｡ 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

typePtr->displayProc は画面上の品目を再描画する為に Tk により起動される｡それは次の原型に合致しなければならない: 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);

canvas and itemPtr 引数は通常の意味を有する｡ display は画布を含む表示装置を識別する､又､ dst は描画可能性を指定するそこでは品目は,照明効果を付けられる; 典型的にはそれは画面外画素地図であり､それを Tk が一度全ての適切な品目が描かれた画布の窓の中に複写する｡ x, y, width, and height は描画される画布座標内の矩形領域を指定する; これに重複する領域の情報のみが再描画に必要である｡ Tk は品目も接続箱が再描画領域と重複しない限り displayProc を呼ばないが､型管理譜は品目の再表示を最適化するために再描画領域を使うことを望むかもしれない｡ The canvas and itemPtr arguments have the usual meaning. 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 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.

摺動と､２重の緩衝域の再表示の為の画面外画素地図の使用との理由で dst 内の品目の座標は画素の座標と同じである必要はない｡ displayProc は画素から dst.に座標を変換する為に Tk_CanvasDrawableCoords を呼ぶべきである｡ 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_CanvasDrawableCoords to transform coordinates from those of the canvas to those of dst.

通常､品目の displayProc は､品目が表示されている領域と重複した場合にのみ起動される｡しかし､もし typePtr->alwaysRedraw の零番目のビットが1,(即ち､ “typePtr->alwaysRedraw & 1 == 1” )の場合､ displayProc は全ての再表示操作で起動される､たとえ品目が再表示領域と重複しない場合も; これは仔供の窓が画面外のときに対応を外す必要がある窓品目の様な場合に便利である｡ Normally an item's displayProc is only invoked if the item overlaps the area being displayed. However, if bit zero of typePtr->alwaysRedraw is 1, (i.e. “typePtr->alwaysRedraw & 1 == 1”) then displayProc is invoked during every redisplay operation, even if the item does not overlap the area of redisplay; this is useful for cases such as window items, where the subwindow needs to be unmapped when it is off the screen.

#### POINTPROC

typePtr->pointProc は与えられた点が画布の品目に如何に近いかを見出す為に Tk により起動される｡ Tk はこの手続函数を､マウスの下の品目の位置決めや与えられた点に最も近い品目の発見の為に使う｡それは次の原型に合致しなければならない: 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 は通常の意味を有する｡ pointPtr は点の x and y 座標を与える２つの数の配列を指す｡ pointProc は点から品目迄の距離を与える実数を返すが､もし点が品目の中にあると 0 を返す｡ 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 は品目と矩形領域の間の関係を見付ける為に Tk により起動される｡それは次の原型に合致しなければならない: 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 は通常の意味を有する｡ rectPtr 四つの実数の配列を指す; 初めの二つは矩形の左上隅の x and y 座標を与える､又､第２の２つは右下隅の x and y 座標を与える｡ areaProc は品目が完全に与えられた領域の外にある場合は -1 を返さねばならず､部分的に内側､部分的に外側の領域にある場合は 0 を､完全に領域の内側にある場合は 1 である｡ 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 は postscript 部品命令の間に品目についてのポストスクリプト形式を生成する為に Tk により起動される｡もし型管理譜がポストスクリプトを発生できない場合､ typePtr->postscriptProc は NULL.になる｡手続函数は次の原型に合致しなければならない: 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);

interp, canvas, and itemPtr は全て通常の意味を有する; prepass は下に記述する｡もし postscriptProc が成功裏に完了すると､解釈実行機能の結果の中の情報に品目に関するポストスクリプトを追記し(譬えば､ Tcl_SetResult ではなく Tcl_AppendResult を呼ぶ)､ TCL_OK を返す｡もし不都合が生じると､ postscriptProc は結果を解消しその内容を不都合伝言文に置換える; その上 TCL_ERROR を返す｡ 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 the interpreter 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 は postscriptProc を簡略化するための便益手続函数の集まりである｡譬えば､ Tk_CanvasPsColor はポストスクリプトに現在の色から与えられた Tk 色に設定させ､ Tk_CanvasPsFont は文字形状の情報を設定させる｡ポストスクリプトを生成する時､型管理譜はポストスクリプトの解釈の絵画状態を変更する為に解除される､そこで Tk は gsave and grestore 命令を品目に関するポストスクリプトの回りに配置する｡型管理譜は画布の x 座標を直接ポストスクリプト内で使用できるが､ y 座標を画布空間(原点は左上隅)からポストスクリプト空間(原点は左下隅)に移す為に Tk_CanvasPsY を呼ぶ必要がある｡ Tk provides a collection of utility procedures to simplify postscriptProc. 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 Postscript, 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).

アドビ社DSCを伴ったポストスクリプトを生成する為には Tk は実際ポストスクリプトを２度通しする｡通す毎に夫々の品目の postscriptProc を呼ぶ｡１度目は文字形状情報を集めるだけの目的である( Tk_CanvasPsFont によって遂行する); 実際のポストスクリプトは遺棄される｡ Tk は第１通しの間に postscriptProc への prepass 引数を 1 に設定する; 型管理譜は Tk_CanvasPsFont.への呼出しを除き全てのポストスクリプト生成を飛越すために prepass を使うことができる｡第２通しの間 prepass は 0,であるので､型管理譜は完全なポストスクリプトを生成する必要がある｡ 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 は scale 部品命令の間に画布品目を再縮小する為に Tk により起動される｡手続函数は次の原型に合致しなければならない: typePtr->scaleProc is invoked by Tk to rescale a canvas item during the scale widget command. The procedure must match the following prototype:

    typedef void Tk_ItemScaleProc(
            Tk_Canvas canvas,
            Tk_Item *itemPtr,
            double originX,
            double originY,
            double scaleX,
            double scaleY);

canvas and itemPtr 引数は通常の意味を有する｡ originX and originY は縮小拡大される品目への原点からの関係を指定する､又､ scaleX and scaleY は x and y は拡大率を与える｡品目はその座標を調整して､品目内の点が有していた座標 x and y は新しい座標 x' and y' を有する､此処で､ 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 は品目の冒頭情報内の結合箱も同じく更新しなければならい｡ scaleProc must also update the bounding box in the item's header.

#### TRANSLATEPROC

typePtr->translateProc は move 部品命令の間に画布品目を移動する為に Tk により起動される｡手続函数は次の原型に合致しなければならない: typePtr->translateProc is invoked by Tk to translate a canvas item during 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);

canvas and itemPtr 引数は通常の意味を有する､又､ deltaX and deltaY は品目の内部でそれぞれの x and y 座標に加えるべき量を与える｡型管理譜は品目の座標を調整し､品目の冒頭情報内の結合箱も更新する｡ 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 は譬えば index 部品命令の間に､文字列索引指定を数字的索引に変換する為に Tk により起動される｡それは索引可能の文書か座標を運営している品目型にのみ適している; typePtr->indexProc は､もし詳細な座標番地を運営していない場合､非文書品目型の為に NULL として指定されるかもしれない｡手続函数は次の原型に合致しなければならない: typePtr->indexProc is invoked by Tk to translate a string index specification into a numerical index, for example during the index widget command. It is only relevant for item types that support indexable text or coordinates; typePtr->indexProc may be specified as NULL for non-textual item types if they do not support detailed coordinate addressing. The procedure must match the following prototype:

    typedef int Tk_ItemIndexProc(
            Tcl_Interp *interp,
            Tk_Canvas canvas,
            Tk_Item *itemPtr,
            Tcl_Obj *indexObj,
            int *indexPtr);

interp, canvas, and itemPtr 引数は通常の意味を有する｡ indexObj は索引の文書的記述を含む､ indexPtr は数的索引を満たす整数値を指す｡註意すべきは､もし TK_CONFIG_OBJS が typePtr->alwaysRedraw 欄内に設定されていなければ､ indexObj 假引数は実際定数文字列へのポインターを含む｡その形式の索引が運営されているかを定めることは型管理譜の責務である(譬えば､数､ insert sel.first end 等)｡ indexProc は Tcl 完了譜を返し行事内の不都合を解釈実行機能の結果に設定する｡ The interp, canvas, and itemPtr arguments all have the usual meaning. indexObj contains a textual description of an index, and indexPtr points to an integer value that should be filled in with a numerical index. Note that if TK_CONFIG_OBJS is not set in the typePtr->alwaysRedraw field, the indexObj parameter will actually contain a pointer to a constant string. 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 the interpreter result in the event of an error.

#### ICURSORPROC

typePtr->icursorProc は index 部品命令の間に､文書的品目の中に挿入遊走子の位置を設定する為に Tk により起動される｡それは挿入遊走子を運営している品目型にのみ適している; typePtr->icursorProc は､もし挿入遊走子を運営していない場合､非文書品目型の為に NULL として指定されるかもしれない｡手続函数は次の原型に合致しなければならない: 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; typePtr->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 引数は通常の意味を有する､ index は以前の typePtr->insertProc.呼出しに返されたものとして､品目の文書に入れた索引である｡型管理譜は index により与えられた文字の直前の品目内に挿入遊走子を置くべきである｡そうであってもなくても､実際挿入遊走子を表示することは Tk_CanvasGetTextInfo により提供された他の情報によって決定される｡ 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 は選択を取出す間に Tk により起動される; 品目内の一部又は全部の選択された文書を返さねばならない(もしあれば)｡それは文書を運営している品目型にのみ適している; typePtr->selectionProc は､非文書型品目では､ NULL として指定されるかもしれない｡手続函数は次の原型に合致しなければならない: 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->selectionProc may be specified as NULL for non-textual item types. The procedure must match the following prototype:

    typedef int Tk_ItemSelectionProc(
            Tk_Canvas canvas,
            Tk_Item *itemPtr,
            int offset,
            char *buffer,
            int maxBytes);

canvas and itemPtr 引数は通常の意味を有する｡ offset はバイト単位の選択内の偏寄で 0 は選択の最初のバイトを参照する; それはこの呼出が返すべき最初の文字を識別する｡ buffer は記憶領域を指し､そこへは要求されたバイトが保存され､ maxBytes は返す最大のバイト数を指定する｡ selectionProc は選択から maxBytes 文字迄を抽出し､ maxBytes に複写する; それは実際複写されたバイトの数の計数を返すべきで､それは､もし選択内に offset+maxBytes バイトがなければ 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 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 are not offset+maxBytes bytes in the selection.

#### INSERTPROC

typePtr->insertProc は insert 部品命令の間に､画布品目の中に新しい文書か座標を挿入する為に Tk により起動される｡それは insert 手段を運営している品目型にのみ適している; typePtr->insertProc は他の品目型に就いては､ NULL として指定されるかもしれない｡手続函数は次の原型に合致しなければならない: typePtr->insertProc is invoked by Tk during the insert widget command to insert new text or coordinates into a canvas item. It is only relevant for item types that support the insert method; typePtr->insertProc may be specified as NULL for other item types. The procedure must match the following prototype:

    typedef void Tk_ItemInsertProc(
            Tk_Canvas canvas,
            Tk_Item *itemPtr,
            int index,
            Tcl_Obj *obj);

canvas と itemPtr は通常の意味を有する｡ index は以前の typePtr->insertProc 呼出しに返されたものとして､品目の文書に入れた索引である､又｡ obj は index により与えられた文字の直前に挿入された新しい文書を含む｡註意すべきは TK_CONFIG_OBJS が typePtr->alwaysRedraw 欄に設定されていない場合､ obj 假引数は実際挿入されるべき定数文字列へのポインターを含むことになる｡もし品目がこれによる座標リスト修正を運営している場合 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 obj contains new text to insert just before the character given by index. Note that if TK_CONFIG_OBJS is not set in the typePtr->alwaysRedraw field, the obj parameter will actually contain a pointer to a constant string to be inserted. If the item supports modification of the coordinates list by this

型管理譜は文書を挿入し品目の冒頭情報の結合箱を再計算すべきである｡ The type manager should insert the text and recompute the bounding box in the item's header.

#### DCHARSPROC

typePtr->dCharsProc は dchars 部品命令の間に､画布品目の文書の範囲又は､経路の品目の座標の範囲から削除する為に Tk により起動される｡それは文書を運営している品目型にのみ適している; typePtr->dCharsProc は座標削除の運営を望まない非文書品目型に就いては､ NULL として指定されるかもしれない｡手続函数は次の原型に合致しなければならない: typePtr->dCharsProc is invoked by Tk during the dchars widget command to delete a range of text from a canvas item or a range of coordinates from a pathed item. It is only relevant for item types that support text; typePtr->dCharsProc may be specified as NULL for non-textual item types that do not want to support coordinate deletion. The procedure must match the following prototype:

    typedef void Tk_ItemDCharsProc(
            Tk_Canvas canvas,
            Tk_Item *itemPtr,
            int first,
            int last);

canvas and itemPtr 引数は通常の意味を有する｡ first and last は以前の typePtr->indexProc 呼出しに返されたものとして､削除されるべき最初と最後のバイトの索引を与える｡型管理譜は指定された文字を削除し､品目の冒頭情報内の結合箱を更新するべきである｡ 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, Tk_CanvasTextInfo, Tk_CanvasTkwin

### KEYWORDS

canvas, focus, item type, selection, type manager
Copyright © 1994-1995 Sun Microsystems, Inc.