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