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

### 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_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions — 部品の為の構成設定指示項目手続き process configuration options for widgets
  SYNOPSIS
    #include <tk.h>
    int
    Tk_ConfigureWidget(interp, tkwin, specs, objc, objv, widgRec, flags)
    int
    Tk_ConfigureInfo(interp, tkwin, specs, widgRec, argvName, flags)
    int
    Tk_ConfigureValue(interp, tkwin, specs, widgRec, argvName, flags)
    Tk_FreeOptions(specs, widgRec, display, flags)
  引数 ARGUMENTS
    Tcl_Interp *interp (入力in)
    Tk_Window tkwin (入力in)
    const Tk_ConfigSpec *specs (入力in)
    Tcl_Size objc (入力in)
    Tcl_Obj *const * objv (入力in)
    char *widgRec (入出力in/out)
    int flags (入力in)
    type name type (入力in)
    field name field (入力in)
    const char *argvName (入力in)
    Display *display (入力in)
  説明 DESCRIPTION
    TK_CONFIG_ACTIVE_CURSOR
    TK_CONFIG_ANCHOR
    TK_CONFIG_BITMAP
    TK_CONFIG_BOOLEAN
    TK_CONFIG_BORDER
    TK_CONFIG_CAP_STYLE
    TK_CONFIG_COLOR
    TK_CONFIG_CURSOR
    TK_CONFIG_CUSTOM
    TK_CONFIG_DOUBLE
    TK_CONFIG_END
    TK_CONFIG_FONT
    TK_CONFIG_INT
    TK_CONFIG_JOIN_STYLE
    TK_CONFIG_JUSTIFY
    TK_CONFIG_MM
    TK_CONFIG_PIXELS
    TK_CONFIG_RELIEF
    TK_CONFIG_STRING
    TK_CONFIG_SYNONYM
    TK_CONFIG_UID
    TK_CONFIG_WINDOW
  GROUPED ENTRIES
  FLAGS
    TK_CONFIG_COLOR_ONLY
    TK_CONFIG_MONO_ONLY
    TK_CONFIG_NULL_OK
    TK_CONFIG_DONT_SET_DEFAULT
  TK_CONFIGUREINFO
  TK_CONFIGUREVALUE
  TK_FREEOPTIONS
  CUSTOM OPTION TYPES
  用例 EXAMPLES
  SEE ALSO
  KEYWORDS

### NAME

Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions — 部品の為の構成設定指示項目手続き process configuration options for widgets

### SYNOPSIS

#include <tk.h>
int
Tk_ConfigureWidget(interp, tkwin, specs, objc, objv, widgRec, flags)
int
Tk_ConfigureInfo(interp, tkwin, specs, widgRec, argvName, flags)
int
Tk_ConfigureValue(interp, tkwin, specs, widgRec, argvName, flags)
Tk_FreeOptions(specs, widgRec, display, flags)

### 引数 ARGUMENTS

Tcl_Interp *interp (入力in)
  不都合伝言文を返す為の解釈実行機能｡　 Interpreter to use for returning error messages.

Tk_Window tkwin (入力in)
  ( X 源資を組上げるに必要な)部品を表現する為の窓｡ Window used to represent widget (needed to set up X resources).

const Tk_ConfigSpec *specs (入力in)
  この部品の為の公式構成設定指定項目を指定する表への指示子｡ Pointer to table specifying legal configuration options for this widget.

Tcl_Size objc (入力in)
  objv 内の引数の個数｡ Number of arguments in objv.

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

char *widgRec (入出力in/out)
  部品記録構造を指す｡この構造の欄は構成設定情報を保有する為にTk_ConfigureWidget によって修正させる｡ Points to widget record structure. Fields in this structure get modified by Tk_ConfigureWidget to hold configuration information.

int flags (入力in)
  非零の場合､構成設定情報の処理を制御する旗印の論理和の組合せを指定する｡ TK_CONFIG_ARGV_ONLY は指定項目基礎データと無為設定に無視させ､ TK_CONFIG_USER_BIT とその上の旗印ビットは空間内の入力の選択的無効化に使用される｡　 If non-zero, then it specifies an OR-ed combination of flags that control the processing of configuration information. TK_CONFIG_ARGV_ONLY causes the option database and defaults to be ignored, and flag bits TK_CONFIG_USER_BIT and higher are used to selectively disable entries in specs.

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

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

const char *argvName (入力in)
  特定の指定項目を参照する為(譬ば､部品生成時､又は configure 部品命令の起動時)の Tcl 命令行上で使用される名前｡もし非 -NULLの場合､情報はこの指示項目の為にのみ返される｡もし､ NULL の場合､情報は全ての利用可能な指示項目に返される｡　 The name used on Tcl command lines to refer to a particular option (e.g. when creating a widget or invoking the configure widget command). If non-NULL, then information is returned only for this option. If NULL, then information is returned for all available options.

Display *display (入力in)
  その記録が開放されている部品を含む表示装置; 源資を開放する為に必要とされる｡ Display containing widget whose record is being freed; needed in order to free up resources.

### 説明 DESCRIPTION

註意: Tk_ConfigureWidget は API Tk_SetOptions に基いた新しい Tcl_Obj に置換えられるべきである｡古い対話機能は上位互換性の為に残されている｡ Note that Tk_ConfigureWidget should be replaced with the new Tcl_Obj based API, Tk_SetOptions. The old interface is retained for backward compatibility.

