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

### 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_CreatePhotoImageFormat — 写真影像の為の新しいファイル書式を定義する　 define new file format for photo images
  SYNOPSIS
    #include <tk.h>
    Tk_CreatePhotoImageFormat(formatPtr)
  引数 ARGUMENTS
    const Tk_PhotoImageFormat *formatPtr (入力in)
  説明 DESCRIPTION
  NAME
  FILEMATCHPROC
  STRINGMATCHPROC
  FILEREADPROC
  STRINGREADPROC
  FILEWRITEPROC
  STRINGWRITEPROC
  LEGACY INTERFACE SUPPORT
  SEE ALSO
  KEYWORDS

### NAME

Tk_CreatePhotoImageFormat — 写真影像の為の新しいファイル書式を定義する　 define new file format for photo images

### SYNOPSIS

#include <tk.h>
Tk_CreatePhotoImageFormat(formatPtr)

### 引数 ARGUMENTS

const Tk_PhotoImageFormat *formatPtr (入力in)
  新しいファイル書式を定義する構造｡ Structure that defines the new file format.

### 説明 DESCRIPTION

Tk_CreatePhotoImageFormat は写真影像の使用の為の影像データの新しいファイル形式を定義するために起動される｡影像ファイル形式の実装の符号命令は影像ファイル形式操作子､又は短的に操作子から呼出される｡写真影像符号はファイルからの読み書きに使える操作子のリストを維持する｡ある操作子は文字列からの影像データの読出し､又は影像データから文字列形式への移送を運営している｡使用者は -format 影像構成設定指示項目を伴うどれかの操作子か､写真影像副命令の read and write を使う為の -format 追加附加子かを指定できる｡ Tk_CreatePhotoImageFormat is invoked to define a new file format for image data for use with photo images. The code that implements an image file format is called an image file format handler, or handler for short. The photo image code maintains a list of handlers that can be used to read and write data to or from a file. Some handlers may also support reading image data from a string or converting image data to a string format. The user can specify which handler to use with the -format image configuration option or the -format option to the read and write photo image subcommands.

影像ファイル形式操作子は手続函数及び Tk_PhotoImageFormat から構成される､後者は影像ファイル形式と､ファイルとその形式の文字列を取扱うために提供された六つの手続函数から構成される｡ Tk_PhotoImageFormat 構造は次の欄を含む: An image file format handler consists of a collection of procedures plus a Tk_PhotoImageFormat structure, which contains the name of the image file format and pointers to six procedures provided by the handler to deal with files and strings in this format. The Tk_PhotoImageFormat structure contains the following fields:

    typedef struct Tk_PhotoImageFormat {
        const char *name;
        Tk_ImageFileMatchProc *fileMatchProc;
        Tk_ImageStringMatchProc *stringMatchProc;
        Tk_ImageFileReadProc *fileReadProc;
        Tk_ImageStringReadProc *stringReadProc;
        Tk_ImageFileWriteProc *fileWriteProc;
        Tk_ImageStringWriteProc *stringWriteProc;
    } Tk_PhotoImageFormat;

その操作子は全ての六つの手続函数の実装を提供する必要はない｡譬えば､文字列データを処理する手続函数は､その中に影像データが２進で保存され､従って零文字を含む形式を提供しないので､零文字を保有しておけばよい｡もしどの手続函数も実装されない場合､相当する Tk_PhotoImageFormat 構造内のポインターは NULL に設定される｡操作子は fileReadProc 手続函数を提供する場合は fileMatchProc 手続函数を提供しなければならない､又､ stringReadProc 手続函数を提供する場合は stringMatchProc 手続函数を提供しなければならない｡ The handler need not provide implementations of all six procedures. For example, the procedures that handle string data would not be provided for a format in which the image data are stored in binary, and could therefore contain null characters. If any procedure is not implemented, the corresponding pointer in the Tk_PhotoImageFormat structure should be set to NULL. The handler must provide the fileMatchProc procedure if it provides the fileReadProc procedure, and the stringMatchProc procedure if it provides the stringReadProc procedure.

#### NAME

formatPtr->name は影像型に関する名前を提供する｡一たび Tk_CreatePhotoImageFormat から帰るとこの名前は -format 影像構成設定指示項目内と副命令の指示項目で使用できる｡写真影像(photo(n))についての取扱説明書の頁に如何に影像ファイル形式がその名前と -format 指示項目に与える値を基に選択されるかを記述する｡ formatPtr->name の最初の文字は ASCII の文字揃えの大文字であってはならない(即ち､文字 A-Z の内の一つ)｡この様な名前は遺産的相互作用の運営のみで使用されている(下を参照されたい)｡ formatPtr->name provides a name for the image type. Once Tk_CreatePhotoImageFormat returns, this name may be used in the -format photo image configuration and subcommand option. The manual page for the photo image (photo(n)) describes how image file formats are chosen based on their names and the value given to the -format option. The first character of formatPtr->name must not be an uppercase character from the ASCII character set (that is, one of the characters A-Z). Such names are used only for legacy interface support (see below).

