A scrollbar is a widget that allows a user to control some numeric
quantity interactively by using the mouse to scroll a slider, similar
to the volume slider on some radios.  The slider is called the "thumb"
or "thumb area" in X terminology. 



----------------------------------------------------------------------

Widget MakeHorizScrollbar(int length, ScrollCB scroll_func, void *data);
Widget MakeVertScrollbar(int height,  ScrollCB scroll_func, void *data);


These two routines create scrollbars.  Scrollbars allow the user to
interactively control some numeric quantity with the mouse. 

When the user presses the left mouse button, the value represented by
the scrollbar increases.  When the press the middle mouse button, they 
can interactively adjust the value.  Clicking the right mouse button
decreases the value represented by the scrollbar.

The arguments to create a scrollbar are its length or height in
pixels, a callback function to call when the scrollbar changes value
and an extra void pointer argument that is passed to the callback
function.

If these routines fail, they return NULL.

To set what values a scrollbar represents, you must use
SetScrollbar().  These two routines only make a scrollbar and do not
set it to return useful values.  You always have to call
SetScrollbar() to set what a scrollbar represents (see the
documentation for SetScrollbar() for more information).

Your callback routine is called everytime the scrollbar changes.
Since the calculations are done in floating point, the value may not
have changed enough to be interesting, but your routine is still
called.  You should take care to see that the value changed enough to
be interesting to your applications (i.e. it is wasteful for a text
editor to repaint the window when the new value is 0.003 different
than the old value).


A scrollbar callback routine should be declared as follows:

    void scroll_func(Widget w, float new_val, void *data)
    {
    }

The first argument, w, is the scrollbar widget that the user is
manipulating.  The second argument is a floating point value that
represents the new value of the scrollbar.  The third argument is the
void pointer argument that was passed to Make{Horiz,Vert}Scrollbar().


SEE ALSO :  SetScrollbar(), SetWidgetPos(), 
            SetFgColor(), SetBgColor(), SetBorderColor()

-----------------------------------------------------------

void  SetScrollbar(Widget w, float where, float max, float size_shown);


This function lets you set the values that a scrollbar represents.
The first argument is a scrollbar widget.  The next three arguments
are floating point numbers that specify the parameters of the
scrollbar. 

Before discussing the details of the three float arguments, let us get
some terms straight.  When we refer to the `container' of a scrollbar,
we mean the entire box that makes up the scrollbar.  The `thumb' of a
scrollbar is the gray area that the user can grab to manipulate.  We
refer to the size or length of the thumb area (the amount of grey) as
the `size shown'.  The total amount represented by the scrollbar is
called `max'.


The arguments mean the following:

      where -- this floating point number specifies where in the
               container the top of the thumb area should start.  If
	       you have a maximum value of 100 and where is 50, the 
	       beginning of the thumb will be in the middle of the
	       container. 

        max -- The maximum value that the scroll bar can have.  You
	       will receive numbers in the range 0 to max (inclusive). 
	       Obviously max should be a positive, and is a float.

 size_shown -- This float value controls how big the grey area that
               the user can grab is.  This represents how much of
	       whatever it is you are representing is visible.  For
	       example, a text editor which shows 24 lines of text
	       would set size_shown to be 24 (out of whatever max
	       is).  If you want the scrollbar to represent a
	       percentage of something, where when it is 100%, the
	       grey area is also 100% of the box, then you should
	       set the size_shown to be equal to max.  If this is
	       confusing, there are examples below.


Now, some examples to clarify things (in the following, assume that
the argument, w, represents a scrollbar widget created with the
MakeHorizScrollbar or MakeVertScrollbar() routines).


For the first example, let's assume you want a scrollbar to let you
set a color value which can range between 0 and 255 with the initial
value at 67.  You sould set the scrollbar as follows:

     SetScrollbar(w, 67.0, 255.0, 1.0);

The first value, 67.0, is where we would like the beginning of the
thumb area to appear.  The next value, 255, is the maximum value the
scrollbar can attain.  The third value, 1, is the size of the thumb
area (the amount represented by the thumb relative to the maximum
size).  This scrollbar will now return values in the range of 0 to 255
(inclusive).  The thumb area will be small, and represents one value
of the 255 possible divisions.  The position of the thumb area in the
container represents its value.

For the next example, suppose we wish to make a scrollbar represent
some percentage of a value.  That is, the size of the thumb area
should be proportional to the value of the scrollbar relative to its
maximum (so when the value is at it maximum, the thumb area is 100% of
the scrollbar).

In this case we would like the size of the thumb area to represent the
amount of the variable (note the difference from the above example).
Let us suppose we want a scrollbar which can represent a percentage 0
to 100, with the initial value being 50.

     SetScrollbar(w, 50.0, 100.0, 100.0);

The first value, 50, is where the thumb area begins (in the middle of
the container).  The next number is 100, and represents the maximum
value of the scrollbar.  The next number, again 100, is the size
shown.  Making this value the same as the max value (in this case
100) causes the thumb area to vary according to the value the
scrollbar represents.


As a final example, let us take a text editor which is displaying a
file.  In this case, let us assume the text file is 259 lines long,
the window can display 47 lines, and the top line currently displayed
is 72.  To create the correct scrollbar, we would do the following:

     SetScrollbar(w, 72.0, 259.0, 47.0);
   
This creates a scrollbar which has a thumb area whose size is 47/259
of the entire container, and is positioned 72/259'ths of the way down
the container.


SEE ALSO: MakeHorizScrollbar(), MakeVertScrollbar(), SetWidgetPos()

-----------------------------------------------------------

void  SetThumbBitmap(Widget w, char *black_bits, int width, int height);

Sets a bitmap for the thumb area in the scrollbar. This function is 
similar to SetWidgetBitmap(), which one can refer to for details. The
default bitmap is a black & white combination of pixels. To get instead 
an entirely black thumb area, one can use

  static unsigned char black_bits[] = { 0xff };
  SetThumbBitmap(scroll_widget, black_bits, 8, 1); 

The default is equivalent to

 static unsigned char black_bits[] = { 0xaa, 0x55 };
 SetThumbBitmap(scroll_widget, black_bits, 8, 2);

SEE ALSO: SetWidgetBitmap()

-----------------------------------------------------------

void SetScrollbarStep(Widget w, float fact)

Sets the fraction of the scrollbar that gets increased or decreased
when the left or right mouse buttons is pressed. The scrollbar thus 
moves faster as fact increases. The default value is fact = 0.1 .
See also the explanations concerning the scrollbar callback functions.

SEE ALSO: MakeHorizScrollbar(), MakeVertScrollbar()

-----------------------------------------------------------

void SetScrollbarDirection(float dir)

The effect of this function is to possibly affect the scrollbar step
by a signed factor dir (normally equal to +1 or -1). If dir = -1, the
direction of the scrollbar moves are reversed with respect to mouse
clicks. This function is useful to deal with the tricky behaviour of the 
standard libraries Xaw, Xaw3d, Xaw95 (Libsx can be linked with any of 
these). Actually Xaw3d, Xaw95 behave differently of Xaw with respect to 
the action of mouse clicks on scrollbars, and the  SetScrollbarDirection() 
function can then be used to adjust that behaviour according to the needs.

SEE ALSO: SetScrollbarStep()