# The Interface Kit: BScrollView

Derived from: public BView

Declared in: be/interface/ScrollView.h

Library: libbe.so

## Overview

A BScrollView object is a container for another view, a target view, typically a view that can be scrolled. The BScrollView creates and positions the scroll bars the target view needs and makes itself the parent of the scroll bars and the target view. It's a convenient way to set up scroll bars for another view.

If requested, the BScrollView draws a border around its children. Otherwise, it does no drawing and simply contains the family of views it set up.

The `ScrollBar()` function provides access to the scroll bars the BScrollView creates, so you can set their ranges and values as needed.

## Constructor and Destructor

### BScrollView()

          BScrollView(const char *name, BView *target,
             uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP,
             uint32 flags = 0,
             bool horizontal = false,
             bool vertical = false,
             border_style border = B_FANCY_BORDER)
          BScrollView(BMessage *archive)

Creates a BScrollView that has target as its target view. The scroll view is "wrapped around" the target: It (the scroll view) will adopt a frame rectangle large enough to contain the target view and any scroll bars that are requested. If horizontal is `true`, there will be a horizontal scroll bar. If vertical is `true`, there will be a vertical scroll bar. Scroll bars are not provided unless you ask for them.

The target and the scroll bars are added as (sibling) children of the scroll view, and the target's `TargetedByScrollView()` function is called. The target must not already be the child of some other view.

The border argument can be one of three values:

`B_PLAIN_BORDER` | Draw a border consisting of just a simple line around the target view and scroll bars.
`B_FANCY_BORDER` | Draw a fancier border that looks like a 3D groove inset into the surface of the view.
`B_NO_BORDER` | Don't draw a border.

If the resize mode of the target view is `B_FOLLOW_ALL_SIDES`, it and the scroll bars will be automatically resized to fill the scroll view whenever the scroll view is resized.

The scroll bars created by the BScrollView have an initial range of 0 to 1000. Use the `ScrollBar()` function to retrieve the scroll bars and reset their ranges.

The name, resizingMode, and flags arguments are identical to those declared in the BView class and are passed to the BView constructor. If a border is requested, `B_WILL_DRAW` is automatically added to the flags mask. The other two arguments are passed to the BView class unchanged.

See also: the BView constructor, `BView:TargetedByScrollView()`

### ~BScrollView()

          virtual ~BScrollView()

Does nothing.

## Static Functions

### Instantiate()

          static BScrollView *Instantiate(BMessage *archive)

Returns a new BScrollView object, allocated by `new` and created with the version of the constructor that takes a BMessage archive. However, if the message doesn't contain data for an archived BScrollView object, `Instantiate()` returns `NULL`.

See also: `BArchivable::Instantiate()`, `instantiate_object()`, `Archive()`

## Member Functions

### Archive()

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

Calls the inherited version of `Archive()`, which will archive the target view and scroll bars if the deep flag is `true`. This function then adds the BScrollView's border style to the archive message.

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

### AttachedToWindow()

          virtual void AttachedToWindow(void)

Resizes scroll bars belonging to BScrollViews that occupy the right bottom corner of a document window (`B_DOCUMENT_WINDOW`) so that room is left for the resize knob. This function assumes that vertical scroll bars are `B_V_SCOLL_BAR_WIDTH` units wide and horizontal scroll bars are `B_H_SCROLL_BAR_HEIGHT` units high. It doesn't check to make sure the window is actually resizable.

This function also sets the default high color to a medium shade of gray.

See also: `BView::AttachedToWindow()`

### Border() see SetBorder()

### Draw()

          virtual void Draw(BRect updateRect)

Draws the border around the target view and scroll views, provided a border was requested when the BScrollView was constructed.

See also: the BScrollView constructor, `BView::Draw()`

### IsBorderHighlighted() see SetBorderHighlighted()

### ScrollBar()

          BScrollBar *ScrollBar(orientation posture) const

Returns the horizontal scroll bar if posture is `B_HORIZONTAL` and the vertical scroll bar if posture is `B_VERTICAL`. If the BScrollView doesn't contain a scroll bar with the requested orientation, this function returns `NULL`.

See also: the BScrollBar class

### SetBorder(), Border()

          virtual void SetBorder(border_style border)

          border_style Border(void) const

These functions set and return the style of the BScrollView's border, which may be `B_PLAIN_BORDER`, `B_FANCY_BORDER`, or `B_NO_BORDER`. The border is originally set by the constructor. The three constants and the border's effect on the BScrollView are discussed there.

See also: the BScrollView constructor

### SetBorderHighlighted(), IsBorderHighlighted()

          virtual status_t SetBorderHighlighted(bool highlighted)

          bool IsBorderHighlighted(void) const

`SetBorderHighlighted()` highlights the border of the BScrollView when the highlighted flag is `true`, and removes the highlighting when the flag is `false`. This function works by calling `Draw()`. However, it works only for a border in the `B_FANCY_BORDER` style. If successful, it returns `B_OK`. Otherwise, it returns `B_ERROR`.

`IsBorderHighlighted()` returns whether the border is currently highlighted. The return value is always `false` for a BScrollView that doesn't have a border or has only a "plain" one.

Highlighting a BScrollView's border shows that the target view is the current focus view for the window. Typically, the target view calls `SetBorderHighlighted()` from its `MakeFocus()` function when the focus changes. (The target knows that it's inside a BScrollView because of the `TargetedByScrollView()` notification it received.)

## Archived Fields

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

Field | Type code | Meaning
"_style" | `B_INT32_TYPE` | Border type.

The following views are added to the "_views" field (deep copy only):

Name | Level | Meaning
target | 0 | Target view for the object.
"_VSB_" | 0 | Vertical BScrollBar.
"_HSB_" | 0 | Horizontal BScrollBar.

Some of these fields may not be present if the setting they represent isn't used, or is the default value. For example, if the border type is `B_FANCY_BORDER`, the "_style" field won't be found in the archive.

The Be Book, in lovely HTML, for BeOS Release 3.

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.