BAlert

Derived from: BWindow > BLooper > BHandler > BArchivable

Declared in: be/interface/Alert.h

Library: libbe.so

Allocation: Constructor only

[method summary]

A BAlert displays a modal window that notifies the user of an error (or the like), and provides a set of buttons (three buttons, max) that lets the user respond to the situation. For example, here's a typical "unsaved changes" alert:

When the user clicks one of the buttons, the alert panel is automatically removed from the screen, the index of the chosen button (0,1, or 2, left to right) is reported to your app, and the BAlert object is deleted.

The buttons are automatically aligned within the panel (as shown above). The rightmost button is the default button--i.e., it's mapped to the Enter key. You can assign your own shortcuts through the SetShortcut() function (don't use BWindow::AddShortcut()).

Construction and Deletion

BAlert objects must be constructed with new; you can't allocate a BAlert on the stack.

A BAlert object deletes itself when it's removed from the screen. You never need to delete the BAlert objects that you display.

Creating and Running an Alert Panel

The following code creates and displays the alert panel shown above:

   BAlert *myAlert = new BAlert("title", "Save changes to ...")
      "Cancel", "Don't save", "Save", 
      B_WIDTH_AS_USUAL, B_OFFSET_SPACING, B_WARNING_ALERT);
   myAlert->SetShortcut(0, B_ESCAPE);
      int32 button_index = alert->Go();

This is the canonical "Do it/Don't do it/Cancel" alert. Any alert that has a "Cancel" button should map the Escape key as a shortcut, as shown here.

The Go() function runs the panel: It displays the panel, removes the panel when the user is done, and returns the index of the button that the user clicked.

Asynchronous Alerts

The default (no argument) version of Go() shown above is synchronous: It doesn't return until the user clicks a button. There's also an asynchronous version of Go() that returns immediately and (optionally) sends back the user's response in a BMessage. See Go() for details.

Look and Feel

By default, a BAlert object uses the B_MODAL_APP_WINDOW_FEEL. This means that it blocks your application's other windows. If you want to broaden the feel so it blocks all windows (B_MODAL_ALL_WINDOW_FEEL), or restrict it so it blocks only a few of your app's windows (B_MODAL_SUBSET_WINDOW_FEEL), call BWindow::SetFeel(). In the subset case, you'll also have to call BWindow::AddToSubset().

Never change the object's look (B_MODAL_WINDOW_LOOK).

Constructor

BAlert(), alert_type, button_spacing

      BAlert(const char *title, const char *text,
         const char *button0Label,
         const char *button1Label = NULL,
         const char *button2Label = NULL,
         button_width widthStyle = B_WIDTH_AS_USUAL,
         alert_type type = B_INFO_ALERT) 
      BAlert(const char *title, const char *text,
         const char *button0Label,
         const char *button1Label,
         const char *button2Label,
         button_width widthStyle,
         button_spacing spacing,
         alert_type type = B_INFO_ALERT) 
      BAlert(BMessage *archive) 
      enum alert_type { B_EMPTY_ALERT, 
         B_INFO_ALERT, 
         B_IDEA_ALERT, 
         B_WARNING_ALERT, 
         B_STOP_ALERT }
      enum button_spacing { B_EVEN_SPACING, B_OFFSET_SPACING }

Creates an alert panel that's ready to be displayed. The arguments are:

title is the name of the panel. Since an alert panel doesn't have a title tab, the title isn't actually displayed in the panel. Nonetheless, it can be useful in debugging: The title is used to name the window thread ("w>title").
text is displayed in the body of the panel; it should describe the reason the panel is being shown ("Are you sure you want to quit?", "Invalid name.", etc.).
The buttonLabel arguments label the panel's buttons. An alert panel can have one, two, or three buttons--however many labels you supply is the number of buttons that are displayed. The buttons are arranged at the bottom of the panel as shown in the illustration above, and each is assigned an index (0, 1, or 2, left to right) that's used to identify the button that the user clicked.
widthStyle is a constant that describes how the buttons should be sized:

Constant Meaning
B_WIDTH_AS_USUAL A default width is used on all buttons.
B_WIDTH_FROM_LABEL Each button is wide enough to accommodate its own label.
B_WIDTH_FROM_WIDEST All buttons are resized to fit the longest label.

Constant	Meaning
`B_WIDTH_AS_USUAL`	A default width is used on all buttons.
`B_WIDTH_FROM_LABEL`	Each button is wide enough to accommodate its own label.
`B_WIDTH_FROM_WIDEST`	All buttons are resized to fit the longest label.

spacing is a constant that describes how the buttons are spaced:

