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

### 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_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap — 単一点地図の基礎データを維持する maintain database of single-plane pixmaps
  SYNOPSIS
    #include <tk.h>
    Pixmap
    Tk_AllocBitmapFromObj(interp, tkwin, objPtr)
    Pixmap
    Tk_GetBitmap(interp, tkwin, info)
    Pixmap
    Tk_GetBitmapFromObj(tkwin, objPtr)
    int
    Tk_DefineBitmap(interp, name, source, width, height)
    const char *
    Tk_NameOfBitmap(display, bitmap)
    Tk_SizeOfBitmap(display, bitmap, widthPtr, heightPtr)
    Tk_FreeBitmapFromObj(tkwin, objPtr)
    Tk_FreeBitmap(display, bitmap)
  引数 ARGUMENTS
    Tcl_Interp *interp (入力in)
    Tk_Window tkwin (入力in)
    Tcl_Obj *objPtr (入出力in/out)
    const char *info (入力in)
    const char *name (入力in)
    const void *source (入力in)
    int width (入力in)
    int height (入力in)
    int *widthPtr (出力out)
    int *heightPtr (出力out)
    Display *display (入力in)
    Pixmap bitmap (入力in)
  説明 DESCRIPTION
    @fileName
    name
      error
      gray75
      gray50
      gray25
      gray12
      hourglass
      info
      questhead
      question
      warning
      document
      stationery
      edition
      application
      accessory
      folder
      pfolder
      trash
      floppy
      ramdisk
      cdrom
      preferences
      querydoc
      stop
      note
      caution
  瑕疵 BUGS
  KEYWORDS

### NAME

Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap — 単一点地図の基礎データを維持する maintain database of single-plane pixmaps

### SYNOPSIS

#include <tk.h>
Pixmap
Tk_AllocBitmapFromObj(interp, tkwin, objPtr)
Pixmap
Tk_GetBitmap(interp, tkwin, info)
Pixmap
Tk_GetBitmapFromObj(tkwin, objPtr)
int
Tk_DefineBitmap(interp, name, source, width, height)
const char *
Tk_NameOfBitmap(display, bitmap)
Tk_SizeOfBitmap(display, bitmap, widthPtr, heightPtr)
Tk_FreeBitmapFromObj(tkwin, objPtr)
Tk_FreeBitmap(display, bitmap)

### 引数 ARGUMENTS

Tcl_Interp *interp (入力in)
  不都合の報告に使う為の解釈実行機能; もしヌルの場合､不都合後に不都合伝言文が残らない｡ Interpreter to use for error reporting; if NULL then no error message is left after errors.

Tk_Window tkwin (入力in)
  点地図が使用される窓に関する字句｡ Token for window in which the bitmap will be used.

Tcl_Obj *objPtr (入出力in/out)
  望ましい点地図を記述する文字列値; 内部代表は対応する点地図への高速記憶域への指示子を修正する｡　 String value describes desired bitmap; internal rep will be modified to cache pointer to corresponding Pixmap.

const char *info (入力in)
  objPtr と同一､但し点地図の記述は文字列として手渡され､結果の画素地図は高速記憶域に記憶されない｡ Same as objPtr except description of bitmap is passed as a string and resulting Pixmap is not cached.

const char *name (入力in)
  定義すべき新しい点地図の名前｡　 Name for new bitmap to be defined.

const void *source (入力in)
  標準点地図書式による点地図のデータ｡値が変化することのない静的記憶内に保存されねばならない｡　 Data for bitmap, in standard bitmap format. Must be stored in static memory whose value will never change.

int width (入力in)
  点地図の巾 Width of bitmap.

int height (入力in)
  点地図の高さ Height of bitmap.

int *widthPtr (出力out)
  点地図の巾を満たす為の単語への指示子｡ Pointer to word to fill in with bitmap's width.

int *heightPtr (出力out)
  点地図の高さを満たす為の単語への指示子｡ Pointer to word to fill in with bitmap's height.

Display *display (入力in)
  点地図が割当てられた表示器｡　 Display for which bitmap was allocated.

Pixmap bitmap (入力in)
  Tk_AllocBitmapFromObj 又は Tk_GetBitmap によって割当てられた点地図の識別子｡　 Identifier for a bitmap allocated by Tk_AllocBitmapFromObj or Tk_GetBitmap.

### 説明 DESCRIPTION