#### FILEMATCHPROC

与えられたファイル内のデータを読むに適した影像ファイル形式操作子について捜索する時に､formatPtr->fileMatchProc は呼出すべき Tk の為の手続函数の番地を提供する｡ formatPtr->fileMatchProc は次の原型に合致しなければならない: formatPtr->fileMatchProc provides the address of a procedure for Tk to call when it is searching for an image file format handler suitable for reading data in a given file. formatPtr->fileMatchProc must match the following prototype:

    typedef int Tk_ImageFileMatchProc(
            Tcl_Channel chan,
            const char *fileName,
            Tcl_Obj *format,
            int *widthPtr,
            int *heightPtr,
            Tcl_Interp *interp);

fileName 引数は chan として読む為に開けた影像データを含むファイルの名前である｡ format 引数は -format 指示項目の為に与えられた値を含むが任意付加子が指定されていない場合は NULL である｡もしファイル内のデータがこの操作子によって運営されている形式で現れると formatPtr->fileMatchProc 手続函数は *widthPtr と *heightPtr の箇所に影像の巾と高さを夫々保存し､ 1.を返すことになり､それ以外の場合は 0.を返す｡ The fileName argument is the name of the file containing the image data, which is open for reading as chan. The format argument contains the value given for the -format option, or NULL if the option was not specified. If the data in the file appears to be in the format supported by this handler, the formatPtr->fileMatchProc procedure should store the width and height of the image in *widthPtr and *heightPtr respectively, and return 1. Otherwise it should return 0.

#### STRINGMATCHPROC

与えられた文字列からデータを読むに適した影像ファイル形式操作子について捜索する時に､formatPtr->stringMatchProc は呼出すべき Tk の為の手続函数の番地を提供する｡ formatPtr->stringMatchProc provides the address of a procedure for Tk to call when it is searching for an image file format handler for suitable for reading data from a given string. formatPtr->stringMatchProc must match the following prototype:

    typedef int Tk_ImageStringMatchProc(
            Tcl_Obj *data,
            Tcl_Obj *format,
            int *widthPtr,
            int *heightPtr,
            Tcl_Interp *interp);

data 引数は影像データを含む対象を指す｡ format 引数は -format 指示項目の為に与えられた値を含むが任意付加子が指定されていない場合は NULL である｡もし文字列内のデータがこの操作子によって運営されている形式で現れると formatPtr->stringMatchProc 手続函数は *widthPtr and *heightPtr の箇所に影像の巾と高さを夫々保存し､ 1 を返すことになり､それ以外の場合は 0 を返す｡ The data argument points to the object containing the image data. The format argument contains the value given for the -format option, or NULL if the option was not specified. If the data in the string appears to be in the format supported by this handler, the formatPtr->stringMatchProc procedure should store the width and height of the image in *widthPtr and *heightPtr respectively, and return 1. Otherwise it should return 0.

#### FILEREADPROC

影像ファイルから写真影像にデータを読む為に､formatPtr->fileReadProc は呼出すべき Tk の為の手続函数の番地を提供する｡ formatPtr->fileReadProc は次の原型に合致しなければならない: formatPtr->fileReadProc provides the address of a procedure for Tk to call to read data from an image file into a photo image. formatPtr->fileReadProc must match the following prototype:

    typedef int Tk_ImageFileReadProc(
            Tcl_Interp *interp,
            Tcl_Channel chan,
            const char *fileName,
            Tcl_Obj *format,
            PhotoHandle imageHandle,
            int destX, int destY,
            int width, int height,
            int srcX, int srcY);

