## Tcl9.0.3/Tk9.0.3 Documentation > Tk C API > SetOptions

### 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_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions — 構成設定項目の処理　 process configuration options
  SYNOPSIS
    #include <tk.h>
    Tk_OptionTable
    Tk_CreateOptionTable(interp, templatePtr)
    Tk_DeleteOptionTable(optionTable)
    int
    Tk_InitOptions(interp, recordPtr, optionTable, tkwin)
    int
    Tk_SetOptions(interp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr)
    Tk_FreeSavedOptions(savedPtr)
    Tk_RestoreSavedOptions(savedPtr)
    Tcl_Obj *
    Tk_GetOptionValue(interp, recordPtr, optionTable, namePtr, tkwin)
    Tcl_Obj *
    Tk_GetOptionInfo(interp, recordPtr, optionTable, namePtr, tkwin)
    Tk_FreeConfigOptions(recordPtr, optionTable, tkwin)
  引数 ARGUMENTS
    Tcl_Interp *interp (入力in)
    const Tk_OptionSpec *templatePtr (入力in)
    Tk_OptionTable optionTable (入力in)
    void *recordPtr (入出力in/out)
    Tk_Window tkwin (入力in)
    Tcl_Size objc (入力in)
    Tcl_Obj *const *objv (入力in)
    Tk_SavedOptions *savePtr (出力out)
    int *maskPtr (出力out)
    Tk_SavedOptions *savedPtr (入出力in/out)
    Tcl_Obj *namePtr (入力in)
    type name type (入力in)
    field name field (入力in)
  説明 DESCRIPTION
  雛形 TEMPLATES
    TK_OPTION_NULL_OK
    TK_OPTION_DONT_SET_DEFAULT
    TK_OPTION_ENUM_VAR
    TK_OPTION_VAR(type)
    TK_OPTION_ANCHOR
    TK_OPTION_BITMAP
    TK_OPTION_BOOLEAN
    TK_OPTION_BORDER
    TK_OPTION_COLOR
    TK_OPTION_CURSOR
    TK_OPTION_CUSTOM
    TK_OPTION_DOUBLE
    TK_OPTION_END
    TK_OPTION_FONT
    TK_OPTION_INT
    TK_OPTION_INDEX
    TK_OPTION_JUSTIFY
    TK_OPTION_PIXELS
    TK_OPTION_RELIEF
    TK_OPTION_STRING
    TK_OPTION_STRING_TABLE
    TK_OPTION_SYNONYM
    TK_OPTION_WINDOW
  STORAGE MANAGEMENT ISSUES
  OBJOFFSET VS. INTERNALOFFSET
  CUSTOM OPTION TYPES
    clientData
    interp
    Tkwin
    valuePtr
    recordPtr
    internalOffset
    saveInternalPtr
    flags
  KEYWORDS

### NAME

Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions — 構成設定項目の処理　 process configuration options

### SYNOPSIS

#include <tk.h>
Tk_OptionTable
Tk_CreateOptionTable(interp, templatePtr)
Tk_DeleteOptionTable(optionTable)
int
Tk_InitOptions(interp, recordPtr, optionTable, tkwin)
int
Tk_SetOptions(interp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr)
Tk_FreeSavedOptions(savedPtr)
Tk_RestoreSavedOptions(savedPtr)
Tcl_Obj *
Tk_GetOptionValue(interp, recordPtr, optionTable, namePtr, tkwin)
Tcl_Obj *
Tk_GetOptionInfo(interp, recordPtr, optionTable, namePtr, tkwin)
Tk_FreeConfigOptions(recordPtr, optionTable, tkwin)

### 引数 ARGUMENTS

Tcl_Interp *interp (入力in)
  Tcl 解釈実行機能｡大部分の手続函数は不都合伝言文を返す為にのみ之を使う; もし NULL の場合､不都合伝言文は返らない｡Tk_CreateOptionTable の為には値は NULL であってはならない; そこで選択的表が使われるような解釈実行機能を与える｡ A Tcl interpreter. Most procedures use this only for returning error messages; if it is NULL then no error messages are returned. For Tk_CreateOptionTable the value cannot be NULL; it gives the interpreter in which the option table will be used.

const Tk_OptionSpec *templatePtr (入力in)
  運営されている構成設定指示項目を記述する静的情報の配列を指す｡Tk_OptionTable の作成に使われる｡この引数に指されれる情報はTk_OptionTable の寿命のある内は存在し続けなければならない｡ Points to an array of static information that describes the configuration options that are supported. Used to build a Tk_OptionTable. The information pointed to by this argument must exist for the lifetime of the Tk_OptionTable.

Tk_OptionTable optionTable (入力in)
  指示項目表の字句結果｡予め呼ばれた Tk_CreateOptionTable によって返されなければならない｡ Token for an option table. Must have been returned by a previous call to Tk_CreateOptionTable.

void *recordPtr (入出力in/out)
  構成設定指示項目の値が保存されている構造を指す; この記録の欄はTk_SetOptions の様な手続函数に修正されTk_GetOptionValue の様な手続函数に読まれる｡ Points to structure in which values of configuration options are stored; fields of this record are modified by procedures such as Tk_SetOptions and read by procedures such as Tk_GetOptionValue.

Tk_Window tkwin (入力in)
  TK_OPTION_COLOR の様な指示項目の為に､この引数はその指示項目が使われる窓を指し示す｡もしoptionTable が窓に依存しない指示項目を使う場合､この引数にはNULL 値が与えられてもよい｡ For options such as TK_OPTION_COLOR, this argument indicates the window in which the option will be used. If optionTable uses no window-dependent options, then a NULL value may be supplied for this argument.

Tcl_Size objc (入力in)
  objv 内の値の数｡ Number of values in objv.

Tcl_Obj *const *objv (入力in)
  構成設定指示項目を設定する為の命令行引数｡ Command-line arguments for setting configuring options.

Tk_SavedOptions *savePtr (出力out)
  もしNULL でなければ､この引数に指されている構造はどれかの指示項目に修正された古い値が入っており､古い値は Tk_SetOptions 内に不都合が生じると自動的に再保存される｡ If not NULL, the structure pointed to by this argument is filled in with the old values of any options that were modified and old values are restored automatically if an error occurs in Tk_SetOptions.

int *maskPtr (出力out)
  もしNULL でなければ､ maskPtr に指された語が入っており､修正される指示項目の為のビット幅の typeMask 欄が入っている｡ If not NULL, the word pointed to by maskPtr is filled in with the bit-wise OR of the typeMask fields for the options that were modified.

Tk_SavedOptions *savedPtr (入出力in/out)
  修正された指示項目の古い値Tk_SetOptions によって以前に満たされていた構造を指す｡ Points to a structure previously filled in by Tk_SetOptions with old values of modified options.

Tcl_Obj *namePtr (入力in)
  この対象の値は特別の指示項目の名前である｡もしNULL がTk_GetOptionInfo に渡されると全ての指示項目に情報が返される｡Tk_GetOptionValue が呼ばれた時はNULL であってはならない｡ The value of this object is the name of a particular option. If NULL is passed to Tk_GetOptionInfo then information is returned for all options. Must not be NULL when Tk_GetOptionValue is called.

type name type (入力in)
  記録の型の名前｡ The name of the type of a record.

field name field (入力in)
  type 型の記録内の欄の名前｡ The name of a field in records of type type.

### 説明 DESCRIPTION

