Public Member Functions | List of all members
BApplication Class Reference

A container object for an application. More...

Inherits BLooper.

Inherited by BServer.

Public Member Functions

 BApplication (const char *signature)
 Initialize a BApplication with the passed in signature. More...
 
 BApplication (const char *signature, status_t *error)
 Initialize a BApplication with the passed in signature and a pointer to an error message. More...
 
virtual ~BApplication ()
 Destructor Method. More...
 
status_t InitCheck () const
 Returns the status of the constructor. More...
 
virtual status_t Perform (perform_code d, void *arg)
 Internal method. More...
 
Message Loop Control
virtual thread_id Run ()
 Starts the message loop in the thread that it is called from, and doesn't return until the message loop stops. More...
 
virtual void Quit ()
 Tells the thread to finish processing the message queue, disallowing any new messages. More...
 
Hook Methods
virtual bool QuitRequested ()
 Hook method that gets invoked when the BApplication receives a B_QUIT_REQUESTED message. More...
 
virtual void ReadyToRun ()
 Hook method that's invoked when the BApplication receives a B_READY_TO_RUN message. More...
 
virtual void ArgvReceived (int32 argc, char **argv)
 Hook method that gets invoked when the application receives a B_ARGV_RECEIVED message. More...
 
virtual void AppActivated (bool active)
 Hook method that gets invoked when the application receives B_APP_ACTIVATED message. More...
 
virtual void RefsReceived (BMessage *message)
 Hook method that gets invoked when the application receives a B_REFS_RECEIVED message. More...
 
virtual void AboutRequested ()
 Hook method that gets invoked when the BApplication receives a B_ABOUT_REQUESTED message. More...
 
Pulse
virtual void Pulse ()
 Hook method that gets invoked when the BApplication receives a B_PULSE message. More...
 
void SetPulseRate (bigtime_t rate)
 Sets the interval that the B_PULSE messages are sent. More...
 
Message Mechanics
virtual void MessageReceived (BMessage *message)
 Handle message that has been received by the associated looper. More...
 
virtual void DispatchMessage (BMessage *message, BHandler *handler)
 Dispatch a message to a handler. Override if there are messages that you want to catch before they are sent to the handlers. More...
 
Scripting
virtual BHandlerResolveSpecifier (BMessage *message, int32 index, BMessage *specifier, int32 form, const char *property)
 Determine the proper handler for a scripting message. More...
 
virtual status_t GetSupportedSuites (BMessage *data)
 Reports the suites of messages and specifiers that derived classes understand. More...
 
Cursor
void ShowCursor ()
 Restores the cursor. More...
 
void HideCursor ()
 Hides the cursor from the screen. More...
 
void ObscureCursor ()
 Hides the cursor until the mouse is moved. More...
 
bool IsCursorHidden () const
 Returns whether or not the cursor is hidden. More...
 
void SetCursor (const void *cursor)
 Sets the cursor to be used when the application is active. More...
 
void SetCursor (const BCursor *cursor, bool sync=true)
 Sets the cursor to be used when the application is active with sync immediately option. More...
 
Info
int32 CountWindows () const
 Returns the number of windows created by the application. More...
 
BWindowWindowAt (int32 index) const
 Returns the BWindow object at the specified index in the application's window list. More...
 
int32 CountLoopers () const
 Returns the number of BLoopers created by the application. More...
 
BLooperLooperAt (int32 index) const
 Returns the BLooper object at the specified index in the application's looper list. More...
 
- Public Member Functions inherited from BLooper
 BLooper (const char *name=NULL, int32 priority=B_NORMAL_PRIORITY, int32 portCapacity=B_LOOPER_PORT_DEFAULT_CAPACITY)
 Construct a new BLooper with a priority and an capacity. More...
 
virtual ~BLooper ()
 Destruct the looper. More...
 
status_t PostMessage (uint32 command)
 Post a message with the command as what identifier to this looper. More...
 
status_t PostMessage (BMessage *message)
 Post a message to this looper. More...
 
status_t PostMessage (uint32 command, BHandler *handler, BHandler *replyTo=NULL)
 Send a message with the command as what identifier to the handler associated with this looper, and (optionally) request a reply. More...
 
