A container object for an application. More...

Inheritance diagram for BApplication:

Public Member Functions
	BApplication (const char *signature)
	Initialize a BApplication with the passed in signature.
	BApplication (const char signature, status_t error)
	Initialize a BApplication with the passed in signature and a pointer to an error message.
virtual	~BApplication ()
	Destructor Method.
virtual status_t	AllArchived (BMessage *archive) const
	Method relating to the use of `BArchiver`.
virtual status_t	AllUnarchived (const BMessage *archive)
	Method relating to the use of `BUnarchiver`.
status_t	InitCheck () const
	Returns the status of the constructor.
virtual status_t	Perform (perform_code d, void *arg)
	Internal method.
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. Run() does not spawn a new thread.
virtual void	Quit ()
	Tells the thread to finish processing the message queue, disallowing any new messages.
Hook Methods
virtual bool	QuitRequested ()
	Hook method that gets invoked when the BApplication receives a `B_QUIT_REQUESTED` message.
virtual void	ReadyToRun ()
	Hook method that's invoked when the BApplication receives a `B_READY_TO_RUN` message.
virtual void	ArgvReceived (int32 argc, char **argv)
	Hook method that gets invoked when the application receives a `B_ARGV_RECEIVED` message.
virtual void	AppActivated (bool active)
	Hook method that gets invoked when the application receives `B_APP_ACTIVATED` message.
virtual void	RefsReceived (BMessage *message)
	Hook method that gets invoked when the application receives a `B_REFS_RECEIVED` message.
virtual void	AboutRequested ()
	Hook method that gets invoked when the BApplication receives a `B_ABOUT_REQUESTED` message.
Pulse
virtual void	Pulse ()
	Hook method that gets invoked when the BApplication receives a `B_PULSE` message.
void	SetPulseRate (bigtime_t rate)
	Sets the interval that the `B_PULSE` messages are sent.
Message Mechanics
virtual void	MessageReceived (BMessage *message)
virtual void	DispatchMessage (BMessage message, BHandler handler)
Scripting
virtual BHandler *	ResolveSpecifier (BMessage message, int32 index, BMessage specifier, int32 form, const char *property)
virtual status_t	GetSupportedSuites (BMessage *data)
Cursor
void	ShowCursor ()
	Restores the cursor.
void	HideCursor ()
	Hides the cursor from the screen.
void	ObscureCursor ()
	Hides the cursor until the mouse is moved.
bool	IsCursorHidden () const
	Returns whether or not the cursor is hidden.
void	SetCursor (const void *cursor)
	Sets the cursor to be used when the application is active.
void	SetCursor (const BCursor *cursor, bool sync=true)
	Sets the cursor to be used when the application is active with sync immediately option.
Info
int32	CountWindows () const
	Returns the number of windows created by the application.
BWindow *	WindowAt (int32 index) const
	Returns the BWindow object at the specified index in the application's window list.
int32	CountLoopers () const
	Returns the number of BLoopers created by the application.
BLooper *	LooperAt (int32 index) const
	Returns the BLooper object at the specified index in the application's looper list.
Message Mechanics
status_t	PostMessage (uint32 command)
	Post a message with the command as `what` identifier to this looper.
status_t	PostMessage (BMessage *message)
	Post a message to this looper.
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.
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.
Message Processing
BMessage *	CurrentMessage () const
	Retrieve the current message.
BMessage *	DetachCurrentMessage ()
	Get ownership of the message currently being processed.
BMessageQueue *	MessageQueue () const
	Get a pointer to the internal message queue of this looper.
bool	IsMessageWaiting () const
	Check if there is a message waiting.
Handler Management
void	AddHandler (BHandler *handler)
	Associate a handler to this looper.
bool	RemoveHandler (BHandler *handler)
	Disassociate a handler from this looper.
int32	CountHandlers () const
	Get the number of handlers associated with this looper.
BHandler *	HandlerAt (int32 index) const
	Get the handler at an index of the list of associated handlers.
int32	IndexOf (BHandler *handler) const
	Get the index of the handler that is in the associated handler list.
BHandler *	PreferredHandler () const
	Get the preferred handler.
void	SetPreferredHandler (BHandler *handler)
	Set a preferred handler.