interp 引数はその中で､影像データを読む為に起動される解釈実行機能である; それは不都合を報告する為に使われる｡影像データは chan として読む為に開けた fileName と名付けたファイルにありる｡ format 引数は -format 指示項目の為に与えられた値を含むが任意付加子が指定されていない場合は NULL である｡ファイル内のデータ､又はその副影像は操作子 imageHandle によって識別された写真影像に読込まれる｡ファイル内の副影像はその寸法が 巾 x 高さ でありその左上隅の座標は(srcX,srcY)である｡それは写真影像内に Tk_PhotoPutBlock 手続函数によって､その左上隅が座標(destX,destY)に保存される｡返り値は標準 Tcl 返り値である｡ The interp argument is the interpreter in which the command was invoked to read the image; it should be used for reporting errors. The image data is in the file named fileName, which is open for reading as chan. The format argument contains the value given for the -format option, or NULL if the option was not specified. The image data in the file, or a subimage of it, is to be read into the photo image identified by the handle imageHandle. The subimage of the data in the file is of dimensions width x height and has its top-left corner at coordinates (srcX,srcY). It is to be stored in the photo image with its top-left corner at coordinates (destX,destY) using the Tk_PhotoPutBlock procedure. The return value is a standard Tcl return value.

#### STRINGREADPROC

文字列から写真影像にデータを読む為に､formatPtr->stringReadProc は呼出すべき Tk の為の手続函数の番地を提供する｡ formatPtr->stringReadProc は次の原型に合致しなければならない: formatPtr->stringReadProc provides the address of a procedure for Tk to call to read data from a string into a photo image. formatPtr->stringReadProc must match the following prototype:

    typedef int Tk_ImageStringReadProc(
            Tcl_Interp *interp,
            Tcl_Obj *data,
            Tcl_Obj *format,
            PhotoHandle imageHandle,
            int destX, int destY,
            int width, int height,
            int srcX, int srcY);

interp 引数はその中で､影像を読む為に起動される解釈実行機能である; それは不都合を報告する為に使われる｡データ引数は対象形式の影像データを指す｡ format 引数は -format 指示項目の為に与えられた値を含むが任意付加子が指定されていない場合は NULL である｡文字列内の影像データ､又はその副影像は操作子 imageHandle によって識別された写真影像に読込まれる｡ファイル内の副影像はその寸法が 巾 x 高さ でありその左上隅の座標は(srcX,srcY)である｡それは写真影像内に Tk_PhotoPutBlock 手続函数によって､その左上隅が座標(destX,destY)に保存される｡返り値は標準 Tcl 返り値である｡ The interp argument is the interpreter in which the command was invoked to read the image; it should be used for reporting errors. The data argument points to the image data in object form. The format argument contains the value given for the -format option, or NULL if the option was not specified. The image data in the string, or a subimage of it, is to be read into the photo image identified by the handle imageHandle. The subimage of the data in the string is of dimensions width x height and has its top-left corner at coordinates (srcX,srcY). It is to be stored in the photo image with its top-left corner at coordinates (destX,destY) using the Tk_PhotoPutBlock procedure. The return value is a standard Tcl return value.

#### FILEWRITEPROC

写真影像からファイルにデータを書く為に､formatPtr->fileWriteProc は呼出すべき Tk の為の手続函数の番地を提供する｡ formatPtr->fileWriteProc は次の原型に合致しなければならない: formatPtr->fileWriteProc provides the address of a procedure for Tk to call to write data from a photo image to a file. formatPtr->fileWriteProc must match the following prototype:

    typedef int Tk_ImageFileWriteProc(
            Tcl_Interp *interp,
            const char *fileName,
            Tcl_Obj *format,
            Tk_PhotoImageBlock *blockPtr);

interp 引数はその中で､影像を書く為に起動される解釈実行機能である; それは不都合を報告する為に使われる｡書くべき影像データは記憶域の中にあり､ blockPtr によって指される Tk_PhotoImageBlock 構造によって記述される; 詳細は取扱説明書の FindPhoto(3) を参照されたい｡ fileName 引数はそこにデータを書くべきファイルの名前を与える文字列を指す｡ format 引数は -format 指示項目の為に与えられた値を含むが任意付加子が指定されていない場合は NULL である｡形式文字列は､形式の名前の後に臨時の文字を含むかもしれない｡それが適切な場合は､ formatPtr->fileWriteProc 手続函数は影像ファイルに関する更なる詳細を指定する為にこれ等の文字を解釈するかもしれない｡返り値は標準 Tcl 返り値である｡ The interp argument is the interpreter in which the command was invoked to write the image; it should be used for reporting errors. The image data to be written are in memory and are described by the Tk_PhotoImageBlock structure pointed to by blockPtr; see the manual page FindPhoto(3) for details. The fileName argument points to the string giving the name of the file in which to write the image data. The format argument contains the value given for the -format option, or NULL if the option was not specified. The format string can contain extra characters after the name of the format. If appropriate, the formatPtr->fileWriteProc procedure may interpret these characters to specify further details about the image file. The return value is a standard Tcl return value.

#### STRINGWRITEPROC

