docs/user/app/Application.dox

   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
  67 main()
  68 {
  69         /* Vendor is your vendor name, application is your application name */
  70         BApplication app("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 //! @}