The BAlert class defines a modal alert dialog which displays a short message and provides a set of labeled buttons that allow the user to respond. More...

Inherits BWindow.

Public Member Functions
	BAlert (const char title, const char text, const char button1, const char button2=NULL, const char *button3=NULL, button_width width=B_WIDTH_AS_USUAL, alert_type type=B_INFO_ALERT)
	Creates and initializes a BAlert dialog.
	BAlert (const char title, const char text, const char button1, const char button2, const char *button3, button_width width, button_spacing spacing, alert_type type=B_INFO_ALERT)
	Creates and initializes a BAlert dialog.
	BAlert (BMessage *data)
	Unarchives an alert from a BMessage.
virtual	~BAlert ()
	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`.
virtual status_t	Archive (BMessage *data, bool deep=true) const
	Archives the BAlert into archive.
BButton *	ButtonAt (int32 index) const
	Returns a pointer to the BButton at the specified index.
virtual void	DispatchMessage (BMessage message, BHandler handler)
	Sends out a message.
virtual void	FrameResized (float new_width, float new_height)
	Resizes the alert dialog.
virtual status_t	GetSupportedSuites (BMessage *data)
	Reports the suites of messages and specifiers that derived classes understand.
int32	Go ()
	Displays the alert window.
status_t	Go (BInvoker *invoker)
	Displays the alert window from a specified invoker.
virtual void	MessageReceived (BMessage *an_event)
	Initiates an action from a received message.
virtual status_t	Perform (perform_code d, void *arg)
	Performs an action give a perform_code and data.
virtual void	Quit ()
	Quits the window closing it.
virtual bool	QuitRequested ()
	Hook method that gets called with the window is closed.
virtual BHandler *	ResolveSpecifier (BMessage message, int32 index, BMessage specifier, int32 form, const char *property)
	Resolves specifiers for properties.
void	SetShortcut (int32 button_index, char key)
	Sets the shortcut character which is mapped to a button at the specified index.
char	Shortcut (int32 button_index) const
	Gets the shortcut character which is mapped to a button at the specified index.
BTextView *	TextView () const
	Returns a TextView containing the text of the Alert.
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.
Static Public Member Functions
static BPoint	AlertPosition (float width, float height)
	Resizes the Alert window to the width and height specified and return the Point of the top-left corner of the Alert window.
static BArchivable *	Instantiate (BMessage *data)
	Instantiates a BAlert from a BMessage.
Protected Member Functions
BMessage *	MessageFromPort (bigtime_t=B_INFINITE_TIMEOUT)
	Hook method to retrieve a message from the looper's port.
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

The BAlert class defines a modal alert dialog which displays a short message and provides a set of labeled buttons that allow the user to respond.

The alert can be configured with a set of one to three buttons. These buttons are assigned indexes 0, 1, and 2 from right-to-left respectively and are automatically positioned by the system. The user can either click on one of the buttons or use a shortcut key to select a button.

The layout of the buttons can be configured by setting the button_width and button_spacing properties in the BAlert constructor. The icon displayed in the alert can also be configured by setting the alert_type property. The right-most button (index 0) is the default button which can be activated by pushing the Enter key.

Below is an example of an unsaved changes alert dialog:

When the user responds by selecting one of the buttons the alert window is removed from the screen. The index of the selected button is returned to the calling application and the BAlert object is deleted.

The code used to create and display an alert dialog like the one shown above is shown below:

BAlert* alert = new BAlert("Close and save dialog", "Save changes to...",
    "Cancel", "Don't save", "Save", B_WIDTH_AS_USUAL, B_OFFSET_SPACING,
    B_WARNING_ALERT);
alert->SetShortcut(0, B_ESCAPE);
int32 button_index = alert->Go();

The messaged displayed in the dialog window along with the button labels are set by the strings in the contructor. The Cancel button is offset to the left relative to the other buttons by setting the B_OFFSET_SPACING flag. The B_WARNING_ALERT flag displays the exclamation mark icon in the dialog.

Any alert with a Cancel button should map the Escape key as shown in the example above. You can setup additional shortcut keys for the buttons with the SetShortcut() method.

The Go() method does the work of loading up and removing the alert window and returns the index of the button that the user selected.

Constructor & Destructor Documentation

BAlert::BAlert	(	const char *	title,
		const char *	text,
		const char *	button1,
		const char *	button2 = `NULL`,
		const char *	button3 = `NULL`,
		button_width	width = `B_WIDTH_AS_USUAL`,
		alert_type	type = `B_INFO_ALERT`
	)

Creates and initializes a BAlert dialog.

Parameters:

title	The title of the window. Since the alert window doesn't have a title tab, the title is not actually displayed anywhere but is useful for debugging purposes.
text	The text that is displayed at the top of the window.
button1	Button 1 label
button2	Button 2 label
button3	Button 3 label
width	A constant that describes how the button should be sized. Options are `B_WIDTH_AS_USUAL` `B_WIDTH_FROM_WIDEST` `B_WIDTH_FROM_LABEL` See button_width for details.
type	Constant that determines which alert icon is displayed. Options are `B_EMPTY_ALERT` `B_INFO_ALERT` `B_IDEA_ALERT` `B_WARNING_ALERT` `B_STOP_ALERT` See alert_type for details.

BAlert::BAlert	(	const char *	title,
		const char *	text,
		const char *	button1,
		const char *	button2,
		const char *	button3,
		button_width	width,
		button_spacing	spacing,
		alert_type	type = `B_INFO_ALERT`
	)

Creates and initializes a BAlert dialog.

You can also set the spacing with this constructor.

Parameters:

title	The title of the window. Since the alert window doesn't have a title tab, the title is not actually displayed anywhere but is useful for debugging purposes.
text	The text that is displayed at the top of the window.
button1	Button 1 label
button2	Button 2 label
button3	Button 3 label
width	A constant that describes how the button should be sized. Options are `B_WIDTH_AS_USUAL` `B_WIDTH_FROM_WIDEST` `B_WIDTH_FROM_LABEL` See button_width for details.
spacing	Determines how the buttons are spaced. Options are `B_EVEN_SPACING` `B_OFFSET_SPACING` See button_spacing for details.
type	Constant that determines which alert icon is displayed. Options are `B_EMPTY_ALERT` `B_INFO_ALERT` `B_IDEA_ALERT` `B_WARNING_ALERT` `B_STOP_ALERT` See alert_type for details.

BAlert::~BAlert ( ) [virtual]

Destructor method.

Standard Destructor method to delete a BAlert.

BAlert::BAlert ( BMessage * data )

Unarchives an alert from a BMessage.

Parameters:

data	The archive.

Member Function Documentation

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

BPoint BAlert::AlertPosition	(	float	width,
		float	height
	)		`[static]`

Resizes the Alert window to the width and height specified and return the Point of the top-left corner of the Alert window.

Parameters:

width	The desired width of the alert window.
height	The desired height of the alert window.

Returns:: The BPoint of the top-left corner of the Alert window.

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.

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

Archives the BAlert into archive.

Parameters:

data	The target archive which the BAlert data will go into.
deep	Whether or not to recursively archive the BAlert's children.

Return values:

B_OK	The archive operation was successful.
B_BAD_VALUE	The archive operation failed.

Reimplemented from BLooper.

BButton * BAlert::ButtonAt ( int32 index ) const

Returns a pointer to the BButton at the specified index.

The index of the buttons begins at 0 and counts from left to right. If a BButton does not exist for the specified index then NULL is returned.

Parameters:

index The index of the desired button.

Returns:: A pointer to the BButton at the specified index.

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

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 BAlert::DispatchMessage	(	BMessage *	msg,
		BHandler *	handler
	)		`[virtual]`

Sends out a message.

See also:: BWindow::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().

void BAlert::FrameResized	(	float	newWidth,
		float	newHeight
	)		`[virtual]`

Resizes the alert dialog.

Parameters:

newWidth	The new alert dialog width.
newHeight	The new alert dialog height.

See also:: BWindow::FrameResized()

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

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

Parameters:

data	The message to report the suite of messages and specifiers.

See also:: BWindow::GetSupportedSuites()

Reimplemented from BLooper.

int32 BAlert::Go ( )

Displays the alert window.

This version of Go() that does not include an invoker is synchronous. Go() returns once the user has clicked a button and the panel has been removed from the screen. The BAlert object is deleted before the method returns.

If the BAlert is sent a B_QUIT_REQUESTED message while the alert window is still on screen then Go() returns -1.

Returns:: The index of the button clicked.

status_t BAlert::Go ( BInvoker * invoker )

Displays the alert window from a specified invoker.

This version of Go() with an invoker is asynchronous. It returns immediately with B_OK and the button index is set to the field of the BMessage that is sent to the target of the invoker.

Go() deletes the BAlert object after the message is sent.

If you call Go() with a NULL invoker argument than the BMessage is not sent.

If the BAlert is sent a B_QUIT_REQUESTED method while the alert window is still on screen then the message is not sent.

Returns:: A status code.

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.

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

Instantiates a BAlert from a BMessage.

Parameters:

data	The message to instantiate the BAlert.

Returns:: a BArchivable object of the BAlert.

Reimplemented from BLooper.

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

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 BAlert::MessageReceived ( BMessage * msg ) [virtual]

Initiates an action from a received message.

Parameters:

msg	The message

See also:: BWindow::MessagedReceived()

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 BAlert::Perform	(	perform_code	code,
		void *	_data
	)		`[virtual]`

Performs an action give a perform_code and data.

Currently the only perform code available is PERFORM_CODE_SET_LAYOUT.

Parameters:

code	The perform code
_data	A pointer to some data to perform on

Returns:: A status code.

See also:: BWindow::Perform().

Reimplemented from BLooper.

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 BAlert::Quit ( ) [virtual]

Quits the window closing it.

See also:: BWindow::Quit()

Reimplemented from BLooper.

bool BAlert::QuitRequested ( ) [virtual]

Hook method that gets called with the window is closed.

Returns:: true if the window closes.

See also:: BWindow::QuitRequested()

Reimplemented from BLooper.

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 * BAlert::ResolveSpecifier	(	BMessage *	msg,
		int32	index,
		BMessage *	specifier,
		int32	form,
		const char *	property
	)		`[virtual]`

Resolves specifiers for properties.

See also:: BHandler::ResolveSpecifier()

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 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 BAlert::SetShortcut	(	int32	index,
		char	key
	)

Sets the shortcut character which is mapped to a button at the specified index.

A button can only have one shortcut except for the rightmost button which, in addition to the shortcut you set, is always mapped to B_ENTER.

If you create a "Cancel" button then you should set its shortcut to B_ESCAPE.

Parameters:

index	The index of the button to set the shortcut to.
key	The shortcut character to set.

char BAlert::Shortcut ( int32 index ) const

Gets the shortcut character which is mapped to a button at the specified index.

Parameters:

index The index of the button to get the shortcut of.

Returns:: The shortcut character mapped to the button at the specified index.

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.