Chapter 2 Display Functions

2章 ディスプレイ関数

• ディスプレイを開く(と接続する)
• ディスプレイ、イメージフォーマット、スクリーンに関する情報を得る
• 何もしないプロトコル要求を生成する
• クライアントにより作られたデータを解放する
• ディスプレイを閉じる(との接続を切る)
• Xサーバとの接続を閉じる操作を使う
• スレッドでXlibを使う
• 内部接続を使う

Opening the Display

ディスプレイを制御しているXサーバと接続を開く XOpenDisplay .

Display *XOpenDisplay(display_name)
char *display_name;

display_name

ハードウェアのディスプレイ名を指定。これは使用するディスプレイと 通信ドメインを決める。 POSIX準拠のシステムでは、display_nameがNULの場合には DISPLAY環境変数の値が使われる。

	hostname:number.screen_number

hostname

ディスプレイが物理的に付いているホストマシンの名前を指定する。 次に、一つのコロン(:)または2つのコロン(::)が続く。

number

ホストマシンのディスプレイサーバの番号を指定。 オップションでディスプレイ番号の後にピリオド(.)が続く。 単独のCPUは一つ以上のディスプレイを持てる。 マルチディスプレイはゼロから番号付けされる。

screen_number

はサーバで使われるスクリーンを指定。 マルチスクリーンは一つのXサーバで制御される。 screen_numberは DefaultScreenマクロもしくはC以外の言語をつかうなら、 XDefaultScreen関数を使ってアクセスされる内部変数をセットする(2.2.1 節 参照)。

dual-headed:0.1

XOpenDisplay関数は Display 構造体を返す。 この構造体はXサーバへの接続を与え、またXサーバに関する全ての情報を 持っている。 XOpenDisplayTCP、DECnet通信プロトコル、または ローカルのプロセス間通信プロトコルを使って アプリケーションとXサーバを接続する。 hostnameがホストマシンの名で、一つのコロン(:)がホスト名とディスプレイ番号を 区切っている場合、 XOpenDisplayTCPストリームを使って接続を行う。 もしhostnameが指定されていない場合、 Xlibは最も通信が速いと思われるものを使用する。 hostnameがホストのマシン名で、2つのコロン(::)がホスト名と ディスプレイ番号を区切っている場合、 XOpenDisplayはDECnetを使って接続を行う。 単独のXサーバがこれらの転送機構のどれかあるいは全てをは同時にサポート していることがある。 特定のXlibの実装では、これら以外の通信機構をサポートしていることもある。

成功した場合には、 XOpenDisplay は Display 構造体へのポインタを返す。 この構造体は <X11/Xlib.h .>で定義されている。 失敗した場合には、 XOpenDisplay はNULLを返す。 XOpenDisplay ,の呼び出しに成功した後は、 クライアントはディスプレイの全てのスクリーンを使うことができる。 引き数display_nameで指定されたスクリーンの数は マクロ DefaultScreen(あるいは関数 XDefaultScreen)で返される。 Displayおよび Screen構造体の要素は専用のマクロや関数を使った場合だけアクセスが許される。 Display 構造体の情報を取得するマクロや関数の使用については、 2.2.1 節を参照すること。

Xサーバは様々な種類のアクセス制御機構を実装している。 (9.8 節参照)

Obtaining Information about the Display, Image Formats, or Screens

Xlibは Display構造体からデータを返す多くの便利なマクロやそれに相当する関数を与える。 マクロはCプログラミングで使われ、 これに相当する関数は他の言語とのバインディングのために使われる。 この節は以下のことを述べる：

• ディスプレイマクロ
• イメージフォーマット関数とマクロ
• スクリーン情報マクロ

Display 構造体の全ての他のメンバー(マクロが定義されていないものもある)はXlibにプライベイトなものであり、 これは使われてはならない。 アプリケーションは Display 構造体のプライベイトなメンバーを直接変更したり、参照してはならない。

