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