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

### 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_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursorFromObj, Tk_FreeCursor — 遊走子の基礎データの維持 maintain database of cursors
  SYNOPSIS
    #include <tk.h>
    Tk_Cursor
    Tk_AllocCursorFromObj(interp, tkwin, objPtr)
    Tk_Cursor
    Tk_GetCursor(interp, tkwin, name)
    Tk_Cursor
    Tk_GetCursorFromObj(tkwin, objPtr)
    Tk_Cursor
    Tk_GetCursorFromData(interp, tkwin, source, mask, width, height, xHot, yHot, fg, bg)
    const char *
    Tk_NameOfCursor(display, cursor)
    Tk_FreeCursorFromObj(tkwin, objPtr)
    Tk_FreeCursor(display, cursor)
  引数 ARGUMENTS
    Tcl_Interp *interp (入力in)
    Tk_Window tkwin (入力in)
    Tcl_Obj *objPtr (in/out)
    const char *name (入力in)
    const char *source (入力in)
    const char *mask (入力in)
    int width (入力in)
    int height (入力in)
    int xHot (入力in)
    int yHot (入力in)
    const char *fg (入力in)
    const char *bg (入力in)
    Display *display (入力in)
    Tk_Cursor cursor (入力in)
  説明 DESCRIPTION
    name [fgColor [bgColor]]
    @sourceName maskName fgColor bgColor
    @sourceName fgColor
    @sourceName
  瑕疵 BUGS
  KEYWORDS

### NAME

Tk_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursorFromObj, Tk_FreeCursor — 遊走子の基礎データの維持 maintain database of cursors

### SYNOPSIS

#include <tk.h>
Tk_Cursor
Tk_AllocCursorFromObj(interp, tkwin, objPtr)
Tk_Cursor
Tk_GetCursor(interp, tkwin, name)
Tk_Cursor
Tk_GetCursorFromObj(tkwin, objPtr)
Tk_Cursor
Tk_GetCursorFromData(interp, tkwin, source, mask, width, height, xHot, yHot, fg, bg)
const char *
Tk_NameOfCursor(display, cursor)
Tk_FreeCursorFromObj(tkwin, objPtr)
Tk_FreeCursor(display, cursor)

### 引数 ARGUMENTS

Tcl_Interp *interp (入力in)
  不都合の報告に使う為の解釈実行機能｡　 Interpreter to use for error reporting.

Tk_Window tkwin (入力in)
  遊走子が使用されることになる窓の字句｡　 Token for window in which the cursor will be used.

Tcl_Obj *objPtr (in/out)
  遊走子の記述; 可能な値については下を参照されたい｡内部代表は対応するTk_Cursor への高速記憶域への指示子を修正する｡　 Description of cursor; see below for possible values. Internal rep will be modified to cache pointer to corresponding Tk_Cursor.

const char *name (入力in)
  objPtr と同一､但し遊走子の記述は文字列として手渡され､結果のTk_Cursor は高速記憶域に記憶されない｡　 Same as objPtr except description of cursor is passed as a string and resulting Tk_Cursor is not cached.

const char *source (入力in)
  遊走子 cursor のデータ､標準遊走子書式による｡　 Data for cursor cursor, in standard cursor format.

const char *mask (入力in)
  櫛 cursor のデータ､標準遊走子書式による｡　 Data for mask cursor, in standard cursor format.

int width (入力in)
  源資と櫛の巾｡　 Width of source and mask.

int height (入力in)
  源資と櫛の高さ｡　 Height of source and mask.

int xHot (入力in)
  遊走子の指示点のX-位置｡　 X-location of cursor hot-spot.

int yHot (入力in)
  遊走子の指示点のY-位置｡　 Y-location of cursor hot-spot.

const char *fg (入力in)
  遊走子の前景色の文書的記述｡　 Textual description of foreground color for cursor.

const char *bg (入力in)
  遊走子の背景色の文書的記述｡　 Textual description of background color for cursor.

Display *display (入力in)
  遊走子が割当てられる表示器　 Display for which cursor was allocated.

Tk_Cursor cursor (入力in)
  遊走子の不透明な Tk 識別子｡もしTk_FreeCursorに手渡される場合､以前の Tk_GetCursor か Tk_GetCursorFromData への呼出しによって予め返されていなければならない｡　 Opaque Tk identifier for cursor. If passed to Tk_FreeCursor, must have been returned by some previous call to Tk_GetCursor or Tk_GetCursorFromData.

### 説明 DESCRIPTION