Note: XDisplayWidth ,XDisplayHeight ,XDisplayCells ,XDisplayPlanes ,XDisplayWidthMM ,と XDisplayHeightMM関数は誤った名前である。 これらの関数はDisplay〜またはXDisplay〜ではなく、 Screen〜またはXScreen〜と名付けられるべきである。 この結果生じる混乱に対して我々は謝罪する。

Display Macros

アプリケーションは Displayと Screen構造体のどんな部分も直接変更すべきではない。 メンバーは読みだし専用と思われるが、 ディスプレイに対するいろいろな操作の結果として変更される。

次のものはC言語マクロと他の言語のバインディングのためにあるそれに相当する関数のリストであり、 両方とも何らかのデータを返す。

AllPlanes

unsigned long XAllPlanes()

両方とも全てのビットを1にした値を返す。これは関数の引き数planeで使える値 になっている。

BlackPixel WhitePixel はモノクロアプリケーションを実装する時に使われる。 これらのピクセル値はデフォルトのカラーマップに永続的に割り当てられた エントリーに対するものである。 実際のRGB(赤、緑、青)の値はいくつかのスクリーンでセットできる。 そして、どんな場合でも、実際に黒または白ではないかもしれない。 名前は予測される色の相対的な強度を伝えられている。

BlackPixel(display, screen_number)

unsigned long XBlackPixel(display, screen_number)
Display *display;
int screen_number;

display

Xサーバへの接続を指定。

screen_number

ホストサーバ上の適切なスクリーン番号を指定。

WhitePixel(display, screen_number)

unsigned long XWhitePixel(display, screen_number)
Display *display;
int screen_number;

display

Xサーバへの接続を指定。

screen_number

ホストサーバ上の適切なスクリーン番号を指定。

ConnectionNumber(display)

int XConnectionNumber(display)
Display *display;

display

Xサーバへの接続を指定。

DefaultColormap(display, screen_number)

Colormap XDefaultColormap(display, screen_number)
Display *display;
int screen_number;

display

Xサーバへの接続を指定する。

screen_number

ホストサーバ上の適切なスクリーン番号を指定する。

DefaultDepth(display, screen_number)

int XDefaultDepth(display, screen_number)
Display *display;
int screen_number;

display

Xサーバへの接続を指定。

screen_number

ホストサーバ上の適切なスクリーン番号を指定。

To determine the number of depths that are available on a given screen, use 与えられたスクリーン上で利用できる深さの数を決定するには、 XListDepths を使う。

int *XListDepths(display, screen_number, count_return)
Display *display;
int screen_number;
int *count_return;

display

Xサーバへの接続を指定。

screen_number

ホストサーバ上の適切なスクリーン番号を指定。

count_return

深さの数を返す。

DefaultGC(display, screen_number)

GC XDefaultGC(display, screen_number)
Display *display;
int screen_number;

display

Xサーバへの接続を指定。

screen_number

ホストサーバ上の適切なスクリーン番号を指定。

DefaultRootWindow(display)

Window XDefaultRootWindow(display)
Display *display;

display

Xサーバへの接続を指定。

DefaultScreenOfDisplay(display)

Screen *XDefaultScreenOfDisplay(display)
Display *display;

display

Xサーバへの接続を指定。

ScreenOfDisplay(display, screen_number)

Screen *XScreenOfDisplay(display, screen_number)
Display *display;
int screen_number;

display

Xサーバへの接続を指定。

screen_number

ホストサーバ上の適切なスクリーン番号を指定。

DefaultScreen(display)

int XDefaultScreen(display)
Display *display;

display

Xサーバへの接続を指定する。

DefaultVisual(display, screen_number)

Visual *XDefaultVisual(display, screen_number)
Display *display;
int screen_number;

display

Xサーバへの接続を指定。

screen_number

ホストサーバ上の適切なスクリーン番号を指定。