これらの手続函数はTk 部品の為のものの様な大部分の構成設定指示項目の解析の詳細を扱う｡これ等の手続函数は､運営されている指示項目の記述が与えられて､指示項目の解析の全ての詳細を取扱い､その値を部品や対象に結合した C 構造に保存する｡その手続函数は第１義に Tk 内の部品の為に設計されているが､他の種類の､構成設定された指示項目の対象も使うことができる｡この取扱説明書の残りの頁内では “部品” はその指示項目が制御されている対象を参照する為に使用する; 実際の処､その対象は実際には部品ではないかもしれない｡用語 “部品の記録” はその中に特定の部品又は対象に関する情報が保存される C-水準構造を参照する為に使われる｡ These procedures handle most of the details of parsing configuration options such as those for Tk widgets. Given a description of what options are supported, these procedures handle all the details of parsing options and storing their values into a C structure associated with the widget or object. The procedures were designed primarily for widgets in Tk, but they can also be used for other kinds of objects that have configuration options. In the rest of this manual page “widget” will be used to refer to the object whose options are being managed; in practice the object may not actually be a widget. The term “widget record” is used to refer to the C-level structure in which information about a particular widget or object is stored.

註意すべきは､この様な手続函数を如何に使うかを容易に学ぶ方法は動く用例を見ることである｡Tk では､最も簡単な用例は tkButton.c 内にある部品の釦族の実装である｡他の例は tkSquare.c とtkMenu.c 内にある｡ Note that the easiest way to learn how to use these procedures is to look at a working example. In Tk, the simplest example is the code that implements the button family of widgets, which is in tkButton.c. Other examples are in tkSquare.c and tkMenu.c.

これらの手続函数を使う為に､部品を実装する命令譜は Tk_OptionSpec 構造の静的配列を含まなくてはならない｡これはその級の部品によって運営された種々の指示項目を記述した原型である; それぞれの種類の部品のための別々の原型がある｡その原型はそれぞれの指示項目の名前､その型､その省略時値､部品内の指示項目の値が保存されている場所､の様な情報を含む｡更なる詳細は下の TEMPLATES を参照されたい｡ In order to use these procedures, the code that implements the widget must contain a static array of Tk_OptionSpec structures. This is a template that describes the various options supported by that class of widget; there is a separate template for each kind of widget. The template contains information such as the name of each option, its type, its default value, and where the value of the option is stored in the widget record. See TEMPLATES below for more detail.

構成設定指示項目を効果的に処理する為に､その静的原型は実行時にのみ利用できる追加的な情報が補強されなければならない｡手続函数 Tk_CreateOptionTable は原型からこの動的情報を生成し､静的と動的の両方の情報を記述するTk_OptionTable の字句結果を返す｡譬えば Tk_SetOptions のような他の全ての手続函数は､引数としてTk_OptionTable 字句結果をとる｡典型的には､Tk_CreateOptionTable は特定の部品が最初に生成される時に呼ばれ､その級の全ての部品について結果のTk_OptionTable が将来使はれる｡Tk_OptionTable は､ interp により与えられたTk_CreateOptionTable への引数の､一つの解釈実行機能のみに使われるかもしれない｡指示項目表が最早必要なくなる時､Tk_DeleteOptionTable はその全ての資源を解放する為に呼ばれる｡もし解釈実行機能が削除されるとTcl 解釈実行機能のための全ての指示項目表は自動的に解除される｡ In order to process configuration options efficiently, the static template must be augmented with additional information that is available only at runtime. The procedure Tk_CreateOptionTable creates this dynamic information from the template and returns a Tk_OptionTable token that describes both the static and dynamic information. All of the other procedures, such as Tk_SetOptions, take a Tk_OptionTable token as argument. Typically, Tk_CreateOptionTable is called the first time that a widget of a particular class is created and the resulting Tk_OptionTable is used in the future for all widgets of that class. A Tk_OptionTable may be used only in a single interpreter, given by the interp argument to Tk_CreateOptionTable. When an option table is no longer needed Tk_DeleteOptionTable should be called to free all of its resources. All of the option tables for a Tcl interpreter are freed automatically if the interpreter is deleted.

Tk_InitOptions は無為設定の値を設定する為に新しい部品が生成される時に起動される｡Tk_InitOptions は指示項目の表(optionTable)と､この部品に関する情報を保有する C 構造の部品の記録(recordPtr)へのポインタの為の字句結果を渡される｡Tk_InitOptions は､それぞれの指示項目の為に､適切な無為設定を選択するための適切な表の中の情報を使う､従ってそれは部品記録の中に既に存在するどの記録も上書きして､無為設定の値を直接に部品記録に保存する｡Tk_InitOptions は通常 TCL_OK を返す｡もし､省略時設定値を設定している間に不具合が起った場合は(譬えば省略時設定値が間違っている)､ TCL_ERROR が返され､もし interp がNULL でない場合は不都合伝言文が interp の結果に残される｡その flags 欄に TK_OPTION_DONT_SET_DEFAULT を設定させるどの様な部品の構成設定の為にも､上述の初期設定は完全に省かれる､下記を参照されたい｡ Tk_InitOptions is invoked when a new widget is created to set the default values. Tk_InitOptions is passed a token for an option table (optionTable) and a pointer to a widget record (recordPtr), which is the C structure that holds information about this widget. Tk_InitOptions uses the information in the option table to choose an appropriate default for each option, then it stores the default value directly into the widget record, overwriting any information that was already present in the widget record. Tk_InitOptions normally returns TCL_OK. If an error occurred while setting the default values (e.g., because a default value was erroneous) then TCL_ERROR is returned and an error message is left in interp's result if interp is not NULL. For any widget's configuration option that has TK_OPTION_DONT_SET_DEFAULT set in its flags field, the above initialization is fully skipped, see below.

Tk_SetOptions はTcl 命令内で指定された情報に基き､構成設定指示項目を修正する為に起動される｡その命令は新しい部品を作成するか既存の部品上の指示項目を修正するものであるべきであろう｡ objc と objv 引数はTcl 命令からの引数の値を記述する｡objv は偶数の対象を含まなくてはならない: 各対の第１の対象は指示項目の名前を与え､第２の対象はその指示項目への新しい値を与える｡Tk_SetOptions は optionTable 内からそれぞれの名前を調べ､指示項目の新しい値が optionTable 内の型に適合するかを検査し､確認し､ recordPtr に与えられた部品記録に指示項目の値を保存する｡Tk_SetOptions は通常TCL_OK を返す｡もし不都合が生じると(未知の指示項目名や指示項目値が不適切､の様な)､TCL_ERROR が返され､もしinterp がNULL でない場合は不都合伝言文が interp's の結果に残される｡ Tk_SetOptions is invoked to modify configuration options based on information specified in a Tcl command. The command might be one that creates a new widget, or a command that modifies options on an existing widget. The objc and objv arguments describe the values of the arguments from the Tcl command. Objv must contain an even number of objects: the first object of each pair gives the name of an option and the second object gives the new value for that option. Tk_SetOptions looks up each name in optionTable, checks that the new value of the option conforms to the type in optionTable, and stores the value of the option into the widget record given by recordPtr. Tk_SetOptions normally returns TCL_OK. If an error occurred (such as an unknown option name or an illegal option value) then TCL_ERROR is returned and an error message is left in interp's result if interp is not NULL.

