@node StructUtility, VLayout, Headerfile, Top
@comment  node-name,  next,  previous,  up
@chapter 構造体とユーティリティ関数

ここでは，v_types.hなどで宣言された，VObjectクラス群やそれを使うソースファイルで使われる構造体，及びそれらを操作するユーティリティ関数を説明する。


@menu
* Struct::                      構造体                     
* UtilityFunction::             ユーティリティ関数            
@end menu

@node Struct, UtilityFunction, StructUtility, StructUtility
@comment  node-name,  next,  previous,  up
@section 構造体

@menu
* VPointStruct::                VPoint構造体                
* VSizeStruct::                 VSize構造体                 
* VRectStruct::                 VRect構造体                 
* VImageStruct::                VImage構造体                
* VObjectListStruct::           VObjectList構造体           
* VObjectStatusStruct::         VObjectStatus構造体         
@end menu

@node VPointStruct, VSizeStruct, Struct, Struct
@comment  node-name,  next,  previous,  up
@subsection VPoint構造体


@heading 定義

@example
@cartouche
typedef struct VPoint @{
    short x;
    short y;
@} VPoint;
@end cartouche
@end example


@heading 用途

画面上の座標を表す。

@node VSizeStruct, VRectStruct, VPointStruct, Struct
@comment  node-name,  next,  previous,  up
@subsection VSize構造体

@heading 定義

@example
@cartouche
typedef struct VSize @{
    short w;
    short h;
@} VSize;
@end cartouche
@end example

@heading 用途
イメージ，オブジェクトなどの大きさを表す。

@node VRectStruct, VImageStruct, VSizeStruct, Struct
@comment  node-name,  next,  previous,  up
@subsection VRect構造体

@subheading 定義

@example
@cartouche
typedef struct VRect @{
    short l;
    short t;
    short r;
    short b;
@} VRect;
@end cartouche
@end example

@heading 用途

画面上で長方形の領域を表す。

@node VImageStruct, VObjectListStruct, VRectStruct, Struct
@comment  node-name,  next,  previous,  up
@subsection VImage構造体

@heading 定義

@example
@cartouche
typedef struct VImage @{
    char *         @var{buf_8};      // 8ビット/ピクセルのバッファ
    short *        @var{buf_16};     // 16ビット/ピクセルのバッファ
    long *         @var{buf_32};     // 32ビット/ピクセルのバッファ
    VSize          @var{size};       // 画像のサイズ（ピクセル単位）
    short          @var{w_border};   // 画像バッファの横方向のピクセル数

    short          @var{ref_cnt};    // 参照カウント
    bool           @var{drawing};    // バッファにアクセス中かのフラグ
    VImageInfo *   @var{info};       // 機種依存データ
@} VImage;
@end cartouche
@end example

@heading 用途
画像データを格納する。

@heading 内容
画像バッファである@var{buf_xx}は，どれか一つだけが使われる。（現在のところ，サポートしているのは32ビットのみ。）
@var{w_border}は，バッファ自体の横幅であり，size.w <= w_border である。余った部分は使用されない。Macintoshのピクセルバッファに横幅を8の倍数にするという制約があるために用意された。

@node VObjectListStruct, VObjectStatusStruct, VImageStruct, Struct
@comment  node-name,  next,  previous,  up
@subsection VObjectList構造体

@heading 定義

@example
@cartouche
typedef struct VObjectList @{
    VObject *                @var{object};
    struct VObjectList *     @var{next};
@} VObjectList;
@end cartouche
@end example

@heading 用途
VObjectのインスタンスのリスト。childrenのリストなどで使用される。

@node VObjectStatusStruct,  , VObjectListStruct, Struct
@comment  node-name,  next,  previous,  up
@subsection VObjectStatus構造体

@heading 用途
@code{VObject}の各種ステータスを格納する。

@subheading 内容

@deftypevr {VObjectStatus} {VObject *} parent
親オブジェクトへのポインタ
@end deftypevr

@deftypevr {VObjectStatus} {VObjectList *} children
子供のリストへのポインタ。子供を持たない場合は@code{NULL}。
@end deftypevr

@deftypevr {VObjectStatus} int id
オブジェクトのID番号（1000から生成順に振られる）。
@end deftypevr

@deftypevr {VObjectStatus} int attr
オブジェクトの属性。サブクラスごとに意味は異なる。
@end deftypevr

@deftypevr {VObjectStatus} int value
オブジェクトの持つ値。サブクラスごとに意味は異なる。
@end deftypevr

@deftypevr {VObjectStatus} {LC_WRITING_STYLE *} ws
オブジェクトのラベルなどに使われるwriting_style。
@end deftypevr

@deftypevr {VObjectStatus} int fsize
オブジェクトのラベルなどに使われるフォントのサイズ。
@end deftypevr

@deftypevr {VObjectStatus} {L_CHAR *} descriptor
オブジェクトのディスクリプタ。ラベルの内容など。
サブクラスごとに意味は異なる。
@end deftypevr

@deftypevr {VObjectStatus} unsigned vert_desc : 1
ラベルを縦書きにする。ただしサポートしているオブジェクトのみで有効。
@end deftypevr

@deftypevr {VObjectStatus} bool visible : 1
オブジェクトが表示状態になっているかのフラグ。
@end deftypevr

