# The Interface Kit: BStatusBar

Derived from: public BView

Declared in: be/interface/StatusBar.h

Library: libbe.so

## Overview

A BStatusBar is a cosmetic object that graphically indicates the progress of an operation. It displays a horizontal bar that's filled with color from left to right as operation is progresses:

The label and text are abutted and aligned at the left of the bar; the trailing text and trailing label are abutted and aligned at the right of the bar.

The texts can change each time the bar is updated. The label and trailing label are set by the constructor and remain constant throughout the display, or until the object is reset for another operation.

To set the amount that the status bar is filled, you can either `SetValue()`, which sets it as an absolute amount, or `Update()`, which lets you add a delta to the current value. The "filling" itself reflects the ratio (`current_value`)/(`max_value`), where `max_value` is 100.0 by default, but can be reset through `SetMaxValue()`. The minimum value of the bar is always 0.0.

`Update()` is the preferred method for "growing" the bar's value. You can call it directly, or invoke it indirectly (and asynchronously) by sending a `B_UPDATE_STATUS_BAR` message to the BStatusBar.

The `Reset()` function, which empties the bar can also be invoked through a message (`B_RESET_STATUS_BAR)`.

## Constructor and Destructor

### BStatusBar()

          BStatusBar(BRect frame, const char *name,
             const char *label = NULL, const char *trailingLabel = NULL)
          BStatusBar(BMessage *archive)

Initializes the BStatusBar with a label and a trailingLabel, which can both be `NULL`. The frame rectangle is used for its origin and width only; when the BStatusBar is attached to a window, it will be resized to a height that precisely accommodates its parts. The name argument is passed on to the BView constructor.

The object is given a `B_WILL_DRAW` flag and a resizing mode that keeps it glued to the left and top sides of its parent.

The default font of the BStatusBar is the system plain font, and the default color of the bar is blue (50, 150, 255). It's initial value is 0.0, the minimum, and its default maximum value is 100.0.

See also: `SetMaxValue()`, `SetBarColor()`

### ~BStatusBar()

          virtual ~BStatusBar()

Frees the labels and the text.

## Static Functions

### Instantiate()

          static BStatusBar *Instantiate(BMessage *archive)

Returns a new BStatusBar object, allocated by `new` and created with the version of the constructor that takes a BMessage archive. However, if the archive doesn't contain data for an BStatusBar object, this function 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()`, then adds the bar color, bar height, current value, and maximum value to the BMessage archive, along with the current text, trailing text, label, and trailing label.

### AttachedToWindow()

          virtual void AttachedToWindow(void)

Resizes the frame rectangle to accommodate the object's graphical parts. The width isn't altered.

This function also sets the view and low colors of the BStatusBar to match the background view color of its new parent. The low color fills the status bar when it's empty.

### BarColor() see SetBarColor()

### BarHeight() see SetBarHeight()

### CurrentValue() see SetMaxValue()

### Draw()

          virtual void Draw(BRect updateRect)

Draws the bar, labels, and text.

### Label(), TrailingLabel()

          const char *Label(void) const

          const char *TrailingLabel(void) const

These functions return pointers to the object's label and trailing label. The returned strings belong to the BStatusBar object and should not be altered. They can be set only on construction or when all values are reset.

See also: `Reset()`

### MaxValue() see SetMaxValue()

### MessageReceived()

          virtual void MessageReceived(BMessage *message)

Responds to `B_UPDATE_STATUS_BAR` and `B_RESET_STATUS_BAR` messages by calling the `Update()` and `Reset()` functions. Each message contains data that can be passed as arguments to the functions.

See also: `BView::MessageReceived()`, `Update()`, `Reset()`, "BStatusBar Messages" in the Message Protocols appendix

### Reset()

          virtual void Reset(const char *label = NULL, const char *trailingLabel = NULL)

Empties the status bar, sets its current value to 0.0 and its maximum value to 100.0, deletes and erases the text and trailing text, and replaces the label and trailing label with copies of the strings passed as arguments. If either argument is `NULL`, the label or trailing label will also be deleted and erased.

This gets the BStatusBar ready to be reused for another operation. For example, if several large files are being downloaded, the BStatusBar could be reset for each one.

You can call this function indirectly (and asynchronously) through a `B_RESET_STATUS_BAR` message. If the message has an entry named "label" containing a string (`B_STRING_TYPE`), the string will be passed to the function as the first argument. If there's a string in an entry named "trailing_label", it will be passed as the second argument. If either entry is absent, the value for the corresponding argument will be `NULL`.

See also: `SetText()`, `Update()`

### SetBarColor(), BarColor()

          virtual void SetBarColor(rgb_color color)

          rgb_color BarColor(void) const

These functions set and return the color that fills the bar to show how much of an operation has been completed. The default bar color is blue (50, 150, 255).

### SetBarHeight(), BarHeight()

          virtual void SetBarHeight(float height)

          float BarHeight(void) const

These functions set and return the height of the bar itself, minus the text and labels. The default height is 16.0 coordinate units. The frame rectangle is adjusted to accommodate the new height, and the object is redrawn.

### SetMaxValue(), MaxValue(), CurrentValue()

          virtual void SetMaxValue(float max)

          float MaxValue(void) const

          float CurrentValue(void) const

`SetMaxValue()` sets the maximum value of the BStatusBar, which by default is 100.0. `MaxValue()` returns the current maximum. The minimum value is 0.0 and cannot be changed.

`CurrentValue()` returns the current value of the BStatusBar. The current value is set by `Update()` and reset to 0.0 by `Reset()`.

The amount of "filling" in the status bar reflects the ratio `CurrentValue()`/`MaxValue()`.

See also: `Update()`, `Reset()`

### SetText(), SetTrailingText(), Text(), TrailingText()

          virtual void SetText(const char *string)

          virtual void SetTrailingText(const char *string)

          const char *Text(void) const

          const char *TrailingText(void) const

These `SetText()` and `SetTrailingText()` functions erase the previous text or trailing text and replace them with copies of the string argument. string can be `NULL`. The view is automatically redrawn.

`Text()` and `TrailingText()` return pointers to the current text strings.

### SetText())

### TrailingLabel() see SetLabel()

### TrailingText() see SetText()

### Update()

          virtual void Update(float delta, const char *text = NULL, const char *trailingText = NULL)

`Update()` updates the BStatusBar by adding delta to its current value and resetting its text and trailing text. Passing `NULL` for the text or trailingText argument retains the existing string(s). The status bar is automatically redrawn.

You can call `Update()` indirectly through a `B_UPDATE_STATUS_BAR` message that contains the following fields, which correspond to the function's arguments:

Field | Type
"delta" | B_FLOAT_TYPE
"text" | B_STRING_TYPE
"trailing text" | B_STRING_TYPE

To pass a `NULL` string through this message, simply don't add the "text" or "trailing text" field.

## Archived Fields

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

Field | Type code | Meaning
"_high" | `B_FLOAT_TYPE` | Status bar height.
"_bcolor" | `B_INT32_TYPE` | Status bar color.
"_val" | `B_FLOAT_TYPE` | Current value.
"_max" | `B_FLOAT_TYPE` | Maximum value.
"_text" | `B_STRING_TYPE` | Status bar text.
"_ttext" | `B_STRING_TYPE` | Trailing text.
"_label" | `B_STRING_TYPE` | Status bar label.
"_tlabel" | `B_STRING_TYPE` | Trailing text label.

Some of these fields may not be present if the setting they represent isn't used, or is the default value. For example, if there is no trailing text, the "_ttext" 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.