DisplayCells(display, screen_number)

int XDisplayCells(display, screen_number)
Display *display;
int screen_number;

display

Xサーバへの接続を指定。

screen_number

ホストサーバ上の適切なスクリーン番号を指定。

DisplayPlanes(display, screen_number)

int XDisplayPlanes(display, screen_number)
Display *display;
int screen_number;

display

Xサーバへの接続を指定する。

screen_number

ホストサーバ上の適切なスクリーン番号を指定する。

DisplayString(display)

char *XDisplayString(display)
Display *display;

display

Xサーバへの接続を指定する。

long XExtendedMaxRequestSize(display) Display *display;

display

Xサーバへの接続を指定する。

long XMaxRequestSize(display) Display *display;

display

Xサーバへの接続を指定する。

LastKnownRequestProcessed(display)

unsigned long XLastKnownRequestProcessed(display)
Display *display;

display

Xサーバへの接続を指定。

NextRequest(display)

unsigned long XNextRequest(display)
Display *display;

display

Xサーバへの接続を指定。

ProtocolVersion(display)

int XProtocolVersion(display)
Display *display;

display

Xサーバへの接続を指定。

ProtocolRevision(display)

int XProtocolRevision(display)
Display *display;

display

Xサーバへの接続を指定。

QLength(display)

int XQLength(display)
Display *display;

display

Xサーバへの接続を指定。

RootWindow(display, screen_number)

Window XRootWindow(display, screen_number)
Display *display;
int screen_number;

display

Xサーバへの接続を指定。

screen_number

ホストサーバ上の適切なスクリーン番号を指定。

ScreenCount(display)

int XScreenCount(display)
Display *display;

display

Xサーバへの接続を指定。

ServerVendor(display)

char *XServerVendor(display)
Display *display;

display

Xサーバ上の接続を指定。

VendorRelease(display)

int XVendorRelease(display)
Display *display;

display

Xサーバへの接続を指定。

Image Format Functions and Macros

アプリケーションはサーバが要求するフォーマットで Xサーバにデータを提示する必要がある。 アプリケーションを単純にするのに役立つように、データをコンバートするのに 要求される仕事の大部分がXlibにより提供される。 (セクション 8.7と16.8 参照)

XPixmapFormatValues構造体はピックスマップのフォーマットの情報へのインターフェイスを提供する。 この情報は接続セットアップ時に返される。

typedef struct {
	int depth;
	int bits_per_pixel;
	int scanline_pad;
} XPixmapFormatValues;

与えられたディスプレイに対するピックスマップフォーマット情報を得るには、 XListPixmapFormats を使う。

XPixmapFormatValues *XListPixmapFormats(display, count_return)
Display *display;
int *count_return;

display

Xサーバへの接続を指定。

count_return

ディスプレイによりサポートされるピックスマップのフォーマットの数を返す。

以下はC言語マクロと他の言語のバインディングのためにあるそれに相当する関数のリストである。 そして、これらは指定されたサーバおよびスクリーンに対して何らかのデータを返す。 これらは単純なアプリケーションと共にツールキットによって使われる。

ImageByteOrder(display)

int XImageByteOrder(display)
Display *display;

display

Xサーバへの接続を指定。

BitmapUnit(display)

int XBitmapUnit(display)
Display *display;

display

Xサーバへの接続を指定。

BitmapBitOrder(display)

int XBitmapBitOrder(display)
Display *display;

ビットマップがスクリーンに表示されるとき、各ビットの最も左のビットが 最上位(LSBFirst)であるか最下位(MSBFirst)であるかを示す。 このマクロまたは関数は LSBFirstまたは MSBFirst .のいずれかを返す。

BitmapPad(display)

int XBitmapPad(display)
Display *display;

display

Xサーバへの接続を返す。

DisplayHeight(display, screen_number)

int XDisplayHeight(display, screen_number)
Display *display;
int screen_number;

