7.4 Scrolling

7.4.1 Programmatic scrolling

Programmatic scrolling is implemented with the generic function scroll. This example shows vertical scrolling in a list-panel:

(setf list-panel
      (contain 
       (make-instance 'list-panel 
                      :items (loop for i below 100 collect i) 
                      :vertical-scroll t)))
 
(apply-in-pane-process 
 list-panel 'scroll list-panel :vertical :move 50)

11 Defining Interface Classes - top level windows shows how an editor-pane can be scrolled using editor commands.

An output-pane can be made to scroll - see 12.4 output-pane scrolling.

You can also use the functions set-horizontal-scroll-parameters and set-vertical-scroll-parameters to affect scrolling operations.

The current scroll position can be found by using get-scroll-position. Using it later in a call to scroll with :move scrolls the pane back to the same position.

7.4.2 Scroll values and initialization keywords

The six :scroll-* simple-pane initargs for each dimension correspond to the six keyword arguments of set-horizontal-scroll-parameters/get-horizontal-scroll-parameters and set-vertical-scroll-parameters/get-vertical-scroll-parameters as follows:

The values for all of these parameters should be real numbers. The set of values supplied for each dimension is treated independently from the other set.

The difference between the max-range and min-range specifies the range of scrolling. When applied to the scrollbar display, all the values are scaled by the ratio between the height/width of the scrollbar and the range, for example:

slug-size-in-pixels =  slug-size * scrollbar-height-in-pixels / (max-range - min-range)

The slug-position is also translated by the min-range:

slug-position-in-pixels = (slug-position - min-range) * scrollbar-height-in-pixels / (max-range - min-range)

The scrolling position of the pane is the slug-position (translated by the min-range) scaled by the ratio between the pane dimension (width or height) and the slug-size, that is:

pane-scrolling-position = (slug-position - min-range) * pane-dimension / slug-size

When slug-size is not supplied or is nil, it is set to track the dimension of the pane, so the scaling factor above is 1, and all the other numbers can be considered as if specified in pixels in the internal coordinates of the pane. If slug-size is supplied, it is in effect creating a scaling factor between the values and the coordinates in the pane.

The min-range initial value defaults to 0, the max-range initial value defaults to either the width/height in pixels of the data in the pane if this is deducible, otherwise to the height of the pane. The latter is not useful, and typically the max-range is the one value that you have to specify. In many cases it is the only value you need to specify.

The initial slug-position defaults to 0.

The step-size defines the amount to scroll for a gesture that means step (typically clicking on the arrows at the ends of the scrollbar). It initially defaults to the dimension of a character in the pane in pixels. Note that this is normally useful only if slug-size is not set, otherwise it is scaled by pane-dimension / slug-size. If you set the slug-size, you probably want to set the step-size too.

page-size defines the amount to scroll for page gestures (typically clicking on the scroll bar outside the scroll slug). It initially defaults to slug-size - step-size, which is normally the useful value.

7.4.3 Automatic scrolling

Automatic scrolling of the parent to show the focus pane can be specified by using scroll-if-not-visible-p.

For output-pane with "internal" scrolling (see 12.4 output-pane scrolling), you can force some area to become visible, that is scroll as needed, by using ensure-area-visible.