status_t PostMessage (BMessage *message, BHandler *handler, BHandler *replyTo=NULL)
 Send a message to the handler associated with this looper, and (optionally) request a reply. More...
 
BMessageCurrentMessage () const
 Retrieve the current message. More...
 
BMessageDetachCurrentMessage ()
 Get ownership of the message currently being processed. More...
 
BMessageQueueMessageQueue () const
 Get a pointer to the internal message queue of this looper. More...
 
bool IsMessageWaiting () const
 Check if there is a message waiting. More...
 
void AddHandler (BHandler *handler)
 Associate a handler to this looper. More...
 
bool RemoveHandler (BHandler *handler)
 Disassociate a handler from this looper. More...
 
int32 CountHandlers () const
 Get the number of handlers associated with this looper. More...
 
BHandlerHandlerAt (int32 index) const
 Get the handler at an index of the list of associated handlers. More...
 
int32 IndexOf (BHandler *handler) const
 Get the index of the handler that is in the associated handler list. More...
 
BHandlerPreferredHandler () const
 Get the preferred handler. More...
 
void SetPreferredHandler (BHandler *handler)
 Set a preferred handler. More...
 
thread_id LockingThread () const
 Return the thread id of the thread that currently holds the lock. More...
 
int32 CountLocks () const
 Return the number of recursive locks that are currently being held on this looper. More...
 
int32 CountLockRequests () const
 Return the number of pending locks. More...
 
sem_id Sem () const
 Return the id of the semaphore that is used to lock this looper. More...
 
virtual void AddCommonFilter (BMessageFilter *filter)
 Add a common filter to the list of filters that are applied to all incoming messages. More...
 
virtual bool RemoveCommonFilter (BMessageFilter *filter)
 Remove a filter from the common message filter list. More...
 
virtual void SetCommonFilterList (BList *filters)
 Set a new list of filters that need to be applied to all incoming messages. More...
 
BListCommonFilterList () const
 Return a list of filters applied to all incoming messages. More...
 
 BLooper (BMessage *data)
 Construct a looper from an archived message. More...
 
bool Lock ()
 Lock the looper. More...
 
void Unlock ()
 Unlock a locked looper. More...
 
bool IsLocked () const
 Check if a looper is locked. More...
 
status_t LockWithTimeout (bigtime_t timeout)
 Lock a looper with a timeout. More...
 
thread_id Thread () const
 Return the thread id of the internal message looper thread. More...
 
team_id Team () const
 Return the team id in which this looper exists. More...
 
- Public Member Functions inherited from BHandler
 BHandler (const char *name=NULL)
 Construct a new handler with a name. More...
 
virtual ~BHandler ()
 Free the filters of this handler, as well as the list of observers. More...
 
 BHandler (BMessage *data)
 Construct a handler from an archived message. More...
 
BLooperLooper () const
 Return a pointer to the looper that this handler is associated with. More...
 
void SetName (const char *name)
 Set or change the name of this handler. More...
 
const char * Name () const
 Return the name of this handler. More...
 
virtual void SetNextHandler (BHandler *handler)
 Set the next handler in the chain that the message is passed on to if this handler cannot process it. More...
 
BHandlerNextHandler () const
 Return the next hander in the chain to which the message is passed on. More...
 
virtual void AddFilter (BMessageFilter *filter)
 Add filter as a prerequisite to this handler. More...
 
virtual bool RemoveFilter (BMessageFilter *filter)
 Remove filter from the filter list. More...
 
virtual void SetFilterList (BList *filters)
 Set the internal list of filters to filters. More...
 
BListFilterList ()
 Return a pointer to the list of filters. More...
 
bool LockLooper ()
 Lock the looper associated with this handler. More...
 
status_t LockLooperWithTimeout (bigtime_t timeout)
 Lock the looper associated with this handler, with a time out value. More...
 
void UnlockLooper ()
 Unlock the looper. More...
 
status_t StartWatching (BMessenger target, uint32 what)
 Subscribe this handler to watch a specific state change of a target. More...
 
status_t StartWatchingAll (BMessenger target)
 Subscribe this handler to watch a target for all events. More...
 
status_t StopWatching (BMessenger target, uint32 what)
 Unsubscribe this handler from watching a specific state. More...
 