Tk_ConfigureWidget は部品の種々の特性､譬えば､色､文字形状､巾の縁､等を構成設定する為に呼ばれる｡ それは､個別の部品管理譜内で構成設定情報を処理する為に書かれなければならない符号命令の量を減らす為に便利な手続函数として意図されている｡ それは典型的には､部品が生成した時に､又 configure 命令が部品の為に起動された時に､起動される｡第一に部品の為に意図されてはいるが､ Tk_ConfigureWidget は他の状況で､ objc-objv 情報が､画布部品や指示項目聚の見出しの為の構成設定する画像的要素等の如く､記録構造内を満たす為に使われるべき処で使うことができる｡ Tk_ConfigureWidget is called to configure various aspects of a widget, such as colors, fonts, border width, etc. It is intended as a convenience procedure to reduce the amount of code that must be written in individual widget managers to handle configuration information. It is typically invoked when widgets are created, and again when the configure command is invoked for a widget. Although intended primarily for widgets, Tk_ConfigureWidget can be used in other situations where objc-objv information is to be used to fill in a record structure, such as configuring graphical elements for a canvas widget or entries of a menu.

Tk_ConfigureWidget は､構成設定の項目を指定している表を処理している､それは､運営されている(規格)と､命令行引数(objc と objv)の集まりとを､記録 (widgRec)の欄に記入する為の表である｡ objv 内に指定されていない widgRec の欄内に満たす為に､指示項目基礎データと specs 内の無為設定指定を使う｡ Tk_ConfigureWidget は通常値 TCL_OK を返す; この場合それは解釈実行機能を修正はしない｡ もし不都合が生じると､ TCL_ERROR が返され､ Tk_ConfigureWidget は Tcl の標準的方式で解釈実行機能の結果内に不都合伝言文を残す｡ もし不都合が生じる前にそのための構成設定情報が成功裏に処理された場合､不都合戻りの行事内で widgRec のどれかの欄が既に設定されたかもしれない｡他の欄は合理的な初期値が設定されることになるので Tk_FreeOptions は刷新の為に呼ばれるかもしれない｡ Tk_ConfigureWidget processes a table specifying the configuration options that are supported (specs) and a collection of command-line arguments (objc and objv) to fill in fields of a record (widgRec). It uses the option database and defaults specified in specs to fill in fields of widgRec that are not specified in objv. Tk_ConfigureWidget normally returns the value TCL_OK; in this case it does not modify interp. If an error occurs then TCL_ERROR is returned and Tk_ConfigureWidget will leave an error message in interpreter interp's result in the standard Tcl fashion. In the event of an error return, some of the fields of widgRec could already have been set, if configuration information for them was successfully processed before the error occurred. The other fields will be set to reasonable initial values so that Tk_FreeOptions can be called for cleanup.

specs 配列は部品に予想される構成設定指示項目の種類を指定する｡それぞれの見出しは一つの構成設定指示項目を指定し次の構造を有する: The specs array specifies the kinds of configuration options expected by the widget. Each of its entries specifies one configuration option and has the following structure:

    typedef struct {
        int type;
        const char *argvName;
        const char *dbName;
        const char *dbClass;
        const char *defValue;
        Tcl_Size offset;
        int specFlags;
        const Tk_CustomOption *customPtr;
    } Tk_ConfigSpec;

type 欄はこれがどの型の構成設定指示項目であるかを指し示す(譬えば､色の値として TK_CONFIG_COLOR ､整数値として TK_CONFIG_INT )｡ type 欄は指示項目の値を如何に使うかを指し示す(詳細は下を参照)｡ argvName 欄はのような文字列 “-font” か “-bg” であり objv 内の値と比較される(もし argvName が NULL の場合､それは群見出しであることを意味する; 下の GROUPED ENTRIES を参照されたい)｡ dbName と dbClass 欄は指示項目基礎データ内のこの指示項目の値の調査に使われる｡ defValue 欄は objv にも指示項目基礎データにも値が指定されてない場合､この構成設定指示項目の為の無為設定を指定する｡ Offset は widgRec 内にこの指示項目について保存される情報を指し示す､又､ specFlags は､この構成設定指示項目の処理を制御する為の追加的情報を含む(下の FLAGS 参照のこと)｡最後の欄 customPtr は､もし type が TK_CONFIG_CUSTOM のときにのみ使用される;下の CUSTOM OPTION TYPES を参照されたい｡ The type field indicates what type of configuration option this is (e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT for an integer value). The type field indicates how to use the value of the option (more on this below). The argvName field is a string such as “-font” or “-bg”, which is compared with the values in objv (if argvName is NULL it means this is a grouped entry; see GROUPED ENTRIES below). The dbName and dbClass fields are used to look up a value for this option in the option database. The defValue field specifies a default value for this configuration option if no value is specified in either objv or the option database. Offset indicates where in widgRec to store information about this option, and specFlags contains additional information to control the processing of this configuration option (see FLAGS below). The last field, customPtr, is only used if type is TK_CONFIG_CUSTOM; see CUSTOM OPTION TYPES below.

Tk_ConfigureWidget は初めに(もしあれば)どの構成設定指示項目が此処で指定されているかを見る為に objv を処理する｡ argv は偶数の欄を含まねばならず; それぞれの対の最初の欄は specs 内のどれかの見出しの argvName に合致しなければならない(他と重複しない短縮形は受入れ可能)､そして､対の第２の欄は構成設定指示項目の為の値を含む｡ もし objv 内に合致する見出しがない様な見出しが spec 内にあれば､ Tk_ConfigureWidget は指示項目基礎データを調査する為に spec 見出しの dbName と dbClass 欄を使う; もし値が見付ると､その指示項目の値として使われる｡ 最後にもし見出しが指示項目の基礎データ内に見付らないと､ specs 見出し内の defValue 欄が構成設定指示項目の値として使われる｡ もし defValue が NULL であるか TK_CONFIG_DONT_SET_DEFAULT ビットが flags 内に設定されていると､無為設定値はなく､もし objv にも指示項目基礎データにも値が指定されていない場合はこの specs 見出しは無視される｡ Tk_ConfigureWidget first processes objv to see which (if any) configuration options are specified there. Argv must contain an even number of fields; the first of each pair of fields must match the argvName of some entry in specs (unique abbreviations are acceptable), and the second field of the pair contains the value for that configuration option. If there are entries in spec for which there were no matching entries in objv, Tk_ConfigureWidget uses the dbName and dbClass fields of the specs entry to probe the option database; if a value is found, then it is used as the value for the option. Finally, if no entry is found in the option database, the defValue field of the specs entry is used as the value for the configuration option. If the defValue is NULL, or if the TK_CONFIG_DONT_SET_DEFAULT bit is set in flags, then there is no default value and this specs entry will be ignored if no value is specified in objv or the option database.

