Scroll Bars

OBJECTS

  typedef void (*ControlFunc)  (Control *c);

FUNCTIONS

  Control * new_scroll_bar(Window *w, Rect r, int max,
                           int size_shown, ControlFunc fn);
  Control * add_scroll_bar(Control *c, Rect r, int max,
                           int size_shown, ControlFunc fn);
  void   change_scroll_bar(Control *c, int pos, int max,
                           int size_shown);
  int    get_control_value(Control *c);

NOTES

The new_scroll_bar function creates a scroll bar which can be used to scroll through text or to change some value within the program. The scroll bar will fill the given rectangle, and will scroll vertically if the rectangle is taller than it is wide, or horizontally otherwise. Manipulating the scrollbar with the mouse changes the scroll position, which has a minimum value of zero (at the left or top of the scroll bar), and a maximum value given by max.

The amount of some value which is displayed by the scrollbar can be set with the size_shown argument. When the user clicks in the scroll bar to make the scroll 'thumb' position jump, it will jump by this amount. For instance, in a text window which scrolls vertically, if 24 lines out of an 84 line document is visible at any one time, size_shown would be set to 24 and max to 84-24, since the top-most line of text on the screen at any time can only range from zero at the start of the document, to 60 at the end. When the user clicks in the scroll bar (other than on the 'thumb') the scroll position will increase or decrease by 24.

Every time the scroll bar position changes, the call-back function fn is called. This function is passed the scroll bar control as a parameter.

The add_scroll_bar function works in the same way as new_scroll_bar, except that it attaches the scroll bar to a control rather than directly to a window.

The change_scroll_bar function changes the values used by the scroll bar. It will reset the scroll bar's position pos, its maximum value max and the size_shown value, and re-draw the control if it is currently visible.

The get_control_value function returns the scroll bar's current position value.