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

### 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_CreateImageType, Tk_GetImageMasterData, Tk_GetImageModelData, Tk_InitImageArgs — 新しい種類の映像を定義する define new kind of image
  SYNOPSIS
    #include <tk.h>
    Tk_CreateImageType(typePtr)
    ClientData
    Tk_GetImageMasterData(interp, name, typePtrPtr)
    ClientData
    Tk_GetImageModelData(interp, name, typePtrPtr)
    Tk_InitImageArgs(interp, argc, argvPtr)
  引数 ARGUMENTS
    const Tk_ImageType *typePtr (入力in)
    Tcl_Interp *interp (入力in)
    const char *name (入力in)
    Tk_ImageType **typePtrPtr (出力out)
    int argc (入力in)
    char ***argvPtr (入出力in/out)
  説明 DESCRIPTION
  名前 NAME
  CREATEPROC
  GETPROC
  DISPLAYPROC
  FREEPROC
  DELETEPROC
  TK_GETIMAGEMODELDATA
  遺産の対話機能の運営 LEGACY INTERFACE SUPPORT
  SEE ALSO
  KEYWORDS

### NAME

Tk_CreateImageType, Tk_GetImageMasterData, Tk_GetImageModelData, Tk_InitImageArgs — 新しい種類の映像を定義する define new kind of image

### SYNOPSIS

#include <tk.h>
Tk_CreateImageType(typePtr)
ClientData
Tk_GetImageMasterData(interp, name, typePtrPtr)
ClientData
Tk_GetImageModelData(interp, name, typePtrPtr)
Tk_InitImageArgs(interp, argc, argvPtr)

### 引数 ARGUMENTS

const Tk_ImageType *typePtr (入力in)
  新しい映像の型を定義する構造｡ Tk 8.4 とそれ以前の版ではこれは静的でなければならない: この構造への指示子は映像番号によって保持されている｡ Tk 8.5では､この制限は解除されている｡ 　 Structure that defines the new type of image. For Tk 8.4 and earlier this must be static: a pointer to this structure is retained by the image code. In Tk 8.5, this limitation was relaxed.

Tcl_Interp *interp (入力in)
  その中で映像が生成される解釈実行機能｡ Interpreter in which image was created.

const char *name (入力in)
  既存の映像の名前｡ Name of existing image.

Tk_ImageType **typePtrPtr (出力out)
  実在する場合は､与えられた映像の為の型情報への指示子を保存する語を指す｡ Points to word in which to store a pointer to type information for the given image, if it exists.

int argc (入力in)
  引数の個数 Number of arguments

char ***argvPtr (入出力in/out)
  引数リストへの指示子 Pointer to argument list

### 説明 DESCRIPTION

Tk_CreateImageType は新しい種類の影像を定義する為に起動される｡影像型は image create 命令の為の type 引数の特定の値に相当する｡幾つもの数の異なる影像の型が実在するかもしれない､又､新しい型は Tk_CreateImageType を呼ぶことにより動的に定義されるかもしれない｡譬えば､２色の画素地図に関する１つの型があるかも知れず､多色影像の為のもの､デイザ影像の為のもの､映像のためのもの､その他｡ Tk_CreateImageType is invoked to define a new kind of image. An image type corresponds to a particular value of the type argument for the image create command. There may exist any number of different image types, and new types may be defined dynamically by calling Tk_CreateImageType. For example, there might be one type for 2-color bitmaps, another for multi-color images, another for dithered images, another for video, and so on.

新しい影像型を実装する命令符号は影像管理譜と呼ばれる｡それは手続函数と三つの異なる種類のデータ構造から構成される｡第１のデータ構造は Tk_ImageType 構造であって､それは影像型の名前とこの型の影像を扱う影像管理譜によって提供された５つの手続函数へのポインターから構成される: The code that implements a new image type is called an image manager. It consists of a collection of procedures plus three different kinds of data structures. The first data structure is a Tk_ImageType structure, which contains the name of the image type and pointers to five procedures provided by the image manager to deal with images of this type:

    typedef struct Tk_ImageType {
        const char *name;
        Tk_ImageCreateProc *createProc;
        Tk_ImageGetProc *getProc;
        Tk_ImageDisplayProc *displayProc;
        Tk_ImageFreeProc *freeProc;
        Tk_ImageDeleteProc *deleteProc;
    } Tk_ImageType;

この構造の欄は後にこの見出しの子供の節に記述される｡ The fields of this structure will be described in later subsections of this entry.

影像管理譜に取扱われる第２の主データ構造は影像管理譜と呼ばれる; それは特定の影像に関する全体の情報を含む､譬えば image create 命令内に指定された構成設定指示項目の値の如し｡通常それぞれの image create 命令の発動のためのこれらの構造の一つが存在する｡ The second major data structure manipulated by an image manager is called an image model; it contains overall information about a particular image, such as the values of the configuration options specified in an image create command. There will usually be one of these structures for each invocation of the image create command.