これ等の手続函数は応用譜に使用されている点地図(一つの平面の画素地図)の集まりを管理する｡手続函数は点地図が効率的に再使用されることを許容し､それにより中央集中処理装置の負担を回避し､又､点地図に文字の文字列による名前付けを許容する｡ These procedures manage a collection of bitmaps (one-plane pixmaps) being used by an application. The procedures allow bitmaps to be re-used efficiently, thereby avoiding server overhead, and also allow bitmaps to be named with character strings.

Tk_AllocBitmapFromObj は点地図に関する画素地図識別子を返す､それは objPtr の記述に合致し､ tkwin.内の使用に適している｡それはもし可能なら､既存の点地図を再使用する､又､そうでない場合は新しく作る｡ objPtr の値は次の形式の内の一つでなければならない: Tk_AllocBitmapFromObj returns a Pixmap identifier for a bitmap that matches the description in objPtr and is suitable for use in tkwin. It re-uses an existing bitmap, if possible, and creates a new one otherwise. ObjPtr's value must have one of the following forms:

@fileName
  FileName は標準 X11 形式で記述されている点地図を含むファイルの名前でなければならない｡ FileName must be the name of a file containing a bitmap description in the standard X11 format.

name
  Name は予め Tk_DefineBitmap 呼出しにより定義した点地図の名前でなければならない｡次の名前は Tk によって定義されている: Name must be the name of a bitmap defined previously with a call to Tk_DefineBitmap. The following names are pre-defined by Tk:

  error
    国際的な “駄目” の信号: 円を横切る径線｡ The international “don't” symbol: a circle with a diagonal line across it.

  gray75
    75% 灰色:４つの内の３が燈る格子板模様｡ 75% gray: a checkerboard pattern where three out of four bits are on.

  gray50
    50% 灰色:一つづつ交互に燈る格子板模様｡ 50% gray: a checkerboard pattern where every other bit is on.

  gray25
    25% 灰色:四つ毎に燈る格子板模様｡ 25% gray: a checkerboard pattern where one out of every four bits is on.

  gray12
    12.5% 灰色:八分の一が燈る､一つ置きの並びの中の四つ毎の画素によって構成される｡ 12.5% gray: a pattern where one-eighth of the bits are on, consisting of every fourth pixel in every other row.

  hourglass
    砂時計記号｡ An hourglass symbol.

  info
    大きな “i” の文字｡ A large letter “i”.

  questhead
    疑問符がついた人物の頭の影絵｡ The silhouette of a human head, with a question mark in it.

  question
    大きな疑問符｡ A large question-mark.

  warning
    大きな感嘆符 A large exclamation point.

    更にマッキントッシュのみで予備定義した次の名前が利用できる: In addition, the following pre-defined names are available only on the Macintosh platform:

    document
      共通文書　 A generic document.

    stationery
      説明書の文房具 Document stationery.

    edition
      校正徴｡ The edition symbol.

    application
      共通応用譜アイコン Generic application icon.

    accessory
      机備品｡ A desk accessory.

    folder
      汎用冊子アイコン Generic folder icon.

    pfolder
      施錠フォルダー　 A locked folder.

    trash
      屑篭　 A trash can.

    floppy
      軟盤 A floppy disk.

    ramdisk
      仮想軟盤 A floppy disk with chip.

    cdrom
      小型盤アイコン A cd disk icon.

    preferences
      A folder with prefs symbol.

    querydoc
      基礎データ説明書アイコン A database document icon.

    stop
      停止記号｡ A stop sign.

    note
      風船に入った語と向合う顔｡ A face with balloon words.

    caution
      感嘆符を伴う三角｡ A triangle with an exclamation point.

通常の環境下では Tk_AllocBitmapFromObj は要求された画素地図の識別子を返す｡もし画素地図を作成する間に不都合が生じると､ objPtr が実在しないファイルを参照するような時､何も返されず不都合伝言文が解釈実行機能が NULL でない限り､解釈実行機能に残される｡ Tk_AllocBitmapFromObj は objPtr 内の返り値に関する情報を高速記憶域に記憶するので､将来の Tk_AllocBitmapFromObj や Tk_GetBitmapFromObj の様な呼び出しを加速する｡ Under normal conditions, Tk_AllocBitmapFromObj returns an identifier for the requested bitmap. If an error occurs in creating the bitmap, such as when objPtr refers to a non-existent file, then None is returned and an error message is left in interp's result if interp is not NULL. Tk_AllocBitmapFromObj caches information about the return value in objPtr, which speeds up future calls to procedures such as Tk_AllocBitmapFromObj and Tk_GetBitmapFromObj.

