BScrollBar¶

Constructor and Destructor¶

BScrollBar()

BScrollBar::BScrollBar(BRect frame, const char *name, BView *target, float min, float max, orientation posture)
BScrollBar::BScrollBar(BMessage *archive)

Initializes the BScrollBar and connects it to the target view that it will scroll. It will be a horizontal scroll bar if posture is B_HORIZONTAL and a vertical scroll bar if posture is B_VERTICAL.

The range of values that the scroll bar can represent at the outset is set by min and max. These values should be calculated from the boundaries of a rectangle that encloses the entire contents of the target view—everything that it can draw. If min and max are both 0, the scroll bar is disabled and the knob is not drawn.

The object’s initial value is 0 even if that falls outside the range set for the scroll bar.

The other arguments, frame and name, are the same as for other BViews:

The frame rectangle locates the scroll bar within its parent view. For consistency in the user interface, a horizontal scroll bar should be B_H_SCROLL_BAR_HEIGHT coordinate units high, and a vertical scroll bar should be B_V_SCROLL_BAR_WIDTH units wide.
The BScrollBar’s name identifies it and permits it to be located by the FindView() function. It can be NULL.

Unlike other BViews, the BScrollBar constructor doesn’t set an automatic resizing mode. By default, scroll bars have the resizing behavior that befits their posture—horizontal scroll bars resize themselves horizontally (as if they had a resizing mode that combined B_FOLLOW_LEFT_RIGHT with B_FOLLOW_BOTTOM) and vertical scroll bars resize themselves vertically (as if their resizing mode combined B_FOLLOW_TOP_BOTTOM with B_FOLLOW_RIGHT).

~BScrollBar()

virtual BScrollBar::~BScrollBar()

Disconnects the scroll bar from its target.

Hook Functions¶

AttachedToWindow()

virtual void BScrollBar::AttachedToWindow()

Makes sure that the Application Server is cognizant of the BScrollBar’s value, if a value was set before the object was attached to a window.

ValueChanged()

virtual void BScrollBar::ValueChanged(float newValue)

Responds to a notification that the value of the scroll bar has changed to newValue. For a horizontal scroll bar, this function interprets newValue as the coordinate value that should be at the left side of the target view’s bounds rectangle. For a vertical scroll bar, it interprets newValue as the coordinate value that should be at the top of the rectangle. It calls ScrollTo() to scroll the target’s contents into position, unless they have already been scrolled.

ValueChanged() is called as the result both of user actions (B_VALUE_CHANGED messages received from the Application Server) and of programmatic ones. Programmatically, scrolling can be initiated by the target view (calling ScrollTo()) or by the BScrollBar (calling SetValue() or SetRange()).

In all these cases, the target view and the scroll bars need to be kept in synch. This is done by a chain of function calls: ValueChanged() calls ScrollTo(), which in turn calls SetValue(), which then calls ValueChanged() again. It’s up to ValueChanged() to get off this merry-go-round, which it does by checking the target view’s bounds rectangle. If newValue already matches the left or top side of the bounds rectangle, if forgoes calling ScrollTo().

ValueChanged() does nothing if a target BView hasn’t been set—or if the target has been set by name, but the name doesn’t correspond to an actual BView within the scroll bar’s window.

Derived classes can override this function to interpret newValue differently, or to do something in addition to scrolling the target view.

Member Functions¶

Archive()

virtual status_t BScrollBar::Archive(BMessage *archive, bool deep = true) const

Calls the inherited version of Archive(), then adds the BScrollBar’s range, orientation, current value and proportion, and the size of its big and little steps to the BMessage archive.

See also: BArchivable::Archive(), Instantiate() static function

Orientation()

orientation BScrollBar::Orientation() const

Returns B_HORIZONTAL if the object represents a horizontal scroll bar and B_VERTICAL if it represents a vertical scroll bar.

SetProportion(), Proportion()

void BScrollBar::SetProportion(float ratio)

float BScrollBar::Proportion() const

These functions set and return a value between 0.0 and 1.0 that represents the proportion of the entire document that can be displayed within the target view—the ratio of the width (or height) of the target’s bounds rectangle to the width (or height) of its data rectangle. This ratio determines the size of a proportional scroll knob relative to the whole scroll bar. It’s not adjusted to take into account the minimum size of the knob.

