1/* 2 * Copyright 2011-2014 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/app/Application.h hrev47355 10 * src/kits/app/Application.cpp hrev47355 11 */ 12 13 14/*! 15 \file Application.h 16 \ingroup app 17 \ingroup libbe 18 \brief Provides the BApplication class. 19*/ 20 21 22/*! 23 \var be_app 24 \brief Global system app object. 25 26 \since BeOS R3 27*/ 28 29 30/*! 31 \var be_app_messenger 32 \brief Global system app messenger object. 33 34 \since BeOS R3 35*/ 36 37 38/*! 39 \class BApplication 40 \ingroup app 41 \ingroup libbe 42 \brief A container object for an application. 43 44 A BApplication establishes a connection between the application and the 45 Application Server. 46 47 The most common task performed by a BApplication object is to handle 48 messages sent to it. The BApplication object also is used 49 to get information about your application such as the number of windows 50 it has, its signature, executable location, and launch flags. 51 52 The BApplication object is automatically assigned to the global \c be_app 53 variable. The \c be_app variable allows you to refer to your BApplication 54 object from anywhere in the code. 55 56 To use a BApplication you first construct the object and then begin its 57 message loop by calling the Run() method. The Run() method 58 continues until the application is told to quit. Once Run() returns you 59 should then delete the BApplication object to free its memory usage. 60 61 Typically, you initialize the BApplication object in the programs main() 62 function. A typical main() function looks something like this: 63 64\code 65#include Application.h 66 67main() 68{ 69 /* Vendor is your vendor name, application is your application name */ 70 BApplication *app = new BApplication("application/x-vnd.vendor-application"); 71 app->Run(); 72 delete app; 73 74 return 0; 75} 76\endcode 77 78 \since BeOS R3 79*/ 80 81 82/*! 83 \fn BApplication::BApplication(const char* signature) 84 \brief Initialize a BApplication with the passed in \a signature. 85 86 The new BApplication is, by default, not running yet. If you have 87 everything set up properly call Run() to start the application. 88 89 You should call InitCheck() to check for constructor initialization 90 errors. 91 92 \param signature The \a signature of the application. 93 94 \since BeOS R3 95*/ 96 97 98/*! 99 \fn BApplication::BApplication(const char* signature, status_t* _error) 100 \brief Initialize a BApplication with the passed in \a signature and a 101 pointer to an error message. 102 103 Any error that occurs while constructing the BApplication will be 104 set to the \a _error pointer. If \a _error points to a \c status_t 105 error then you should not call Run(). 106 107 Alternately, you can call InitCheck() to check for constructor 108 initialization errors. 109 110 \param signature The \a signature of the application. 111 \param _error A pointer to a \c status_t set by the BApplication 112 constructor. 113 114 \since BeOS R5 115*/ 116 117/*! 118 \fn status_t BApplication::InitCheck() const 119 \brief Returns the status of the constructor. 120 121 \returns If initialization succeeded returns \c B_OK, otherwise returns an 122 error status. 123 124 \since BeOS R5 125*/ 126 127 128/*! 129 \name Archiving 130*/ 131 132 133//! @{ 134 135 136/*! 137 \fn BApplication::BApplication(BMessage* data) 138 \brief Initialize a BApplication object from a message. 139 140 The message must contain the signature of the application you wish to 141 initialize in the "mime_sig" variable. 142 143 \param data The message to initialize the BApplication from. 144 145 \since BeOS R3 146*/ 147 148 149/*! 150 \fn status_t BApplication::Archive(BMessage* data, bool deep) const 151 \brief Archive the BApplication object into a BMessage. 152 153 \sa BArchivable::Archive() 154 155 \since BeOS R3 156*/ 157 158 159/*! 160 \fn BArchivable* BApplication::Instantiate(BMessage* data) 161 \brief Restores the BApplication object from a BMessage. 162 163 \sa BArchivable::Instantiate() 164 165 \since BeOS R3 166*/ 167 168 169//! @} 170 171 172/*! 173 \fn BApplication::~BApplication() 174 \brief Destructor Method 175 176 \since BeOS R3 177*/ 178 179 180/*! 181 \name Message Loop Control 182*/ 183 184 185//! @{ 186 187 188/*! 189 \fn thread_id BApplication::Run() 190 \brief Starts the message loop in the thread that it is called from, 191 and doesn't return until the message loop stops. 192 193 Run() does not spawn a new thread. 194 195 \return The thread_id of the thread that the BApplication is called from. 196 197 \since BeOS R3 198*/ 199 200 201/*! 202 \fn void BApplication::Quit() 203 \brief Tells the thread to finish processing the message queue, disallowing 204 any new messages. 205 206 Quit() doesn't kill the looper thread. After Quit() returns, it doesn't wait 207 for the message queue to empty. Run() will be then able to return. 208 209 Quit() doesn't delete the BApplication object after Run() is called. You 210 should delete the BApplication object yourself one Run() returns. 211 However Quit() does delete the object if it's called before the message loop 212 starts i.e. before Run() is called. 213 214 \since BeOS R3 215*/ 216 217 218//! @} 219 220 221/*! 222 \name Hook Methods 223*/ 224 225 226//! @{ 227 228 229/*! 230 \fn bool BApplication::QuitRequested() 231 \brief Hook method that gets invoked when the BApplication receives a 232 \c B_QUIT_REQUESTED message. 233 234 BApplication sends a QuitRequested() message to each of its BWindow objects. 235 If all of the BWindow s return \c true then the windows are 236 each destroyed (through BWindow::Quit()) and QuitRequested() returns 237 \c true. If any of the BWindow returns \c false, the BWindow s 238 are not destroyed and QuitRequested() returns \c false. 239 240 \return \c true if the application quit or \c false if the 241 application failed to quit. 242 243 \since BeOS R3 244*/ 245 246 247/*! 248 \fn void BApplication::ReadyToRun() 249 \brief Hook method that's invoked when the BApplication receives a 250 \c B_READY_TO_RUN message. 251 252 The ReadyToRun() method is automatically called by the Run() method. It is 253 sent after the initial \c B_REFS_RECEIVED and \c B_ARGV_RECEIVED messages 254 (if any) have already been handled. ReadyToRun() is the only message that 255 every running application is guaranteed to receive. 256 257 The default version of ReadyToRun() is empty. You should override the 258 ReadyToRun() method to do whatever you want to do. If you haven't 259 constructed any windows in your application yet then this would be a good 260 place to do so. 261 262 \since BeOS R3 263*/ 264 265 266/*! 267 \fn void BApplication::ArgvReceived(int32 argc, char** argv) 268 \brief Hook method that gets invoked when the application receives a 269 \c B_ARGV_RECEIVED message. 270 271 If command line arguments are specified when the application is launched 272 from the the shell, or if \c argv/argc values are passed to 273 BRoster::Launch(), then this method is executed. 274 275 \warning ArgvReceived() is not called if no command line arguments are 276 specified, or if BRoster::Launch() was called without any \c argv/argc 277 values. 278 279 The arguments passed to ArgvReceived() are the constructed in the same way 280 as those passed to command line programs. The number of command line 281 arguments is passed in \a argc and the arguments themselves are passed as an 282 array of strings in \a argv. The first \a argv string is the name of the 283 program and the rest of the strings are the command line arguments. 284 285 BRoster::Launch() adds the program name to the front of the \a argv array 286 and increments the \a argc value. 287 288 The \c B_ARGV_RECEIVED message (if sent) is sent only once, just 289 before the \c B_READY_TO_RUN message is sent. However, if you try to 290 relaunch an application that is already running and the application is set 291 to \c B_EXCLUSIVE_LAUNCH or \c B_SINGLE_LAUNCH then the application will 292 generate a \c B_ARGV_RECEIVED message and send it to the already running 293 instance. Thus in this case the \c B_ARGV_RECEIVED message can show 294 up at any time. 295 296 \since BeOS R3 297*/ 298 299 300/*! 301 \fn void BApplication::AppActivated(bool active) 302 \brief Hook method that gets invoked when the application receives 303 \c B_APP_ACTIVATED message. 304 305 The message is sent whenever the application changes its active application 306 status. The active flag set to is \c true when the application becomes 307 active and is set to \c false when the application becomes inactive. 308 309 The application becomes activated in response to a user action such as 310 clicking on or unhiding one of its windows. The application can have its 311 active status set programmatically by calling either the BWindow::Activate() 312 or BRoster::ActivateApp() methods. 313 314 This method is called after ReadyToRun() provided the application is 315 displaying a window that can be set active. 316 317 \since BeOS R3 318*/ 319 320 321/*! 322 \fn void BApplication::RefsReceived(BMessage* message) 323 \brief Hook method that gets invoked when the application receives a 324 \c B_REFS_RECEIVED message. 325 326 The message is sent in response to a user action such as a user 327 drag-and-dropping a file on your app's icon or opening a file that the 328 application is set to handle. You can use the IsLaunching() method to 329 discern whether the message arrived when the application is launched or 330 after the application has already been running. 331 332 The default implementation is empty. You can override this method to do 333 something with the received refs. Typically you create BEntry or BFile 334 objects from the passed in refs. 335 336 \param message contains a single field named "be:refs" that contains one 337 or more entry_ref (\c B_REF_TYPE) items, one for each file sent. 338 339 \since BeOS R3 340*/ 341 342 343/*! 344 \fn void BApplication::AboutRequested() 345 \brief Hook method that gets invoked when the BApplication receives a 346 \c B_ABOUT_REQUESTED message. 347 348 You should override this method to pop an alert to provide information 349 about the application. 350 351 The default implementation pops a basic alert dialog. 352 353 \since BeOS R3 354*/ 355 356 357//! @} 358 359 360/*! 361 \name Cursor 362*/ 363 364 365//! @{ 366 367 368/*! 369 \fn BApplication::ShowCursor() 370 \brief Restores the cursor. 371 372 \since BeOS R3 373*/ 374 375 376/*! 377 \fn void BApplication::HideCursor() 378 \brief Hides the cursor from the screen. 379 380 \since BeOS R3 381*/ 382 383 384/*! 385 \fn void BApplication::ObscureCursor() 386 \brief Hides the cursor until the mouse is moved. 387 388 \since BeOS R3 389*/ 390 391 392/*! 393 \fn bool BApplication::IsCursorHidden() const 394 \brief Returns whether or not the cursor is hidden. 395 396 \returns \c true if the cursor is hidden, \c false if not. 397 398 \since BeOS R3 399*/ 400 401 402/*! 403 \fn void BApplication::SetCursor(const void* cursor) 404 \brief Sets the \a cursor to be used when the application is active. 405 406 You can pass one of the pre-defined cursor constants such as 407 \c B_HAND_CURSOR or \c B_I_BEAM_CURSOR or you can create your own pass 408 in your own cursor image. The cursor data format is described in the BCursor 409 class. 410 411 \param cursor The cursor data to set the cursor to. 412 413 \since BeOS R3 414*/ 415 416 417/*! 418 \fn void BApplication::SetCursor(const BCursor* cursor, bool sync) 419 \brief Sets the \a cursor to be used when the application is active 420 with \a sync immediately option. 421 422 The default BCursors to use are \c B_CURSOR_SYSTEM_DEFAULT for the hand 423 cursor and \c B_CURSOR_I_BEAM for the I-beam cursor. 424 425 \param cursor A BCursor object to set the \a cursor to. 426 \param sync synchronize the cursor immediately. 427 428 \since BeOS R5 429*/ 430 431 432//! @} 433 434 435/*! 436 \name Info 437*/ 438 439 440//! @{ 441 442 443/*! 444 \fn int32 BApplication::CountWindows() const 445 \brief Returns the number of windows created by the application. 446 447 \returns the number of windows created by the application. 448 449 \since BeOS R3 450*/ 451 452 453/*! 454 \fn BWindow* BApplication::WindowAt(int32 index) const 455 \brief Returns the BWindow object at the specified \a index in the 456 application's window list. 457 458 If \a index is out of range, this function returns \c NULL. 459 460 \warning Locking the BApplication object doesn't lock the window list. 461 462 \param index The \a index of the desired BWindow. 463 464 \returns The BWindow object at the specified \a index or \c NULL 465 if the \a index is out of range. 466 467 \since BeOS R3 468*/ 469 470 471/*! 472 \fn int32 BApplication::CountLoopers() const 473 \brief Returns the number of BLoopers created by the application. 474 475 \warning This method may return \c B_ERROR. 476 477 \returns The number of BLoopers in the application. 478 479 \since BeOS R5 480*/ 481 482 483/*! 484 \fn BLooper* BApplication::LooperAt(int32 index) const 485 \brief Returns the BLooper object at the specified index in the 486 application's looper list. 487 488 If index is out of range, this function returns \c NULL. 489 490 \returns The BLooper object at the specified \a index or \c NULL 491 if the \a index is out of range. 492 493 \since BeOS R5 494*/ 495 496 497//! @} 498 499 500/*! 501 \name Status 502*/ 503 504 505//! @{ 506 507 508/*! 509 \fn bool BApplication::IsLaunching() const 510 \brief Returns whether or not the application is in the process of 511 launching. 512 513 \returns \c true if the application is launching, \c false if the 514 application is already running. 515 516 \since BeOS R3 517*/ 518 519 520/*! 521 \fn status_t BApplication::GetAppInfo(app_info *info) const 522 \brief Fills out the \a info parameter with information about the 523 application. 524 525 This is equivalent to 526 be_roster->GetRunningAppInfo(be_app->Team(), info); 527 528 \returns \c B_NO_INIT on an error or \c B_OK if all goes well. 529 530 \sa BRoster::GetAppInfo() 531 532 \since BeOS R3 533*/ 534 535 536/*! 537 \fn BResources* BApplication::AppResources() 538 \brief Returns a BResources object for the application. 539 540 \since BeOS R5 541*/ 542 543 544//! @} 545 546 547/*! 548 \name Message Mechanics 549*/ 550 551 552//! @{ 553 554 555/*! 556 \fn void BApplication::MessageReceived(BMessage *message) 557 \copydoc BHandler::MessageReceived() 558*/ 559 560 561/*! 562 \fn void BApplication::DispatchMessage(BMessage *message, 563 BHandler *handler) 564 \copydoc BLooper::DispatchMessage() 565*/ 566 567 568//! @} 569 570 571/*! 572 \name Pulse 573*/ 574 575 576//! @{ 577 578 579/*! 580 \fn void BApplication::Pulse() 581 \brief Hook method that gets invoked when the BApplication receives a 582 \c B_PULSE message. 583 584 An action is performed each time app_server calls the Pulse() method. 585 The pulse rate is set by SetPulseRate(). You can implement Pulse() to do 586 anything you want. The default version does nothing. The pulse granularity 587 is no better than once per 100,000 microseconds. 588 589 \sa SetPulseRate() 590 591 \since BeOS R3 592*/ 593 594 595/*! 596 \fn void BApplication::SetPulseRate(bigtime_t rate) 597 \brief Sets the interval that the \c B_PULSE messages are sent. 598 599 If the \a rate is set to 0 then the \c B_PULSE messages are not sent. 600 The pulse rate can be no faster than once per 100,000 microseconds or so. 601 602 \param rate The rate at which \c B_PULSE messages are sent to the 603 application. 604 605 \since BeOS R3 606*/ 607 608 609//! @} 610 611 612/*! 613 \name Scripting 614*/ 615 616 617//! @{ 618 619 620/*! 621 \fn BHandler* BApplication::ResolveSpecifier(BMessage* message, 622 int32 index, BMessage *specifier, int32 what, const char *property) 623 \copydoc BHandler::ResolveSpecifier() 624*/ 625 626 627/*! 628 \fn status_t BApplication::GetSupportedSuites(BMessage* data) 629 \copydoc BHandler::GetSupportedSuites() 630*/ 631 632 633//! @} 634