Constant Meaning
B_EVEN_SPACING The buttons are evenly spaced. This is used by the constructor without the spacing argument.
B_OFFSET_SPACING If the alert has more than one button, the leftmost button is shifted left to separate it from its neighbor(s). You should use this configuration for an alert that has a (leftmost) "Cancel" button, as shown in the illustration at the beginning of this document.

Constant	Meaning
`B_EVEN_SPACING`	The buttons are evenly spaced. This is used by the constructor without the spacing argument.
`B_OFFSET_SPACING`	If the alert has more than one button, the leftmost button is shifted left to separate it from its neighbor(s). You should use this configuration for an alert that has a (leftmost) "Cancel" button, as shown in the illustration at the beginning of this document.

type is a constant that determines the icon that's displayed in the panel. There are five alert_type constants:

B_EMPTY_ALERT B_INFO_ALERT B_IDEA_ALERT B_WARNING_ALERT B_STOP_ALERT
(none)

After the BAlert is constructed, Go() must be called to display it. The panel is removed and the object is deleted after the user clicks a button.

Member Functions

AlertPosition()

      BPoint AlertPosition(float width, float height) const

Computes the "best" frame for an alert of the given width and height, and returns the top left corner of the computed frame in screen coordinates. This function is called automatically when you construct your BAlert; you never have to invoke it yourself.38541: head1: \xa5 Archived Fields

Archive(), see

ButtonAt()

      BButton *ButtonAt(int32 index) const

Returns a pointer to the BButton object identified by index. Indices begin at 0 and count buttons from left to right. The BButton belongs to the BAlert object and should not be freed.

FrameResized() see BWindow::FrameResized()

GetSupportedSuites(), See, BHandler::GetSupportedSuites()

Go()

      int32 Go(void)
      status_t Go(BInvoker *invoker)

Displays the alert panel. Go() can operate synchronously or asynchronously:

The no-argument version is synchronous: The function doesn't return until the user has clicked a button and the panel has been removed from the screen.. The value it returns is the index of the clicked button (0,1, or 2, left-to-right)..
The BInvoker argument version is asynchronous: The function returns immediately (with B_OK) and the button index is delivered as the int32 "which" field of the BMessage that's sent to the BInvoker's target.
If you call Go() with a (literal) NULL argument...

   alert->Go(NULL);

...the asynchronous version is used, but the BMessage isn't sent.

The synchronous version deletes the object before it returns; the asynchronous version deletes it after the message is sent. In either case, you should consider the BAlert object to be invalid after you call Go().

If the BAlert is sent a B_QUIT_REQUESTED message while the panel is still on-screen, the synchronous version of Go() returns -1; the asynchronous version suppresses the index-reporting message.

MessageReceived() see BWindow::MessageReceived()

Scripting Support

ResolveSpecifier(), see

SetShortcut(), Shortcut()

      void SetShortcut(int32 index, char shortcut)
      char Shortcut(int32 index) const

These functions set and return the shortcut character that's mapped to the button at index. A given button can have only one shortcut except for the rightmost button, which, in addition to the shortcut that you give it here, is always mapped to B_ENTER.

If you create a "Cancel" button, you should give it a shortcut of B_ESCAPE.

TextView()

      BTextView *TextView(void) const

Returns a pointer to the BTextView object that contains the textual information that's displayed in the panel. You can fiddle with this object but you mustn't delete it.

Archived Fields

Field Type code Meaning
"_text" B_STRING_TYPE The alert's descriptive text.
"_atype" B_INT32_TYPE The alert_type value.
"_but_width" B_INT32_TYPE The button_width value.
"_but_key" (array) B_INT32_TYPE Keyboard shortcut values (one field per button).

Field	Type code	Meaning
"_text"	`B_STRING_TYPE`	The alert's descriptive text.
"_atype"	`B_INT32_TYPE`	The `alert_type` value.
"_but_width"	`B_INT32_TYPE`	The `button_width` value.
"_but_key" (array)	`B_INT32_TYPE`	Keyboard shortcut values (one field per button).

In a deep copy, the following views appear in the "_views" field:

View name Level Meaning
"_master_" 0 Background view.
"_tv_" 1 BTextView for the alert panel's text.
"_b0_" 1 BButton with index 0.
"_b1_" 1 BButton with index 1.
"_b2_" 1 BButton with index 2.

View name	Level	Meaning
"_master_"	0	Background view.
"_tv_"	1	BTextView for the alert panel's text.
"_b0_"	1	BButton with index 0.
"_b1_"	1	BButton with index 1.
"_b2_"	1	BButton with index 2.

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

Last modified January 5, 1999.

`B_EMPTY_ALERT`	`B_INFO_ALERT`	`B_IDEA_ALERT`	`B_WARNING_ALERT`	`B_STOP_ALERT`
(none)