Tk_SetOptions は更に二つの特徴を有する｡第１､もし maskPtr 引数が NULL でない場合､修正された指示項目に関する情報が詰まった整数値を指す｡Tk_CreateOptionTable に渡された原型内のそれぞれの指示項目について typeMask 欄がある｡この欄のビットは部品を実装した命令譜によって定義される; 譬えば､それぞれのビットは個別の構成設定指示項目に対応している｡或は､ビットは機能的に使われるかもしれない｡譬えば､一つのビットが再表示に使用されるかもしれず: 表示される部品を要求する指示項目の変更の如く､部品の表示に影響を与える全ての指示項目はその様なビットの組を有するかもしれない｡他のビットは再計算されるべき部品の幾何を指し示し､同様に続くかもしれない｡Tk_SetOptions は修正された全ての指示項目の typeMask 欄を､論理的或は､で結合し､ *maskPtr に値を返す､呼出し者はこの情報を自身の最適化に使うことができ､譬えば､修正された指示項目が部品の外観に影響を与えない場合は部品を再表示しない｡ Tk_SetOptions has two additional features. First, if the maskPtr argument is not NULL then it points to an integer value that is filled in with information about the options that were modified. For each option in the template passed to Tk_CreateOptionTable there is a typeMask field. The bits of this field are defined by the code that implements the widget; for example, each bit might correspond to a particular configuration option. Alternatively, bits might be used functionally. For example, one bit might be used for redisplay: all options that affect the widget's display, such that changing the option requires the widget to be redisplayed, might have that bit set. Another bit might indicate that the geometry of the widget must be recomputed, and so on. Tk_SetOptions OR's together the typeMask fields from all the options that were modified and returns this value at *maskPtr; the caller can then use this information to optimize itself so that, for example, it does not redisplay the widget if the modified options do not affect the widget's appearance.

第２の追加的特長は不都合からの回復である｡指示項目の構成設定処理課程に不都合が生じた場合､この特徴により全ての構成設定指示項目の以前の値を取戻すことができる｡不都合は､Tk_SetOptions 内の指示項目処理課程でもその後の呼出し側でも起り得る｡多くの場合呼出し側では､Tk_SetOptions から戻った後に追加的処理を行う; 譬えば､指示項目の値を変数の追跡に設定して､変数が単純変数から配列に替わる不都合を検出するかもしれない｡不都合からの回復はTk_SetOptions の savePtr 引数に非-NULL値を渡すことにより可能になる; 之は呼出し側の棚上の非初期化Tk_SavedOptions 構造へのポインターであろう｡Tk_SetOptions は手続函数により修正されたどの指示項目の古い値に関する情報により savePtr に指される構造も上書きする｡Tk_SetOptions が成功裡に返ると呼出し側は二つのうちの一つの方法で構造を使用する｡呼出し側は何も不都合なしに新しい指示項目の処理を完了した場合は､構造をTk_FreeSavedOptions に渡し､旧値が解放できるようにしなければならない｡指示項目の処理の間に不都合を検出した場合は､構造を Tk_RestoreSavedOptions を渡し､それにより古い値を部品の記録に写し戻し新しい値を解除するべきである｡もしTk_SetOptions が不都合を検出すると既に修正されたどの指示項目も自動的に元に戻され､ *savePtr は空状態に残される: 呼出し側からはTk_FreeSavedOptions も Tk_RestoreSavedOptions も呼ぶ必要はない｡もしTk_SetOptions のsavePtr 引数がNULL の場合､Tk_SetOptions は指示項目に新しい値を設定する時にそれぞれの古い指示項目値をすぐさま解放する｡この場合､もし第３の指示項目内で不都合が生じると､初めの二つの指示項目の古い値は回復する事はできない｡ The second additional feature of Tk_SetOptions has to do with error recovery. If an error occurs while processing configuration options, this feature makes it possible to restore all the configuration options to their previous values. Errors can occur either while processing options in Tk_SetOptions or later in the caller. In many cases the caller does additional processing after Tk_SetOptions returns; for example, it might use an option value to set a trace on a variable and may detect an error if the variable is an array instead of a scalar. Error recovery is enabled by passing in a non-NULL value for the savePtr argument to Tk_SetOptions; this should be a pointer to an uninitialized Tk_SavedOptions structure on the caller's stack. Tk_SetOptions overwrites the structure pointed to by savePtr with information about the old values of any options modified by the procedure. If Tk_SetOptions returns successfully, the caller uses the structure in one of two ways. If the caller completes its processing of the new options without any errors, then it must pass the structure to Tk_FreeSavedOptions so that the old values can be freed. If the caller detects an error in its processing of the new options, then it should pass the structure to Tk_RestoreSavedOptions, which will copy the old values back into the widget record and free the new values. If Tk_SetOptions detects an error then it automatically restores any options that had already been modified and leaves *savePtr in an empty state: the caller need not call either Tk_FreeSavedOptions or Tk_RestoreSavedOptions. If the savePtr argument to Tk_SetOptions is NULL then Tk_SetOptions frees each old option value immediately when it sets a new value for the option. In this case, if an error occurs in the third option, the old values for the first two options cannot be restored.

Tk_GetOptionValue は特定の部品の構成設定指示項目の現在の値を返す｡namePtr 引数は指示項目の名前を含む; Tk_GetOptionValue は指示項目を捜すためにoptionTable を使い､ recordPtr が指す部品記録から値を抽出し､次にその値を含む対象を返す｡もし不都合が生じると(譬えば､namePtr が未知の指示項目の名前を含む)､NULL が返され､interp がNULL でない限り､不都合伝言文がinterp の結果に残される｡ Tk_GetOptionValue returns the current value of a configuration option for a particular widget. The namePtr argument contains the name of an option; Tk_GetOptionValue uses optionTable to lookup the option and extract its value from the widget record pointed to by recordPtr, then it returns an object containing that value. If an error occurs (e.g., because namePtr contains an unknown option name) then NULL is returned and an error message is left in interp's result unless interp is NULL.

Tk_GetOptionInfo は構成設定指示項目に関する情報をconfigure 部品命令に適する形式で返す｡もしnamePtr 引数がNULL でない場合､それは構成設定指示項目の名前を与える対象を指す; Tk_GetOptionInfo は５つの要素を含む対象を返す､それは､指示項目の名前､指示項目基礎データ内の指示項目に使われる名前と級､指示項目の無為設定値､指示項目の現在の値である｡もしnamePtr 引数がNULL である場合､Tk_GetOptionInfo は全ての指示項目の情報をリストの形式で返す; それぞれの副リストが一つの指示項目を記述する｡類義語の指示項目はnamePtr が NULL であるかないかによって処理される: namePtr が NULL の場合､それぞれの類義語指示項目の副リストは､指示項目の名前とそれが参照している他の指示項目の名前の二つだけの要素を持つ; namePtr が 非NULL で類義語指示項目を名付けている場合､返される対象は類義語が参照している他の指示項目の５つの要素のリストである｡もし不都合が生じると(譬えば､namePtr が未知の指示項目の名前を含む)､NULL が返され､interp がNULL でない限り､不都合伝言文がinterp's の結果に残される｡ Tk_GetOptionInfo returns information about configuration options in a form suitable for configure widget commands. If the namePtr argument is not NULL, it points to an object that gives the name of a configuration option; Tk_GetOptionInfo returns an object containing a list with five elements, which are the name of the option, the name and class used for the option in the option database, the default value for the option, and the current value for the option. If the namePtr argument is NULL, then Tk_GetOptionInfo returns information about all options in the form of a list of lists; each sublist describes one option. Synonym options are handled differently depending on whether namePtr is NULL: if namePtr is NULL then the sublist for each synonym option has only two elements, which are the name of the option and the name of the other option that it refers to; if namePtr is non-NULL and names a synonym option then the object returned is the five-element list for the other option that the synonym refers to. If an error occurs (e.g., because namePtr contains an unknown option name) then NULL is returned and an error message is left in interp's result unless interp is NULL.