Loop debugging
These methods may aid you in debugging problems when they occur, but do not use these in actual production code. These methods are unrealiable because they are not thread-safe, and as such are only useful in specific debugging situations. Handle with care.
thread_id	LockingThread () const
	Return the thread id of the thread that currenty holds the lock.
int32	CountLocks () const
	Return the number of recursive locks that are currently being held on this looper.
int32	CountLockRequests () const
	Return the number of pending locks.
sem_id	Sem () const
	Return the id of the semaphore that is used to lock this looper.
Looper Message Filters
Note that filters added with these methods will be applied to all associated handlers. Have a look at the filtering methods of the BHandler class to see how filters can be applied to the inherited handler of this looper specifically.
virtual void	AddCommonFilter (BMessageFilter *filter)
	Add a common filter to the list of filters that are applied to all incoming messages.
virtual bool	RemoveCommonFilter (BMessageFilter *filter)
	Remove a filter from the common message filter list.
virtual void	SetCommonFilterList (BList *filters)
	Set a new list of filters that need to be applied to all incoming messages.
BList *	CommonFilterList () const
	Return a list of filters applied to all incoming messages.
Core Handler Functionality
BLooper *	Looper () const
	Return a pointer to the looper that this handler is associated with.
void	SetName (const char *name)
	Set or change the name of this handler.
const char *	Name () const
	Return the name of this handler.
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.
BHandler *	NextHandler () const
	Return the next hander in the chain to which the message is passed on.
Message Filtering
virtual void	AddFilter (BMessageFilter *filter)
	Add filter as a prerequisite to this handler.
virtual bool	RemoveFilter (BMessageFilter *filter)
	Remove filter from the filter list.
virtual void	SetFilterList (BList *filters)
	Set the internal list of filters to filters.
BList *	FilterList ()
	Return a pointer to the list of filters.
Locking
This class provides some utility functions to look the looper associated with this handler.
bool	LockLooper ()
	Lock the looper associated with this handler.
status_t	LockLooperWithTimeout (bigtime_t timeout)
	Lock the looper associated with this handler, with a time out value.
void	UnlockLooper ()
	Unlock the looper.
Observing
Handlers can function as state machines, which emit messages to observers when the state changes. Use the following methods to subscribe to these notifications. Note that there is a semantic difference between the two StartWatching() methods. The overloaded method that accepts a BHandler, expects as argument an observer that watches this handler. The method that accepts a BMessenger, expects a target that emits the state changes to this handler.
status_t	StartWatching (BMessenger target, uint32 what)
	Subscribe this handler to watch a specific state change of a target.
status_t	StartWatching (BHandler *observer, uint32 what)
	Subscribe an observer for a specific state change of this handler.
status_t	StartWatchingAll (BMessenger target)
	Subscribe this handler to watch a target for all events.
status_t	StartWatchingAll (BHandler *observer)
	Subscribe an observer for a all state changes.
status_t	StopWatching (BMessenger target, uint32 what)
	Unsubscribe this handler from watching a specific state.
status_t	StopWatching (BHandler *observer, uint32 what)
	Unsubscribe an observer from watching a specific state.
status_t	StopWatchingAll (BMessenger target)
	Unsubscribe this handler from watching all states.
status_t	StopWatchingAll (BHandler *observer)
	Unsubscribe an observer from watching all states.
Emitting State Changes
If your handler functions as a state machine, and it has observers (which subscribed using the StartWatching() method), you can emit these state changes.
virtual void	SendNotices (uint32 what, const BMessage *notice=NULL)
	Emit a state change to the observers.
bool	IsWatched () const
	Check if there are any observers watching this handler.
Protected Member Functions
BMessage *	MessageFromPort (bigtime_t=B_INFINITE_TIMEOUT)
	Hook method to retrieve a message from the looper's port.
Archiving
	BApplication (BMessage *data)
	Initialize a BApplication object from a message.
virtual status_t	Archive (BMessage *data, bool deep=true) const
	Archive the BApplication object into a BMessage.
static BArchivable *	Instantiate (BMessage *data)
	Restores the BApplication object from a BMessage.
Status
bool	IsLaunching () const
	Returns whether or not the application is in the process of launching.
status_t	GetAppInfo (app_info *info) const
	Fills out the info parameter with information about the application.
static BResources *	AppResources ()
	Returns a BResources object for the application.
