ID 757211
Date 7/23/2021
Public

## Using Scroll Bars

With a Scroll bar, the user determines input by manipulating the slide up and down or right and left. Your application sets the range for the Scroll bar, and thus can interpret a position of the slide as a number. If you want to display this number to the user, you need to send the number (as a character string) to a Static text or Edit Box control.

You set the lower and upper limits of the Scroll bar range by setting the control index DLG_RANGEMIN and DLG_RANGEMAX with DLGSET or DLGSETINT. The default values are 1 and 100. For example:

  LOGICAL retlog
retlog = DLGSET (dlg, IDC_SCROLLBAR1, 212, DLG_RANGEMAX)

You get the slide position by retrieving the control index DLG_POSITION with DLGGET or DLGGETINT. For example:

  INTEGER slide_position
retlog = DLGGET (dlg, IDC_SCROLLBAR1, slide_position, DLG_POSITION)

You can also set the increment taken when the user clicks in the blank area above or below the slide in a vertical Scroll bar, or to the left or right of the slide in a horizontal Scroll bar, by setting the control index DLG_BIGSTEP. For example:

  retlog = DLGSET (dlg, IDC_SCROLLBAR1, 20, DLG_BIGSTEP)

When the user clicks on the arrow buttons of the Scroll bar, the position is always incremented or decremented by 1.

The maximum value (DLG_POSITION) that a scroll bar can report (that is, the maximum scrolling position) depends on the page size (DLG_BIGSTEP). If the scroll bar has a page size greater than one, the maximum scrolling position is less than the maximum range value (DLG_RANGEMAX or DLG_RANGE). You can use the following formula to calculate the maximum scrolling position:

  MaxScrollPos = MaxRangeValue - (PageSize - 1)

For example, if a scroll bar has DLG_RANGEMAX = 100 (100 is the default value of DLG_RANGEMAX) and DLG_BIGSTEP = 10 (10 is the default value of DLG_BIGSTEP), then the maximum DLG_POSITION is 91 (100 - (10 - 1)).

This allows your application to implement a "proportional" scroll bar. The size of the scroll box (or thumb) is determined by the value of DLG_BIGSTEP and should represent a "page" of data (that is, the amount of data visible in the window).

When the user clicks in the "shaft" of the scroll bar, the next (or previous) page is displayed. The top of the thumb (for a vertical scroll bar) or the left edge of the thumb (for a horizontal scroll bar) represents the position of the scroll bar (DLG_POSITION).

The size of the thumb represents the amount of data currently visible. There is a minimum thumb size so as not to affect usability. When the scroll bar is at its maximum position, the position will represent the position in the data such that the last "page" of data is visible in the window. When the top (or left edge) of the scroll bar is at the mid-point of the shaft, DLG_POSITION will be the mid-point of the range and the mid-point of the data should be displayed at the top of the window.