Derived from: public BWindow
Declared in: <interface/Alert.h>
A BAlert places a modal window on-screen in front of other windows and keeps it there until the user dismisses it. The window is an alert panel that has a message for the user to read and one or more buttons along the bottom that present various options for the user to choose among. Operating a button with the keyboard or mouse selects a course of action and dismisses the panel (closes the window). The message in the alert panel 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 (by operating the appropriate button).
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, the BAlert class provides a simple way to do it. 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();
Go() doesn't return until the user operates a button to dismiss the panel. When it returns, the window will have been closed, the window thread will have been killed, and the BAlert object will have been deleted.
The value Go() returns indicates which button dismissed the panel. If the user clicked the "Cancel" button in this example 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.
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)
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 let the width of each button adjust 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. Before returning, Go() destroys the object. You don't need to write code to delete it.
See also: Go(), SetShortcut()
inline BButton *ButtonAt(long 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()
long Go(void)
Calls the Show() virtual function to place the alert panel on-screen, sets the modal loop for the BAlert in motion, and returns when the loop has quit and the window has been closed. The value returned is the index of the button that the user operated to dismiss the window. Buttons are numbered from left to right, beginning with 0.
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.
void SetShortcut(long index, char shortcut)
Sets 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.
inline 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, 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.