Loop Control
bool	Lock ()
	Lock the looper.
void	Unlock ()
	Unlock a locked looper.
bool	IsLocked () const
	Check if a looper is locked.
status_t	LockWithTimeout (bigtime_t timeout)
	Lock a looper with a timeout.
thread_id	Thread () const
	Return the thread id of the internal message looper thread.
team_id	Team () const
	Return the team id in which this looper exists.
static BLooper *	LooperForThread (thread_id thread)
	Static method to retrieve a BLooper for a specified thread.

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;
}

Constructor & Destructor Documentation

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:

signature The signature of the application.

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:

signature	The signature of the application.
_error	A pointer to a `status_t` set by the BApplication constructor.

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:

data	The message to initialize the BApplication from.

Member Function Documentation

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.

void BLooper::AddCommonFilter ( BMessageFilter * filter ) [virtual, inherited]

Add a common filter to the list of filters that are applied to all incoming messages.

Filters can only be applied once, so they cannot be shared between loopers, a handler and a looper or between two handlers.

The filter is not copied; rather a pointer is stored. Keep the filter alive as long as it is used by a looper.

See also:: RemoveCommonFilter(), SetCommonFilterList(), CommonFilterList()

void BHandler::AddFilter ( BMessageFilter * filter ) [virtual, inherited]

Add filter as a prerequisite to this handler.

If the handler is associated with a looper, this looper needs to be locked in order for this operation to succeed.

Note that the filter is not copied, rather a pointer to the filter is stored. As such, you need to make sure that the filter object exists as long as it is added to this handler.

See also:: RemoveFilter(), SetFilterList()

void BLooper::AddHandler ( BHandler * handler ) [inherited]

Associate a handler to this looper.

The handler will be associated to this looper. By default, the handler in this looper will be chained to the supplied handler.

Parameters:

handler The handler to associate with this looper. If the handler is already associated to another looper, the operation will fail silently. Check beforehand if you cannot be sure that the handler is unassociated.

See also:: RemoveHandler()

status_t BArchivable::AllArchived ( BMessage * into ) const [virtual, inherited]

Method relating to the use of BArchiver.

This hook function is called once the first BArchiver that was created in an archiving session is either destroyed, or has its Finish() method called. Implementations of this method can be used, in conjunction with BArchiver::IsArchived(), to reference objects in your archive that you do not own, depending on whether or not those objects were archived by their owners. Implementations of this method should call the implementation of their parent class, the same as for the Archive() method.

Warning:: To guarantee that your AllArchived() method will be called during archival, you must create a BArchiver object in your Archive() implementation.; You should archive any objects you own in your Archive() method implementation, and NOT your AllArchived() method.

See also:: BArchiver BArchiver::Finish()

Reimplemented in BView, BLayout, BGridLayout, BLayoutItem, BTwoDimensionalLayout, BAbstractLayout, and BGroupLayout.

status_t BArchivable::AllUnarchived ( const BMessage * archive ) [virtual, inherited]

Method relating to the use of BUnarchiver.

This hook function is called triggered in the BUnarchiver::Finish() method. In this method, you can rebuild references to objects that may be direct children of your object, or may be children of other objects. Implementations of this method should call the implementation of their parent class, the same as for the Archive() method.

Warning:: To guarantee that your AllUnarchived() method will be called during unarchival, you must create a BUnarchiver object in your archive constructor.

See also:: BUnarchiver, BUnarchiver::Finish()

Reimplemented in BView, BLayout, BGridLayout, BLayoutItem, BTwoDimensionalLayout, BAbstractLayout, and BGroupLayout.

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.

status_t BApplication::Archive	(	BMessage *	data,
		bool	deep = `true`
	)		const `[virtual]`

Archive the BApplication object into a BMessage.

See also:: BArchivable::Archive()

Reimplemented from BLooper.

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.

BList * BLooper::CommonFilterList ( ) const [inherited]

Return a list of filters applied to all incoming messages.

Returns:: A pointer to the internal filter list, or NULL if such a list has not yet been created. Please note that you should use the internal list management functions to manipulate the internal filter list, in order to maintain internal consistency.

See also:: AddCommonFilter(), RemoveCommonFilter(), SetCommonFilterList()

int32 BLooper::CountHandlers ( ) const [inherited]