Tk_GetBitmap は Tk_AllocBitmapFromObj と同一であるが､違いは点地図の記述は対象の代りに文字列で指定する｡これは Tk_GetBitmap を高速記憶から阻むので Tk_GetBitmap は Tk_AllocBitmapFromObj より効率が見劣りする｡ Tk_GetBitmap is identical to Tk_AllocBitmapFromObj except that the description of the bitmap is specified with a string instead of an object. This prevents Tk_GetBitmap from caching the return value, so Tk_GetBitmap is less efficient than Tk_AllocBitmapFromObj.

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

Tk_DefineBitmap は記憶域内の点地図データと名前を結合するので､名前は後の Tk_AllocBitmapFromObj や Tk_GetBitmap.呼出しに使える｡ nameId 引数は点地図の名前を与える; それは以前の Tk_DefineBitmap 呼出しに使われていてはならない｡ source, width, and height 引数は点地図を記述する｡Tk_DefineBitmap は通常 TCL_OK を返す; もし不都合が生じると(譬えば､ nameId と名付けた点地図が既に定義されていた)､ TCL_ERROR が返され不都合伝言文が解釈実行機能に残される｡註意: Tk_DefineBitmap は source に指された静的記憶域であることを期待している: Tk_DefineBitmap はこの記憶の私的複写を作成しないが､後の Tk_AllocBitmapFromObj や Tk_GetBitmap 呼出し内で source により指示されたバイトを使用する｡ Tk_DefineBitmap associates a name with in-memory bitmap data so that the name can be used in later calls to Tk_AllocBitmapFromObj or Tk_GetBitmap. The nameId argument gives a name for the bitmap; it must not previously have been used in a call to Tk_DefineBitmap. The arguments source, width, and height describe the bitmap. Tk_DefineBitmap normally returns TCL_OK; if an error occurs (e.g. a bitmap named nameId has already been defined) then TCL_ERROR is returned and an error message is left in interpreter interp's result. Note: Tk_DefineBitmap expects the memory pointed to by source to be static: Tk_DefineBitmap does not make a private copy of this memory, but uses the bytes pointed to by source later in calls to Tk_AllocBitmapFromObj or Tk_GetBitmap.

典型的には Tk_DefineBitmap は #include-している点地図ファイルにより直接 C 算譜に使われファイルに定義される変数の参照をする｡譬えばファイル stip.bitmap が実在すると仮定すると､それは､ bitmap 算譜によって作成された且つ点画紋様を含む｡次の符号命令は新しい foo と名付けた点地図を定義する為に Tk_DefineBitmap を使う: Typically Tk_DefineBitmap is used by #include-ing a bitmap file directly into a C program and then referencing the variables defined by the file. For example, suppose there exists a file stip.bitmap, which was created by the bitmap program and contains a stipple pattern. The following code uses Tk_DefineBitmap to define a new bitmap named foo:

    Pixmap bitmap;
    #include "stip.bitmap"
    Tk_DefineBitmap(interp, "foo", stip_bits,
        stip_width, stip_height);
    	...
    bitmap = Tk_GetBitmap(interp, tkwin, "foo");

この符号命令は点地図ファイルに機械語翻訳時に読まれ点地図情報を算譜の実行可能影像に合体させる｡同じ点地図ファイルは実行時に Tk_GetBitmap を使って読むことができる: This code causes the bitmap file to be read at compile-time and incorporates the bitmap information into the program's executable image. The same bitmap file could be read at run-time using Tk_GetBitmap:

    Pixmap bitmap;
    bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap");

第２の形式は幾らか柔軟であるが(算譜が機械語翻訳された後で､ファイルが修正できる､又は異なるファイルを読む為に異なる文字列を提供できる)､若干遅くなり､且つ､点地図ファイルが算譜と別に存在することが要求される｡ The second form is a bit more flexible (the file could be modified after the program has been compiled, or a different string could be provided to read a different file), but it is a little slower and requires the bitmap file to exist separately from the program.

