XPM:Basic functions

目次
1 イントロ
2 入門編／とりあえず使ってみる
3 応用編／アトリビュートを使う

# 2. 入門編／とりあえず使ってみる

この章では、XPMファイルおよびインクルードされたデータからPixmap を作ってみます。また、エラー時にエラーの説明を取得します。

## 2.1. ヘッダファイル

XPMライブラリを使うときは、`X11/xpm.h`をインクルードします。 なぜか`x`が小文字です。注意して下さい。

## 2.2. ライブラリのリンク

コンパイルする時は`libXpm`をリンクします。 こっちの`X`は大文字です。 これ以降のサンプルソースをコンパイルする時は、FreeBSDだと次のようになります。

    $ cc -o sample1 sample1.c -lXaw -lXmu -lXt -lXpm -lX11 -L/usr/X11R6/lib -I/usr/X11R6/include

## 2.3. XPMファイルから読んでみよう

sample1.cは、 コマンドラインで指定したXPMファイルを表示するプログラムです。

### 2.3.1. XpmReadFiletoPixmap関数

XPMファイルを読み込んでPixmapを作るには、XpmReadFileToPixmap関数を 使用します(25行目)。

>     int XpmReadFileToPixmap(
>     	Display *display,
>     	Drawable d,
>     	char *filename,
>     	Pixmap *pixmap_return,
>     	Pixmap *shapemask_return,
>     	XpmAttributes *attributes
>     );

- 成功した場合戻り値は0になり、エラーの時はエラーコードが返されます。
- `display`および`d`は、作成するPixmapのDisplayおよびScreen を決めるためのものです。Xlibでおなじみの奴です。
- `filename`は、XPMファイルを指定します。 末尾が`.gz`または`.Z`の時は、gzip/uncompressを呼び出して 勝手に伸張してくれます。
- 画像のPixmapのIDは、`pixmap_return`に格納されます。
- クリップマスクのBitmapのIDは、`shapemask_return`に格納されます。 クリップマスクは、色がNone以外のところが1になるBitmapです。
- attributesは、作成時に属性を指定したり、作成した画像の情報(サイズなど) を取得したりする時に`XpmAttributes`構造体へのポインタを渡します。 これについては3章で説明します。

`pixmap_return`および`shapemask_return`は、必要ない時はNULLを 指定します。この例ではマスクは使っていません。また、`attributes`も、 使用しない時はNULLを指定します。

## 2.4. XPMデータをビルトインしよう

sample2.cは、 ソースにインクルードされたXPMデータを表示します。

### 2.4.1. XpmCreatePixmapFromData関数

文字列の配列(char*の配列、前の版でcharの2次元配列と書いたのは勘違いでした)から Pixmapを作るには、XpmCreatePixmapFromData関数を使用します(22行目)。

>     int XpmCreatePixmapFromData(
>     	Display *display,
>     	Drawable d,
>     	char **data,
>     	Pixmap *pixmap_return,
>     	Pixmap *shapemask_return,
>     	XpmAttributes *attributes
>     );

- `XpmReadFileToPixmap`関数との違いは、`filename` の替りに`data`を指定することです。

ソース中の`sample2_xpm`は、sample2.xpm の中で定義されている配列の名前です。

## 2.5. エラー処理

XPMライブラリの関数は、基本的に成功時に0を返し、 エラーの時はエラーコードを返します。

### 2.5.1 XpmGetErrorString関数

エラーコードからエラーの内容を説明する文字列を取得するには、 XpmGetErrString関数を使用します(sample1.cの27行目およびsample2の24行目)。

>     char *XpmGetErrorString( int errcode );

目次
1 イントロ
2 入門編／とりあえず使ってみる
3 アトリビュートを使う