一度文字列値が構成設定指示項目の為に定められると､ Tk_ConfigureWidget は文字列値を更に便利な形式に変換する､譬えば､もし型が TK_CONFIG_COLOR の場合の 色 ､もし型が TK_CONFIG_INTの場合の 整数 ｡ この値は､widgRecに指定される記録に保存される｡ この記録は部品の管理譜に適切な情報を含むと仮定されている; その厳密な型は Tk_ConfigureWidget には未知である｡ それぞれの specs 見出しの offset 欄は､この構成設定指示項目に関する情報を widgRec内 の何処に保存するべきかを指し示す｡ offset 値の生成には offsetof マクロを使うべきである｡ widgRec と offset によって指し示された位置は下の記述で “目標” と参照される｡ Once a string value has been determined for a configuration option, Tk_ConfigureWidget translates the string value into a more useful form, such as a color if type is TK_CONFIG_COLOR or an integer if type is TK_CONFIG_INT. This value is then stored in the record pointed to by widgRec. This record is assumed to contain information relevant to the manager of the widget; its exact type is unknown to Tk_ConfigureWidget. The offset field of each specs entry indicates where in widgRec to store the information about this configuration option. You should use the offsetof macro to generate offset values. The location indicated by widgRec and offset will be referred to as the “target” in the descriptions below.

specs 内のそれぞれの見出しの型欄はその構成設定指示項目の文字列値を如何にするかを定める｡型に就いての公式の値と､対応する活動は次の通り: The type field of each entry in specs determines what to do with the string value of that configuration option. The legal values for type, and the corresponding actions, are:

TK_CONFIG_ACTIVE_CURSOR
  値は Tk_GetCursor に渡すに適した形式の遊走子を識別する ASCII 文字列でなければならない｡値は Tk_GetCursor を呼出して Tk_Cursor に変換され､結果は目標に保存される｡更に､結果の遊走子は XDefineCursor を呼出して tkwin の為の活動的遊走子にされる｡もし specFlags 内に TK_CONFIG_NULL_OK が指定されていると､値は空文字列かもしれず､その場合 tkwin の活動遊走子なしに設定される｡もし目標の以前の値がなしでなければ､それを Tk_FreeCursor に渡して解放される｡ The value must be an ASCII string identifying a cursor in a form suitable for passing to Tk_GetCursor. The value is converted to a Tk_Cursor by calling Tk_GetCursor and the result is stored in the target. In addition, the resulting cursor is made the active cursor for tkwin by calling XDefineCursor. If TK_CONFIG_NULL_OK is specified in specFlags then the value may be an empty string, in which case the target and tkwin's active cursor will be set to None. If the previous value of the target was not None, then it is freed by passing it to Tk_FreeCursor.

TK_CONFIG_ANCHOR
  値は Tk_GetAnchor に受入れられる内の一つの方法で錨を識別する ASCII 文字列でなければならない｡文字列は Tk_GetAnchor を呼出して Tk_Anchor に変換され､結果は目標に保存される｡ The value must be an ASCII string identifying an anchor point in one of the ways accepted by Tk_GetAnchor. The string is converted to a Tk_Anchor by calling Tk_GetAnchor and the result is stored in the target.

TK_CONFIG_BITMAP
  値は Tk_GetBitmap に渡すに適した形式の点地図を識別する ASCII 文字列でなければならない｡値は Tk_GetBitmap を呼出して Pixmap に変換され､結果は目標に保存される｡もし specFlags 内の TK_CONFIG_NULL_OK が指定されていると､値は空文字列かもしれず､その場合目標ははなしに設定される｡もし目標の以前の値がなしでなければ､それを Tk_FreeBitmap に渡して解放される｡ The value must be an ASCII string identifying a bitmap in a form suitable for passing to Tk_GetBitmap. The value is converted to a Pixmap by calling Tk_GetBitmap and the result is stored in the target. If TK_CONFIG_NULL_OK is specified in specFlags then the value may be an empty string, in which case the target is set to None. If the previous value of the target was not None, then it is freed by passing it to Tk_FreeBitmap.

TK_CONFIG_BOOLEAN
  値は論理値を指定する ASCII 文字列でなければならない｡ “true”, “yes”, “on”, or “1” やこれ等の値の短縮形の内のどれでもが真値を意味する; “false”, “no”, “off”, or “0” やこれ等の値の短縮形の内のどれでもが偽値を意味する｡ 目標は整数であることが期待される; 真値については 1 ､偽値については 0 に設定される｡ The value must be an ASCII string specifying a boolean value. Any of the values “true”, “yes”, “on”, or “1”, or an abbreviation of one of these values, means true; any of the values “false”, “no”, “off”, or “0”, or an abbreviation of one of these values, means false. The target is expected to be an integer; for true values it will be set to 1 and for false values it will be set to 0.

TK_CONFIG_BORDER
  値は Tk_Get3DBorder に渡すに適した形式の縁の色を識別する ASCII 文字列でなければならない｡値は Tk_Get3DBorder を呼出して (Tk_3DBorder *) に変換され､結果は目標に保存される｡もし specFlags 内の TK_CONFIG_NULL_OK が指定されていると､値は空文字列かもしれず､その場合目標は NULLに設定される｡もし目標の以前の値が NULLでなければ､それを Tk_Free3DBorder に渡して解放される｡ The value must be an ASCII string identifying a border color in a form suitable for passing to Tk_Get3DBorder. The value is converted to a (Tk_3DBorder *) by calling Tk_Get3DBorder and the result is stored in the target. If TK_CONFIG_NULL_OK is specified in specFlags then the value may be an empty string, in which case the target will be set to NULL. If the previous value of the target was not NULL, then it is freed by passing it to Tk_Free3DBorder.