写真影像から文字列にデータを変換する為に､formatPtr->stringWriteProc は呼出すべき Tk の為の手続函数の番地を提供する｡ formatPtr->stringWriteProc は次の原型に合致しなければならない: formatPtr->stringWriteProc provides the address of a procedure for Tk to call to translate image data from a photo image into a string. formatPtr->stringWriteProc must match the following prototype:

    typedef int Tk_ImageStringWriteProc(
            Tcl_Interp *interp,
            Tcl_Obj *format,
            Tk_PhotoImageBlock *blockPtr);

interp 引数はその中で､影像を変換する為に起動される解釈実行機能である; それは不都合を報告する為に使われる｡変換されるべき影像データは記憶域の中にあり､ blockPtr によって指される Tk_PhotoImageBlock 構造によって記述される; 詳細は取扱説明書の FindPhoto(3) を参照されたい｡文字列に関するデータは解釈実行機能の interp 結果に入れられる｡ format 引数は -format 指示項目の為に与えられた値を含むが任意付加子が指定されていない場合は NULL である｡形式文字列は､形式の名前の後に臨時の文字を含むかもしれない｡それが適切な場合は､ formatPtr->stringWriteProc 手続函数は影像ファイルに関する更なる詳細を指定する為にこれ等の文字を解釈するかもしれない｡返り値は標準 Tcl 返り値である｡ The interp argument is the interpreter in which the command was invoked to convert the image; it should be used for reporting errors. The image data to be converted are in memory and are described by the Tk_PhotoImageBlock structure pointed to by blockPtr; see the manual page FindPhoto(3) for details. The data for the string should be put in the interpreter interp result. The format argument contains the value given for the -format option, or NULL if the option was not specified. The format string can contain extra characters after the name of the format. If appropriate, the formatPtr->stringWriteProc procedure may interpret these characters to specify further details about the image file. The return value is a standard Tcl return value.

### LEGACY INTERFACE SUPPORT

Tk 8.2 以前は Tk_PhotoImageFormat 構造の欄に保存された全ての函数ポインター型の定義は互換性が異なる｡当時の遺産の算譜と外部函数は依然古い相互作用機能を使って拡張 Tk 写真影像形式を定義する命令符号に含まれている｡もし符号がマクロ USE_OLD_IMAGE 定義と共に機械語翻訳された場合には､ Tk 冒頭ファイルは依然この遺産相互作用機能を運営している｡もし formatPtr->name の最初の文字が ASCII 大文字(A-Z)､且つ型不整合を許容するために明示的な casts が使われている場合､代わりに遺産相互作用機能が使われる｡譬えば､ In Tk 8.2 and earlier, the definition of all the function pointer types stored in fields of a Tk_PhotoImageFormat struct were incompatibly different. Legacy programs and libraries dating from those days may still contain code that defines extended Tk photo image formats 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. Alternatively, the legacy interfaces are used if the first character of formatPtr->name is an uppercase ASCII character (A-Z), and explicit casts are used to forgive the type mismatch. For example,

    static Tk_PhotoImageFormat myFormat = {
        "MyFormat",
        (Tk_ImageFileMatchProc *) FileMatch,
        NULL,
        (Tk_ImageFileReadProc *) FileRead,
        NULL,
        NULL,
        NULL
    };

は最小の Tk_PhotoImageFormat を定義する､それは､ FileMatch and FileRead が Tk 8.2 以前の遺産的相互作用機能に従って書かれている場合に､ファイルを読む能力のみを提供する｡ would define a minimal Tk_PhotoImageFormat that operates provide only file reading capability, where FileMatch and FileRead are written according to the legacy interfaces of Tk 8.2 or earlier.

どの stub-可能拡張も USE_OLD_IMAGE マクロによって遺産相互作用機能経由の拡張形式の写真影像を提供する､それは Tk 8.5 冒頭情報に対して機械語翻訳され Tk 8.5 stub 外部函数に連結され､ Tk 8.5 以降の解釈実行機能にのみ組込み可能である; 即ち､通常の stub-互換性規則通りである｡もし開発者が Tk 8.4 依然の解釈実行機能に組込み可能である様なファイルの命令符号を発生する必要がある場合､ Tk 8.4 冒頭情報と､ stub 外部函数を使い同様にする必要がある｡ Any stub-enabled extension providing an extended photo image format via the legacy interface enabled by the USE_OLD_IMAGE macro 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_FindPhoto, Tk_PhotoPutBlock

### KEYWORDS

photo image, image file
Copyright © 1994 The Australian National University
Copyright © 1994-1997 Sun Microsystems, Inc.