FreeConfigOptions は部品が削除された時に起動されなければならない｡それは optionTable によってrecordPtr 内に定義されたどの構成設定指示項目に結合した原資も全て解除する｡ Tk_FreeConfigOptions must be invoked when a widget is deleted. It frees all of the resources associated with any of the configuration options defined in recordPtr by optionTable.

### 雛形 TEMPLATES

Tk_OptionSpec 構造はその templatePtr 引数経由で Tk_CreateOptionTable に部品の特定の級により運営されている構成設定指示項目の記述を渡す｡それぞれの構造は一つの構成設定指示項目を指定し､次の欄を有する: The array of Tk_OptionSpec structures passed to Tk_CreateOptionTable via its templatePtr argument describes the configuration options supported by a particular class of widgets. Each structure specifies one configuration option and has the following fields:

    typedef struct {
        Tk_OptionType type;
        const char *optionName;
        const char *dbName;
        const char *dbClass;
        const char *defValue;
        Tcl_Size objOffset;
        Tcl_Size internalOffset;
        int flags;
        const void *clientData;
        int typeMask;
    } Tk_OptionSpec;

type 欄はそれがどの様な構成設定指示項目であるかを指し示す(譬えば､色の値としてTK_OPTION_COLOR ､又は整数値として TK_OPTION_INT )｡ type は指示項目の値が如何に解析されるかを定める(詳細は下に)｡ optionName 欄は -font や -bg の様な文字列であり; それは Tcl 命令内の指示項目の為に使われる名前であり､ objc や namePtr 引数経由で手続函数に渡される｡ dbName と dbClass 欄は Tk_InitOptions にこの指示項目基礎データ内から無為設定値を捜す為に使われる; もし dbName が NULL であると､この指示項目の為には指示項目基礎データは使われない｡もしこの指示項目基礎データ内に値が指定されていない場合は､その defValue 欄はこの構成設定指示項目のための無為設定値を指定する｡ objOffset と internalOffset 欄は部品記録内の指定された値が保存される場所を指し示す(詳細は下に); objOffset と internalOffset 欄の為の値は常に Tk_Offset マクロにより作成される｡ flags 欄はこの構成設定指示項目の処理を制御する追加的情報を含む(詳細は下を参照のこと)｡ ClientData は特定の型に必要とされる追加的な型指定データを提供する｡譬えば､ TK_OPTION_COLOR 型の為に clientData は白黒表示器上で使う為の無為設定値を与える文字列である｡更なる詳細は､下の異なる型の記述を参照されたい｡最後の欄 typeMask, は修正された指示項目に関する情報を返す為に使われる; 詳細は上の Tk_SetOptions の記述を参照されたい｡ The type field indicates what kind of configuration option this is (e.g. TK_OPTION_COLOR for a color value, or TK_OPTION_INT for an integer value). Type determines how the value of the option is parsed (more on this below). The optionName field is a string such as -font or -bg; it is the name used for the option in Tcl commands and passed to procedures via the objc or namePtr arguments. The dbName and dbClass fields are used by Tk_InitOptions to look up a default value for this option in the option database; if dbName is NULL then the option database is not used by Tk_InitOptions for this option. The defValue field specifies a default value for this configuration option if no value is specified in the option database. The objOffset and internalOffset fields indicate where to store the value of this option in widget records (more on this below); values for the objOffset and internalOffset fields should always be generated with the offsetof macro. The flags field contains additional information to control the processing of this configuration option (see below for details). ClientData provides additional type-specific data needed by certain types. For instance, for TK_OPTION_COLOR types, clientData is a string giving the default value to use on monochrome displays. See the descriptions of the different types below for details. The last field, typeMask, is used by Tk_SetOptions to return information about which options were modified; see the description of Tk_SetOptions above for details.

Tk_InitOptions と Tk_SetOptions が指示項目の値を部品記録に保存する時､それは二つの方法を使える｡もしその Tk_OptionSpec の objOffset 欄が零と同じかより大きいと､指示項目の値は objOffset によって与えられる部品記録内の場所に (Tcl_Obj *) として保存される｡もしその Tk_OptionSpec の internalOffset 欄が零と同じかより大きいと､指示項目の値は internalOffset によって与えられる部品記録内の位置に型指定の内部形式ないに保存される｡譬えば､もし指示項目の型が TK_OPTION_INT である場合､内部形式は整数である｡もし objOffset か internalOffset 欄が負値である場合､値はその形式内には保存されない､少なくとも､そのどちらか一つは零と等しいかより大きくなくはならない｡ When Tk_InitOptions and Tk_SetOptions store the value of an option into the widget record, they can do it in either of two ways. If the objOffset field of the Tk_OptionSpec is greater than or equal to zero, then the value of the option is stored as a (Tcl_Obj *) at the location in the widget record given by objOffset. If the internalOffset field of the Tk_OptionSpec is greater than or equal to zero, then the value of the option is stored in a type-specific internal form at the location in the widget record given by internalOffset. For example, if the option's type is TK_OPTION_INT then the internal form is an integer. If the objOffset or internalOffset field is negative then the value is not stored in that form. At least one of the offsets must be greater than or equal to zero.

The flags field consists of one or more bits ORed together. The following flags are supported:

TK_OPTION_NULL_OK
  指示項目の為のこのビットが設定されている場合､指示項目の為の値として空文字列が受付けられ､結果として､内部形式は指示項目の型に従って､零ポインターか､零値か､ None かになる｡もし旗印が設定されていない場合､空文字列は不都合の結果になる｡ TK_OPTION_NULL_OK は典型的には特性を永久に断にすることを許容する為に使われる､譬えば遊走子の値を None に設定し､窓が単純に親の遊走子を引継ぐ様にする｡全ての指示項目の型が TK_OPTION_NULL_OK 旗印を運営している訳ではない; 下に記述したことの明示的な兆候があるようなものがそれに該当する｡ If this bit is set for an option then an empty string will be accepted as the value for the option and the resulting internal form will be a NULL pointer, a zero value, or None, depending on the type of the option. If the flag is not set then empty strings will result in errors. TK_OPTION_NULL_OK is typically used to allow a feature to be turned off entirely, e.g. set a cursor value to None so that a window simply inherits its parent's cursor. Not all option types support the TK_OPTION_NULL_OK flag; for those that do, there is an explicit indication of that fact in the descriptions below.

TK_OPTION_DONT_SET_DEFAULT
  指示項目の為のこのビットが設定されている場合､指示項目の為の Tk_InitOptions の値として無為設定の値が設定される事はない｡この指示項目に値を与える為に､追加指示の基礎データも､どの様なOSの無為設定値も､追加表も使われることはない｡その代わりに､使用者が部品命令内に無為設定値を既に供給したと仮定される｡ If this bit is set for an option then no default value will be set in Tk_InitOptions for this option. Neither the option database, nor any system default value, nor optionTable are used to give a default value to this option. Instead it is assumed that the caller has already supplied a default value in the widget code.