これ等の手続は応用譜に使用される遊走子の集まりを管理する｡その手続函数は遊走子が効果的に再使用されることを許容し､そこで中央集中処理装置の負担を避け､又､遊走子が文字列で名前を付けられる事を許容する｡ These procedures manage a collection of cursors being used by an application. The procedures allow cursors to be re-used efficiently, thereby avoiding server overhead, and also allow cursors to be named with character strings.

Tk_AllocCursorFromObj は遊走子を記述する対象を引数として取り､記述に対応する遊走子に関する不透明な Tk 識別子を返す｡もし可能なら､既存の遊走子を再使用する､だめなら新しく別のを作成する｡ Tk_AllocCursorFromObj は objPtr,内の返り値に関する情報を高速域に記憶する､それは Tk_AllocCursorFromObj や Tk_GetCursorFromObj. の将来の呼出しを高速化する｡もし､譬えば objPtr が実在しないファイルを参照した時の様に､遊走子の作成に不都合が生じると､ None が返され､もし解釈実行機能が NULL.でなければ､不都合伝言文が解釈実行機能の結果に保存される｡ objPtr は次の形式の一つの標準 Tcl リストを含まねばならない: Tk_AllocCursorFromObj takes as argument an object describing a cursor, and returns an opaque Tk identifier for a cursor corresponding to the description. It re-uses an existing cursor if possible and creates a new one otherwise. Tk_AllocCursorFromObj caches information about the return value in objPtr, which speeds up future calls to procedures such as Tk_AllocCursorFromObj and Tk_GetCursorFromObj. If an error occurs in creating the cursor, such as when objPtr refers to a non-existent file, then None is returned and an error message will be stored in interp's result if interp is not NULL. ObjPtr must contain a standard Tcl list with one of the following forms:

name [fgColor [bgColor]]
  name は標準 X 遊走子遊走子内の遊走子の名前である､即ち､どの名前も XC_.なしに cursorcursor.h, 内に定義される｡値の幾つかの例は X_cursor, hand2, や left_ptr.である｡ Scheifler & Gettys 氏著 “The X Window System” の付録 B はこの様な遊走子がどの様な容貌かを図示している｡もし fgColor と bgColor の両方が指定されると､それは前景と背景色を遊走子の為に使う( Tk_GetColor が使うどの様な形式も受入れられる)｡もし fgColor のみが指定されると､背景色はない: 背景は透明になる｡もしどの色も指定されないと色は前景には黒､背景には白が使われる｡ Name is the name of a cursor in the standard X cursor cursor, i.e., any of the names defined in cursorcursor.h, without the XC_. Some example values are X_cursor, hand2, or left_ptr. Appendix B of “The X Window System” by Scheifler & Gettys has illustrations showing what each of these cursors looks like. If fgColor and bgColor are both specified, they give the foreground and background colors to use for the cursor (any of the forms acceptable to Tk_GetColor may be used). If only fgColor is specified, then there will be no background color: the background will be transparent. If no colors are specified, then the cursor will use black for its foreground color and white for its background color.

  Tk のマッキントッシュ版は全ての X 遊走子を運営し､又､ ibeam, crosshair, watch, plus, や arrow.を含む標準マック遊走子のどれも受入れられる｡更に､ Tk はマック遊走子原資の型 crsr (天然色)と CURS (白黒)を原資の名前により積み込む｡応用譜と公開動的外部函数源資は常に名付けられた遊走子を捜す｡もし衝突があると､常に天然色の遊走子が黒白遊走子より優先して積込まれる｡ The Macintosh version of Tk supports all of the X cursors and will also accept any of the standard Mac cursors including ibeam, crosshair, watch, plus, and arrow. In addition, Tk will load Macintosh cursor resources of the types crsr (color) and CURS (black and white) by the name of the resource. The application and all its open dynamic library's resource files will be searched for the named cursor. If there are conflicts color cursors will always be loaded in preference to black and white cursors.

@sourceName maskName fgColor bgColor
  この形式内の sourceName and maskName は遊走子の原資のビットと篩について遊走子を記述するファイルの名前である｡夫々のファイルは標準 X11 遊走子形式でなければならない｡ FgColor and bgColor は遊走子について色を指定する､ Tk_GetColor が使うどの様な形式も受入れられる｡この命令の形式はマックや Windows では動かない｡ In this form, sourceName and maskName are the names of files describing cursors for the cursor's source bits and mask. Each file must be in standard X11 cursor format. FgColor and bgColor indicate the colors to use for the cursor, in any of the forms acceptable to Tk_GetColor. This form of the command will not work on Macintosh or Windows computers.