影像に関連する第３のデータ構造は影像実現値である｡特定の部品内の影像の夫々の用途のための構造の一つが通常存在することになる｡一つの影像について､多数の部品内で同時に､又は､同じ部品内に多数回現れることが可能である｡更に､異なる画面や表示器上に異なる実現値もありえる｡影像実現値データ構造は､色や図表の再表示の為の状況の様な実現値から実現値に変化するかもしれないことを記述する｡部品や画布品目の為に指定された夫々の -image 指示項目の為に通常一つの実現値構造が存在する｡ The third data structure related to images is an image instance. There will usually be one of these structures for each usage of an image in a particular widget. It is possible for a single image to appear simultaneously in multiple widgets, or even multiple times in the same widget. Furthermore, different instances may be on different screens or displays. The image instance data structure describes things that may vary from instance to instance, such as colors and graphics contexts for redisplay. There is usually one instance structure for each -image option specified for a widget or canvas item.

次の小節では Tk_ImageType の欄の更なる詳細を記述する｡ The following subsections describe the fields of a Tk_ImageType in more detail.

#### 名前 NAME

typePtr->name は影像型の為の名前を提供する｡一度 Tk_CreateImageType が戻ると､この名前は image create 命令の中で新しい型の影像を作成する為に使われる｡もし既にこの名前の影像型が実在する場合､新しい影像型は古いものに置換わる｡ typePtr->name provides a name for the image type. Once Tk_CreateImageType returns, this name may be used in image create commands to create images of the new type. If there already existed an image type by this name then the new image type replaces the old one.

#### CREATEPROC

typePtr->createProc は､何時であれ､新しい型の影像を作成する為に image create が起動される為に､ Tk を呼出す為の手続函数の番地を提供する｡ typePtr->createProc は次の原型に適合しなくてはならない: typePtr->createProc provides the address of a procedure for Tk to call whenever image create is invoked to create an image of the new type. typePtr->createProc must match the following prototype:

    typedef int Tk_ImageCreateProc(
            Tcl_Interp *interp,
            const char *name,
            int objc,
            Tcl_Obj *const objv[],
            const Tk_ImageType *typePtr,
            Tk_ImageMaster model,
            ClientData *modelDataPtr);

interp 引数はその中で image 命令が起動される解釈実行機能であり､ name は新しい影像の為の名前であり､それは image 命令内で明示的に指定されるか､ image 命令により自動的に発生される｡ objc と objv 引数は､新しい影像の為の全ての構成設定指示項目( image の後の引数の全ての名前)を記述する｡ master 引数は字句であり､この影像に関する Tk の情報を参照する; 影像管理譜は Tk_ImageChanged 手続函数を起動する時､この字句を Tk に返さねばならない｡典型的には､ createProc は objc と objv を解析し､新しい影像の為に､影像集約データ構造を作成する｡ createProc は､任意の１語値を *modelDataPtr に保存し､他の回収が起動された時､影像管理譜に渡し戻すことになる｡典型的にはその値はその影像の集約データ構造へのポインターである｡ The interp argument is the interpreter in which the image command was invoked, and name is the name for the new image, which was either specified explicitly in the image command or generated automatically by the image command. The objc and objv arguments describe all the configuration options for the new image (everything after the name argument to image). The model argument is a token that refers to Tk's information about this image; the image manager must return this token to Tk when invoking the Tk_ImageChanged procedure. Typically createProc will parse objc and objv and create an image model data structure for the new image. createProc may store an arbitrary one-word value at *modelDataPtr, which will be passed back to the image manager when other callbacks are invoked. Typically the value is a pointer to the model data structure for the image.

createProc は不都合に遭遇した場合､不都合伝言文を解釈実行機能内に残し TCL_ERROR を返す; それ以外は TCL_OK を返す｡ If createProc encounters an error, it should leave an error message in the interpreter result and return TCL_ERROR; otherwise it should return TCL_OK.

createProc は影像の寸法を設定する為に又最初の再表示を要求する為に Tk_ImageChanged を呼ぶべきである｡ createProc should call Tk_ImageChanged in order to set the size of the image and request an initial redisplay.

#### GETPROC

typePtr->getProc は､何時であれ､特定の影像を使う為に部品が Tk_GetImage を呼ぶときに､起動される｡この手続函数は次の原型に適合しなくてはならない: typePtr->getProc is invoked by Tk whenever a widget calls Tk_GetImage to use a particular image. This procedure must match the following prototype:

    typedef ClientData Tk_ImageGetProc(
            Tk_Window tkwin,
            ClientData modelData);