Get the number of handlers associated with this looper.

See also:: HandlerAt(), IndexOf()

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.

int32 BApplication::CountWindows ( ) const

Returns the number of windows created by the application.

Returns:: the number of windows created by the application.

BMessage * BLooper::CurrentMessage ( ) const [inherited]

Retrieve the current message.

Attention:: Only call this method from within the thread that processes the messages. It contains a pointer to the message that is currently being handled. Due to the multithreaded nature of the operating system, this method will not safely let you read the message that is being processed by this handler from outside the context of the processing. If you do want to use a message outside of the processing thread, have a look at DetachCurrentMessage() to safely retrieve a message.

Returns:: A pointer to the message that is currently being processed. Note that calling it from outside the thread that processes the message, could give you a NULL pointer or an invalid pointer.

BMessage * BLooper::DetachCurrentMessage ( ) [inherited]

Get ownership of the message currently being processed.

Retrieve the current message and gain ownership of it. This means that the message will not be deleted as soon as the looper is done processing it. You can then use it for different purposes.

Attention:: Only call this method from within the thread that processes the messages. Due to the multithreaded nature of the operating system, calling it from another thread is very likely to give you an invalid or a NULL pointer.

void BApplication::DispatchMessage	(	BMessage *	message,
		BHandler *	handler
	)		`[virtual]`

See also:: BLooper::DispatchMessage()

Reimplemented from BLooper.

BList * BHandler::FilterList ( ) [inherited]

Return a pointer to the list of filters.

Returns:: A pointer to the list of filters. Do not manipulate the list of filters directly, but use the methods provided by this class, in order to maintain internal consistency.

See also:: AddFilter(), RemoveFilter(), SetFilterList().

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()

status_t BApplication::GetSupportedSuites ( BMessage * data ) [virtual]

See also:: BHandler::GetSupportedSuites()

Reimplemented from BLooper.

BHandler * BLooper::HandlerAt ( int32 index ) const [inherited]

Get the handler at an index of the list of associated handlers.

Returns:: A pointer to the handler at that index, or NULL if the index is out of range.

See also:: CountHandlers(), IndexOf()

int32 BLooper::IndexOf ( BHandler * handler ) const [inherited]

Get the index of the handler that is in the associated handler list.

Returns:: If the handler is not in the list, this method will return -1. Else, you will get the index of the handler in the list.

status_t BApplication::InitCheck ( ) const

Returns the status of the constructor.

Returns:: If initialization succeeded returns B_OK, otherwise returns an error status.

BArchivable * BApplication::Instantiate ( BMessage * data ) [static]

Restores the BApplication object from a BMessage.

See also:: BArchivable::Instantiate()

Reimplemented from BLooper.

bool BApplication::IsCursorHidden ( ) const

Returns whether or not the cursor is hidden.

Returns:: true if the cursor is hidden, false if not.

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.

bool BLooper::IsLocked ( ) const [inherited]

Check if a looper is locked.

Return values:

true	The looper is locked.
false	The looper is not locked, or the looper has been deleted.

See also:: Lock(), Unlock(), LockWithTimeout()

bool BLooper::IsMessageWaiting ( ) const [inherited]

Check if there is a message waiting.

Return values:

true	There are still messages to be processed.
false	There is no message waiting.

bool BLooper::Lock ( ) [inherited]

Lock the looper.

For most operations involving the internal data of the looper, you need to hold the lock. Each looper implements a global lock, which you can use to perform operations on internal data in a thread-safe manner.

Do not forget to pair each Lock() request with an Unlock() request. Lock() requests can be stacked, which means that recursively locking a looper from a thread that actually holds the lock, will not cause a deadlock. See BLocker for more information on locking internals.

Return values:

true	The locking request succeeded.
false	The locking request could not be completed. There are a variety of reasons for this to happen, for example when the looper is destroyed.

See also:: Unlock(), LockWithTimeout(), IsLocked()

bool BHandler::LockLooper ( ) [inherited]

Lock the looper associated with this handler.

Return values:

true	The looper is locked.
false	There was an error acquiring the lock.

See also:: LockLooperWithTimeout(), UnlockLooper()

status_t BHandler::LockLooperWithTimeout ( bigtime_t timeout ) [inherited]

Lock the looper associated with this handler, with a time out value.