display

Xサーバへの接続を指定。

screen_number

ホストサーバ上の適切なスクリーン番号を指定。

DisplayHeightMM(display, screen_number)

int XDisplayHeightMM(display, screen_number)
Display *display;
int screen_number;

display

Xサーバへの接続を指定。

screen_number

ホストサーバ上の適切なスクリーン番号を指定。

DisplayWidth(display, screen_number)

int XDisplayWidth(display, screen_number)
Display *display;
int screen_number;

display

Xサーバへの接続を指定。

screen_number

ホストサーバ上への適切なスクリーン番号を指定。

DisplayWidthMM(display, screen_number)

int XDisplayWidthMM(display, screen_number)
Display *display;
int screen_number;

display

Xサーバへの接続を指定。

screen_number

ホストサーバ上の適切なスクリーン番号を指定。

Screen Information Macros

以下のものはC言語マクロまたは他の言語の バイディングのためにあるそれに相当する関数のリストであり、 これらは何らかのデータを返す。 これらのマクロや関数は適切なScreen構造体へのポインタを取る。

BlackPixelOfScreen(screen)

unsigned long XBlackPixelOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

WhitePixelOfScreen(screen)

unsigned long XWhitePixelOfScreen(screen)
Screen *screen;

screen

適切なスクリーン Screen構造体を指定。

CellsOfScreen(screen)

int XCellsOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

DefaultColormapOfScreen(screen)

Colormap XDefaultColormapOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

DefaultDepthOfScreen(screen)

int XDefaultDepthOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

DefaultGCOfScreen(screen)

GC XDefaultGCOfScreen(screen)
Screen *screen;

screen

適切な Screenスクリーン構造体を指定。

DefaultVisualOfScreen(screen)

Visual *XDefaultVisualOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

DoesBackingStore(screen)