tkwin 引数は､その中で影像が使われる窓を識別し､ modelData は影像の集約が作成された時に createProc によって返された値である｡ getProc は通常､与えられた窓内に表示される為に必要な原資のようなものを含む新しい現実値の為のデータ構造を作成する｡ getProc は実現値の為の１語字句を返す､それは典型的には実現値データ構造の番地である｡Tk はこの値をその displayProc と freeProc 手続函数を起動する時に影像に戻す｡ The tkwin argument identifies the window in which the image will be used and modelData is the value returned by createProc when the image model was created. getProc will usually create a data structure for the new instance, including such things as the resources needed to display the image in the given window. getProc returns a one-word token for the instance, which is typically the address of the instance data structure. Tk will pass this value back to the image manager when invoking its displayProc and freeProc procedures.

#### DISPLAYPROC

typePtr->displayProc は､何時であれ､影像が表示されることが必要な時(即ち､何時であれ､部品が Tk_RedrawImage を呼ぶとき)､ Tk によって起動される｡ displayProc は次の原型に適合しなくてはならない: typePtr->displayProc is invoked by Tk whenever an image needs to be displayed (i.e., whenever a widget calls Tk_RedrawImage). displayProc must match the following prototype:

    typedef void Tk_ImageDisplayProc(
            ClientData instanceData,
            Display *display,
            Drawable drawable,
            int imageX,
            int imageY,
            int width,
            int height,
            int drawableX,
            int drawableY);

instanceData は実現値が作成された時に getProc によって返される値と同じである｡ display and drawable は影像を表示する場所を指し示す; drawable は getProc に指定された窓よりも画素地図であるかもしれない(これはよく起る､理由は大部分の部品は滑らかな視覚効果を得る為に再表示を二重に保存するから)｡ imageX, imageY, width, and height は再表示されるべき影像の領域を識別する｡この領域は常に､最も最近の Tk_ImageChanged.への呼出しのなかで指定された影像の寸法の内部にある｡ drawableX and drawableY は影像が表示されるべき drawable 内の位置を指し示す; displayProc は影像の与えられた領域を表示して､影像内の点(imageX, imageY)が drawable.内の(drawableX, drawableY)に現れる様にする｡ The instanceData will be the same as the value returned by getProc when the instance was created. display and drawable indicate where to display the image; drawable may be a pixmap rather than the window specified to getProc (this is usually the case, since most widgets double-buffer their redisplay to get smoother visual effects). imageX, imageY, width, and height identify the region of the image that must be redisplayed. This region will always be within the size of the image as specified in the most recent call to Tk_ImageChanged. drawableX and drawableY indicate where in drawable the image should be displayed; displayProc should display the given region of the image so that point (imageX, imageY) in the image appears at (drawableX, drawableY) in drawable.

#### FREEPROC

typePtr->freeProc は､影像実現値が解放される時に､ Tk が起動する手続の番地を含む(即ち､ Tk_FreeImage が起動される時)｡これは､譬えば､部品が削除された時や画素内の影像品目が削除された時､又は､部品内の影像が表示された時､または画素品目が変化した時に生じる｡ freeProc は次の原型に適合しなくてはならない: typePtr->freeProc contains the address of a procedure that Tk will invoke when an image instance is released (i.e., when Tk_FreeImage is invoked). This can happen, for example, when a widget is deleted or a image item in a canvas is deleted, or when the image displayed in a widget or canvas item is changed. freeProc must match the following prototype:

    typedef void Tk_ImageFreeProc(
            ClientData instanceData,
            Display *display);

instanceData は実現値が作成された時に getProc によって返された値と同じである､又､ display は実現値の為の窓を含む表示である｡ freeProc は影像実現値に結合したどの原資も解放する､理由はその実現値は再び使われることはないから｡ The instanceData will be the same as the value returned by getProc when the instance was created, and display is the display containing the window for the instance. freeProc should release any resources associated with the image instance, since the instance will never be used again.

#### DELETEPROC

typePtr->deleteProc は､影像実現値が解放される時に､ Tk が起動する手続である｡(即ち､ image delete 命令が起動される時)｡ deleteProc を起動する前に Tk は夫々の影像の実現値の為に freeProc を起動する｡ deleteProc は次の原型に適合しなくてはならない: typePtr->deleteProc is a procedure that Tk invokes when an image is being deleted (i.e. when the image delete command is invoked). Before invoking deleteProc Tk will invoke freeProc for each of the image's instances. deleteProc must match the following prototype:

    typedef void Tk_ImageDeleteProc(
            ClientData modelData);

modelData 引数は実現値が作成された時に createProc によって *modelDataPtr 内に保存された値と同じである｡ deleteProc は影像に結合したどの原資も解放する｡ The modelData argument will be the same as the value stored in *modelDataPtr by createProc when the image was created. deleteProc should release any resources associated with the image.