Parameters:

timeout The time to wait for acquiring the lock in microseconds. You may also use B_INFINITE_TIMEOUT, in which this method will wait as long as it takes to acquire the lock.

Return values:

B_OK	Locking succeeded.
B_BAD_VALUE	This handler is not associated with a looper (anymore).
B_TIMED_OUT	The time specified in timeout has passed without locking the looper.

See also:: LockLooper(), UnlockLooper()

status_t BLooper::LockWithTimeout ( bigtime_t timeout ) [inherited]

Lock a looper with a timeout.

This method locks the looper like Lock(), but if the locking request does not succeed within the provided timeout, the method will return.

Parameters:

timeout The maximum time to wait for the lock request to succeed.

Return values:

B_OK	The lock is acquired.
B_BAD_VALUE	The looper has been destroyed.
other errors	There was an error acquiring the lock.

See also:: Lock(), Unlock(), IsLocked()

BLooper * BHandler::Looper ( ) const [inherited]

Return a pointer to the looper that this handler is associated with.

Returns:: If the handler is not yet associated with a looper, it will return NULL.

See also:: BLooper::AddHandler(); LockLooper()

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.

BMessage * BLooper::MessageFromPort ( bigtime_t timeout = B_INFINITE_TIMEOUT ) [protected, inherited]

Hook method to retrieve a message from the looper's port.

The default implementation is called by the internal message looping thread and retrieves the next message from the port that belongs to this looper.

If you use a looper in a context where it might receive messages from other sources, you can override this method in order to insert these methods into the message processing. Note that any messages that are returned by this method will be deleted by this looper, so make sure you have ownership of the message. If you override this method, remember to call the base implementation every now and then, in order to retrieve the messages arriving at the default port.

BMessageQueue * BLooper::MessageQueue ( ) const [inherited]

Get a pointer to the internal message queue of this looper.

You can use this pointer to manipulate the message queue. Note that the message that is being processed is already detached from this queue.

Returns:: A pointer to the internal message queue.

void BApplication::MessageReceived ( BMessage * message ) [virtual]

See also:: BHandler::MessageReceived()

Reimplemented from BLooper.

const char * BHandler::Name ( ) const [inherited]

Return the name of this handler.

See also:: SetName()

BHandler * BHandler::NextHandler ( ) const [inherited]

Return the next hander in the chain to which the message is passed on.

See also:: SetNextHandler()

status_t BLooper::PostMessage ( uint32 command ) [inherited]

Post a message with the command as what identifier to this looper.

Posting a message puts it in the message queue. The message passes through the default handler chain.

Parameters:

command The what identifier of the message that needs to be sent.

Return values:

B_OK	The operation succeeded, and the message is sent to the port.
B_ERROR	There was a general operation error.
B_BAD_VALUE	This looper is not yet running and therefore cannot receive messages.

See also:: PostMessage(BMessage *) if you want to send a message with data members.; PostMessage(uint32, BHandler *, BHandler *) if you want to send a message to a specific handler, and request a reply.; PostMessage(BMessage *, BHandler *, BHandler *) for the same thing, but with a complete message.

status_t BLooper::PostMessage ( BMessage * message ) [inherited]

Post a message to this looper.

Posting a message puts it in the message queue. The message passes through the default handler chain.

The message is copied, and as such, you should make sure you will not leak it. The best way to send messages is like this:

    BMessage message;
    message.what = B_DO_SOMETHING;
    message.AddString("some_data", "This is data")
    
    aLooper->PostMessage(&message);

Parameters:

message The message you would like to pass to this method.

Return values:

B_OK	The operation succeeded, and the message is sent to the port.
B_ERROR	There was a general operation error.
B_BAD_VALUE	This looper is not yet running and therefore cannot receive messages.

See also:: PostMessage(uint32) if you want to send a message without data members.; PostMessage(uint32, BHandler *, BHandler *) if you want to send a message to a specific handler, and request a reply.; PostMessage(BMessage *, BHandler *, BHandler *) for the same thing, but with a complete message.

status_t BLooper::PostMessage	(	uint32	command,
		BHandler *	handler,
		BHandler *	replyTo = `NULL`
	)		`[inherited]`

Send a message with the command as what identifier to the handler associated with this looper, and (optionally) request a reply.

