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