int XDoesBackingStore(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

DoesSaveUnders(screen)

Bool XDoesSaveUnders(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

DisplayOfScreen(screen)

Display *XDisplayOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

int XScreenNumberOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

EventMaskOfScreen(screen)

long XEventMaskOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

WidthOfScreen(screen)

int XWidthOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

HeightOfScreen(screen)

int XHeightOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

WidthMMOfScreen(screen)

int XWidthMMOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

HeightMMOfScreen(screen)

int XHeightMMOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

MaxCmapsOfScreen(screen)

int XMaxCmapsOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

MinCmapsOfScreen(screen)

int XMinCmapsOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

PlanesOfScreen(screen)

int XPlanesOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

RootWindowOfScreen(screen)

Window XRootWindowOfScreen(screen)
Screen *screen;

screen

適切な Screen構造体を指定。

Generating a NoOperation Protocol Request

NoOperation プロトコルリクエストを実行するには、 XNoOp を使う。

XNoOp(display)
Display *display;

display

Xサーバへの接続を指定。

Freeing Client-Created Data

Xlib関数により作られたメモリ内のデータを解放するには、 XFree を使う。

XFree(data)
void *data;

data

解放されるデータを指定。

Closing the Display

ディスプレイを閉じるもしくはXサーバと接続を切るには、 XCloseDisplay .を使う。

XCloseDisplay(display)
Display *display;

display

Xサーバへの接続を指定。

XCloseDisplayはエラー BadGCを起こすことがある。

Xlibにはクライアントの接続が閉じられた後、生き残っているクライアントにより リソースが所有される事を認める関数がある。 クライアントの終了モードを変えるために、 XSetCloseDownMode を使う。

XSetCloseDownMode(display, close_mode)
Display *display;
int close_mode;

display

Xサーバへの接続を指定。

close_mode

クライアントの終了モードを指定。 DestroyAll , RetainPermanent , また RetainTemporary . を渡す。

XSetCloseDownModeはエラー BadValue を起こすことがある。

Using X Server Connection Close Operations

クライアントへのXサーバの接続が明示的に XCloseDisplayを呼び出すか、プロセスの終了によって閉じられる時、 Xサーバは次の操作を自動的に行う。

• クライアントに所有されている全てのセレクションを切り離す。 ( XSetSelectionOwner を参照)
• クライアントがポインタ、キーボードを捕まえているなら、 XUngrabPointerと XUngrabKeyboard を行う。
• クライアントがサーバを捕まえているなら、 XUngrabServer を行う。
• クライアントにより作られた透過的な接続口を開放する。
• 終了モードが RetainPermanentあるいは RetainTemporary のどちらであるかによって、 永続的、一時的なものとしてクライアントにより割り当てられた リソース(カラーマップエントリーを含む)をマークづけする。 しかしながら、これは明示的に他のアプリケーションが リソースを破棄する事をさまたげない。( XSetCloseDownMode を参照)

終了モードが DestroyAll ,である時、Xサーバは以下のように全てのクライアントのリソースを破壊する。

• クライアントのセーブセット内のウィンドウが クライアントにより作られたウィンドウの下位(サブウィンドウ)があるかどうかを 決定しようとする。 (セーブセットは他のクライアントウィンドウのリストである。 このウィンドウはセーブセットウィンドウとして参照される。) そうなら、Xサーバは最も近い親ウィンドウにセーブセットウィンドウを再び作る。 これは、セーブセットウィンドウがクライアントにより作られた下位のウィンドウではない ためである。 ふたたび作られた物はセーブセットウィンドウの左上の外側の角の(ルートウィンドウに対して) 変わらない絶対座標上に残す。
• セーブセットウィンドウがマップされていないなら、 MapWindowを実行する。 The X server does this even if the save-set window was not an inferior of a window created by the client. セーブセットウィンドウがクライアントにより作られた下位のウィンドウでないとしても、 Xサーバはこれを行う。
• クライアントにより作られた全てのウィンドウを破壊する。
• このXサーバ内でクライアントにより作られたウィンドウでないリソース(例えば Font , Pixmap , Cursor , Colormap , や GContext )における適切な解放リクエストを行う。
• クライアントアプリケーションにより割り当てられた全ての色とカラーマップエントリーを解放する。

Xサーバへの最後の接続が閉じられる時、追加的処理を起こす。 Xサーバは接続をおこなう、行わないというサイクルを通り抜ける。 Xサーバへの最後の接続が DestroyAll の終了モードで閉じられる時、 Xサーバは以下のような事を行う。

• 接続開始時の状態にリセットする。 Xサーバは RetainPermanentあるいは RetainTemporaryモードで終了したクライアントからの全てのリソースを破棄しようとする。
• 事前に定義されている全てのアトムのIDを消す。
• 全てのルートウィンドウにある全てのプロパティを消す。(4.3 節を参照)
• アクセス制御リストと共に全てのデバイスマップと属性 (例えば、キークリック、ベルの音量、そしてアクセラレータ) をリセットする。
• 標準的なルートタイトルとカーソルに戻す。
• デフォルトフォントパスを戻す。
• PointerRoot 状態の入力フォーカスに戻す。

しかしながら、終了モードを RetainPermanentあるいは RetainTemporary .にセットして接続を切るなら、Xサーバはリセットしない。

Using Xlib with Threads

スレッドを持つシステムにおいては、マルチスレッドで同時にXlibを使う ことを認めている。

コンカレントスレッドのサポートを初期化するには、 XInitThreads を使う。

Status XInitThreads( );

関数 XInitThreadsfunction initializes Xlib support for concurrent threads. はコンカレントスレッドのXlibサポートを初期化する。 この関数はマルチスレッドプログラミングの最初のXlib関数で なければならず、他のXlib関数が呼ばれる前に動作終了していなければならない。 この関数は初期化が成功すれば、ゼロでない値を返し、そうでない場合は、 ゼロを返す。 スレッドをサポートしないシステムの場合、この関数は必ずゼロを返す。

もしマルチスレッドでXlibの関数を平行して使う場合には、この関数を呼び出す だけでよい。 Xlibの関数の呼び出し全ては他のアクセス機構によって保護され(例えば、ツールキットで使われる 共通の排他ロックやクライアントプログラムでの明示的な処理)、 Xlibスレッドの初期化は必要ない。 単独スレッドのプログラムでは、この関数は呼ばない方がよい。

Xlib呼び出しからディスプレイを締め出すには、 XLockDisplay を使う。

void XLockDisplay(display)
Display *display;

display

Xサーバへの接続を指定。

ディスプレイの締め出しを解除するには、 XUnlockDisplay を使う。

void XUnlockDisplay(display)
Display *display;

display

Xサーバへの接続を指定。

Using Internal Connections

Xサーバへの接続に加えて、Xlibの実装は 他の種類のサーバへの接続を必要とする(例えば、 13章に示されているインプットメソッドサーバへの接続)。 複数のディスプレイを使っている、あるいは他の入力との組み合わせでディスプレイ を使うツールキットとクライアントはこれらの追加的な接続を得る必要がある。 これは入力が利用可能であり、その入力が利用可能な時、入力を処理する必要 があるまで正確にブロックするためである。 単一ディスプレイを使い、Xlibのイベント関数での入力 に対してブロックを使う単純なクライアントはこれらの機能を使う必要がない。

ディスプレイに対する内部接続を追跡するには、 XAddConnectionWatch を使う。

typedef void (*XConnectionWatchProc)(display, client_data, fd, opening, watch_data)
Display *display;
XPointer client_data;
int fd;
Bool opening;
XPointer *watch_data;

Status XAddConnectionWatch(display, procedure, client_data)
Display *display;
XWatchProc procedure;
XPointer client_data;

display

Xサーバへの接続を指定。

procedure

呼び出される手続きを指定。

client_data

付加的なクライアントデータを指定。

この関数はディスプレイをオープンした後はいつでも呼ぶことができる。 内部接続が既に存在する場合、登録された手続きは それぞれの接続に対して即座に呼び出される。 XAddConnectionWatchから処理が戻ってくる前に行われる。 XAddConnectionWatchは手続きの登録に成功すればゼロでない値を返し、 そうでない場合には、ゼロを返す。

登録する手続きからはXlibの関数を呼び出してはならない。 手続きが直接的、間接的に内部接続の状態を変えたり、 監視の手続きを変えたりした場合の結果は未定義である。 Xlibがスレッドを使うように初期化されている場合、この手続きは 呼び出される時にロックされたディスプレイを与えるが、ディスプレイをロックするような Xlib function that locks the display is not defined unless the executing Xlib関数を呼び出すとその結果は未定義となる。ただし、動作している スレッドが XLockDisplay .を使って外部からディスプレイをロックしている場合はこの限りではない。

ディスプレイに対する内部接続の監視を止めるには、 XRemoveConnectionWatch を使う。

Status XRemoveConnectionWatch(display, procedure, client_data)
Display *display;
XWatchProc procedure;
XPointer client_data;

display

Xサーバへの接続を指定。

procedure

呼び出される手続きを指定。

client_data

付加的なクライアントデータを指定。

内部接続において入力を処理するには、 XProcessInternalConnection を使う。

void XProcessInternalConnection(display, fd)
Display *display;
int fd;

display

Xサーバへの接続を指定。

fd

ファイルディスクリプタを指定する。

ディスプレイに対する現在の内部接続を得るには XInternalConnectionNumbers を使う。

Status XInternalConnectionNumbers(display, fd_return, count_return)
Display *display;
int **fd_return;
int *count_return;

display

Xサーバへの接続を指定。

fd_return

ファイルディスクリプタを返す。

count_return

ファイルディスクリプタの数を返す。