TK_CONFIG_CAP_STYLE
  値は Tk_GetCapStyle に受入れられる内の一つの方法で端末形状を識別する ASCII 文字列でなければならない｡文字列は Tk_GetCapStyle を呼出して整数値に変換され､結果は目標に保存される｡ The value must be an ASCII string identifying a cap style in one of the ways accepted by Tk_GetCapStyle. The string is converted to an integer value corresponding to the cap style by calling Tk_GetCapStyle and the result is stored in the target.

TK_CONFIG_COLOR
  値は Tk_GetColor に渡すに適した形式の色を識別する ASCII 文字列でなければならない｡値は Tk_GetColorを呼出して (XColor *) に変換され､結果は目標に保存される｡もし specFlags 内の TK_CONFIG_NULL_OK が指定されていると､値は空文字列かもしれず､その場合目標はなしに設定される｡もし目標の以前の値が NULLでなければ､それを Tk_FreeColor に渡して解放される｡ The value must be an ASCII string identifying a color in a form suitable for passing to Tk_GetColor. The value is converted to an (XColor *) by calling Tk_GetColor and the result is stored in the target. If TK_CONFIG_NULL_OK is specified in specFlags then the value may be an empty string, in which case the target will be set to None. If the previous value of the target was not NULL, then it is freed by passing it to Tk_FreeColor.

TK_CONFIG_CURSOR
  This option is identical to TK_CONFIG_ACTIVE_CURSOR except that the new cursor is not made the active one for tkwin.

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

TK_CONFIG_DOUBLE
  値は strtol に受入れられる形式の ASCII 浮動小数文字列でなければならない｡文字列は倍精度値に変換され､値は目標に保存される｡ The value must be an ASCII floating-point number in the format accepted by strtol. The string is converted to a double value, and the value is stored in the target.

TK_CONFIG_END
  表の末尾に印を付ける｡ specs 内の最後の見出しはこの型を有さなければならない; それの全ての他の欄は無視され､どの引数にも合致することはない｡ Marks the end of the table. The last entry in specs must have this type; all of its other fields are ignored and it will never match any arguments.

TK_CONFIG_FONT
  値は Tk_GetFont に渡すに適した形式の文字形状を識別する ASCII 文字列でなければならない｡値は Tk_GetFont を呼出して Tk_Font に変換され､結果は目標に保存される｡もし specFlags 内の TK_CONFIG_NULL_OK が指定されていると､値は空文字列かもしれず､その場合目標は NULL に設定される｡もし目標の以前の値が NULLでなければ､それを Tk_FreeFont に渡して解放される｡ The value must be an ASCII string identifying a font in a form suitable for passing to Tk_GetFont. The value is converted to a Tk_Font by calling Tk_GetFont and the result is stored in the target. If TK_CONFIG_NULL_OK is specified in specFlags then the value may be an empty string, in which case the target will be set to NULL. If the previous value of the target was not NULL, then it is freed by passing it to Tk_FreeFont.

TK_CONFIG_INT
  値は strtol に受入れられる形式の ASCII 整数文字列でなければならない(譬えば､それぞれ八進と十六進数を指定する “0” と “0x” 前置辞が使われるかもしれない)｡文字列は整数値に変換され､整数は目標に保存される｡ The value must be an ASCII integer string in the format accepted by strtol (e.g. “0” and “0x” prefixes may be used to specify octal or hexadecimal numbers, respectively). The string is converted to an integer value and the integer is stored in the target.

TK_CONFIG_JOIN_STYLE
  値は Tk_GetJoinStyle に受入れられる内の一つの方法で接続様式を識別する ASCII 文字列でなければならない｡文字列は Tk_GetJoinStyle を呼出して接続様式に対応した整数に変換され､結果は目標に保存される｡ The value must be an ASCII string identifying a join style in one of the ways accepted by Tk_GetJoinStyle. The string is converted to an integer value corresponding to the join style by calling Tk_GetJoinStyle and the result is stored in the target.

TK_CONFIG_JUSTIFY
  値は Tk_GetJustify に受入れられる内の一つの方法で行端揃えを識別する ASCII 文字列でなければならない｡文字列は Tk_GetJustify を呼出して Tk_Justify に変換され､結果は目標に保存される｡ The value must be an ASCII string identifying a justification method in one of the ways accepted by Tk_GetJustify. The string is converted to a Tk_Justify by calling Tk_GetJustify and the result is stored in the target.

TK_CONFIG_MM
  値は Tk_GetScreenMM に受入れられる内の一つの方法で画面距離を識別しなければならない｡文字列は倍精度浮動小数ミリ単位の距離に変換され､値は目標に保存される｡ The value must specify a screen distance in one of the forms acceptable to Tk_GetScreenMM. The string is converted to double-precision floating-point distance in millimeters and the value is stored in the target.

TK_CONFIG_PIXELS
  値は Tk_GetPixels に受入れられる内の一つの方法で画面距離を識別しなければならない｡文字列は整数の画素単位の距離に変換され､値は目標に保存される｡ The value must specify screen units in one of the forms acceptable to Tk_GetPixels. The string is converted to an integer distance in pixels and the value is stored in the target.

TK_CONFIG_RELIEF
  値は Tk_GetRelief に渡すに適した形式の立体感を識別する ASCII 文字列でなければならない｡値は Tk_GetRelief を呼出して整数に変換され､結果は目標に保存される｡ suitable for passing to Tk_GetRelief. The value is converted to an integer relief value by calling Tk_GetRelief and the result is stored in the target.