The target handler should be associated with this looper. This method bypasses the default message queue.

Parameters:

command	The value you want as the message's `what` identifier.
handler	The handler you would like to pass this message to.
replyTo	If you would like to request a reply, pass the handler to which this reply should be directed to. If you pass `NULL`, you will not receive a reply.

Return values:

B_OK	The operation succeeded, and the message is sent to the port.
B_ERROR	There was a general operation error.
B_BAD_VALUE	This looper is not yet running and therefore cannot receive messages.
B_MISMATCHED_VALUES	The handler is not associated with this looper.

See also:: PostMessage(uint32) if you want to send a message without data members.; PostMessage(BMessage *) if you want to send a message with data members.; PostMessage(BMessage *, BHandler *, BHandler *) if you want to send a message to a specific handler, and request a reply.

status_t BLooper::PostMessage	(	BMessage *	message,
		BHandler *	handler,
		BHandler *	replyTo = `NULL`
	)		`[inherited]`

Send a message to the handler associated with this looper, and (optionally) request a reply.

The target handler should be associated with this looper. This method bypasses the default message queue.

The message is copied, and as such, you should make sure you will not leak it. The best way to send messages is like this:

    BMessage message;
    message.what = B_DO_SOMETHING;
    message.AddString("some_data", "This is data")

    aLooper->PostMessage(&message, aHandler);

Parameters:

message	The message you want to pass.
handler	The handler you would like to pass this message to.
replyTo	If you would like to request a reply, pass the handler to which this reply should be directed to. If you pass `NULL`, you will not receive a reply.

Return values:

B_OK	The operation succeeded, and the message is sent to the port.
B_ERROR	There was a general operation error.
B_BAD_VALUE	This looper is not yet running and therefore cannot receive messages.
B_MISMATCHED_VALUES	The handler is not associated with this looper.

See also:: PostMessage(uint32) if you want to send a message without data members.; PostMessage(BMessage *) if you want to send a message with data members.; PostMessage(uint32, BHandler *, BHandler *) if you want to send a message without data to a specific handler, and request a reply.

BHandler * BLooper::PreferredHandler ( ) const [inherited]

Get the preferred handler.

Returns:: A pointer to the preferred handler, or NULL if none is set.

See also:: SetPreferredHandler()

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()

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.

Reimplemented from BLooper.

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.

Return values:

true	The application quit.
false	The application failed to quit.

Reimplemented from BLooper.

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.

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:

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

bool BLooper::RemoveCommonFilter ( BMessageFilter * filter ) [virtual, inherited]

Remove a filter from the common message filter list.

Note that this will not free the memory used by the filter, so you should dispose of it yourself.

See also:: AddCommonFilter(), SetCommonFilterList(), CommonFilterList()

bool BHandler::RemoveFilter ( BMessageFilter * filter ) [virtual, inherited]

Remove filter from the filter list.

If the handler is associated with a looper, this looper needs to be locked in order for this operation to succeed.

Note that the filter is not deleted, merely removed from the list. You need to take care of the memory yourself.

Return values:

true	The filter was in the filter list and is removed.
false	The filter was not found in the filter list.

See also:: AddFilter(), FilterList()

bool BLooper::RemoveHandler ( BHandler * handler ) [inherited]

Disassociate a handler from this looper.

If the handler is disassociated, it can be reassociated to another looper.

Return values:

true	The handler has been removed from this looper.
false	The handler was invalid. or the handler was not associated to this looper.

See also:: AddHandler()

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

See also:: BHandler::ResolveSpecifier()

Reimplemented from BLooper.

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.

Reimplemented from BLooper.

void BHandler::SendNotices	(	uint32	what,
		const BMessage *	msg = `NULL`
	)		`[virtual, inherited]`

Emit a state change to the observers.

The actual state (specified by what) will not be transmitted. This is merely for internal bookkeeping. It is not entirely unimaginable that you still want to inform the observers of what actually took place. You can use the msg to transmit this, and any other data you want. Note that the message will be copied and slightly altered: the what member of the message will be B_OBSERVER_NOTICE_CHANGE, and the what constant you specified will be stored in the B_OBSERVE_ORIGINAL_WHAT label.

Parameters:

what	The identifier of the state.
msg	Any data associated with the state change. You retain ownership of this data, so make sure you dispose it when you are done.