@sourceName fgColor
  この形式は､上で説明したものとよく似ているが原資も櫛として使われることが異なる｡これは遊走子の背景が透明であることを意味する｡この命令の形式はマックや Windows では動かない｡ This form is similar to the one above, except that the source is used as mask also. This means that the cursor's background is transparent. This form of the command will not work on Macintosh or Windows computers.

@sourceName
  この形式は Windows 上でのみ動き､ sourceName.に指定したファイルから Windows の系遊走子を積込む(.ani or .cur)｡ This form only works on Windows, and will load a Windows system cursor (.ani or .cur) from the file specified in sourceName.

Tk_GetCursor は Tk_AllocCursorFromObj と同一であるが､違いは遊走子の記述は対象の代りに文字列で指定される｡これは Tk_GetCursor を返り値を高速記憶から妨げており､その為 Tk_GetCursor は Tk_AllocCursorFromObj.よりも効率が見劣りする｡ Tk_GetCursor is identical to Tk_AllocCursorFromObj except that the description of the cursor is specified with a string instead of an object. This prevents Tk_GetCursor from caching the return value, so Tk_GetCursor is less efficient than Tk_AllocCursorFromObj.

Tk_GetCursorFromObj は窓と遊走子を作成する為の記述を与えられ､既存の遊走子に関する字句を返す｡ Tk_GetCursorFromObj は実際遊走子を作成しない; 遊走子は以前の Tk_AllocCursorFromObj or Tk_GetCursor.によって作成されていなければならない｡返り値は objPtr 内に高速域に記憶されるそれは､将来の同じ objPtr と tkwin.を伴う Tk_GetCursorFromObj 呼出しを加速する｡ Tk_GetCursorFromObj returns the token for an existing cursor, given the window and description used to create the cursor. Tk_GetCursorFromObj does not actually create the cursor; the cursor must already have been created with a previous call to Tk_AllocCursorFromObj or Tk_GetCursor. The return value is cached in objPtr, which speeds up future calls to Tk_GetCursorFromObj with the same objPtr and tkwin.

Tk_GetCursorFromData は遊走子がその原資と篩遊走子の記憶内の記述から作成されることを許容する｡原資は遊走子の原資のビットについての標準遊走子データを指し｡又､ mask は原資のどの画素が描画されどれが透明と看做されるかを記述した標準遊走子データを指す｡ Width and height は遊走子の寸法を与え､ xHot and yHot は遊走子の熱点(行事が生じた時に報告される点)を指し示す､ fg and bg は遊走子の前景と背景の色を文書的に記述する( Tk_GetColor が使用できるどの形式も受入れられる)｡典型的には Tk_GetCursorFromData への引数は､算譜の為の原資に入れる直接遊走子ファイルを含むことにより作られる､つぎの例のように: Tk_GetCursorFromData allows cursors to be created from in-memory descriptions of their source and mask cursors. Source points to standard cursor data for the cursor's source bits, and mask points to standard cursor data describing which pixels of source are to be drawn and which are to be considered transparent. Width and height give the dimensions of the cursor, xHot and yHot indicate the location of the cursor's hot-spot (the point that is reported when an event occurs), and fg and bg describe the cursor's foreground and background colors textually (any of the forms suitable for Tk_GetColor may be used). Typically, the arguments to Tk_GetCursorFromData are created by including a cursor file directly into the source code for a program, as in the following example:

    Tk_Cursor cursor;
    #include "source.cursor"
    #include "mask.cursor"
    cursor = Tk_GetCursorFromData(interp, tkwin, source_bits,
        mask_bits, source_width, source_height, source_x_hot,
        source_y_hot, "red", "blue");

通常の条件下では Tk_GetCursorFromData は要求された遊走子のための識別子を返す｡もし遊走子の作成中に不都合が生じると､何も返されず不都合伝言文が解釈実行機能の結果に保存される｡ Under normal conditions Tk_GetCursorFromData will return an identifier for the requested cursor. If an error occurs in creating the cursor then None is returned and an error message will be stored in interp's result.

