Scrollbar

Scrollbars are typically used to allow the user to scroll a window onto a document or control the data displayed by a table component.

No Scrollbar may be the child of a Clipper, nor the child of a child of a Clipper, etc.

Two Common Examples

There are two main ways that programs use Scrollbars:

A Scrollbar working with a Text or Table component, will use the concept of rows of cells or lines of text; the Scrollbar's value should reflect a row or line number. If the number of rows/lines changes, you'll probably want an event handler that looks something like the following handler for a text component's _numLinesChanged() event:

SUB text1_numLinesChanged( self AS text )
scrollbar1.maximum = self.numLines
scrollbar1.thumbSize = self.lastVisibleLine - self.firstVisibleLine + 1
END SUB
SUB scrollbar1_changed( self AS scrollbar, scrollType AS integer )
text1.firstVisibleLine = self.value
END SUB

A Scrollbar which vertically re-positions the child of a clipper would probably be set up something like this:

sub module_init( )
scrollbar1.maximum = childOfClipper.height
scrollbar1.thumbSize = clipper1.height
end sub
SUB scrollbar1_changed( self AS scrollbar, scrollType AS integer )
childOfClipper.top = -self.value
END SUB

Scrollbar Looks

The following looks are available:

0 Normal Scrollbar. Note that within NewBuild, the scrollbar's on-screen thumb size depends upon the thumbSize property.

1 Spin Buttons.

Scrollbar Properties

Standard Properties:
enabled, height, left, sizeHControl, sizeVControl, parent, proto, top, version, visible, width.
height, width: When height and/or width is too small to draw the scrollbar, its look is undefined. The height of horizontal scrollbars, and the width of vertical scrollbars are fixed and cannot be changed regardless of the sizeHControl and sizeVControl properties.
sizeHControl, sizeVControl: Only SIZE_AS_NEEDED and SIZE_AS_SPECIFIED will be supported. SIZE_AS_NEEDED will only be partially supported: when the component becomes visible and their height or width is zero, the component will size itself to a default value.

increment integer (1-)
Amount by which thumb (the part of the scrollbar which slides up and down) will move when the user taps the scroll-up or scroll-down button on the Scrollbar.

minimum integer
The smallest amount that the value property can attain, i.e. when the thumb (the part of the scrollbar which slides up and down) is all the way to the left or the top of the Scrollbar, then value = minimum.

maximum integer
The largest amount that the value property can attain, i.e. when the thumb (the part of the scrollbar which slides up and down) is all the way to the right or the bottom of the Scrollbar, then value is the greater of (maximum-thumbSize) and minimum.

notifyDrag integer (0-1)
By default, the changed event is generated when the thumb (the part of the scrollbar which slides up and down) is dropped by the user. Setting notifyDrag non-zero causes this event to be sent continuously as the thumb is being dragged (though it will not be sent when the thumb is dropped).
This property may be changed at run-time only if the Scrollbar's visible property is zero.

orientation integer (0-1)
The Scrollbar's direction: 0 means horizontal, 1 means vertical. Changes to this property will not take effect if the scollbar is visible.

thumbSize integer (0-)
Amount of total range currently being shown (relative to the entire size of the document). Set to zero if this metric is not appropriate for the situation. thumbSize determines how much the value property changes when the user clicks inside the scroller area.

value integer (minimum-(maximum-thumbSize) )
Describes the position of the top of the thumb. Lowest value occurs when the thumb is in the topmost (vertical) or leftmost (horizontal) position.

Scrollbar Events

_changed()

_changed( self AS component, scrollType AS integer )

This event is generated when the user interacts with the Scrollbar, either tapping a button, tapping the Scrollbar itself, or dragging the thumb (the part of the scrollbar which slides up and down). (If the notifyDrag property is 0, this event is generated when the user releases the thumb. If notifyDrag is 1, the event is generated with each movement of the thumb, but is not generated when the thumb is released.)

This event is only generated as the direct result of the user interacting with the Scrollbar--it won't be generated each time your BASIC code changes the Scrollbar's value property.

When this event is generated, the Scrollbar's value property will already reflect changes made by the user.

Pass:

self component
The Scrollbar experiencing the event.

scrollType integer (1-5)

Number specifying what the user did to the Scrollbar.

1 Dragged or dropped the thumb (the part of the scrollbar which slides up and down).

2 Tapped the back button (the up/left button)

3 Tapped the forward button (the down/right button)

4 Tapped the page back area (the up page/left page area)

5 Tapped the page forward area (the down page/right page area)

Scrollbar Actions

None.