Tk は現在使われている全ての点地図の基礎データを運営する｡何時であれ可能な時は､新しく作るのではなく､既存の点地図を返す｡点地図が最早使われなくなると､ Tk は自動的に解放する｡この利用法は継続的な中央集中処理装置の負担を減ずるので､一般には XReadBitmapFile の様な Xlib 手続函数よりも Tk_AllocBitmapFromObj and Tk_GetBitmap を使うべきである｡ Tk maintains a database of all the bitmaps that are currently in use. Whenever possible, it will return an existing bitmap rather than creating a new one. When a bitmap is no longer used, Tk will release it automatically. This approach can substantially reduce server overhead, so Tk_AllocBitmapFromObj and Tk_GetBitmap should generally be used in preference to Xlib procedures like XReadBitmapFile.

Tk_AllocBitmapFromObj と Tk_GetBitmap に返された点地図は共有されるので､呼出し側は修正してはならない｡もし動的に点地図を修正する必要がある時は､直接 XReadBitmapFile か XCreatePixmap の様な Xlib を呼出して作成するべきである｡ The bitmaps returned by Tk_AllocBitmapFromObj and Tk_GetBitmap are shared, so callers should never modify them. If a bitmap must be modified dynamically, then it should be created by calling Xlib procedures such as XReadBitmapFile or XCreatePixmap directly.

手続函数Tk_NameOfBitmap は大略 Tk_GetBitmap の逆である｡ X 画素地図引数を与えられ､点地図が作成された時に Tk_GetBitmap に渡された文字的な記述を返す｡点地図は以前の Tk_AllocBitmapFromObj か Tk_GetBitmap への呼出しにより返された値でなければならない｡ The procedure Tk_NameOfBitmap is roughly the inverse of Tk_GetBitmap. Given an X Pixmap argument, it returns the textual description that was passed to Tk_GetBitmap when the bitmap was created. Bitmap must have been the return value from a previous call to Tk_AllocBitmapFromObj or Tk_GetBitmap.

Tk_SizeOfBitmap はその点地図引数の寸法を widthPtr と heightPtr 引数により指される語に返す｡ Tk_NameOfBitmap と同じ様に点地図は以前の Tk_AllocBitmapFromObj か Tk_GetBitmap への呼出しにより返された値でなければならない｡ Tk_SizeOfBitmap returns the dimensions of its bitmap argument in the words pointed to by the widthPtr and heightPtr arguments. As with Tk_NameOfBitmap, bitmap must have been created by Tk_AllocBitmapFromObj or Tk_GetBitmap.

点地図が最早必要なくなった時はそれを解放する為にTk_FreeBitmapFromObj か Tk_FreeBitmap が呼ばれるべきである｡ Tk_FreeBitmapFromObj に就いて､点地図の解放はそれを作った時に使ったと同じ情報を指定する; Tk_FreeBitmap について､解放するためにその点地図字句を指定する｡それぞれの Tk_AllocBitmapFromObj や Tk_GetBitmap 呼出しについて厳密に一回の Tk_FreeBitmapFromObj か Tk_FreeBitmap 呼出しがあるべきである｡ When a bitmap is no longer needed, Tk_FreeBitmapFromObj or Tk_FreeBitmap should be called to release it. For Tk_FreeBitmapFromObj the bitmap to release is specified with the same information used to create it; for Tk_FreeBitmap the bitmap to release is specified with its Pixmap token. There should be exactly one call to Tk_FreeBitmapFromObj or Tk_FreeBitmap for each call to Tk_AllocBitmapFromObj or Tk_GetBitmap.

### 瑕疵 BUGS

新しい要求を満足するために既存の点地図は使えるかを定める時に､ Tk_AllocBitmapFromObj と Tk_GetBitmap は文字列記述の直接の値のみしか考慮しない｡譬えば､ファイル名前が Tk_GetBitmap に渡された時 Tk_GetBitmap は同じファイル名から作成された既存の点地図の再使用は安全であることを仮定する: それは､ファイル自身が変更されたか､現在のディレクトリーは変更されているかを確認しない､そこで異なるファイルを参照する名前が惹き起こされる｡ In determining whether an existing bitmap can be used to satisfy a new request, Tk_AllocBitmapFromObj and Tk_GetBitmap consider only the immediate value of the string description. For example, when a file name is passed to Tk_GetBitmap, Tk_GetBitmap will assume it is safe to re-use an existing bitmap 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.

### KEYWORDS

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