status_t StopWatchingAll (BMessenger target)
 Unsubscribe this handler from watching all states. More...
 
status_t StartWatching (BHandler *observer, uint32 what)
 Subscribe an observer for a specific state change of this handler. More...
 
status_t StartWatchingAll (BHandler *observer)
 Subscribe an observer for a all state changes. More...
 
status_t StopWatching (BHandler *observer, uint32 what)
 Unsubscribe an observer from watching a specific state. More...
 
status_t StopWatchingAll (BHandler *observer)
 Unsubscribe an observer from watching all states. More...
 
virtual void SendNotices (uint32 what, const BMessage *notice=NULL)
 Emit a state change to the observers. More...
 
bool IsWatched () const
 Check if there are any observers watching this handler. More...
 
- Public Member Functions inherited from BArchivable
 BArchivable (BMessage *from)
 Constructor. Does important behind-the-scenes work in the unarchiving process. More...
 
 BArchivable ()
 Constructor. Does nothing. More...
 
virtual ~BArchivable ()
 Destructor. Does nothing. More...
 
virtual status_t AllArchived (BMessage *archive) const
 Method relating to the use of BArchiver. More...
 
virtual status_t AllUnarchived (const BMessage *archive)
 Method relating to the use of BUnarchiver. More...
 

Archiving

 BApplication (BMessage *data)
 Initialize a BApplication object from a message. More...
 
virtual status_t Archive (BMessage *data, bool deep=true) const
 Archive the BApplication object into a BMessage. More...
 
static BArchivableInstantiate (BMessage *data)
 Restores the BApplication object from a BMessage. More...
 

Status

bool IsLaunching () const
 Returns whether or not the application is in the process of launching. More...
 
status_t GetAppInfo (app_info *info) const
 Fills out the info parameter with information about the application. More...
 
static BResourcesAppResources ()
 Returns a BResources object for the application. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from BLooper
static BArchivableInstantiate (BMessage *data)
 Static method to instantiate a looper from an archived message. More...
 
static BLooperLooperForThread (thread_id thread)
 Static method to retrieve a BLooper for a specified thread. More...
 
- Static Public Member Functions inherited from BHandler
static BArchivableInstantiate (BMessage *data)
 Static method to instantiate a handler from an archived message. More...
 
- Static Public Member Functions inherited from BArchivable
static BArchivableInstantiate (BMessage *archive)
 Static member to restore objects from messages. More...
 
- Protected Member Functions inherited from BLooper
BMessageMessageFromPort (bigtime_t=B_INFINITE_TIMEOUT)
 Hook method to retrieve a message from the looper's port. More...
 

Detailed Description

A container object for an application.

A BApplication establishes a connection between the application and the Application Server.

The most common task performed by a BApplication object is to handle messages sent to it. The BApplication object also is used to get information about your application such as the number of windows it has, its signature, executable location, and launch flags.

The BApplication object is automatically assigned to the global be_app variable. The be_app variable allows you to refer to your BApplication object from anywhere in the code.

To use a BApplication you first construct the object and then begin its message loop by calling the Run() method. The Run() method continues until the application is told to quit. Once Run() returns you should then delete the BApplication object to free its memory usage.

Typically, you initialize the BApplication object in the programs main() function. A typical main() function looks something like this:

#include Application.h
main()
{
/* Vendor is your vendor name, application is your application name */
BApplication app("application/x-vnd.vendor-application");
app->Run();
delete app;
return 0;
}
Since
BeOS R3

Constructor & Destructor Documentation

◆ BApplication() [1/3]

BApplication::BApplication ( const char *  signature)

Initialize a BApplication with the passed in signature.

The new BApplication is, by default, not running yet. If you have everything set up properly call Run() to start the application.

You should call InitCheck() to check for constructor initialization errors.

Parameters
signatureThe signature of the application.
Since
BeOS R3

◆ BApplication() [2/3]

BApplication::BApplication ( const char *  signature,
status_t _error 
)

Initialize a BApplication with the passed in signature and a pointer to an error message.

Any error that occurs while constructing the BApplication will be set to the _error pointer. If _error points to a status_t error then you should not call Run().

Alternately, you can call InitCheck() to check for constructor initialization errors.

Parameters
signatureThe signature of the application.
_errorA pointer to a status_t set by the BApplication constructor.
Since
BeOS R5

