Derived from: public BView
Declared in: <interface/ScrollBar.h>
A BScrollBar object displays a scroll bar that users can operate to scroll the contents of another view, a target view. Scroll bars usually come in pairs, one horizontal and one vertical, and are often grouped as siblings of the target view under a common parent. That way, when the parent is resized, the target and scroll bars can be automatically resized to match. (A companion class, BScrollView, defines just such a container view; a BScrollView object sets up the scroll bars for a target view and makes itself the parent of the target and the scroll bars.)
BScrollBars are different from other views in one important respect: All their drawing and event handling is carried out within the Application Server, not in the application. A BScrollBar object doesn't receive Draw() or MouseDown() notifications; the Server intercepts updates and interface messages that would otherwise be reported to the BScrollBar and handles them itself. As the user moves the knob on a scroll bar or presses a scroll arrow, the Application Server continuously refreshes the scroll bar's image on- screen and informs the application with a steady stream of messages reporting value- changed events.
The window dispatches these messages by calling the BScrollBar's ValueChanged() function. Each function call notifies the BScrollBar of a change in its value and, consequently, of a need to scroll the target view.
Confining the update mechanism for scroll bars to the Application Server limits the volume of communication between the application and Server and enhances the efficiency of scrolling. The application's messages to the Server can concentrate on updating the target view as its contents are being scrolled, rather than on updating the scroll bars themselves.
A scroll bar's value determines what the target view displays. The default assumption is that the left coordinate value of the target view's bounds rectangle should match the value of the horizontal scroll bar, and the top of the target view's bounds rectangle should match the value of the vertical scroll bar. When a BScrollBar is notified of a change of value (through its ValueChanged() function), it scrolls the target view to put the new value at the left or top of the bounds rectangle.
The value reported in a ValueChanged() notification depends on where the user moves the scroll bar's knob and on the range of values the scroll bar represents. The range is first set in the BScrollBar constructor and can be modified by the SetRange() function.
The range must be large enough to bring all the coordinate values where the target view
can draw into its bounds rectangle. If everything the target view can draw is conceived as
being enclosed in a "data rectangle," the range of a horizontal scroll bar must extend from
a minimum that makes the left side of the target's bounds rectangle coincide with the left
side of its data rectangle, to a maximum that puts the right side of the bounds rectangle at
the right side of the data rectangle. This is illustrated in part below:
As this illustration helps demonstrate, the maximum value of a horizontal scroll bar can be no less than the right coordinate value of the data rectangle minus the width of the bounds rectangle. Similarly, for a vertical scroll bar, the maximum value can be no less than the bottom coordinate of the data rectangle minus the height of the bounds rectangle. The range of a scroll bar subtracts the dimensions of the target's bounds rectangle from its data rectangle. (The minimum values of horizontal and vertical scroll bars can be no greater than the left and top sides of the data rectangle.)
What the target view can draw may change from time to time as the user adds or deletes data. As this happens, the range of the scroll bar should be updated with the SetRange() function. The range may also need to be recalculated when the target view is resized.
Users have control over some aspects of how scroll bars look and behave. With the ScrollBar preferences application, they can choose:
When this class constructs a new BScrollBar, it conforms the object to the choices the user has made.
See also: set_scroll_bar_info(), BView::ScrollBar(), the BScrollView class
ValueChanged() | Scrolls the target view when the BScrollBar is informed that its value has changed; can be implemented to alter the default interpretation of the scroll bar's value. |
BScrollBar(BRect frame, const char *name, BView *target, long min, long max, orientation posture)
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:
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).
virtual ~BScrollBar(void)
Disconnects the scroll bar from its target.
inline orientation Orientation(void) const
Returns HORIZONTAL if the object represents a horizontal scroll bar and VERTICAL if it represents a vertical scroll bar.
See also: the BScrollBar constructor
void SetProportion(float ratio) float Proportion(void) 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.
void SetRange(long min, long max) void GetRange(long *min, long *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.
See also: the BScrollBar constructor
void SetSteps(long smallStep, long bigStep) void GetSteps(long *smallStep, long *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. When the user clicks in the bar itself (other than on the knob), it changes by a bigStep. 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, which should be too small for most purposes; the default large step is 10, which is also probably too small.
< Currently, a BScrollBar's steps can be successfully set only after it's attached to a window. >
See also: ValueChanged()
void SetTarget(BView *view) void SetTarget(const char *name) inline BView *Target(void) 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.
See also: the BScrollBar constructor, ValueChanged(), BView::ScrollBar()
void SetValue(long value) long Value(void) 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.
See also: ValueChanged() , SetRange()
virtual void ValueChanged(long 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 view's contents accordingly.
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.
ValueChanged() is called as the result both of value-changed messages received from the Application Server and of SetValue() and SetRange() function calls within the application.
See also: SetTarget()
The Be Book, HTML Edition, for Developer Release 8 of the Be Operating System.
Copyright © 1996 Be, Inc. All rights reserved.
Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.
Last modified September 6, 1996.