TK_OPTION_ENUM_VAR
  指示項目に関してこの値が設定されると､それは､ 整数変数の代りに 列挙型変数への内部偏移指示子を指し示す｡ TK_OPTION_BOOLEANかTK_OPTION_ANCHORかK_OPTION_JUSTIFYかTK_OPTION_ANCHOR と組合せる場合のみ便利である｡ If this value is set for an option, then it indicates the the internalOffset points to an enum variable in stead of an int variable. Only useful in combination with TK_OPTION_STRING_TABLE, TK_OPTION_BOOLEAN, TK_OPTION_ANCHOR, TK_OPTION_JUSTIFY, or TK_OPTION_ANCHOR.

TK_OPTION_VAR(type)
  指示項目に関してこの値が設定されると､それは､ 整数変数の代りに type変数への内部偏移指示子を指し示す｡ TK_OPTION_STRING_TABLE か TK_OPTION_BOOLEAN ､又は TK_OPTION_INTを伴うTK_OPTION_VAR(Tcl_Size)と､ 組合せる場合にのみ便利である｡ If this value is set for an option, then it indicates the the internalOffset points to a type variable in stead of an int variable. Only useful in combination with TK_OPTION_STRING_TABLE or TK_OPTION_BOOLEAN, or as TK_OPTION_VAR(Tcl_Size) with TK_OPTION_INT

  それぞれの Tk_OptionSpec 構造の type 欄はその構成設定指示項目の値を如何に解析するかを定義する｡ type の為の適正な値と対応する動作は下に記述されている｡もし型が Tk_SetOptions の様な手続函数に渡される tkwin 値を要求するか､もしそれが Tk_OptionSpec の clientData を使う場合､それは明示的に指し示される; もし記述されていない場合､型は tkwin も clientData も要求しない｡ The type field of each Tk_OptionSpec structure determines how to parse the value of that configuration option. The legal value for type, and the corresponding actions, are described below. If the type requires a tkwin value to be passed into procedures like Tk_SetOptions, or if it uses the clientData field of the Tk_OptionSpec, then it is indicated explicitly; if not mentioned, the type requires neither tkwin nor clientData.

TK_OPTION_ANCHOR
  値は ne [左上]や center の様な標準的な錨位置でなければならない｡内部形式は Tk_GetAnchorFromObj によって返されたものに似ている Tk_Anchor 値である｡ この指示項目型は､TK_OPTION_NULL_OK旗徴に対応している; もし空文字列が指示項目の値として指定されると､ 整数立体感値がTK_ANCHOR_NULLに設定される｡ The value must be a standard anchor position such as ne or center. The internal form is a Tk_Anchor value like the ones returned by Tk_GetAnchorFromObj. This option type supports the TK_OPTION_NULL_OK flag; if the empty string is specified as the value for the option, the integer relief value is set to TK_ANCHOR_NULL.

TK_OPTION_BITMAP
  値は標準 Tk 点地図名前でなければならない｡内部形式は画素地図字句結果であり Tk_AllocBitmapFromObj. によって返されるに似たものである｡この指示項目の型は Tk_SetOptions の様な手続函数に与えられる tkwin を要求し､ TK_OPTION_NULL_OK 旗印を運営する｡ The value must be a standard Tk bitmap name. The internal form is a Pixmap token like the ones returned by Tk_AllocBitmapFromObj. This option type requires tkwin to be supplied to procedures such as Tk_SetOptions, and it supports the TK_OPTION_NULL_OK flag.

TK_OPTION_BOOLEAN
  値は真値や偽値の様な標準的論理値でなければならない｡内部の形式は値 0 か 1 の整数である｡註意すべきは､ objOffset 欄が使われないと､この指示項目の元の値が失われる｡ この指示項目型は､TK_OPTION_NULL_OK旗徴に対応している; もしヌル値が設定されると､内部表現は -1 に設定される｡ The value must be a standard boolean value such as true or no. The internal form is an integer with value 0 or 1. Note that if the objOffset field is not used, information about the original value of this option will be lost. This option type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the internal representation is set to -1.

TK_OPTION_BORDER
  値は red や #ff8080 の様な標準色名でなければならない｡内部の形式は Tk_Alloc3DBorderFromObj に返されものに似た Tk_3DBorder 字句結果である｡この指示項目の型は Tk_SetOptions の様な手続函数に与えられる tkwin を要求し､ TK_OPTION_NULL_OK 旗印を運営する｡ The value must be a standard color name such as red or #ff8080. The internal form is a Tk_3DBorder token like the ones returned by Tk_Alloc3DBorderFromObj. This option type requires tkwin to be supplied to procedures such as Tk_SetOptions, and it supports the TK_OPTION_NULL_OK flag.

TK_OPTION_COLOR
  値は red や #ff8080 の様な標準色名でなければならない｡内部形式は Tk_AllocColorFromObj によって返されたものに似ている (XColor *) 字句結果である｡この指示項目の型は Tk_SetOptions の様な手続函数に与えられる tkwin を要求し､ TK_OPTION_NULL_OK 旗印を運営する｡ The value must be a standard color name such as red or #ff8080. The internal form is an (XColor *) token like the ones returned by Tk_AllocColorFromObj. This option type requires tkwin to be supplied to procedures such as Tk_SetOptions, and it supports the TK_OPTION_NULL_OK flag.

TK_OPTION_CURSOR
  この値は cross や @foo の様な標準遊走子の名前でなければならない｡内部形式はTk_AllocCursorFromObj から返されるもののような Tk_Cursor 字句結果である｡この指示項目の型は Tk_SetOptions の様な手続函数に与えられる tkwin を要求し､指示項目が設定された時､その窓への遊走子は XDefineCursor の呼出しにより変更される｡この指示項目の型は旗印も TK_OPTION_NULL_OK 運営する｡ The value must be a standard cursor name such as cross or @foo. The internal form is a Tk_Cursor token like the ones returned by Tk_AllocCursorFromObj. この指示項目型は､ Tk_SetOptionsの様な手続き函数に供給される､ tkwinを要求し､且つ 指示項目が窓の遊標を設定する時､ XDefineCursorの呼出によって変更される。 ｡[訳註:???] この指示項目の型もTK_OPTION_CUSTOM旗徴に対応する｡ This option type requires tkwin to be supplied to procedures such as Tk_SetOptions, and when the option is set the cursor for the window is changed by calling XDefineCursor. This option type also supports the TK_OPTION_NULL_OK flag.

TK_OPTION_CUSTOM
  この指示項目は新しい指示項目型を定義するために応用譜を許容する｡入口の clientData 欄は新しい指示項目型を定義する構造をさす｡詳細については下の CUSTOM OPTION TYPES 節を参照されたい｡ This option allows applications to define new option types. The clientData field of the entry points to a structure defining the new option type. See the section CUSTOM OPTION TYPES below for details.

TK_OPTION_DOUBLE
  文字列値は､strtol によって受容れられ得る書式の､ 浮動小数でなければならない｡ 内部書式は C 言語の倍精度値である｡ この指示項目型は､TK_OPTION_NULL_OK旗徴に対応している; もしヌル値が設定されると､内部表現は NaN に設定される｡ The string value must be a floating-point number in the format accepted by strtol. The internal form is a C double value. This option type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the internal representation is set to NaN.

