1/* 2 * Copyright 2011 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * John Scipione, jscipione@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/interface/Alert.h rev 42274 10 * src/kits/interface/Alert.cpp rev 42274 11 */ 12 13 14/*! 15 \file Alert.h 16 \ingroup interface 17 \ingroup libbe 18 \brief BAlert class definition and support enums. 19*/ 20 21 22/*! 23 \enum alert_type 24 \ingroup interface 25 \brief Type of alert. 26 27 Determines which icon (if any) is displayed in the alert dialog. 28 Choose one option. If the constructor doesn't include an 29 alert_type argument than \c B_EMPTY_ALERT is used. 30 31 \since BeOS R3 32*/ 33 34 35/*! 36 \var alert_type B_EMPTY_ALERT 37 38 No icon 39 40 \since BeOS R3 41*/ 42 43/*! 44 \var alert_type B_INFO_ALERT 45 46 \image html https://www.haiku-os.org/images/alert_info_32.png 47 48 Info icon 49 50 \since BeOS R3 51*/ 52 53/*! 54 \var alert_type B_IDEA_ALERT 55 56 \image html https://www.haiku-os.org/images/alert_idea_32.png 57 58 Idea icon 59 60 \since BeOS R3 61*/ 62 63/*! 64 \var alert_type B_WARNING_ALERT 65 66 \image html https://www.haiku-os.org/images/alert_warning_32.png 67 68 Warning icon 69 70 \since BeOS R3 71*/ 72 73/*! 74 \var alert_type B_STOP_ALERT 75 76 \image html https://www.haiku-os.org/images/alert_stop_32.png 77 78 Stop icon 79 80 \since BeOS R3 81*/ 82 83 84/*! 85 \enum button_spacing 86 \ingroup interface 87 \brief Method of spacing of buttons in alerts. 88 89 Determines how the buttons on the alert dialog are spaced relative 90 to each other. Choose one option. If the constructor doesn't include a 91 button_spacing argument than \c B_EVEN_SPACING is used. 92 93 \since BeOS R3 94*/ 95 96 97/*! 98 \var button_spacing B_EVEN_SPACING 99 100 If the alert dialog has more than one button than the buttons are 101 spaced evenly across the bottom of the alert dialog. 102 103 \since BeOS R3 104*/ 105 106 107/*! 108 \var button_spacing B_OFFSET_SPACING 109 110 If the alert dialog has more than one button than the leftmost button 111 is offset to the left-hand side of the dialog while the rest of the 112 buttons are grouped on the right. This is useful to separate off a 113 leftmost "Cancel" or "Delete" button. 114 115 \since BeOS R3 116*/ 117 118 119/*! 120 \class BAlert 121 \ingroup interface 122 \ingroup libbe 123 \brief The BAlert class defines a modal alert dialog which displays a short 124 message and provides a set of labeled buttons that allow the user to 125 respond. 126 127 The alert can be configured with a set of one to three buttons. These 128 buttons are assigned indexes 0, 1, and 2 from right-to-left respectively 129 and are automatically positioned by the system. The user can either click 130 on one of the buttons or use a shortcut key to select a button. 131 132 The layout of the buttons can be configured by setting the #button_width 133 and #button_spacing properties in the BAlert constructor. The icon displayed 134 in the alert can also be configured by setting the #alert_type property. The 135 right-most button (index 0) is the default button which can be activated 136 by pushing the \key{Enter} key. 137 138 Below is an example of an unsaved changes alert dialog: 139 140 \image html BAlert_example.png 141 142 When the user responds by selecting one of the buttons the alert window is 143 removed from the screen. The index of the selected button is returned to 144 the calling application and the BAlert object is deleted. 145 146 The code used to create and display an alert dialog like the one shown 147 above is shown below: 148 149\code 150BAlert* alert = new BAlert("Close and save dialog", "Save changes to...", 151 "Cancel", "Don't save", "Save", B_WIDTH_AS_USUAL, B_OFFSET_SPACING, 152 B_WARNING_ALERT); 153alert->SetShortcut(0, B_ESCAPE); 154int32 button_index = alert->Go(); 155\endcode 156 157 The messaged displayed in the dialog window along with the button labels 158 are set by the strings in the contructor. The Cancel button is offset to 159 the left relative to the other buttons by setting the \c B_OFFSET_SPACING 160 flag. The \c B_WARNING_ALERT flag displays the exclamation mark icon in 161 the dialog. 162 163 Any alert with a Cancel button should map the \key{Escape} key as shown in 164 the example above. You can setup additional shortcut keys for the buttons 165 with the SetShortcut() method. 166 167 The Go() method does the work of loading up and removing the alert 168 window and returns the index of the button that the user selected. 169 170 \since BeOS R3 171*/ 172 173 174/*! 175 \fn BAlert::BAlert() 176 \brief Create an unconfigured BAlert dialog. 177 178 This method creates an unconfigured BAlert. You can configure it with 179 methods like SetText(), SetType() and SetButtonSpacing. 180 181 It is advised to use one of the other constructors that help set up all 182 the configuration in one go, instead of doing it piece by piece with this 183 method. 184 185 \since BeOS R3 186*/ 187 188 189/*! 190 \fn BAlert::BAlert(const char* title, const char* text, 191 const char* button1, const char* button2, const char* button3, 192 button_width width, alert_type type) 193 \brief Creates and initializes a BAlert dialog. 194 195 \param title The title of the window. Since the alert window doesn't have 196 a title tab, the title is not actually displayed anywhere but is 197 useful for debugging purposes. 198 \param text The text that is displayed at the top of the window. 199 \param button1 Button 1 label 200 \param button2 Button 2 label 201 \param button3 Button 3 label 202 \param width A constant that describes how the button should be sized. 203 Options are 204 \li \c B_WIDTH_AS_USUAL 205 \li \c B_WIDTH_FROM_WIDEST 206 \li \c B_WIDTH_FROM_LABEL 207 208 See button_width for details. 209 \param type Constant that determines which alert icon is displayed. 210 Options are 211 \li \c B_EMPTY_ALERT 212 \li \c B_INFO_ALERT 213 \li \c B_IDEA_ALERT 214 \li \c B_WARNING_ALERT 215 \li \c B_STOP_ALERT 216 217 See alert_type for details. 218 219 \since BeOS R3 220*/ 221 222 223/*! 224 \fn BAlert::BAlert(const char* title, const char* text, const char* button1, 225 const char* button2, const char* button3, button_width width, 226 button_spacing spacing, alert_type type) 227 \brief Creates and initializes a BAlert dialog. 228 229 You can also set the \a spacing with this constructor. 230 231 \param title The title of the window. Since the alert window doesn't have 232 a title tab, the title is not actually displayed anywhere but is 233 useful for debugging purposes. 234 \param text The text that is displayed at the top of the window. 235 \param button1 Button 1 label 236 \param button2 Button 2 label 237 \param button3 Button 3 label 238 \param width A constant that describes how the button should be sized. 239 Options are 240 \li \c B_WIDTH_AS_USUAL 241 \li \c B_WIDTH_FROM_WIDEST 242 \li \c B_WIDTH_FROM_LABEL 243 244 See button_width for details. 245 \param spacing Determines how the buttons are spaced. Options are 246 \li \c B_EVEN_SPACING 247 \li \c B_OFFSET_SPACING 248 249 See button_spacing for details. 250 \param type Constant that determines which alert icon is displayed. 251 Options are 252 \li \c B_EMPTY_ALERT 253 \li \c B_INFO_ALERT 254 \li \c B_IDEA_ALERT 255 \li \c B_WARNING_ALERT 256 \li \c B_STOP_ALERT 257 258 See alert_type for details. 259 260 \since BeOS R4 261*/ 262 263 264/*! 265 \fn BAlert::BAlert(BMessage* data) 266 \brief Unarchives an alert from a BMessage. 267 268 \param data The archive. 269 270 \since BeOS R3 271*/ 272 273 274/*! 275 \fn BAlert::~BAlert() 276 \brief Destructor method. 277 278 Standard Destructor method to delete a BAlert. 279 280 \since BeOS R3 281*/ 282 283 284/*! 285 \name Archiving 286*/ 287 288 289//! @{ 290 291 292/*! 293 \fn BArchivable* BAlert::Instantiate(BMessage* data) 294 \brief Instantiates a BAlert from a BMessage. 295 296 \param data The message to instantiate the BAlert. 297 298 \returns a BArchivable object of the BAlert. 299 300 \since BeOS R3 301*/ 302 303 304/*! 305 \fn status_t BAlert::Archive(BMessage* data, bool deep) const 306 \brief Archives the BAlert into \a archive. 307 308 \param data The target archive which the BAlert \a data will go into. 309 \param deep Whether or not to recursively archive the BAlert's children. 310 311 \return A status code. 312 \retval B_OK The archive operation was successful. 313 \retval B_BAD_VALUE The archive operation failed. 314 315 \since BeOS R3 316*/ 317 318 319//! @} 320 321 322/*! 323 \fn alert_type BAlert::Type() const 324 \brief Get the alert_type of this alert. 325 326 \return Returns one of the values from the alert_type enum. 327 328 \since BeOS R3 329*/ 330 331 332/*! 333 \fn void BAlert::SetType(alert_type type) 334 \brief Set the type of the alert. 335 336 \param type Pass one of the alert_type enum values to set the type. 337 338 \since BeOS R3 339*/ 340 341 342/*! 343 \fn void BAlert::SetIcon(BBitmap *bitmap) 344 \brief Set a custom icon for the alert. 345 346 \param bitmap A valid BBitmap. The BAlert assumes ownership of the bitmap. 347 348 \since Haiku R1 349*/ 350 351 352/*! 353 \fn void BAlert::SetText(const char *text) 354 \brief Set the text for the alert. 355 356 \param text The text you want the alert to display. 357 358 \since BeOS R3 359*/ 360 361 362/*! 363 \fn void BAlert::SetButtonSpacing(button_spacing spacing) 364 \brief Set the button spacing for the alert. 365 366 \param spacing Pass one of the button_spacing values to configure the 367 spacing. 368 369 \since BeOS R3 370*/ 371 372 373/*! 374 \fn void BAlert::SetButtonWidth(button_width width) 375 \brief Set the button width for the buttons of the alert. 376 377 \param width Pass one of the button_width values to configure the width. 378 379 \since BeOS R3 380*/ 381 382 383/*! 384 \fn void BAlert::SetShortcut(int32 index, char key) 385 \brief Sets the shortcut character which is mapped to a button at the 386 specified \a index. 387 388 A button can only have one shortcut except for the rightmost button which, 389 in addition to the shortcut you set, is always mapped to \c B_ENTER. 390 391 If you create a "Cancel" button then you should set its shortcut to 392 \c B_ESCAPE. 393 394 \param index The \a index of the button to set the shortcut to. 395 \param key The shortcut character to set. 396 397 \since BeOS R3 398*/ 399 400 401/*! 402 \fn char BAlert::Shortcut(int32 index) const 403 \brief Gets the shortcut character which is mapped to a button at the 404 specified \a index. 405 406 \param index The \a index of the button to get the shortcut of. 407 408 \return The shortcut character mapped to the button at the specified 409 \a index. 410 411 \since BeOS R3 412*/ 413 414 415/*! 416 \fn int32 BAlert::Go() 417 \brief Displays the alert window. 418 419 This version of Go() that does not include an invoker is 420 synchronous. Go() returns once the user has clicked a button and 421 the panel has been removed from the screen. The BAlert object is 422 deleted before the method returns. 423 424 If the BAlert is sent a \c B_QUIT_REQUESTED message while the alert 425 window is still on screen then Go() returns -1. 426 427 \returns The index of the button clicked. 428 429 \since BeOS R3 430*/ 431 432 433/*! 434 \fn status_t BAlert::Go(BInvoker* invoker) 435 \brief Displays the alert window from a specified \a invoker. 436 437 This version of Go() with an \a invoker is asynchronous. It returns 438 immediately with \c B_OK and the button \a index is set to the field 439 of the BMessage that is sent to the target of the \a invoker. 440 441 Go() deletes the BAlert object after the message is sent. 442 443 If you call Go() with a \c NULL invoker argument than the BMessage 444 is not sent. 445 446 If the BAlert is sent a \c B_QUIT_REQUESTED method while the alert 447 window is still on screen then the message is not sent. 448 449 \returns A status code. 450 451 \since BeOS R3 452*/ 453 454 455/*! 456 \fn void BAlert::MessageReceived(BMessage* message) 457 \brief Initiates an action from a received message. 458 459 \copydetails BWindow::MessageReceived() 460*/ 461 462 463/*! 464 \fn void BAlert::FrameResized(float newWidth, float newHeight) 465 \brief Resizes the alert dialog. 466 467 \copydetails BWindow::FrameResized() 468*/ 469 470 471/*! 472 \fn void BAlert::AddButton(const char *label, char key=0) 473 \brief Adds a button to the alert. 474 475 \param label The label of the button. 476 \param key The key a user can press to quickly select this button. 477 478 \since BeOS R3 479*/ 480 481 482/*! 483 \fn int32 BAlert::CountButtons() const 484 \brief Counts the number of buttons in the alert. 485 486 \return The number of buttons in this alert window. 487 488 \see AddButton() and ButtonAt() 489 490 \since BeOS R3 491*/ 492 493 494/*! 495 \fn BButton* BAlert::ButtonAt(int32 index) const 496 \brief Returns a pointer to the BButton at the specified \a index. 497 498 The \a index of the buttons begins at \c 0 and counts from left to right. 499 If a BButton does not exist for the specified \a index then \c NULL is 500 returned. 501 502 \param index The \a index of the desired button. 503 504 \return A pointer to the BButton at the specified \a index. 505 506 \since BeOS R3 507*/ 508 509 510/*! 511 \fn BTextView* BAlert::TextView() const 512 \brief Returns the Alert's TextView. 513 514 \since BeOS R3 515*/ 516 517 518/*! 519 \fn BHandler* BAlert::ResolveSpecifier(BMessage* message, int32 index, 520 BMessage* specifier, int32 what, const char* property) 521 \copydoc BHandler::ResolveSpecifier() 522*/ 523 524 525/*! 526 \fn status_t BAlert::GetSupportedSuites(BMessage* data) 527 \copydoc BWindow::GetSupportedSuites() 528*/ 529 530 531/*! 532 \fn void BAlert::DispatchMessage(BMessage* msg, BHandler* handler) 533 \brief Sends out a message. 534 535 \copydetails BWindow::DispatchMessage() 536*/ 537 538 539/*! 540 \fn void BAlert::Quit() 541 \brief Quits the window closing it. 542 543 \copydetails BWindow::Quit() 544*/ 545 546 547/*! 548 \fn bool BAlert::QuitRequested() 549 \brief Hook method that gets called with the window is closed. 550 551 \copydetails BWindow::QuitRequested() 552*/ 553 554 555/*! 556 \fn BPoint BAlert::AlertPosition(float width, float height) 557 \brief Resizes the Alert window to the width and height specified and 558 return the Point of the top-left corner of the alert window. 559 560 \param width The desired \a width of the alert window. 561 \param height The desired \a height of the alert window. 562 563 \returns The BPoint of the top-left corner of the Alert window. 564 565 \since BeOS R3 566*/ 567 568 569/*! 570 \fn status_t BAlert::Perform(perform_code code, void* _data) 571 \brief Perform some action. (Internal Method) 572 573 \param code The perform code. 574 \param _data A pointer to store some data. 575 576 \returns A status code. 577 578 \sa BLooper::Perform() 579 580 \since Haiku R1 581*/ 582