The proportion should be reset as the size of the data rectangle changes (as data is entered and removed from the document) and when the target view is resized.

SetRange(), GetRange()

void BScrollBar::SetRange(float min, float max)

void BScrollBar::GetRange(float *min, float *max) const

These functions modify and return the range of the scroll bar. SetRange() sets the minimum and maximum values of the scroll bar to min and max. GetRange() places the current minimum and maximum in the variables that min and max refer to.

If the scroll bar’s current value falls outside the new range, it will be reset to the closest value—either min or max—within range. ValueChanged() is called to inform the BScrollBar of the change whether or not it’s attached to a window.

If the BScrollBar is attached to a window, any change in its range will be immediately reflected on-screen. The knob will move to the appropriate position to reflect the current value.

Setting both the minimum and maximum to 0 disables the scroll bar. It will be drawn without a knob.

SetSteps(), GetSteps()

void BScrollBar::SetSteps(float smallStep, float bigStep)

void BScrollBar::GetSteps(float *smallStep, float *bigStep) const

SetSteps() sets how much a single user action should change the value of the scroll bar—and therefore how far the target view should scroll. GetSteps() provides the current settings.

When the user presses one of the scroll arrows at either end of the scroll bar, its value changes by a smallStep coordinate units. When the user clicks in the bar itself (other than on the knob), it changes by a bigStep units. For an application that displays text, the small step of a vertical scroll bar should be large enough to bring another line of text into view.

The default small step is 1.0, which should be too small for most purposes; the default large step is 10.0, which is also probably too small.

Note

Although the step values are specified using type float, only integral values should be specified; otherwise, the scroll bar won’t behave as expected.

Currently, a BScrollBar’s steps can be successfully set only after it’s attached to a window.

SetTarget(), Target()

void BScrollBar::SetTarget(BView *view)
void BScrollBar::SetTarget(const char *name)

BView *BScrollBar::Target() const

These functions set and return the target of the BScrollBar, the view that the scroll bar scrolls. SetTarget() sets the target to view, or to the BView identified by name. Target() returns the current target view. The target can also be set when the BScrollBar is constructed.

SetTarget() can be called either before or after the BScrollBar is attached to a window. If the target is set by name, the named view must eventually be found within the same window as the scroll bar. Typically, the target and its scroll bars are children of a container view that serves to bind them together as a unit.

When the target is successfully set, a pointer to the BScrollBar object is passed to the target view. This lets the target update its scroll bars when its contents are scrolled.

See also: The BScrollBar constructor, ValueChanged(), BView::ScrollBar()

SetValue(), Value()

void BScrollBar::SetValue(float value)

float BScrollBar::Value() const

These functions modify and return the value of the scroll bar. The value is usually set as the result of user actions; SetValue() provides a way to do it programmatically. Value() returns the current value, whether set by SetValue() or by the user.

SetValue() assigns a new value to the scroll bar and calls the ValueChanged() hook function, whether or not the new value is really a change from the old. If the value passed lies outside the range of the scroll bar, the BScrollBar is reset to the closest value within range—that is, to either the minimum or the maximum value previously specified.

If the scroll bar is attached to a window, changing its value updates its on-screen display. The call to ValueChanged() enables the object to scroll the target view so that it too is updated to conform to the new value.

The initial value of a scroll bar is 0.

Static Functions¶

Instantiate()

static BArchivable *BScrollBar::Instantiate(BMessage *archive)

Returns a new BScrollBar object, allocated by new and created with the version of the constructor that takes a BMessage archive. However, if the archive message doesn’t contain data for a BScrollBar object, the return value will be NULL.

Archived Fields¶

The Archive() function adds the following fields to its BMessage argument:

Field	Type code	Description
_range (array)	`B_FLOAT_TYPE`	Minimum and maximum values of the scroll bar.
_steps (array)	`B_FLOAT_TYPE`	Small and large steps of the scroll bar.
_val	`B_FLOAT_TYPE`	Current value of the scroll bar
_orient	`B_INT32_TYPE`	Orientation of the scroll bar.
_prop	`B_FLOAT_TYPE`	Proportion of the document visible in the target view.