◆ ~BApplication()

BApplication::~BApplication ( )
virtual

Destructor Method.

Since
BeOS R3

◆ BApplication() [3/3]

BApplication::BApplication ( BMessage data)

Initialize a BApplication object from a message.

The message must contain the signature of the application you wish to initialize in the "mime_sig" variable.

Parameters
dataThe message to initialize the BApplication from.
Since
BeOS R3

Member Function Documentation

◆ AboutRequested()

void BApplication::AboutRequested ( )
virtual

Hook method that gets invoked when the BApplication receives a B_ABOUT_REQUESTED message.

You should override this method to pop an alert to provide information about the application.

The default implementation pops a basic alert dialog.

Since
BeOS R3

◆ AppActivated()

void BApplication::AppActivated ( bool  active)
virtual

Hook method that gets invoked when the application receives B_APP_ACTIVATED message.

The message is sent whenever the application changes its active application status. The active flag set to is true when the application becomes active and is set to false when the application becomes inactive.

The application becomes activated in response to a user action such as clicking on or unhiding one of its windows. The application can have its active status set programmatically by calling either the BWindow::Activate() or BRoster::ActivateApp() methods.

This method is called after ReadyToRun() provided the application is displaying a window that can be set active.

Since
BeOS R3

◆ AppResources()

BResources * BApplication::AppResources ( )
static

Returns a BResources object for the application.

Since
BeOS R5

◆ Archive()

status_t BApplication::Archive ( BMessage data,
bool  deep = true 
) const
virtual

Archive the BApplication object into a BMessage.

See also
BArchivable::Archive()
Since
BeOS R3

Reimplemented from BLooper.

◆ ArgvReceived()

void BApplication::ArgvReceived ( int32  argc,
char **  argv 
)
virtual

Hook method that gets invoked when the application receives a B_ARGV_RECEIVED message.

If command line arguments are specified when the application is launched from the the shell, or if argv/argc values are passed to BRoster::Launch(), then this method is executed.

Warning
ArgvReceived() is not called if no command line arguments are specified, or if BRoster::Launch() was called without any argv/argc values.

The arguments passed to ArgvReceived() are the constructed in the same way as those passed to command line programs. The number of command line arguments is passed in argc and the arguments themselves are passed as an array of strings in argv. The first argv string is the name of the program and the rest of the strings are the command line arguments.

BRoster::Launch() adds the program name to the front of the argv array and increments the argc value.

The B_ARGV_RECEIVED message (if sent) is sent only once, just before the B_READY_TO_RUN message is sent. However, if you try to relaunch an application that is already running and the application is set to B_EXCLUSIVE_LAUNCH or B_SINGLE_LAUNCH then the application will generate a B_ARGV_RECEIVED message and send it to the already running instance. Thus in this case the B_ARGV_RECEIVED message can show up at any time.

Since
BeOS R3

◆ CountLoopers()

int32 BApplication::CountLoopers ( ) const

Returns the number of BLoopers created by the application.

Warning
This method may return B_ERROR.
Returns
The number of BLoopers in the application.
Since
BeOS R5

◆ CountWindows()

int32 BApplication::CountWindows ( ) const

Returns the number of windows created by the application.

Returns
the number of windows created by the application.
Since
BeOS R3

◆ DispatchMessage()

void BApplication::DispatchMessage ( BMessage message,
BHandler handler 
)
virtual

Dispatch a message to a handler. Override if there are messages that you want to catch before they are sent to the handlers.

This method is called by the message looping thread to dispatch a message to handler. If you implement the BLooper class and your looper receives messages that absolutely have to be processed by the looper instead of any of the handlers, override this method. For example, the default implementation catches B_QUIT_REQUESTED messages before they are sent to the handlers, so that the looper will quit at those messages.

You are discouraged from using this method to filter out any messages you do not want to process. For this, there is a more generic method using the BMessageFilter class. If you want to skip messages with certain patterns, have a look at the AddCommonFilter() and SetCommonFilterList() methods.

If you do override this method, please remember to call the DispatchMessage() method of the parent class.

Since
BeOS R3

Reimplemented from BLooper.

◆ GetAppInfo()

status_t BApplication::GetAppInfo ( app_info info) const

