comment -*- mode: text; tab-width:2; indent-tabs-mode:nil -*-

mltermでは、オリジナルのスクロールバーを比較的簡単に実装するためのフレームワーク
を提供しています。

以下では、その実装方法について説明します。

* 実装方法の概略
  1. x_sb_view_t の各イベントごとの描画処理を実装。
  2. コンパイル、共有ライブラリの作成
  3. 所定のディレクトリに、ライブラリを配置

* 必要な環境
  下記のいずれかが使用可能であること。

  o UNIX98 dlopen インターフェース
  o HP-UX sh_load インターフェース
  o Win32API LoadLibrary
  o Mac OS X NSModule インターフェース (EXPERIMENTAL)
  o libltdl ライブラリ

* x_sb_view_t
  現在定義されているイベント

  o void (*get_geometry_hints)(struct x_sb_view *, unsigned int *width, 
                               unsigned int *top_margin,
                               unsigned int *bottom_margin,
                               int *up_button_y,
                               unsigned int *up_button_height,
                               int *down_button_y,
                               unsigned int *down_button_height);
    スクロールバーのジオメトリ情報を渡すイベント
    スクロールバーの幅、および、垂直方向のマージン、そして、上下スクロールボタン
    の位置を渡します。
    (必須)

  o void (*get_default_color)(struct x_sb_view *, char **fg_color,
                              char **bg_color);
    デフォルトの前景背景色を渡すイベント
    前景背景色に使える名前は、{fg|bg}_color 設定で使えるものと同じです。
    文字列は、呼び出し側では解放しませんので、内部で処理して下さい。
    (推奨)
    
  o void (*realized)(struct x_sb_view *, Display *, int, Window, GC,
                     unsigned int win_height);
    スクロールバーが、画面にMAPされる直前で呼ばれるイベント
    スクロールバーオブジェクトの内部状態の初期化します。
    受け取ったDisplay,screen,Window,GCを、x_sb_view_t の各メンバに設定するのを忘
    れないで下さい。
    (必須)
    
  o void (*resized)(struct x_sb_view *, Window, unsigned int height);
    スクロールバーの高さが変更された場合に呼ばれるイベント
    スクロールバーオブジェクト内部の状態を再設定します。
    受け取った Window を、x_sb_view_t のメンバに設定するのを忘れないで下さい。
    (必須)
    
  o void (*color_changed)(struct x_sb_view *, int is_fg);
    前景色又は背景色が変更された場合に呼ばれるイベント

  o void (*delete)(struct x_sb_view *);
    スクロールバーオブジェクトの破壊イベント
    不要になったデータを解放して下さい。
    (必須)

  o void (*draw_scrollbar)(struct x_sb_view *, int bar_top_y,
                           unsigned int bar_height);
    スクロールバーの描画イベント
    bar_top_y 位置(top_margin として渡した値は含まれます)から、bar_height 分の
    高さのバーを描画します。
    (必須)

  o void (*draw_background)(struct x_sb_view *, int y, unsigned int height);
    スクロールバーの背景の描画イベント
    (推奨)

  o void (*draw_up_button)(struct x_sb_view *, int is_pressed);
  o void (*draw_down_button)(struct x_sb_view *, int is_pressed);
    スクロールバーのボタンを描画するイベント
    (推奨)

* 実装、コンパイル
  コンストラクタは、必ず、

  x_sb_view_t *x_[yourbar]_sb_view_new(void);  /* 通常版 */
  x_sb_view_t *x_[yourbar]_transparent_sb_view_new(void);  /* 透過処理対応版 */

  としてください。

  通常のバーと、透過処理に対応したスクロールバーの両方を用意するのが望ましいです。
  (透過処理版がない場合は、透過処理中でも、通常版が使われます)

  複数のptyウィンドウを起動している場合には、スクロールバーオブジェクトも複数生
  成されることになりますので、独自のデータ構造をstaticにもっている場合には、それ
  らの扱いには十分注意して下さい。

  x_sb_view_t を拡張し、

  x_your_sb_view_t {
    x_sb_view_t ;
	  your own data ;
  };

  を作って、独自データを、構造体のメンバにもつのが一番確実です。

  ライブラリ名については、必ず、

  lib[yourbar].so

  としてください。

  また、プリプロセッサが、x_sb_view.h を見つけられるよう、x_sb_view.hのあるパス
  を -I オプションに加えるようにして下さい。

* 登録作業
  現在のところ、$(PREFIX)/lib/mlterm以下に、できあがったライブラリをコピーしてく
  ださい。

* 実際に使ってみる
  $ mlterm -S "your_sb"

  で、作成されたスクロールバーが表示されるはずです。
  もし、指定した名前のスクロールバーが存在しない場合は、"simple"(mlterm本体に組
  み込み)が使われます。

* 補足
  細かい手順などについては、xwindow/x_simple_sb_view.[ch],scrollbar/sample を参
  照下さい。
