The Interface Kit: BStatusBar

Derived from: public BView

Declared in: be/interface/StatusBar.h

Library: libbe.so


Overview

A BStatusBar object draws a status bar, also called a progress bar, that indicates the progression and pace of a time-consuming operation. It gives the user something to look at while the operation is taking place and provides some indication of how long it will take. The bar is filled with color from left to right as more and more of the operation is completed.

A BStatusBar can display a label on the far left above the bar itself and some text immediately to the right of the label. It can also display a trailing label on the far right and trailing text immediately to its left. The label and text are aligned at the left of the bar; the trailing text and trailing label are aligned at the right of the bar. In neither case is there any Kitspace between the label and text; to separate words you must add space characters to one string or the other.

The text and trailing text can change each time the bar is updated--that is, each time a bit more of the bar is filled. The label and trailing label, on the other hand, are set when the BStatusBar is constructed and remain constant throughout the display, or until the object is reset for another operation.

For example, a status bar that's displayed while a large file is being downloaded might have the file name as the label and no text. It could have the percentage completed as the trailing text and something like "% done" as the trailing label. A BStatusBar that tracks the processing of, say, 40 employee records could have "Employee: " as the label, the employee's name as the text, the number of the record being processed as the trailing text, and " of 40" as the trailing label.

The value of a BStatusBar determines how much of the bar is filled with color. The minimum value (none of the bar is filled) is 0.0; the maximum value (all of the bar is filled) is 100.0 by default, but can be set to another positive number. For example, if the maximum value is 400.0 and current value is 86.0, 21.5% (86/400) of the bar will be filled.

A BStatusBar is controlled synchronously by calling its Update() and Reset() functions. Update() fills a bit more of the bar each time it's called and can change the text and trailing text. Reset() resets the current value to 0.0 so the bar can show the progress of another operation; it can change the label and trailing label.

You can also control a BStatusBar asynchronously by making it the target of B_UPDATE_STATUS_BAR and B_RESET_STATUS_BAR messages, which indirectly call Update() and Reset(). These messages are described under the corresponding functions.

See also: Update(), Reset()


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 trailing label, which can both be NULL. The frame and name arguments are the same as those declared for the BView constructor and are passed to the BView class unchanged along with the B_WILL_DRAW flag and a resizing mode that will keep the BStatusBar glued to the left and top sides of its parent.

Regardless of the frame rectangle, however, when the BStatusBar is attached to a window, it will be resized to a height that precisely accommodates the bar, the labels, and the text given the current font.

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(void)

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.

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


AttachedToWindow()


      virtual void AttachedToWindow(void)

Resizes the frame rectangle to the optimal height for displaying the bar, labels, and text. If the height of the bar has not been set yet, a default height is chosen for it.

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.

See also: BView::AttachedToWindow()


BarColor() see SetBarColor()


BarHeight() see SetBarHeight()


CurrentValue() see SetMaxValue()


Draw()


      virtual void Draw(BRect updateRect)

Draws the bar, labels, and text.

See also: BView::Draw()


Label(), TrailingLabel()


      const char *Label(void) const

      const char *TrailingLabel(void) const

These functions return the current label and trailing label of the BStatusBar. 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. When the BStatusBar is attached to a window, its frame rectangle is resized to a height that fits the bar height and the height of the current font for displaying the text and labels. Therefore, if you want a bar that's taller or shorter than the default height, you should call SetBarHeight() before adding the BStatusBar to a view hierarchy.

See also: AttachedToWindow()


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, which determines how much of the bar is filled with the bar color. For example, if the maximum is 300.0 and the current value is 120.0, the bar color will fill 40% of the bar. The current value is set by Update() and reset to 0.0 by Reset().

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 functions set and return the text and the trailing text of the BStatusBar. The Set...() functions free the previous text and replace it with a copy of the string that's passed. The string can be NULL. Both functions erase the previous text and redraw the view to display the new text. The text and trailing text can also be replaced by calling Update().

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

See also: Update()


Text() see SetText()


TrailingLabel() see Label()


TrailingText() see SetText()


Update()


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

Updates the BStatusBar by adding a delta increment to its current value and resetting its text and trailing text. For example, if the current value is 50.0 and delta is 8.0, the new value will be 58.0. The change in value is immediately reflected on-screen in a corresponding increment in how much of the bar is filled with color. Passing NULL for the text or trailingText argument retains the previous text or trailing text string.

You can call this function indirectly through a B_UPDATE_STATUS_BAR message. The message must have a B_FLOAT_TYPE entry named "delta" containing the value that should be passed to the function as the delta argument. If it also has a string in an entry named "text", the string will be passed as the text argument. And if it has a string entry named "trailing_text", that string will be passed as the trailingText argument. If either string entry is omitted, the corresponding argument will be NULL.

See also: Reset(), CurrentValue(), SetText()






The Be Book, in lovely HTML, for the BeOS Preview Release.

Copyright © 1997 Be, Inc. All rights reserved.

Be is a registered trademark; BeOS, BeBox, BeWare, GeekPort, the Be logo, and the BeOS logo are trademarks of Be, Inc.

Last modified September 18, 1997.