Fills out the info parameter with information about the application.

This is equivalent to be_roster->GetRunningAppInfo(be_app->Team(), info);

Returns
B_NO_INIT on an error or B_OK if all goes well.
See also
BRoster::GetAppInfo()
Since
BeOS R3

◆ GetSupportedSuites()

status_t BApplication::GetSupportedSuites ( BMessage data)
virtual

Reports the suites of messages and specifiers that derived classes understand.

Since
BeOS R3

Reimplemented from BLooper.

◆ HideCursor()

void BApplication::HideCursor ( )

Hides the cursor from the screen.

Since
BeOS R3

◆ InitCheck()

status_t BApplication::InitCheck ( ) const

Returns the status of the constructor.

Returns
If initialization succeeded returns B_OK, otherwise returns an error status.
Since
BeOS R5

◆ Instantiate()

BArchivable * BApplication::Instantiate ( BMessage data)
static

Restores the BApplication object from a BMessage.

See also
BArchivable::Instantiate()
Since
BeOS R3

◆ IsCursorHidden()

bool BApplication::IsCursorHidden ( ) const

Returns whether or not the cursor is hidden.

Returns
true if the cursor is hidden, false if not.
Since
BeOS R3

◆ IsLaunching()

bool BApplication::IsLaunching ( ) const

Returns whether or not the application is in the process of launching.

Returns
true if the application is launching, false if the application is already running.
Since
BeOS R3

◆ LooperAt()

BLooper * BApplication::LooperAt ( int32  index) const

Returns the BLooper object at the specified index in the application's looper list.

If index is out of range, this function returns NULL.

Returns
The BLooper object at the specified index or NULL if the index is out of range.
Since
BeOS R5

◆ MessageReceived()

void BApplication::MessageReceived ( BMessage message)
virtual

Handle message that has been received by the associated looper.

This method is reimplemented by subclasses. If the messages that have been received by a looper pass through the filters, then they end up in the MessageReceived() methods.

The example below shows a very common way to handle message. Usually, this involves parsing the BMessage::what constant and then perform an action based on that.

void
ShowImageApp::MessageReceived(BMessage *message)
{
switch (message->what) {
case MSG_FILE_OPEN:
fOpenPanel->Show();
break;
case B_CANCEL:
// File open panel was closed,
// start checking count of open windows.
StartPulse();
break;
default:
// We do not handle this message, pass it on to the base class.
break;
}
}

If your handler cannot process this message, you should pass it on to the base class. Eventually, it will reach the base implementation, which will reply with B_MESSAGE_NOT_UNDERSTOOD.

Attention
If you want to keep or manipulate the message, have a look at BLooper::DetachCurrentMessage() to receive ownership of the message.
Parameters
messageThe message that needs to be handled.
Since
BeOS R3

Reimplemented from BLooper.

◆ ObscureCursor()

void BApplication::ObscureCursor ( )

Hides the cursor until the mouse is moved.

Since
BeOS R3

◆ Perform()

virtual status_t BApplication::Perform ( perform_code  d,
void *  arg 
)
virtual

Internal method.

Since
Haiku R1

Reimplemented from BLooper.

◆ Pulse()

void BApplication::Pulse ( )
virtual

Hook method that gets invoked when the BApplication receives a B_PULSE message.

An action is performed each time app_server calls the Pulse() method. The pulse rate is set by SetPulseRate(). You can implement Pulse() to do anything you want. The default version does nothing. The pulse granularity is no better than once per 100,000 microseconds.

See also
SetPulseRate()
Since
BeOS R3

◆ Quit()

void BApplication::Quit ( )
virtual

Tells the thread to finish processing the message queue, disallowing any new messages.

Quit() doesn't kill the looper thread. After Quit() returns, it doesn't wait for the message queue to empty. Run() will be then able to return.

Quit() doesn't delete the BApplication object after Run() is called. You should delete the BApplication object yourself one Run() returns. However Quit() does delete the object if it's called before the message loop starts i.e. before Run() is called.

Since
BeOS R3

Reimplemented from BLooper.

◆ QuitRequested()

bool BApplication::QuitRequested ( )
virtual

Hook method that gets invoked when the BApplication receives a B_QUIT_REQUESTED message.