TK_OPTION_END
  雛形の末尾に印を附る｡それぞれの雛形の末尾にTK_OPTION_END 型を伴う Tk_OptionSpec 構造が存在しなけらばならない｡この型の clientData 欄が NULL,でない場合､それはそれ自身が他の TK_OPTION_END 呼出し位置によって終了される Tk_OptionSpec の追加的配列を指す｡雛形は任意の深さに変更されてもよい｡この特性は幾つかの部品の級により共有される共通の指示項目を許容する｡ Marks the end of the template. There must be a Tk_OptionSpec structure with type TK_OPTION_END at the end of each template. If the clientData field of this structure is not NULL, then it points to an additional array of Tk_OptionSpec's, which is itself terminated by another TK_OPTION_END entry. Templates may be chained arbitrarily deeply. This feature allows common options to be shared by several widget classes.

TK_OPTION_FONT
  この値は Times 16 の様な標準的文字形状名でなければならない｡内部形状は Tk_AllocFontFromObj によって返されるものの如き Tk_Font 処理子である｡この指示項目型は Tk_SetOptions の如き手続函数に供給される tkwin を要求し､ TK_OPTION_NULL_OK 旗印を運営する｡ The value must be a standard font name such as Times 16. The internal form is a Tk_Font handle like the ones returned by Tk_AllocFontFromObj. This option type requires tkwin to be supplied to procedures such as Tk_SetOptions, and it supports the TK_OPTION_NULL_OK flag.

TK_OPTION_INT
  文字列値は､strtol によって受容れられ得る書式の､ 整数でなければならない (譬えば､前置辞0と0xは､八進や十六進数をそれぞれ指定する)｡ 内部書式は C 言語の整数である｡ この指示項目の型はTK_OPTION_NULL_OK旗徴に対応する; もしヌル値が設定されると､内部表現は INT_MINに設定される｡ The string value must be an integer in the format accepted by strtol (e.g. 0 and 0x prefixes may be used to specify octal or hexadecimal numbers, respectively). The internal form is a C int value. This option type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the internal representation is set to INT_MIN.

TK_OPTION_INDEX
  文字列値は､Tcl_GetIntForIndex()によって受容れられ得る書式の､ 索引か､空文字列か､でなければならない｡ 内部書式は C 言語の整数である｡ もし､文字列が-で開始されると､内部表現ははINT_MINに設定される｡ もし､文字列がend-???の形式を有すると､結果は負数になる: -1はendを表し､-2はend-1を表し､以下同様に続く｡ この指示項目の型は､TK_OPTION_NULL_OK旗徴に対応する; もし､指示項目の値として､空文字列が指定されると､ 内部の立体感の値はINT_MINに設定される｡ The string value must be an index in the format accepted by Tcl_GetIntForIndex() or the empty string. The internal form is a C int value. If the string starts with -, the internal representation will be set to INT_MIN. If the string has the form end-???, then the result will be a negative number: -1 stands for end, -2 stands for end-1 and so on. This option type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the internal representation is set to INT_MIN.

TK_OPTION_JUSTIFY
  この値は left の様な標準的な正常の値を指定しなければならない｡ 内部の書式はTk_GetJustifyFromObjによって返されるTk_Justifyの如き値なり｡ この指示項目は､TK_OPTION_NULL_OK旗徴に対応する; もし､指示項目の値として､空文字列が指定されると､ 内部の立体感の値はTK_JUSTIFY_NULLに設定される｡ The value must be a standard justification value such as left. The internal form is a Tk_Justify like the values returned by Tk_GetJustifyFromObj. This option type supports the TK_OPTION_NULL_OK flag; if the empty string is specified as the value for the option, the integer relief value is set to TK_JUSTIFY_NULL.

TK_OPTION_PIXELS
  この値は 2i や 6.4 の様な画面距離を指定しなければならない｡内部形式は Tk_GetPixelsFromObj によって返される値の様な､画素単位の距離を与える整数値である｡註意すべきは､もしこの objOffset 欄 が使われない場合､この指示項目の元の値に関する情報は失われる｡更なる詳細は下の OBJOFFSET VS. INTERNALOFFSET を参照されたい｡この指示項目型は TK_OPTION_NULL_OK 旗印を運営する; もし NULL 値が設定されている場合､内部表現は 最小整数 INT_MIN に設定される｡ The value must specify a screen distance such as 2i or 6.4. The internal form is an integer value giving a distance in pixels, like the values returned by Tk_GetPixelsFromObj. Note that if the objOffset field is not used, information about the original value of this option will be lost. See OBJOFFSET VS. INTERNALOFFSET below for details. This option type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the internal representation is set to INT_MIN.

TK_OPTION_RELIEF
  この値は raised の様な標準的な立体感の値でなければならない｡その内部形式は､ TK_RELIEF_RAISED の様な整数立体感の値である｡この指示項目型は TK_OPTION_NULL_OK 旗印を運営する; もし NULL 値が設定されると､内部表現は TK_RELIEF_NULL に設定される｡ The value must be standard relief such as raised. The internal form is an integer relief value such as TK_RELIEF_RAISED. This option type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the internal representation is set to TK_RELIEF_NULL.

TK_OPTION_STRING
  この値はどの様な文字列でもよい｡その内部形式は､値の動的に割付けられた複写を指す (char *) である｡この指示項目の型はTK_OPTION_NULL_OK 旗印を運営する｡ The value may be any string. The internal form is a (char *) pointer that points to a dynamically allocated copy of the value. This option type supports the TK_OPTION_NULL_OK flag.

TK_OPTION_STRING_TABLE
  この型の為に､ clientData はTcl_GetIndexFromObj に渡す為に適した文字列の配列へのポインタである｡その値は表内の一つの文字列か文字列の一つの唯一の短縮形でなければならない｡この内部形式は合致する文字列の表への索引を与える整数値であり､ Tcl_GetStringFromObj からの返り値に似ている｡この指示項目は TK_OPTION_NULL_OK 旗徴を運用している; もし NULL 値が設定されると内部表現は -1 に設定される｡ For this type, clientData is a pointer to an array of strings suitable for passing to Tcl_GetIndexFromObj. The value must be one of the strings in the table, or a unique abbreviation of one of the strings. The internal form is an integer giving the index into the table of the matching string, like the return value from Tcl_GetStringFromObj. This option type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the internal representation is set to -1.

TK_OPTION_SYNONYM
  この型は指示項目への代替名を提供する為に使われる(譬えば､-bg はしばしば -background の類似語として使われる)｡その clientData 欄は同じ表内の他の指示項目の名前を与える文字列である｡何時であれ､類似語の指示項目が使用されると､他の指示項目からの情報が代りに使われる｡ This type is used to provide alternative names for an option (for example, -bg is often used as a synonym for -background). The clientData field is a string that gives the name of another option in the same table. Whenever the synonym option is used, the information from the other option will be used instead.

TK_OPTION_WINDOW
  この値は窓の経路名でなければならない｡内部形式は窓の為の Tk_Window 字句結果である｡この指示項目型は Tk_SetOptions のような手続函数に提供される tkwin を要求し(応用譜を識別する為に)､ TK_OPTION_NULL_OK 旗印を運営する｡ The value must be a window path name. The internal form is a Tk_Window token for the window. This option type requires tkwin to be supplied to procedures such as Tk_SetOptions (in order to identify the application), and it supports the TK_OPTION_NULL_OK flag.

### STORAGE MANAGEMENT ISSUES