### TK_GETIMAGEMODELDATA

手続函数 Tk_GetImageMasterData は影像に関する情報を取り出す為に起動されるかもしれない｡譬えば､影像管理譜はこの手続函数を影像の為の影像集約データを据えるために使うことができる｡もし interp によって与えられる解釈実行機能内に name の名前の影像が実在する場合､ *typePtrPtr は影像の為の型情報によって満たされ(影像型が登録された時 Tk_CreateImageType に渡された typePtr 値)､返り値は､影像が作成された時に createProc によって返された ClientData 値である(これは､典型的には影像集約データ構造へのポインターである)｡この様な影像が実在しない時は NULL が返され､ NULL は *typePtrPtr の箇所に保存される｡ The procedure Tk_GetImageMasterData may be invoked to retrieve information about an image. For example, an image manager can use this procedure to locate its image model data for an image. If there exists an image named name in the interpreter given by interp, then *typePtrPtr is filled in with type information for the image (the typePtr value passed to Tk_CreateImageType when the image type was registered) and the return value is the ClientData value returned by the createProc when the image was created (this is typically a pointer to the image model data structure). If no such image exists then NULL is returned and NULL is stored at *typePtrPtr.

Tk_GetImageModelData is synonym for Tk_GetImageMasterData

### 遺産の対話機能の運営 LEGACY INTERFACE SUPPORT

Tk 8.2 とそれ以前は Tk_ImageCreateProc の定義は互換性が無く､異なっていた､次の原型に従っていた: In Tk 8.2 and earlier, the definition of Tk_ImageCreateProc was incompatibly different, with the following prototype:

    typedef int Tk_ImageCreateProc(
            Tcl_Interp *interp,
            char *name,
            int argc,
            char **argv,
            Tk_ImageType *typePtr,
            Tk_ImageMaster model,
            ClientData *modelDataPtr);

その様な時期の遺産算譜と外部函数は依然､古い相互作用を使った拡張 Tk 影像型を定義した命令符号を含んでいる｡ Tk 冒頭ファイルは､もし符号命令が USE_OLD_IMAGE に定義されたマクロを伴って機械語翻訳されている場合､依然この遺産的相互作用を運営している｡ Legacy programs and libraries dating from those days may still contain code that defines extended Tk image types using the old interface. The Tk header file will still support this legacy interface if the code is compiled with the macro USE_OLD_IMAGE defined.

Tk_ImageModel は Tk_ImageMaster の類義語である Tk_ImageModel is synonym for Tk_ImageMaster

USE_OLD_IMAGE が遺産運営を可能にしている時は､機能譜 Tk_InitImageArgs が使われているかを確認されたい｡これは stub-可能を作成する為に使われる移行道具類であり､それは Tk 8.1 以降の全ての版を含む解釈実行機能に組込むことができる｡ Tk 8.5 は最早この機能譜を提供せず､代りにこの機能譜を呼ぶどの様な試みも空注釈に変換するマクロを使う｡遺産的相互作用経由で拡張された影像型を提供するどの様な stub-可能拡張も､ Tk 8.5 冒頭情報に対して機械語翻訳され Tk 8.5 stub 外部函数に連結されたものは､ Tk 8.5 以降のみの解釈実行機能に組込み可能のファイルを産出する; これは通常の stub-両立規則である｡もし開発者がその様な符号命令から Tk 8.4 以前の解釈実行機能に組込み可能のファイルを発生させる必要がある場合､ Tk 8.4 冒頭情報とその様に振舞う stub 外部函数を使う必要がある｡ When the USE_OLD_IMAGE legacy support is enabled, you may see the routine Tk_InitImageArgs in use. This was a migration tool used to create stub-enabled extensions that could be loaded into interps containing all versions of Tk 8.1 and later. Tk 8.5 no longer provides this routine, but uses a macro to convert any attempted calls of this routine into an empty comment. Any stub-enabled extension providing an extended image type via the legacy interface that is compiled against Tk 8.5 headers and linked against the Tk 8.5 stub library will produce a file that can be loaded only into interps with Tk 8.5 or later; that is, the normal stub-compatibility rules. If a developer needs to generate from such code a file that is loadable into interps with Tk 8.4 or earlier, they must use Tk 8.4 headers and stub libraries to do so.

今日書かれる新しい命令符号は遺産の対話機能を使うようにすべきではない｡ Tk 9 では対応が終わるように期待して｡ Any new code written today should not make use of the legacy interfaces. Expect their support to go away in Tk 9.

### SEE ALSO

Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage

### KEYWORDS

image manager, image type, instance, model
Copyright © 1994 The Regents of the University of California.
Copyright © 1994-1997 Sun Microsystems, Inc.