BApplication sends a QuitRequested() message to each of its BWindow objects. If all of the BWindow s return true then the windows are each destroyed (through BWindow::Quit()) and QuitRequested() returns true. If any of the BWindow returns false, the BWindow s are not destroyed and QuitRequested() returns false.

Returns
true if the application quit or false if the application failed to quit.
Since
BeOS R3

Reimplemented from BLooper.

◆ ReadyToRun()

void BApplication::ReadyToRun ( )
virtual

Hook method that's invoked when the BApplication receives a B_READY_TO_RUN message.

The ReadyToRun() method is automatically called by the Run() method. It is sent after the initial B_REFS_RECEIVED and B_ARGV_RECEIVED messages (if any) have already been handled. ReadyToRun() is the only message that every running application is guaranteed to receive.

The default version of ReadyToRun() is empty. You should override the ReadyToRun() method to do whatever you want to do. If you haven't constructed any windows in your application yet then this would be a good place to do so.

Since
BeOS R3

◆ RefsReceived()

void BApplication::RefsReceived ( BMessage message)
virtual

Hook method that gets invoked when the application receives a B_REFS_RECEIVED message.

The message is sent in response to a user action such as a user drag-and-dropping a file on your app's icon or opening a file that the application is set to handle. You can use the IsLaunching() method to discern whether the message arrived when the application is launched or after the application has already been running.

The default implementation is empty. You can override this method to do something with the received refs. Typically you create BEntry or BFile objects from the passed in refs.

Parameters
messagecontains a single field named "be:refs" that contains one or more entry_ref (B_REF_TYPE) items, one for each file sent.
Since
BeOS R3

◆ ResolveSpecifier()

BHandler * BApplication::ResolveSpecifier ( BMessage message,
int32  index,
BMessage specifier,
int32  what,
const char *  property 
)
virtual

Determine the proper handler for a scripting message.

Parameters
messageThe scripting message to determine the handler.
indexThe index of the specifier.
specifierThe message which contains the specifier.
whatThe 'what' field of the specifier message.
propertyThe name of the target property.
Returns
A pointer to the proper BHandler for the given scripting message.
Since
BeOS R3

Reimplemented from BLooper.

◆ Run()

thread_id BApplication::Run ( )
virtual

Starts the message loop in the thread that it is called from, and doesn't return until the message loop stops.

Run() does not spawn a new thread.

Returns
The thread_id of the thread that the BApplication is called from.
Since
BeOS R3

Reimplemented from BLooper.

◆ SetCursor() [1/2]

void BApplication::SetCursor ( const void *  cursor)

Sets the cursor to be used when the application is active.

You can pass one of the pre-defined cursor constants such as B_HAND_CURSOR or B_I_BEAM_CURSOR or you can create your own pass in your own cursor image. The cursor data format is described in the BCursor class.

Parameters
cursorThe cursor data to set the cursor to.
Since
BeOS R3

◆ SetCursor() [2/2]

void BApplication::SetCursor ( const BCursor cursor,
bool  sync = true 
)

Sets the cursor to be used when the application is active with sync immediately option.

The default BCursors to use are B_CURSOR_SYSTEM_DEFAULT for the hand cursor and B_CURSOR_I_BEAM for the I-beam cursor.

Parameters
cursorA BCursor object to set the cursor to.
syncsynchronize the cursor immediately.
Since
BeOS R5

◆ SetPulseRate()

void BApplication::SetPulseRate ( bigtime_t  rate)

Sets the interval that the B_PULSE messages are sent.

If the rate is set to 0 then the B_PULSE messages are not sent. The pulse rate can be no faster than once per 100,000 microseconds or so.

Parameters
rateThe rate at which B_PULSE messages are sent to the application.
Since
BeOS R3

◆ ShowCursor()

BApplication::ShowCursor ( )

Restores the cursor.

Since
BeOS R3

◆ WindowAt()

BWindow * BApplication::WindowAt ( int32  index) const

Returns the BWindow object at the specified index in the application's window list.

If index is out of range, this function returns NULL.

Warning
Locking the BApplication object doesn't lock the window list.
Parameters
indexThe index of the desired BWindow.
Returns
The BWindow object at the specified index or NULL if the index is out of range.
Since
BeOS R3