horizontal-scroll-bar

Class

The class of a horizontal-scroll-bar control. Note this is unrelated to scrollbars placed in certain windows automatically by the system.

Control

An instance of the :horizontal-scrollbar class. This control is paired programmatically with other controls (static pictures, for instance) to permit horizontal scrolling when too much information prevents the viewer from seeing everything on their display simultaneously.

Scrollbars can also be used as sliders to affect another control by raising or lowering a number, intensifying or fading a color, or otherwise gradually increasing/decreasing some characteristic of the attached control. A good model of this appears in the Car Payments Example in the Examples tab of the Navigator dialog (display with Help | CG Examples).

The range property of the scrollbar is a list of two integers: for example, (0 100). The value of the scrollbar determines the position of the scrollbox along the length of the scrollbar. The value of the scrollbar is an integer within the range.

The delayed property controls whether the scrollbar's value is updated as the user scrolls or only at the end of the scrolling operation.

See the Navigator dialog example (on the Examples tab) entitled "Car Payments" for an example of basic usage of scroll-bar widgets.

Adding a horizontal-scroll-bar control to your form

Click the horizontal-scroll-bar icon on of the Component toolbar. Move the mouse cursor to the part of the form where you want to place the control, and click again. The control will appear with colored resizing handles.

Resizing and moving the control

Controls can only be resized and moved on forms during the design stage; the size and location of everything is fixed on a running form.

Resize the control by clicking the mouse cursor and dragging one of the handles to the new size-point. Release the mouse key when you are satisfied with the new size.

Move the control by clicking anywhere on it except a resizing handle and dragging it to a new location on the form. Release the mouse key when you are ready to place the control.

Customizing the horizontal-scrollbar

Attaching a scrollbar to another control. Scrollbars are not attached to other controls (as the up-down-control is, e.g.) You have to customize the on-change (typically) event handler for the scrollbar to programmatically make whatever scrolling effect you want.

Attaching a scrollbar to a window. Scrollbars on windows and various components such as multi-line-editable-text or outline are implemented differently. They are added when needed when the scrollbars property is true.

Scrolling by logical objects rather than by pixels

In a typical custom scrolling scheme, an application does not need to worry about how much data is above the current scroll position, and so the redisplay-window method can simply start drawing whatever is known to be currently scrolled to the top of the window. This means that the application does not have to compute and/or cache the pixel sizes of everything above the scroll-position, which simplifies the coding and can also speed scrolling up quite a bit when there is a huge amount of data to be scrolled. The drawbacks are that (1) this approach may be applicable only if data is entirely arranged into "rows" or "columns", (2) scrolling is not as visually smooth since an individual data object is always aligned with the top and/or left side of the window, and (3) custom methods need to be written to override several CG generic functions that are exported for this purpose.

See the Navigator dialog example (on the Examples tab) entitled "Scrolling by arbitrary objects rather than pixels" for a complete example of this special alternative for custom scrolling by logical objects..

It is now possible to customize scrolling in this way by overriding the default methods of several generic functions. Typically this is useful for scrolling by some sort of logical objects such as lines of text or grid cells rather than by pixels, as the default methods do. The generic functions that may need to be modified are:

redisplay-window to decide what should be drawn based on a custom scroll-position and then draw it

nscroll-position to return a position object where a coordinate might be an index into a set of arbitrary objects rather than a pixel distance

scroll-range which may return a value indicating the number of objects to be scrolled into the window rather than a pixel size

update-scroll-bars-for-new-window-size to adjust the scroll-range after a window has been resized

scroll-to to interpret a new programmatic scroll position

user-scroll to interpret an interactive scrolling gesture

See About how to get sample code for creating controls in cgide.htm, which explains how to use the IDE to create such code.

A diagram of window and widget classes is shown in Widget and window classes in cgide.htm.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.