TK_CONFIG_STRING
  値の複写は Tcl_Alloc を使い記憶域の割当てにより作られる､又､値を動的に割当てられた領域に複写する｡新しい文字列へのポインターは目標に保存される｡もし TK_CONFIG_NULL_OK が specFlags 内に設定された場合､値は空文字列になることもある｡その場合､目標は NULL に設定されることになる｡もし目標の以前の値が NULLでなければ､それを Tcl_Free に渡して解放される｡ A copy of the value is made by allocating memory space with Tcl_Alloc and copying the value into the dynamically-allocated space. A pointer to the new string is stored in the target. If TK_CONFIG_NULL_OK is specified in specFlags then the value may be an empty string, in which case the target will be set to NULL. If the previous value of the target was not NULL, then it is freed by passing it to Tcl_Free.

TK_CONFIG_SYNONYM
  この型の値は他の見出しに関する類義語である specs 内の特定の見出しを識別する｡ もし objv 値が TK_CONFIG_SYNONYM 見出しの argvName に合致する場合､その見出しは直接使われない｡ 代りに､ Tk_ConfigureWidget は specs からその argvName が TK_CONFIG_SYNONYM 見出し内の dbName と等しい他の見出しを求めて捜す; この新しい見出しは､恰もその argvName が objv に合致したかの如く使われる｡ 類義語の仕組みは多重の objv 値が一つの構成設定指示項目として使用されることを許容する､譬えば “-background” と “-bg” の様に｡ This type value identifies special entries in specs that are synonyms for other entries. If an objv value matches the argvName of a TK_CONFIG_SYNONYM entry, the entry is not used directly. Instead, Tk_ConfigureWidget searches specs for another entry whose argvName is the same as the dbName field in the TK_CONFIG_SYNONYM entry; this new entry is used just as if its argvName had matched the objv value. The synonym mechanism allows multiple objv values to be used for a single configuration option, such as “-background” and “-bg”.

TK_CONFIG_UID
  値は Tk_Uid に変換される( Tk_GetUid に渡されて)｡結果の値は目標に保存される｡もし TK_CONFIG_NULL_OK が specFlags 内に設定され且つ､値が空文字列の場合､目標は NULL に設定されることになる｡ The value is translated to a Tk_Uid (by passing it to Tk_GetUid). The resulting value is stored in the target. If TK_CONFIG_NULL_OK is specified in specFlags and the value is an empty string then the target will be set to NULL.

TK_CONFIG_WINDOW
  値は窓経路名でなければならない｡それは Tk_Window 字句に変換され､字句は目標に保存される｡ The value must be a window path name. It is translated to a Tk_Window token and the token is stored in the target.

### GROUPED ENTRIES

ある場合には一つの構成設定値から多重原資を生成すると便利である｡譬えば､色の名前は部品の為の背景の作成( TK_CONFIG_COLOR を使って)と､部品の周囲に描くために立体縁を作成( TK_CONFIG_BORDER を使って)する為の両方に使われる｡この様な場合､ specs 内の幾つかの連続した見出しを群として取扱われることを指定することが可能である｡最初の見出しは値の決定に使われる(その argvName, dbName, dbClass, and defValue 欄を使う)｡値は何回も処理され(群内のそれぞれの見出しの為に)､多重の異なる原資を生成し､ widgRec 内部の多重目標を修正する｡最初のものの後のそれぞれの見出しはその argvName 欄に NULL 値を有さなければならない; それは見出しは先行する見出しと一纏めにされることを意味する｡ type and offset 欄のみは其れに続く見出しに使われる｡ In some cases it is useful to generate multiple resources from a single configuration value. For example, a color name might be used both to generate the background color for a widget (using TK_CONFIG_COLOR) and to generate a 3-D border to draw around the widget (using TK_CONFIG_BORDER). In cases like this it is possible to specify that several consecutive entries in specs are to be treated as a group. The first entry is used to determine a value (using its argvName, dbName, dbClass, and defValue fields). The value will be processed several times (one for each entry in the group), generating multiple different resources and modifying multiple targets within widgRec. Each of the entries after the first must have a NULL value in its argvName field; this indicates that the entry is to be grouped with the entry that precedes it. Only the type and offset fields are used from these follow-on entries.

### FLAGS

Tk_ConfigureWidget に渡される flags 引数は specs の見出しの specFlags 欄と一緒に使われ､構成設定指示項目の処理に追加的は制御を提供する｡これ等の値は下に述べる異なる三つの方法で使用される｡ The flags argument passed to Tk_ConfigureWidget is used in conjunction with the specFlags fields in the entries of specs to provide additional control over the processing of configuration options. These values are used in three different ways as described below.

第１､もし Tk_ConfigureWidget への flags 引数が TK_CONFIG_ARGV_ONLY ビットを設定していた場合(即ち､ flags | TK_CONFIG_ARGV_ONLY != 0)､指示項目基礎データと defValue 欄は使われない｡この場合､もし specs 内の見出しが objv 内の欄に合致しない場合､何も起らない: 対応する目標は修正されない｡この性質は､ configure 部品命令が処理中の様な､現在の状態内に他が留まっている間に特定の構成設定指示項目を修正することが目的の場合には便利である｡ First, if the flags argument to Tk_ConfigureWidget has the TK_CONFIG_ARGV_ONLY bit set (i.e., flags | TK_CONFIG_ARGV_ONLY != 0), then the option database and defValue fields are not used. In this case, if an entry in specs does not match a field in objv then nothing happens: the corresponding target is not modified. This feature is useful when the goal is to modify certain configuration options while leaving others in their current state, such as when a configure widget command is being processed.

第２､ specs 内の見出しの specFlags 欄はその見出しの処理の制御に使われるかも知れない｡それぞれの specFlags 欄は､次の値の､或は､の結合で構成される: Second, the specFlags field of an entry in specs may be used to control the processing of that entry. Each specFlags field may consists of an OR-ed combination of the following values:

TK_CONFIG_COLOR_ONLY
  もしこのビットが設定されている場合､ tkwin の表示装置が１ビット以上の画面を有する場合にのみ見出しが考慮される｡もし表示装置が白黒の場合､この specs 見出しは無視される｡ If this bit is set then the entry will only be considered if the display for tkwin has more than one bit plane. If the display is monochromatic then this specs entry will be ignored.

TK_CONFIG_MONO_ONLY
  もしこのビットが設定されている場合､ tkwin の表示装置が正確に１ビット画面を有する場合にのみ見出しが考慮される｡もし表示装置が白黒でない場合､この specs 見出しは無視される｡ If this bit is set then the entry will only be considered if the display for tkwin has exactly one bit plane. If the display is not monochromatic then this specs entry will be ignored.

TK_CONFIG_NULL_OK
  このビットはある見出しの型にのみ適正である(上の種々の型の記述を参照されたい)｡もし､このビットが設定されている場合､それはその欄に関する空文字列が受入れられる事を指し示す､もしそれが生じると目標の型に従って､目標は NULL か無しが設定される｡この旗印は典型的には､見出しの取り止めを許容する為に使用される､譬えば､遊走子値をなしに設定して窓が単純に親の遊走子を引継ぐ｡もしこのビットが設定されていない場合､空文字列は文字列として処理され､それは一般には不都合になる｡ This bit is only relevant for some types of entries (see the descriptions of the various entry types above). If this bit is set, it indicates that an empty string value for the field is acceptable and if it occurs then the target should be set to NULL or None, depending on the type of the target. This flag 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. If this bit is not set then empty strings are processed as strings, which generally results in an error.

TK_CONFIG_DONT_SET_DEFAULT
  もしこのビットが１であると､見出しの defValue 欄は Tk_ConfigureInfo 内の無為設定を返す為に使われるべきである事を意味する｡ Tk_ConfigureWidget への呼出しでは､無為設定はこの旗印が設定された見出しには与えられない; 呼出し側は既に目標に無為設定を供給したことが仮定されている｡この旗印は無為設定文字列の処理が高負担である場合の最適化の改善を提供する: 依頼側は無為設定を一度計算でき､値を保存して Tk_ConfigureWidget を呼出す前に提供することができる｡ If this bit is one, it means that the defValue field of the entry should only be used for returning the default value in Tk_ConfigureInfo. In calls to Tk_ConfigureWidget no default will be supplied for entries with this flag set; it is assumed that the caller has already supplied a default value in the target location. This flag provides a performance optimization where it is expensive to process the default string: the client can compute the default once, save the value, and provide it before calling Tk_ConfigureWidget.

TK_CONFIG_MONO_ONLY と TK_CONFIG_COLOR_ONLY 旗印は典型的には､白黒と天然色表示装置の為に異なる無為設定を指定するために使われる｡これは specs の中に､その defValue と specFlags 欄に拘わることを除いて同一である二つの見出しを作る事によりなされる｡一つの見出しはその specFlags 内の値 TK_CONFIG_MONO_ONLY と､その defValue 内の白黒表示装置のための無為設定とを有するべきである; 他の見出しはその specFlags 内の値 TK_CONFIG_COLOR_ONLY と､天然色表示装置の為に適切な defValue とを有するべきである｡ The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are typically used to specify different default values for monochrome and color displays. This is done by creating two entries in specs that are identical except for their defValue and specFlags fields. One entry should have the value TK_CONFIG_MONO_ONLY in its specFlags and the default value for monochrome displays in its defValue; the other entry should have the value TK_CONFIG_COLOR_ONLY in its specFlags and the appropriate defValue for color displays.

第３､ flags と specFlags を一緒に使って何かの見出しを選択的に不能にすることに使えるかもしれない｡この性質は滅多に必要とされない｡幾つかの似ている種類の部品が一つの場所に実装されている場合に便利である｡それは全ての部品型の為の全ての構成設定指示項目を伴って一つの specs 表が作成されることを許容する｡特定の部品型の処理中はその型に適する見出しのみが使われる｡この効果は specFlags 値内か flags 内の高い順序のビットを( TK_CONFIG_USER_BIT と同じかより大きい位置内の)設定することで到達される｡ specs 内の特定の見出しの為に使われる為､その高い順序のビットは Tk_ConfigureWidget に渡された flags 値の高い順序のビットに厳密に合致しなければならない｡もし specs 表が N の異なる部品型の為に使われると､高い順序の N のビットが使われる｡それぞれの specs 見出しは多くのこれ等の中の一つのビットを specFlags 欄内に設定させて､この見出しが適正である部品型を示している｡ Tk_ConfigureWidget が呼ばれる時､ flags は好ましい部品型の為の見出しを選択する為にこれらのビットの内の１つを設定する｡この性質の動いている例は tkButton.c 内の符号命令を参照されたい｡ Third, it is possible to use flags and specFlags together to selectively disable some entries. This feature is not needed very often. It is useful in cases where several similar kinds of widgets are implemented in one place. It allows a single specs table to be created with all the configuration options for all the widget types. When processing a particular widget type, only entries relevant to that type will be used. This effect is achieved by setting the high-order bits (those in positions equal to or greater than TK_CONFIG_USER_BIT) in specFlags values or in flags. In order for a particular entry in specs to be used, its high-order bits must match exactly the high-order bits of the flags value passed to Tk_ConfigureWidget. If a specs table is being used for N different widget types, then N of the high-order bits will be used. Each specs entry will have one of more of those bits set in its specFlags field to indicate the widget types for which this entry is valid. When calling Tk_ConfigureWidget, flags will have a single one of these bits set to select the entries for the desired widget type. For a working example of this feature, see the code in tkButton.c.

### TK_CONFIGUREINFO