もし部品記録の端が自身の偏寄を Tk_OptionSpec 構造の objOffset か internalOffset 欄内に保存する場合､ここで記載される手続函数は､全ての記憶域の割当てとその欄に結合した問題を管理する原資を取扱う｡指示項目の値が変化する時､Tk_SetOptions (又はTk_FreeSavedOptions )は､ TK_OPTION_FONT 指示項目の為の Tk_Fonts や､ TK_OPTION_STRING 指示項目の為の動的に割当てられた記憶域のような､古い値に結合された原資を自動的に解放する｡ Tk_OptionSpec の objOffset 欄を使う対象として保存された指示項目の為に､部品の記録は､ Tk_SetOptions の呼出しからの objv 値により指される対象を共有する｡この対象の為の参照回数はそれへのポインタが部品記録に保存された時に増加され､指示項目が修正された時に減らされる｡部品が削除された時､Tk_FreeConfigOptions が起動される; 全ての指示項目に結合した原資が解除され､どの対象への参照回数も減少する｡ If a field of a widget record has its offset stored in the objOffset or internalOffset field of a Tk_OptionSpec structure then the procedures described here will handle all of the storage allocation and resource management issues associated with the field. When the value of an option is changed, Tk_SetOptions (or Tk_FreeSavedOptions) will automatically free any resources associated with the old value, such as Tk_Fonts for TK_OPTION_FONT options or dynamically allocated memory for TK_OPTION_STRING options. For an option stored as an object using the objOffset field of a Tk_OptionSpec, the widget record shares the object pointed to by the objv value from the call to Tk_SetOptions. The reference count for this object is incremented when a pointer to it is stored in the widget record and decremented when the option is modified. When the widget is deleted Tk_FreeConfigOptions should be invoked; it will free the resources associated with all options and decrement reference counts for any objects.

しかし､部品符号は Tk_InitOptions の起動より前に､全てのポインタと字句結果欄に NULL か無しを保存することについて責務がある｡これは､Tk_InitOptions 内に不具合が起る稀な場合に､適切な刷新を許容するために必要である｡ However, the widget code is responsible for storing NULL or None in all pointer and token fields before invoking Tk_InitOptions. This is needed to allow proper cleanup in the rare case where an error occurs in Tk_InitOptions.

### OBJOFFSET VS. INTERNALOFFSET

多くの場合､ Tk_OptionSpec 構造の internalOffset 欄を使い objOffset 欄を使わない事は簡単である｡それは､値の内部形式をして部品符号に直接利用可能にし､それにより､その値がそれが使われる度に対象からは抽出されなくする｡然しながら､ objOffset 欄が便利な二つの場合がある｡第１の場合は､ TK_OPTION_PIXELS 指示項目の為の場合である｡その場合､その内部形式は整数の画素値であり､特定の画面にのみ適切である｡もし指示項目の値が取り返された場合､それは単純な数として返される｡譬えば､命令 .b configure-borderwidth 2m の後の､命令 .b configure-borderwidth は7 を返すが､それは 2m に対応する整数画素値である｡不幸な事に､之は元の画面依存値を損失している｡従って､ TK_OPTION_PIXELS 指示項目の為に､objOffset 欄を使うことが好ましい｡この場合､指示項目の元の値は対象内に残され､指示項目が取り返された時に返されることが可能である｡ 但し､拡大縮小が含まれると､ internalOffsetは､拡大率が変わる時に､値を変更しない｡ 従って､何時であれ必要な時には､対象から整数値を抽出する為には Tk_GetPixelsFromObjを使う事が好ましい｡ 註意：取出し時の情報の逸失の問題は､TK_OPTION_PIXELS指示項目 についてのみに存す｡ In most cases it is simplest to use the internalOffset field of a Tk_OptionSpec structure and not the objOffset field. This makes the internal form of the value immediately available to the widget code so the value does not have to be extracted from an object each time it is used. However, there are two cases where the objOffset field is useful. The first case is for TK_OPTION_PIXELS options. In this case, the internal form is an integer pixel value that is valid only for a particular screen. If the value of the option is retrieved, it will be returned as a simple number. For example, after the command .b configure -borderwidth 2m, the command .b configure -borderwidth might return 7, which is the integer pixel value corresponding to 2m. Unfortunately, this loses the original screen-independent value. Thus for TK_OPTION_PIXELS options it is better to use the objOffset field. In this case the original value of the option is retained in the object and can be returned when the option is retrieved. It might seem convenient to use the internalOffset field as well, so that the integer value is immediately available for use in the widget code. But if scaling is involved, internalOffset won't change value when the scaling changes. Therefore it is better always to use Tk_GetPixelsFromObj to extract the integer value from the object whenever it is needed. Note: the problem of losing information on retrievals exists only for TK_OPTION_PIXELS options.

objOffset 欄を使う第２の理由はこのような手続函数に運営されていない指示項目の新しい型を実装するためである｡指示項目の新しい型を実装する為に､ Tk_OptionSpec 構造内の型として TK_OPTION_STRING を使うことができる､ internalOffset 欄ではなく objOffset 欄を設定されたい｡次いで､ The second reason to use the objOffset field is in order to implement new types of options not supported by these procedures. To implement a new type of option, you can use TK_OPTION_STRING as the type in the Tk_OptionSpec structure and set the objOffset field but not the internalOffset field. Then, after calling Tk_SetOptions, convert the object to internal form yourself.

Ttk 部品は 装置的な internalOffset に対応しない｡Ttk 部品の指示項目の値は常に (Tcl_Obj *) として保存され､即ち､ objOffset 欄が使われねばならない｡ Ttk widgets do not support the internalOffset machinery. Option values of Ttk widgets are always stored as (Tcl_Obj *), meaning that the objOffset field must be used.

### CUSTOM OPTION TYPES

応用譜は､保存した型の複写を解析､印刷､解除､再保存する為に手続函数を書くことにより､又これ等の手続函数を指す構造を作成することにより､組込み構成設定型を追加的構成設定型と共に拡張する事ができる｡ Applications can extend the built-in configuration types with additional configuration types by writing procedures to parse, print, free, and restore saved copies of the type and creating a structure pointing to those procedures:

    typedef struct {
        const char *name;
        Tk_CustomOptionSetProc *setProc;
        Tk_CustomOptionGetProc *getProc;
        Tk_CustomOptionRestoreProc *restoreProc;
        Tk_CustomOptionFreeProc *freeProc;
        void *clientData;
    } Tk_ObjCustomOption;

    typedef int Tk_CustomOptionSetProc(
        void *clientData,
        Tcl_Interp *interp,
        Tk_Window tkwin,
        Tcl_Obj **valuePtr,
        char *recordPtr,
        Tcl_Size internalOffset,
        char *saveInternalPtr,
        int flags);

    typedef Tcl_Obj *Tk_CustomOptionGetProc(
        void *clientData,
        Tk_Window tkwin,
        char *recordPtr,
        Tcl_Size internalOffset);

    typedef void Tk_CustomOptionRestoreProc(
        void *clientData,
        Tk_Window tkwin,
        char *internalPtr,
        char *saveInternalPtr);

    typedef void Tk_CustomOptionFreeProc(
        void *clientData,
        Tk_Window tkwin,
        char *internalPtr);

Tk_ObjCustomOption は６つの欄を有する: 誂えた指示項目型の為の名前; 四つの手続函数へのポインタ; それらが起動された時に渡される clientData 値､である｡ clientData 値は､典型的には､手続函数が指示項目を解析､印刷している時に､手続函数によって必要とされる情報を含む構造を指す｡RestoreProc と freeProc は NULL でもよく､それは､このような操作の為に何も函数が呼ばれないことを指し示す｡ The Tk_ObjCustomOption structure contains six fields: a name for the custom option type; pointers to the four procedures; and a clientData value to be passed to those procedures when they are invoked. The clientData value typically points to a structure containing information that is needed by the procedures when they are parsing and printing options. RestoreProc and freeProc may be NULL, indicating that no function should be called for those operations.