Tk_AllocCursorFromObj, Tk_GetCursor, and Tk_GetCursorFromData は以前に作成した全ての遊走子の基礎データを維持している｡何時であれ､可能な時は､ Tk_AllocCursorFromObj, Tk_GetCursor, or Tk_GetCursorFromData への呼出しは新しく作成したものでなく､既存の遊走子を返す｡この方法は引続き中央集中処理装置の負担を減らすので､ Tk 手続函数は XCreateFontCursor or XCreatePixmapCursor,の様な Xlib 手続函数より一般に優先して使用される､後者は新しい遊走子を呼出す度に作成する｡ Tk 手続函数は又低水準 X 手続函数よりも互換性に富む｡ Tk_AllocCursorFromObj, Tk_GetCursor, and Tk_GetCursorFromData maintain a database of all the cursors they have created. Whenever possible, a call to Tk_AllocCursorFromObj, Tk_GetCursor, or Tk_GetCursorFromData will return an existing cursor rather than creating a new one. This approach can substantially reduce server overhead, so the Tk procedures should generally be used in preference to Xlib procedures like XCreateFontCursor or XCreatePixmapCursor, which create a new cursor on each call. The Tk procedures are also more portable than the lower-level X procedures.

手続函数 Tk_NameOfCursor は大略 Tk_GetCursor.の逆である｡もしその遊走子引数が Tk_GetCursor,により作成された場合､返り値は名前引数であり､それは､遊走子を作成する為に Tk_GetCursor に渡されたものである｡もし遊走子が Tk_GetCursorFromData,への呼出しにより作成されたものか､何か他の仕組による場合､返り値は遊走子の X 識別子を与える十六進数である｡註意: Tk_NameOfCursor に返される文字列は次の Tk_NameOfCursor.への呼出し迄存続することが保証されるのみである｡又､この呼出しは Tk_GetCursor.に返された遊走子を除き互換性はない｡ The procedure Tk_NameOfCursor is roughly the inverse of Tk_GetCursor. If its cursor argument was created by Tk_GetCursor, then the return value is the name argument that was passed to Tk_GetCursor to create the cursor. If cursor was created by a call to Tk_GetCursorFromData, or by any other mechanism, then the return value is a hexadecimal string giving the X identifier for the cursor. Note that the string returned by Tk_NameOfCursor is only guaranteed to persist until the next call to Tk_NameOfCursor. Also, this call is not portable except for cursors returned by Tk_GetCursor.

Tk_AllocCursorFromObj, Tk_GetCursor, or Tk_GetCursorFromData から返された遊走子が最早不要になった時､それを解除する為に Tk_FreeCursorFromObj or Tk_FreeCursor が呼ばれる｡ Tk_FreeCursorFromObj について､解放される遊走子は作成された時と同じ情報が指定される｡夫々の Tk_AllocCursorFromObj かTk_GetCursor か Tk_GetCursorFromData への呼出し毎に１回の Tk_FreeCursor への呼出しがあるべきである｡ When a cursor returned by Tk_AllocCursorFromObj, Tk_GetCursor, or Tk_GetCursorFromData is no longer needed, Tk_FreeCursorFromObj or Tk_FreeCursor should be called to release it. For Tk_FreeCursorFromObj the cursor to release is specified with the same information used to create it; for Tk_FreeCursor the cursor to release is specified with its Tk_Cursor token. There should be exactly one call to Tk_FreeCursor for each call to Tk_AllocCursorFromObj, Tk_GetCursor, or Tk_GetCursorFromData.

### 瑕疵 BUGS

新しい要求を満足するために既存の遊走子が使えるかを定めるのに､Tk_AllocCursorFromObj と Tk_GetCursor と Tk_GetCursorFromData はその引数の直接の値のみを考慮する｡譬えば､ファイルの名前が Tk_GetCursor に渡された時､ Tk_GetCursor は同じファイル名から作成された既存の遊走子の再使用は安全であると仮定している: ファイル自身が変化したか､或は､現在のディレクトリーが変化したかを検査しない､そこで異なるファイルを参照する名前を惹き起こす｡同様に､ Tk_GetCursorFromData はもし同じ原資のポインターが二つの異なる呼出しに使われる場合､ポインターは同じデータを参照する; 実際のデータが変化したかを確認しない｡ In determining whether an existing cursor can be used to satisfy a new request, Tk_AllocCursorFromObj, Tk_GetCursor, and Tk_GetCursorFromData consider only the immediate values of their arguments. For example, when a file name is passed to Tk_GetCursor, Tk_GetCursor will assume it is safe to re-use an existing cursor created from the same file name: it will not check to see whether the file itself has changed, or whether the current directory has changed, thereby causing the name to refer to a different file. Similarly, Tk_GetCursorFromData assumes that if the same source pointer is used in two different calls, then the pointers refer to the same data; it does not check to see if the actual data values have changed.

### KEYWORDS

cursor
Copyright © 1990 The Regents of the University of California.
Copyright © 1994-1998 Sun Microsystems, Inc.