Derived from: public BWindow
Declared in: <interface/Alert.h>
A BAlert places a modal window on-screen in front of other windows. The window is an alert panel that has a message for the user to read and one or more buttons the user can operate. The message might warn the user of something or convey some information that the application doesn't want the user to overlook. Typically, it asks a question that the user must answer. Operating a button chooses a course of action and dismisses the panel (closes the window).
The alert panel stays on-screen only temporarily, until the user operates one of the buttons. As long as it's on-screen, other parts of the application's user interface are disabled. However, the user can continue to move windows around and work in other applications.
It's possible to design such a panel using a BWindow object, some BButtons, and other views. However, it's simpler to use a BAlert object. There's no need to construct views and arrange them, or call functions to show the window and then get rid of it. All you do is:
For example:
BAlert *alert;
long result;
alert = new BAlert("", "Time's up! Do you want to continue?",
"Cancel", "Continue", NULL,
B_WIDTH_FROM_WIDEST, B_WARNING_ALERT);
alert->SetShortcut(0, B_ESCAPE);
result = alert->Go();
Like other windows, the alert panel runs in its own thread. Go() can run it synchronously or asynchronously. If synchronously, Go() doesn't return until the user operates a button to dismiss the panel. It returns an index to the button the user picked. If the user clicked the "Cancel" button in the example above or pressed the Escape key, the return result would be 0. If the user clicked "Continue", the result would be 1. Since the BAlert sets up the rightmost button as the default button for the window, the user could also operate the "Continue" button by pressing the Enter key.
If it runs the panel asynchronously, Go() returns immediately with, of course, no indication of which button the user will choose. If it's important to take some action when the user acts, a BInvoker object must be passed to the function:
alert->Go(someInvoker);
The BInvoker will send its message when the user acts. The index of the button the user chose is stuffed into the message as a int32 integer under the name "which".
In either case, when the user dismisses the panel, the window thread is killed, and the BAlert object is deleted.
BAlert(const char *title, const char *text,
const char *firstButton,
const char *secondButton = NULL,
const char *thirdButton = NULL,
button_width width = B_WIDTH_AS_USUAL,
alert_type type = B_INFO_ALERT)
BAlert(BMessage *archive)
Creates an alert panel as a modal window. The window displays some text for the user to read, and can have up to three buttons. There must be at least a firstButton; the others are optional. The BAlert must also have a title, even though the panel doesn't have a title tab to display it. The title can be NULL or an empty string.
The buttons are arranged in a row at the bottom of the panel so that one is always in the right bottom corner. They're placed from left to right in the order specified to the constructor. If labels for three buttons are provided, firstButton will be on the left, secondButton in the middle, and thirdButton on the right. If only two labels are provided, firstButton will come first and secondButton will be in the right bottom corner. If there's just one label (firstButton), it will be at the right bottom location.
By default, the user can operate the rightmost button by pressing the Enter key. If a "Cancel" button is included, it should be assigned the B_ESCAPE character as a keyboard shortcut. Other buttons can be assigned other shortcut characters. Use BAlert's SetShortcut() function to set up the shortcuts, rather than BWindow's AddShortcut(). Shortcuts added by a BWindow require the user to hold down a Command key, while those set by a BAlert don't.
By default, all the buttons have a standard, minimal width (B_WIDTH_AS_USUAL). This is adequate for most buttons, but may not be wide enough to accommodate an especially long label. To adjust the width of each button to the width of its label, set the width parameter to B_WIDTH_FROM_LABEL. To ensure that the buttons are all the same width, yet wide enough to display the widest label, set the width parameter to B_WIDTH_FROM_WIDEST.
For more hands-on manipulation of the buttons, you can get the BButton objects that the BAlert creates by calling the ButtonAt() function. To get the BTextView object that displays the text string, you can call TextView().
There are various kinds of alert panels, depending on the content of the textual message and the nature of the options presented to the user. The type parameter should classify the BAlert object as one of the following:
| B_EMPTY_ALERT
B_INFO_ALERT B_IDEA_ALERT B_WARNING_ALERT B_STOP_ALERT |
Currently, the alert type is used only to select a representative icon that's displayed at the left top corner of the window. A B_EMPTY_ALERT doesn't have an icon.
After the BAlert is constructed, Go() must be called to place it on-screen. The object is deleted when the user closes the window; you don't need to write code to delete it.
See also: Go(), SetShortcut()
static BAlert *Instantiate(BMessage *archive)
Returns a new BAlert 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 BAlert object, the return value will be NULL.
See also: BArchivable::Instantiate(), instantiate_object(), Archive()
virtual status_t Archive(BMessage *archive, bool deep = true) const
Calls the inherited version of Archive(), then adds the BAlert's type, buttons, keyboard shortcuts, preferred button width, and the text it displays to the BMessage archive.
See also: BArchivable::Archive(), Instantiate() static function
BButton *ButtonAt(int32 index) const
Returns a pointer to the BButton object for the button at index. Indices begin at 0 and count buttons from left to right. The BButton belongs to the BAlert object and should not be freed.
See also: TextView()
virtual void FrameResized(float width, float height)
Overrides the BView function to adjust the layout within the panel when its dimensions change. This function is called as the panel is being resized; there's no need to call it or override it in application code.
See also: BWindow::FrameResized()
int32 Go(void)
status_t Go(BInvoker *invoker)
Sets the modal loop for the BAlert in motion and calls the Show() virtual function to place the panel on-screen. Go() can operate synchronously or asynchronously:
This version of Go() is passed a BInvoker object, which the BAlert will use to send a message when the user operates a button to close the panel. The index of the button the user chooses is added to the message as a 32-bit value under the name "which". This is in addition to the "when" entry added by the BInvoker.
If you don't need to know what action the user takes, invoker can be NULL.
To put an alert panel on-screen, simply construct a BAlert object, set its keyboard shortcuts, if any, and call this function. See the example code in the "Overview" section above.
Before returning, this function deletes the BAlert object, and all the objects it created.
See also: the BAlert constructor
virtual void MessageReceived(BMessage *message)
Closes the window in response to messages posted from the window's buttons. There's no need for your application to call or override this function.
See also: BHandler::MessageReceived()
void SetShortcut(int32 index, char shortcut)
char Shortcut(int32 index) const
These functions set and return a shortcut character that the user can type to operate the button at index. Buttons are indexed from left to right beginning with 0. By default, B_ENTER is the shortcut for the rightmost button.
A "Cancel" button should be assigned the B_ESCAPE character as a shortcut.
The shortcut doesn't require the user to hold down a Command key or other modifier (except for any modifiers that would normally be required to produce the shortcut character).
The shortcut is valid only while the window is on-screen.
BTextView *TextView(void) const
Returns a pointer to the BTextView object that contains the textual information that's displayed in the panel. The object is created and the text is set when the BAlert is constructed. The BTextView object belongs to the BAlert and should not be freed.
See also: the BAlert constructor, ButtonAt()
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 June 28, 1997.