Tk_ConfigureInfo 手続函数は与えられた部品に就いて一つ或は全ての指示項目についての情報を得ることに使うことができる｡窓に関する字句(tkwin)と､部品の級に関する構成設定指示項目を記述する表(specs)と､部品に関する現在の情報を含む部品記録へのポインター(widgRec)と､ NULL argvName 引数が与えられ､ Tk_ConfigureInfo は窓に関する全ての構成設定指示項目を記述する文字列を生成する｡文字列は解釈実行機能 interp の結果に置かれる｡通常の状況では TCL_OK を返す; 不都合が生じると TCL_ERROR を返し､解釈実行機能の結果が不都合伝言文を含む｡ The Tk_ConfigureInfo procedure may be used to obtain information about one or all of the options for a given widget. Given a token for a window (tkwin), a table describing the configuration options for a class of widgets (specs), a pointer to a widget record containing the current information for a widget (widgRec), and a NULL argvName argument, Tk_ConfigureInfo generates a string describing all of the configuration options for the window. The string is placed in interpreter interp's result. Under normal circumstances it returns TCL_OK; if an error occurs then it returns TCL_ERROR and the interpreter's result will contain an error message.

もし argvName が NULL の場合､ Tk_ConfigureInfo により解釈実行機能の結果に残された値は､一つ或はそれ以上の見出しで構成され､そのそれぞれは一つの構成設定指示項目を記述する(即ち､ specs 内の一つの見出し)｡リスト内のそれぞれの見出しはそれぞれ２つか五つの値を含む｡もし相当する specs 内の見出しが型 TK_CONFIG_SYNONYM を有する場合､リストは二つの値を含む: 見出しの為の argvName と dbName (類義語名)｡それ以外では､リストは五つの値を有する: argvName, dbName, dbClass, defValue 現在の値｡現在の値は widgRec の適切な欄から Tk_NameOfColor の様な手続函数を呼出して計算される｡ If argvName is NULL, then the value left in the interpreter's result by Tk_ConfigureInfo consists of a list of one or more entries, each of which describes one configuration option (i.e. one entry in specs). Each entry in the list will contain either two or five values. If the corresponding entry in specs has type TK_CONFIG_SYNONYM, then the list will contain two values: the argvName for the entry and the dbName (synonym name). Otherwise the list will contain five values: argvName, dbName, dbClass, defValue, and current value. The current value is computed from the appropriate field of widgRec by calling procedures like Tk_NameOfColor.

Tk_ConfigureInfo への argvName 引数が非-NULL の場合､それは一つの指示項目を指し示す､又返される情報はその選択にの為のものだけである｡解釈実行機能の結果内に置かれた文字列は上で記述された様に二つか五つの値から構成されるリストである; これは argvName が NULL であった時に返される､対応する副リストと同一でる｡ If the argvName argument to Tk_ConfigureInfo is non-NULL, then it indicates a single option, and information is returned only for that option. The string placed in the interpreter's result will be a list containing two or five values as described above; this will be identical to the corresponding sublist that would have been returned if argvName had been NULL.

Tk_ConfigureInfo への flags 引数は Tk_ConfigureWidget の如く､考慮する為の specs 見出しを制限するために使われる｡ The flags argument to Tk_ConfigureInfo is used to restrict the specs entries to consider, just as for Tk_ConfigureWidget.

### TK_CONFIGUREVALUE

Tk_ConfigureValue は Tk_ConfigureInfo に似た引数を取る; 値のリストを返す代りに､ argvName ( argvName は NULLではないはず)によって与えられた指示項目の現在の値を返す｡値は解釈実行機能 interp の結果に返され､又通常 TCL_OK が手続函数の結果として返される｡不都合が Tk_ConfigureValue 内に生じると(譬えば､ argvName が適正な指示項目名ではない)､ TCL_ERROR が返され､不都合伝言文が解釈実行機能の結果に残される｡この手続函数は典型的には cget 部品命令を実装するために呼出される｡ Tk_ConfigureValue takes arguments similar to Tk_ConfigureInfo; instead of returning a list of values, it just returns the current value of the option given by argvName (argvName must not be NULL). The value is returned in interpreter interp's result and TCL_OK is normally returned as the procedure's result. If an error occurs in Tk_ConfigureValue (e.g., argvName is not a valid option name), TCL_ERROR is returned and an error message is left in the interpreter's result. This procedure is typically called to implement cget widget commands.

### TK_FREEOPTIONS

Tk_FreeOptions 手続函数は構成設定指示項目に結合した全ての原資を解放する為に部品を浄化している間に起動されるかもしれない｡それは specs と､それぞれの明示的に解放されるべき原資に対応する見出しについて走査し(譬えば､型 TK_CONFIG_COLOR の様な)､部品記録内の原資を解放する｡もし部品記録の欄が原資を参照していない場合(譬えば､零ポインターを含んでいた)､その見出しに就いては原資は解放されない｡原資の解放後､ Tk_FreeOptions は部品記録の相当する欄に零を設定する｡ The Tk_FreeOptions procedure may be invoked during widget cleanup to release all of the resources associated with configuration options. It scans through specs and for each entry corresponding to a resource that must be explicitly freed (e.g. those with type TK_CONFIG_COLOR), it frees the resource in the widget record. If the field in the widget record does not refer to a resource (e.g. it contains a null pointer) then no resource is freed for that entry. After freeing a resource, Tk_FreeOptions sets the corresponding field of the widget record to null.

### CUSTOM OPTION TYPES

