comment -*- mode: text -*-
comment $Id: README.sb,v 1.6 2003/10/01 10:46:55 arakiken Exp $

This document describes how to implement your own scrollbar.

* General intructions
  1. implement member functions of x_sb_view_t.
  2. compile and make shared library.
  3. place it in certain directory.

* Requirement
  Any interface of the following:

  o UNIX98 dlopen interface
  o HP-UX sh_load interface
  o Win32API LoadLibrary
  o Mac OS X NSModule interface (EXPERIMENTAL)
  o libltdl library

* Members of 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) ;
    This provides geometry info of your scrollbar.
    (must)

  o void (*get_default_color)( struct x_sb_view * , char **  fg_color ,
         char **  bg_color) ;
    This provides default colors of your scrollbar.
    You can use the same color names as {fg|bg}_color.
    (recommended)
    
  o void (*realized)( struct  x_sb_view *  , Display * , int , Window , GC ,
         unsigned int  win_height) ;
    This is invoked just before the Window is mapped.
    x_sb_view_t status should be initialized here.
    Don't forget to set display, screen, window, gc given as arguments to each
    member of x_sb_view_t.
    (must)
    
  o void (*resized)( struct  x_sb_view * , Window , unsigned int  height) ;
    This is invoked when the height of scrollbar is changed.
    x_sb_view_t status should be reset here.
    Don't forget to set window argument to the member of x_sb_view_t.
    (must)
    
  o void (*delete)( struct  x_sb_view *) ;
    This is invoked when x_sb_view_t is never used.
    Free resources you allocaed.
    (must)

  o void (*draw_decoration)( struct  x_sb_view *) ;
    This is invoked when scrollbar decoration should be drawn.
    (recommended)
    
  o void (*draw_scrollbar)( struct  x_sb_view * , int  bar_top_y ,
         unsigned int  bar_height) ;
    This is invoked when scrollbar should be drawn.
    You should draw scrollbar of bar_height from bar_top_y position.
    (recommended)

  o void (*up_button_pressed)( struct  x_sb_view *) ;
  o void (*down_button_pressed)( struct  x_sb_view *) ;
  o void (*up_button_released)( struct  x_sb_view *) ;
  o void (*down_button_released)( struct  x_sb_view *) ;
    These are invoked when up_button or down_button is pressed or released.
    (recommended)
  
* compilation
  You must name your scrollbar constructor functions as below.

  x_sb_view_t *  x_[yourbar]_sb_view_new(void) ;  /* normal version */
  x_sb_view_t *  x_[yourbar]_transparent_sb_view_new(void) ;  /* transparent version */

  You should prepare both normal and transparent versions of your scrollbar.
  If transparent version is not found, normal version is used under transparent mode.

  Be careful of using static data, which may be shared by multiple x_sb_view_t objects
  If more than one pty windows are created.

  You must also name your scrollbar library as below.

  lib[yourbar].so

  When you compile, don't forget to add the directory of x_sb_view.h to cc -I
  option for cpp to find it.

* Registration
  Place your scrollbar library to $(PREFIX)/lib/mlterm.

* Usage
  $ mlterm -S "your_sb"

  If your_sb scrollbar is not found, simple scrollbar is used.

* See xwindow/x_simple_sb_view.[ch] and scrollbar/sample for detail.