1/* 2 * Copyright 2019-2020 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Niels Sascha Reedijk, niels.reedijk@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/app/Notification.h hrev51445 10 * src/kits/app/Notification.cpp hrev52287 11 */ 12 13 14 /*! 15 \file Notification.h 16 \ingroup app 17 \ingroup libbe 18 \brief Provides BNotification class and the notification_type enum. 19*/ 20 21 22///// notification_type enum ///// 23 24 25/*! 26 \enum notification_type 27 \brief Visual style of the notification. 28 29 \since Haiku R1 30*/ 31 32 33/*! 34 \var notification_type::B_INFORMATION_NOTIFICATION 35 \brief Information type 36 37 This will have the notification appear with a grey side bar. 38 39 \image html notification_information_type.png 40 41 \since Haiku R1 42*/ 43 44 45/*! 46 \var notification_type::B_IMPORTANT_NOTIFICATION 47 \brief Important type 48 49 This will have the notification appear with a blue side bar. 50 51 \image html notification_important_type.png 52 53 \since Haiku R1 54*/ 55 56 57/*! 58 \var notification_type::B_ERROR_NOTIFICATION 59 \brief Error type 60 61 This will have the notification appear with a red side bar. 62 63 \image html notification_error_type.png 64 65 \since Haiku R1 66*/ 67 68 69/*! 70 \var notification_type::B_PROGRESS_NOTIFICATION 71 \brief Progress type 72 73 This will have the notification appear with a progress bar. 74 75 \image html notification_progress_type.png 76 77 \since Haiku R1 78*/ 79 80 81///// BNotification class ///// 82 83 84/*! 85 \class BNotification 86 \ingroup app 87 \ingroup libbe 88 \brief Construct system-default notifications to be displayed to the user. 89 90 Haiku provides a notification system that allows you to display messages to 91 the user. There is quite some flexibility in how the message is presented. 92 You may use this class to build and send the notification. The properties 93 you can set are: 94 - The \link BNotification::BNotification() type of notification\endlink, 95 which can be an information message, a warning, an error, or a progress 96 message. 97 - The \link BNotification::SetGroup() group\endlink, which allows you to 98 organize notification display into different categories. 99 - A \link BNotification::SetTitle() title\endlink, which is a distinct 100 text element at the top of a notification view. 101 - The \link BNotification::SetContent() content\endlink, which is the text 102 message that is shown to the user. 103 - A \link BNotification::SetMessageID() message identifier\endlink that 104 allows you to modify the contents of a message that is being displayed, 105 which is particularly useful for progress notifications. 106 - For progress notifications, the 107 \link BNotification::SetProgress() percentage of completion\endlink can be 108 set. 109 - By default the notification uses the application's icon, but you may 110 set an \link BNotification::SetIcon() alternative icon\endlink. 111 - Finally there are a few ways you can configure the actions that happen 112 when a user clicks the notification. More on that below. 113 114 For example, with the following code, you may display a notification: 115 116 \code{.cpp} 117 BNotification notification(B_PROGRESS_NOTIFICATION); 118 notification.SetGroup("Group"); 119 notification.SetTitle("Title"); 120 notification.SetContent("This is the content"); 121 notification.SetMessageID("mainwindow_progress"); 122 notification.SetProgress(0.5); 123 notification.Send(); 124 \endcode 125 126 \image html notification_intro.png 127 128 Note that in the previous code example, we set a 129 \link BNotification::SetMessageID message identifier\endlink, which will 130 allow to update the notification when we have progressed. The use would be: 131 132 \code{.cpp} 133 // After sending the notification, you retain ownership so that you can update it 134 notification.SetProgress(0.7); 135 136 // In order to display the update, you send it again 137 notification.Send(); 138 \endcode 139 140 Furthermore, it is possible to support some form of follow-up action, when 141 the user clicks the notification. First of all, you need to choose whether 142 you want to \link BNotification::SetOnClickApp() open a specific 143 application\endlink, or whether you want to 144 \link BNotification::SetOnClickFile() open a specific file\endlink and have 145 the system determine which application fits that. Additionally, you may 146 specify \link BNotification::AddOnClickArg() command line arguments\endlink 147 or pass additional \link BNotification::AddOnClickRef() file 148 references\endlink for the receiving application to process. 149 150 Finally, a note about the \c notification_server and how it groups and 151 handles messages coming from your application. The system is aware of the 152 source of the notifications, and identifies your application by it's 153 signature. That means that the identification of your application is 154 consistent, even if it is restarted, or if you have multiple instances 155 running. This impacts the \link BNotification::SetGroup() grouping\endlink 156 functionality and the \link BNotification::SetMessageID() message 157 updating\endlink functionality. If you have an application that can have 158 multiple instances, you will need to make sure that you properly manage 159 your group names and identifiers if you want to keep things separate. 160 161 \since Haiku R1 162*/ 163 164 165/*! 166 \fn BNotification::BNotification(notification_type type) 167 \brief Construct an empty message, with the specified \a type. 168 169 The type influences the style of the notification view. See the 170 \ref notification_type enumerator for details. 171 172 \since Haiku R1 173*/ 174 175 176/*! 177 \fn BNotification::BNotification(BMessage* archive) 178 \brief Construct a notification from an archive. 179 180 \since Haiku R1 181*/ 182 183 184/*! 185 \fn virtual BNotification::~BNotification() 186 \brief Frees all resources associated with the object. 187 188 \since Haiku R1 189*/ 190 191 192/*! 193 \fn status_t BNotification::InitCheck() const 194 \brief Returns the status of the constructor. 195 196 \since Haiku R1 197*/ 198 199 200/*! 201 \fn static BArchivable* BNotification::Instantiate(BMessage* archive) 202 \brief Returns a new BNotification object from \a archive. 203 204 This class implements the archiving API, and as such, you can 205 build a new BNotification object from a previously created 206 BMessage archive. However, if the message doesn't contain an archived data 207 for a BNotification object, this method returns \c NULL. 208 209 \returns BNotification object from \a archive or \c NULL if it doesn't 210 contain a valid BNotification object. 211 212 \since Haiku R1 213*/ 214 215 216/*! 217 \fn virtual status_t BNotification::Archive(BMessage* archive, 218 bool deep = true) const 219 \brief Archives the BNotification in the \c archive. 220 221 \see BArchivable::Archive(), Instantiate() static function. 222 \returns \c B_OK: if everything went fine, or other errors that describe why 223 archiving has failed. 224 225 \since Haiku R1 226*/ 227 228 229/*! 230 \fn const char* BNotification::SourceSignature() const 231 \brief Returns signature of the application where the notification 232 originated. 233 234 When you build your own notifications, this will contain the signature of 235 the current application. If you receive notifications from other 236 applications, it will include theirs. 237 238 \returns Signature of the source application. 239 240 \since Haiku R1 241*/ 242 243 244/*! 245 \fn const char* BNotification::SourceName() const 246 \brief Returns the name of the application where the notification 247 originated. 248 249 When you build your own notifications, this will contain the name of 250 the current application. If you receive notifications from other 251 applications, it will include theirs. 252 253 \returns Name of the source application. 254 255 \since Haiku R1 256*/ 257 258 259/*! 260 \fn notification_type BNotification::Type() const 261 \brief Returns the type of the notification. 262 263 \returns A value of the \c notification_type enum that represents 264 notification type. 265 266 \since Haiku R1 267*/ 268 269 270/*! 271 \fn const char* BNotification::Group() const 272 \brief Returns the group of the notification. 273 274 \see BNotification::SetGroup() for more information about groups. 275 276 \returns The string of the notification's group. 277 278 \since Haiku R1 279*/ 280 281 282/*! 283 \fn void BNotification::SetGroup(const BString& group) 284 \brief Set a group for the notifcation. 285 286 The default behaviour of the \c notification_server is group the visible 287 notifications per running application, and then in order in which they have 288 been received. There may be situations where you want to override that 289 behavior and group related notifications. When you set a group name, the 290 \c notification_server will create a box with the \c group name as label, 291 and insert all related notifications in that box. 292 293 \image html notification_group.png 294 295 \since Haiku R1 296*/ 297 298 299/*! 300 \fn const char* BNotification::Title() const 301 \brief Returns the title of the notification. 302 303 \returns The title of the notification as a string. 304 305 \since Haiku R1 306*/ 307 308 309/*! 310 \fn void BNotification::SetTitle(const BString& title) 311 \brief Set a title for the notification. 312 313 \since Haiku R1 314*/ 315 316 317/*! 318 \fn const char* BNotification::Content() const 319 \brief Returns the message of the notification. 320 321 \returns The message of the notification as a string. 322 323 \since Haiku R1 324*/ 325 326 327/*! 328 \fn void BNotification::SetContent(const BString& content) 329 \brief Set a message for the notification. 330 331 \since Haiku R1 332*/ 333 334 335/*! 336 \fn const char* BNotification::MessageID() const 337 \brief Returns the identifier of the notification. 338 339 \see BNotification::SetMessageID() for the purpose of having an identifier. 340 341 \returns The identifier of the notification as a string. 342 343 \since Haiku R1 344*/ 345 346 347/*! 348 \fn void BNotification::SetMessageID(const BString& id) 349 \brief Sets notification's message identifier. 350 351 If you want to update the contents of an existing notification, you can 352 set a identifier for this message. When you send a new or updated message 353 with the same identifier, the \c notification_server will update the 354 existing message with the new content. 355 356 In order to effectively use this feature, you will have to make sure the 357 identifier is unique within the current application. 358 359 \since Haiku R1 360*/ 361 362 363/*! 364 \fn float BNotification::Progress() const 365 \brief Returns the progress for the notification. 366 367 \see BNotification::SetProgress() for more information about this value. 368 369 \returns A value between 0.0 and 1.0 if notification's type is 370 \c B_PROGRESS_NOTIFICATION, or otherwise -1. 371 372 \since Haiku R1 373*/ 374 375 376/*! 377 \fn void BNotification::SetProgress(float progress) 378 \brief Sets progress information. 379 380 When you are building a notification of the type \c B_PROGRESS_NOTIFICATION 381 the notification view will show a progress bar and a label that 382 expresses the progress in a percentage. Using this method you can set 383 what the bar and label express. 384 385 The valid range is between 0.0 and 1.0. If \c progress is lower than 0.0 386 (i.e. negative), the value will be set to 0.0. If it is higher than 1.0, 387 it will be set to 1.0. 388 389 \since Haiku R1 390*/ 391 392 393/*! 394 \fn const char* BNotification::OnClickApp() const 395 \brief Returns the signature of the application that will be called when 396 the notification is clicked. 397 398 \see More information about this property in BNotification::SetOnClickApp(). 399 400 \since Haiku R1 401*/ 402 403 404/*! 405 \fn void BNotification::SetOnClickApp(const BString& app) 406 \brief Set which application should be called when the notification is 407 clicked by the user. 408 409 The value \c app should be a valid application signature, for example 410 \c 'application/x-vnd.Haiku-StyledEdit'. 411 412 Using this property has precedence on when BNotification::SetOnClickFile() 413 is used. If you want interacting with the notification opening a specific 414 file, then you should use this method in combination with 415 BNotification::AddOnClickRef(). 416 417 \see Additional actions and parameters can be set through 418 BNotification::SetOnClickFile(), BNotification::AddOnClickRef() 419 and BNotification::AddOnClickArg(). 420 421 \since Haiku R1 422*/ 423 424 425/*! 426 \fn const entry_ref* BNotification::OnClickFile() const 427 \brief Returns the reference to the file that will be opened when the 428 notification is clicked. 429 430 \see More information about this property in BNotification::SetOnClickFile(). 431 432 \since Haiku R1 433*/ 434 435 436/*! 437 \fn status_t BNotification::SetOnClickFile(const entry_ref* file) 438 \brief Set which file should be opened when the notification is 439 clicked by the user. 440 441 The file will be opened by the default application for this file type. 442 443 You cannot use this action in combination with 444 BNotification::SetOnClickApp(). If you use this way of setting an action, 445 this action will be ignored. 446 447 \see Additional actions and parameters can be set through 448 BNotification::SetOnClickApp(), BNotification::AddOnClickRef() 449 and BNotification::AddOnClickArg(). 450 451 \since Haiku R1 452*/ 453 454 455/*! 456 \fn status_t BNotification::AddOnClickRef(const entry_ref* ref) 457 \brief Add a \c ref to the list of arguments passed when a user clicks the 458 notification. 459 460 This method allows you to construct a list of refs, that will be sent to 461 the application specified by BNotification::AddOnClickApp(), or the one 462 that is associated with BNotification::AddOnClickFile(). The refs will be 463 handled by the application's BApplication::RefsReceived() hook method. 464 465 \since Haiku R1 466*/ 467 468 469/*! 470 \fn int32 BNotification::CountOnClickRefs() const 471 \brief Returns the number of refs to be passed when the user clicks on 472 the notification. 473 474 \see BNotification::AddOnClickRef() 475 476 \since Haiku R1 477*/ 478 479 480/*! 481 \fn const entry_ref* BNotification::OnClickRefAt(int32 index) const 482 \brief Returns the ref that is stored at \c index. 483 484 \see BNotification::AddOnClickRef() 485 486 \since Haiku R1 487*/ 488 489 490/*! 491 \fn status_t BNotification::AddOnClickArg(const BString& arg) 492 \brief Add to a list of arguments that are passed to an application when 493 the user clicks on the notification. 494 495 This method allows you to construct a list of arguments, that will be sent 496 to the application specified by BNotification::AddOnClickApp(), or the one 497 that is associated with BNotification::AddOnClickFile(). The args will be 498 handled by the application's BApplication::ArgvReceived() hook method. 499 500 \since Haiku R1 501*/ 502 503 504/*! 505 \fn int32 BNotification::CountOnClickArgs() const 506 \brief Returns the number of args to be passed when the user clicks on 507 the notification. 508 509 \see BNotification::AddOnClickArg() 510 511 \since Haiku R1 512*/ 513 514 515/*! 516 \fn const char* BNotification::OnClickArgAt(int32 index) const 517 \brief Returns the arg that is stored at \c index. 518 519 \see BNotification::AddOnClickArg() 520 \since Haiku R1 521*/ 522 523 524/*! 525 \fn const BBitmap* BNotification::Icon() const 526 \brief Returns the icon for the notification. 527 528 \see BNotification::SetIcon() for more information on this property. 529 530 \return Returns a borrowed unchangeable reference to the icon. 531 532 \since Haiku R1 533*/ 534 535 536/*! 537 \fn status_t BNotification::SetIcon(const BBitmap* icon) 538 \brief Set the icon of the notification. 539 540 Set the icon for the notification. By default, the application icon is 541 used. This method makes a copy of the \a icon. 542 543 \param icon The icon that should be displayed with the notification. 544 \returns \c B_OK if everything went fine, \c B_NO_MEMORY when the \a icon 545 could not be copied, or another error if something else went 546 wrong. 547 548 \since Haiku R1 549*/ 550 551 552/*! 553 \fn status_t BNotification::Send(bigtime_t timeout = -1) 554 \brief Send the notification to the notification_server. 555 556 The notification is delivered asynchronously to the notification_server, 557 which will display it according to its settings and filters. 558 559 After sending, you retain ownership of the notification. The advantage is 560 that you can re-use the notification at a later moment, or use the object to 561 update the notification. See BNotification::SetMessageID() about updating 562 displayed notifications. If you allocate the notification on the heap, be 563 sure to free the memory. 564 565 \param timeout The \a timeout in microsecond that the notification should 566 be displayed. If you want to use the default timing, use the default 567 argument or pass \c -1. 568 \returns \c B_OK if everything went fine, \c B_BAD_PORT_ID if there was a 569 problem connecting to the \c notification_server, or any other 570 errors if something went wrong transmitting the notification. 571 572 \since Haiku R1 573*/ 574