setProc 手続函数は､ Tcl_Obj を内部表現に変換する為に Tk_SetOptions によって起動され､結果の値は部品記録内に保存される｡引数は: The setProc procedure is invoked by Tk_SetOptions to convert a Tcl_Obj into an internal representation and store the resulting value in the widget record. The arguments are:

clientData
  Tk_ObjCustomOption 構造内の clientData 欄の複写｡ A copy of the clientData field in the Tk_ObjCustomOption structure.

interp
  Tcl 解釈実行機能へのポインター､不都合報告に使用される｡ A pointer to a Tcl interpreter, used for error reporting.

Tkwin
  Tk_SetOptions への tkwin 引数の複写 A copy of the tkwin argument to Tk_SetOptions

valuePtr
  指示項目の為の新しい値を記述している Tcl_Obj を参照するポインタ; それは､ Tk_SetOptions への呼出し内に明示的に指定されるかもしれないし､指示項目基本データ又は省略時設定から来るかもしれない｡もし､指示項目への objOffset が非負の場合(指示項目値は部品記録内に(Tcl_Obj *)として保存される)､ by valuePtr に参照されている Tcl_Obj ポインターは､指示項目の為の objOffset の箇所に保存されるべきポインターである｡ SetProc は必要な場合は値を修正してもよい; 譬えば､ setProc はTK_OPTION_NULL_OK 旗印を運営する為に値が NULL に変更されてもよい｡ A pointer to a reference to a Tcl_Obj describing the new value for the option; it could have been specified explicitly in the call to Tk_SetOptions or it could come from the option database or a default. If the objOffset for the option is non-negative (the option value is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj pointer referenced by valuePtr is the pointer that will be stored at the objOffset for the option. SetProc may modify the value if necessary; for example, setProc may change the value to NULL to support the TK_OPTION_NULL_OK flag.

recordPtr
  修正すべき部品記録の始まりへのポインター｡ A pointer to the start of the widget record to modify.

internalOffset
  指示項目の値の内部表現が置かれる場所への部品の記録の始まりからのバイト単位の距離｡ Offset in bytes from the start of the widget record to the location where the internal representation of the option value is to be placed.

saveInternalPtr
  元の指示項目の値の内部表現の為の Tk_SavedOptions 構造内に割付けられた記憶域へのポインター｡その新しい値への指示項目の設定の前に､ setProc は､ Tk_RestoreSavedOptions を運営する為に指示項目の元の値へ､ saveInternalPtr により参照された値を設定する｡ A pointer to storage allocated in a Tk_SavedOptions structure for the internal representation of the original option value. Before setting the option to its new value, setProc should set the value referenced by saveInternalPtr to the original value of the option in order to support Tk_RestoreSavedOptions.

flags
  その指示項目の為の Tk_OptionSpec 構造内の flags 欄の複写 A copy of the flags field in the Tk_OptionSpec structure for the option

SetProc は標準的 Tcl 結果を返す: TCL_OK は成功裡の処理を指し示し､ TCL_ERROR は何かの失敗を指し示す｡不都合伝言文は不都合の場合に interp によって与えられた Tcl 解釈実行機能内に残されるかもしれない｡ SetProc returns a standard Tcl result: TCL_OK to indicate successful processing, or TCL_ERROR to indicate a failure of any kind. An error message may be left in the Tcl interpreter given by interp in the case of an error.

その getProc 手続函数は､指示項目の内部表現を取戻す為に Tk_GetOptionValue と Tk_GetOptionInfo により起動される｡ clientData 引数は Tk_ObjCustomOption 構造内の clientData 欄の複写である｡ tkwin は Tk_GetOptionValue か Tk_GetOptionInfo への tkwin 引数である｡RecordPtr は待ち行列への部品記録の始まりへのポインターである｡ InternalOffset は指示項目値が保存されている内部表現の位置への始まり位置からバイト単位の距離である｡ GetProc はその指示項目の値の Tcl_Obj 表現へのポインターを返さねばならない｡ The getProc procedure is invoked by Tk_GetOptionValue and Tk_GetOptionInfo to retrieve a Tcl_Obj representation of the internal representation of an option. The clientData argument is a copy of the clientData field in the Tk_ObjCustomOption structure. Tkwin is a copy of the tkwin argument to Tk_GetOptionValue or Tk_GetOptionInfo. RecordPtr is a pointer to the beginning of the widget record to query. InternalOffset is the offset in bytes from the beginning of the widget record to the location where the internal representation of the option value is stored. GetProc must return a pointer to a Tcl_Obj representing the value of the option.

その restoreProc 手続函数は､以前に保存した誂え指示項目値の内部表現を再保存する為に Tk_RestoreSavedOptions により起動される｡その clientData 引数は Tk_ObjCustomOption 構造内の clientData 欄の複写である｡ tkwin は Tk_GetOptionValue か Tk_GetOptionInfo への tkwin 引数の複写である｡InternalPtr は指示項目値の内部表現が保存されている位置へのポインターである｡ SaveInternalPtr は保存した値へのポインターである｡ RestoreProc は値を取戻す為に saveInternalPtr から internalPtr へ値を複写しなければらない｡ RestoreProc は internalPtr と saveInternalPtr のどちらと結合しているどの記憶域も解放する必要はない; freeProc は必要ならその記憶域を解消する為に起動される｡ RestoreProc は返り値を有さない｡ The restoreProc procedure is invoked by Tk_RestoreSavedOptions to restore a previously saved internal representation of a custom option value. The clientData argument is a copy of the clientData field in the Tk_ObjCustomOption structure. Tkwin is a copy of the tkwin argument to Tk_GetOptionValue or Tk_GetOptionInfo. InternalPtr is a pointer to the location where internal representation of the option value is stored. SaveInternalPtr is a pointer to the saved value. RestoreProc must copy the value from saveInternalPtr to internalPtr to restore the value. RestoreProc need not free any memory associated with either internalPtr or saveInternalPtr; freeProc will be invoked to free that memory if necessary. RestoreProc has no return value.

その freeProc 手続函数は誂え指示項目の内部表現の為の割当てられた記憶域を解放する為に Tk_SetOptions と Tk_FreeSavedOptions によって起動される｡ clientData 引数は Tk_ObjCustomOption 構造内の clientData 欄の複写である｡ tkwin は Tk_GetOptionValue か Tk_GetOptionInfo への tkwin 引数の複写である｡ InternalPtr は､指示項目値の内部表現値が保存されている位置へのポインターである｡ freeProc は指示項目に結合したどの記憶域も解放しなければならない｡ FreeProc は返り値を有さない｡ The freeProc procedure is invoked by Tk_SetOptions and Tk_FreeSavedOptions to free any storage allocated for the internal representation of a custom option. The clientData argument is a copy of the clientData field in the Tk_ObjCustomOption structure. Tkwin is a copy of the tkwin argument to Tk_GetOptionValue or Tk_GetOptionInfo. InternalPtr is a pointer to the location where the internal representation of the option value is stored. The freeProc must free any storage associated with the option. FreeProc has no return value.

### KEYWORDS

anchor, bitmap, boolean, border, color, configuration option, cursor, double, font, integer, justify, pixels, relief, screen distance, synonym
Copyright © 1998 Sun Microsystems, Inc.