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