- Scrollbars
- MakeHorizScrollbar
- MakeVertScrollbar
- SetScrollbar
- SetThumbBitmap

## Scrollbars

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() , SetThumbBitmap() , 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() , SetThumbBitmap() , 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: MakeHorizScrollbar() , MakeVertScrollbar() , SetWidgetPos() 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() ,