void BLooper::SetCommonFilterList ( BList * filters ) [virtual, inherited]

Set a new list of filters that need to be applied to all incoming messages.

You are responsible for validating that all the items in the list of filters are actual filters. The old list is discarded; all the filters are destroyed.

Note that filters can only be applied to one looper or handler. If any of the filters is already associated with another one, this call will fail.

See also:: AddCommonFilter(), RemoveCommonFilter(), CommonFilterList()

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:

cursor The cursor data to set the cursor to.

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:

cursor	A BCursor object to set the cursor to.
sync	synchronize the cursor immediately.

void BHandler::SetFilterList ( BList * filters ) [virtual, inherited]

Set the internal list of filters to filters.

If the handler is associated with a looper, this looper needs to be locked in order for this operation to succeed.

The internal list will be replaced with the new list of filters. All the existing filters will be deleted.

See also:: AddFilter(), FilterList()

void BHandler::SetName ( const char * name ) [inherited]

Set or change the name of this handler.

See also:: Name()

void BHandler::SetNextHandler ( BHandler * handler ) [virtual, inherited]

Set the next handler in the chain that the message is passed on to if this handler cannot process it.

This method has three requirements:

This handler should belong to a looper.
The looper needs to be locked. See LockLooper().
The handler that you pass must be associated with the same looper.

Failure to meet any of these requirements will result in your application crashing.

By default, the handlers are chained in order that they were associated to a looper with BLooper::AddHander().

See also:: NextHandler()

void BLooper::SetPreferredHandler ( BHandler * handler ) [inherited]

Set a preferred handler.

If messages are posted to this looper using one of the PostMessage() methods without a specific BHandler argument, the messages will be handled by the looper itself (since a looper is a subclass of BHandler, this is perfectly possible). If you want to override that behavior, you should set a preferred handler. This handler will be called if incoming messages do not ask to be directly passed on to a specific handler.

Parameters:

handler The preferred handler you want undesignated messages to be handled by. If you want to unset the preferred handler, pass NULL. If the supplied handler is not associated with this looper, this call will fail silently and the current preferred handler will be unset.

See also:: PreferredHandler()

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:

rate	The rate at which `B_PULSE` messages are sent to the application.

status_t BHandler::StartWatching	(	BMessenger	target,
		uint32	what
	)		`[inherited]`

Subscribe this handler to watch a specific state change of a target.

Use this method to subscribe messengers to watch state changes in this handler, this also means that observers from other teams can be subscribed.

// Handler B watches Handler A
BHandler A, B;
BMessenger messengerA(&A)

B.StartWatching(messengerA, kNetworkConnection);

Parameters:

target	The messenger from which the notifications would be received.
what	The state that needs to be watched.

Returns:: During the call of this method, a notification will be transmitted using the target. If this works, then this method will return B_OK.

See also:: StartWatchingAll(BMessenger), StopWatching(BMessenger, uint32)

status_t BHandler::StartWatching	(	BHandler *	observer,
		uint32	what
	)		`[inherited]`

Subscribe an observer for a specific state change of this handler.

Use this method to subscribe observers to watch this handler. State changes of this handler that match the what argument, will be sent.

// Handler B wants to observe Handler A
BHandler A, B;

A.StartWatching(&B, kNetworkConnection);

Since pointers to handlers can only exist in the local namespace, have a look at StartWatching(BMessenger, uint32) for inter-team watching.

Parameters:

observer	The observer for this handler.
what	The state that needs to be watched.

Returns:: During the call of this method, a notification will be transmitted using the observer. If this works, then this method will return B_OK.

See also:: StartWatchingAll(BHandler*), StopWatching(BHandler*, uint32)

status_t BHandler::StartWatchingAll ( BMessenger target ) [inherited]

Subscribe this handler to watch a target for all events.

This method performs the same task as StartWatching(BMessenger, uint32), but it will subscribe to all the state changes the target knows.

See also:: StartWatching(BMessenger, uint32), StopWatchingAll(BMessenger)

status_t BHandler::StartWatchingAll ( BHandler * observer ) [inherited]

Subscribe an observer for a all state changes.

This method performs the same task as StartWatching(BHandler, uint32), but it will subscribe the observer to all the state changes this handler tracks.