応用譜は､型の指示項目を解析して印刷する為の手続函数を書き､これ等の手続函数を指す構造を作成することにより､追加的構成設定型を伴う組込み構成設定型を拡張可能である: Applications can extend the built-in configuration types with additional configuration types by writing procedures to parse and print options of the a type and creating a structure pointing to those procedures:

    typedef struct {
        Tk_OptionParseProc *parseProc;
        Tk_OptionPrintProc *printProc;
        void *clientData;
    } Tk_CustomOption;

    typedef int Tk_OptionParseProc(
            void *clientData,
            Tcl_Interp *interp,
            Tk_Window tkwin,
            const char *value,
            char *widgRec,
            Tcl_Size offset);

    typedef const char *Tk_OptionPrintProc(
            void *clientData,
            Tk_Window tkwin,
            char *widgRec,
            Tcl_Size offset,
            Tcl_FreeProc **freeProcPtr);

Tk_CustomOption 構造は三つの欄を含む､それは二つの手続函数へのポインターと､起動された時にこれ等の手続に渡される clientData 値である｡ clientData 値は典型的には指示項目を解析され印刷する時に手続函数に必要とされる情報を含む構造を指す｡ The Tk_CustomOption structure contains three fields, which are pointers to the two 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.

parseProc 手続函数は文字列を解析し結果の値を部品記録に保存する為に Tk_ConfigureWidget により起動される｡ clientData 引数は Tk_CustomOption 構造内の clientData 欄の複写である｡ interp 引数は不都合報告の為の Tcl 解釈実行機能を指す｡ tkwin は Tk_ConfigureWidget への tkwin 引数の複写である｡ value 引数は指示項目の為の値を記述する文字列である; それは Tk_ConfigureWidget への呼出し内で明示的に指定される得が､指示項目基礎データか､無為設定に由来することもある｡ value は零ポインターになることはないが､空文字列を指すかもしれない｡ RecordPtr は Tk_ConfigureWidget への widgRec 引数と同じである; それは修正すべき部品の記録の開始を指す｡最後の引数 offset は指示項目値が置かれるべき部品記録の開始位置からの偏寄をバイト単位で与える｡手続函数は文字列を何であれ指示項目の為に適切な形式に変換し部品記録に保存する｡それは通常 TCL_OK を返すが､文字列から値への変換に不都合が生じ場合､それは TCL_ERROR を返し､不都合伝言文を解釈実行機能 interp の結果に保存する｡ The parseProc procedure is invoked by Tk_ConfigureWidget to parse a string and store the resulting value in the widget record. The clientData argument is a copy of the clientData field in the Tk_CustomOption structure. The interp argument points to a Tcl interpreter used for error reporting. Tkwin is a copy of the tkwin argument to Tk_ConfigureWidget. The value argument is a string describing the value for the option; it could have been specified explicitly in the call to Tk_ConfigureWidget or it could come from the option database or a default. Value will never be a null pointer but it may point to an empty string. RecordPtr is the same as the widgRec argument to Tk_ConfigureWidget; it points to the start of the widget record to modify. The last argument, offset, gives the offset in bytes from the start of the widget record to the location where the option value is to be placed. The procedure should translate the string to whatever form is appropriate for the option and store the value in the widget record. It should normally return TCL_OK, but if an error occurs in translating the string to a value then it should return TCL_ERROR and store an error message in interpreter interp's result.

printProc 手続函数は既存の指示項目を記述する文字列値を生成する為に Tk_ConfigureInfo に呼出される｡その clientData, tkwin, widgRec, and offset 引数全ては Tk_OptionParseProc 手続函数の為と同じ意味を有する｡ printProc 手続函数は､その値が widgRec 内の offset の箇所に保存される指示項目を調べ､その指示項目を記述する文字列を生成し､その文字列へのポインターを返す｡もし文字列が動的に割当てられた記憶域に保存されると､手続函数は文字列の記憶域を解放する為に *freeProcPtr を手続函数の番地に設定しなければならない; Tk_ConfigureInfo は文字列が終った時に､この手続函数を呼ぶ｡もし結果の文字列が静的記憶に保存されている場合､ printProc は freeProcPtr 引数について何もする必要がない｡ The printProc procedure is called by Tk_ConfigureInfo to produce a string value describing an existing option. Its clientData, tkwin, widgRec, and offset arguments all have the same meaning as for Tk_OptionParseProc procedures. The printProc procedure should examine the option whose value is stored at offset in widgRec, produce a string describing that option, and return a pointer to the string. If the string is stored in dynamically-allocated memory, then the procedure must set *freeProcPtr to the address of a procedure to call to free the string's memory; Tk_ConfigureInfo will call this procedure when it is finished with the string. If the result string is stored in static memory then printProc need not do anything with the freeProcPtr argument.

一度 parseProc と printProc が定義され､ Tk_CustomOption 構造がその為に作成され､新しい型の指示項目が Tk_ConfigSpec 見出しを伴って実装される､その型欄は TK_CONFIG_CUSTOM でありその customPtr 欄は Tk_CustomOption 構造を指す｡ Once parseProc and printProc have been defined and a Tk_CustomOption structure has been created for them, options of this new type may be manipulated with Tk_ConfigSpec entries whose type fields are TK_CONFIG_CUSTOM and whose customPtr fields point to the Tk_CustomOption structure.

### 用例 EXAMPLES

Tk_ConfigureWidget の説明は大変込入っているが､実際の使用は素直である｡最も容易な始め方は既存の部品から符号命令を複写することである｡枠の実装の外部函数は(tkFrame.c)簡単な構成設定表を有する､又釦の実装の外部函数は(tkButton.c)更に複雑な表を有し､多数の面白い specFlags 仕組みを使う｡ Although the explanation of Tk_ConfigureWidget is fairly complicated, its actual use is pretty straightforward. The easiest way to get started is to copy the code from an existing widget. The library implementation of frames (tkFrame.c) has a simple configuration table, and the library implementation of buttons (tkButton.c) has a much more complex table that uses many of the fancy specFlags mechanisms.

### SEE ALSO

Tk_SetOptions

### KEYWORDS

anchor, bitmap, boolean, border, cap style, color, configuration options, cursor, custom, double, font, integer, join style, justify, millimeters, pixels, relief, synonym, uid
Copyright © 1990-1994 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.