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 terminoligy.

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().

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.