@deftypevr {VObjectStatus} bool enabled : 1
オブジェクトが使用可能か。使用できないオブジェクトはグレイ表示される。
@end deftypevr

@deftypevr {VObjectStatus} bool	homogeneous : 1
子オブジェクトのサイズを全て同じにする。
@end deftypevr

@deftypevr {VObjectStatus} VSize spacing
子オブジェクトどうしの間隔を指定する。
@end deftypevr

@deftypevr {VObjectStatus} unsigned alignv  : 2;
@deftypevrx {VObjectStatus} unsigned alignh  : 2;
子オブジェクトの縦方向，横方向の並べ方。
以下の値が使用できる。

@example
VALIGN_LEFT / VALIGN_TOP　左/上に寄せて表示
VALIGN_RIGHT / VALIGN_BOTTOM　右/下に寄せて表示
VALIGN_EXPAND　オブジェクトを可能なだけ広くとったスペースの中央に配置
VALIGN_FILL　オブジェクトの大きさを可能なだけ広くする
@end example

オブジェクトの配置のしかたは，@var{homogeneous}の指定によっても変化する。
@end deftypevr

@deftypevr {VObjectStatus} VSize padding
オブジェクト自体の大きさに余裕を持たせる。
@end deftypevr

@deftypevr {VObjectStatus} {VCursor *} cursor
ポイントされたときのカーソル形状。
@end deftypevr

@deftypefn {VObjectStatus} void {(*value_event_handler)} (VObject*)
オブジェクトの値が変化したときに呼び出されるコールバック関数。
@end deftypefn

@deftypefn {VObjectStatus} void {(*descriptor_event_handler)} (VObject*)
オブジェクトのディスクリプタが変化したときに呼び出されるコールバック関数。
@end deftypefn

@deftypevr {VObjectStatus} VSize min_size
このオブジェクトの最小サイズ。@code{VLayout}との通信用。
@code{VWindow}を除き書き込みはできず，また通常は読み出し行ってはいけない。
@end deftypevr

@deftypevr {VObjectStatus} VSize size
このオブジェクトのサイズ。@code{VLayout}との通信用。
@code{VWindow}を除き書き込みはできず，また通常は読み出し行ってはいけない。
@end deftypevr

@deftypevr {VObjectStatus} VPoint position
このオブジェクトの位置。@code{VLayout}との通信用。
@code{VWindow}を除き書き込みはできず，また通常は読み出し行ってはいけない。
@end deftypevr


@node UtilityFunction,  , Struct, StructUtility
@comment  node-name,  next,  previous,  up
@section ユーティリティ関数

@menu
* VObjectStatus::               
* VImage::                      
@end menu

@node VObjectStatus, VImage, UtilityFunction, UtilityFunction
@comment  node-name,  next,  previous,  up
@subsection VObjectStatus関連

@deftypefun void free_vobject_status (VObjectStatus *s)
取得したステータスの内容を解放する。@var{s}自身は解放しない。
@end deftypefun

@deftypefun L_CHAR* v_make_vert_desc (const L_CHAR* desc)
ディスクリプタを縦書きに変換する。
@end deftypefun

@node VImage,  , VObjectStatus, UtilityFunction
@comment  node-name,  next,  previous,  up
@subsection VImage関連

一般に，VImageを新たに作って，VDrawに描画させる場合は，下のような手順になる。

@example
VImage *img = v_image_new(w,h,32);      // 新たにイメージを作成（参照カウントは1）
v_image_draw_start(img);                // 描画を開始
// draw...                              // img->buf_32に書き込み ...
v_image_draw_end(img);                  // 描画終了
vdraw->set_image(img);                  //  VDrawにイメージをセット (参照カウントが1増える)
v_image_unref(img);                     // イメージの参照カウントを1減らす
vdraw->redraw();                        // VDrawを再描画させる
@end example

なお，一度@code{VDraw}にセットしたイメージを操作する場合は，@code{VDraw}のメソッドを使うことになる。その方法は@code{VDraw}の項を参照。

各関数の説明は次の通り。

@deftypefun VImage* v_image_new (short w, short h, char depth)
@var{w} : 幅
@var{h} : 高さ
@var{depth} : ピクセルあたりのビット数（現在は32のみサポート）

新しい@code{VImage}構造体を作成する。参照カウントは1となる。
@end deftypefun

@deftypefun void v_image_ref (VImage* img)
@code{Vimage}構造体の参照カウントを1増やす。
@end deftypefun

@deftypefun void v_image_unref (VImage* img)
@code{Vimage}構造体の参照カウントを1減らす。
カウントが0になるとイメージは解放される。
@end deftypefun

@deftypefun void v_image_free (VImage* img)
@code{VImage}構造体を解放する。
@end deftypefun

@deftypefun VImage* v_image_copy (VImage* img)
@code{VImage}構造体を複製する。
@end deftypefun

@deftypefun void v_image_draw_start (VImage* img)
@code{VImage}構造体への描画を開始する。
バッファの読み書きは開始後でなければできない。（GTKでは落ちないが，Macでアクセスフォールトになる）
複数回開始しようとするとエラーになるので，複数スレッドで@code{VImage}構造体を扱う場合は別途ロックなどが必要。
@end deftypefun

@deftypefun void v_image_draw_end (VImage* img)
@code{VImage}構造体への描画を終了する。
@end deftypefun
