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