Derived from: public BObject
Declared in: <app/Handler.h>
BHandlers are the objects that respond to messages received in message loops. The class declares a hook function--MessageReceived() --that derived classes must implement to handle expected messages. BLooper's DispatchMessage() function calls MessageReceived() to pass incoming messages from the BLooper to the BHandler.
All messages are passed to BHandler objects--even system messages, which are passed by calling a message-specific function, not MessageReceived(). These specific functions are declared in classes derived from BHandler --especially BWindow and BView in the Interface Kit and BLooper and BApplication in this Kit. For example, the BApplication class declares a ReadyToRun() function to respond to B_READY_TO_RUN messages, and the BView class declares a KeyDown() function to respond to B_KEY_DOWN messages. (BHandler itself declares the function that responds to B_HANDLERS_REQUESTED system messages, HandlersRequested().)
All messages that aren't matched to a specific hook function--messages defined by applications rather than the kits--are dispatched by calling MessageReceived() .
BHandlers can be chained together in a linked list. The default behavior for MessageReceived() is simply to pass the message to the next handler in the chain. However, system messages are not passed from handler to handler.
To be eligible to get messages from a BLooper, a BHandler must be in the BLooper's circle of handlers. At any given time, a BHandler can belong to only one BLooper.
A target BHandler can be designated for a message when calling BLooper's PostMessage() function to post it. Messages that a BMessenger object sends are targeted to the BHandler that was named when constructing the BMessenger. Messages that a user drags and drops are targeted to the object (a BView) that controls the part of the window where the message was dropped. The messaging mechanism eventually passes the target BHandler to DispatchMessage(), so that the message can be delivered to its designated destination.
| HandlersRequested() | Can be implemented to supply BMessengers for other BHandler objects associated with this BHandler. |
| MessageReceived() | Implemented to handle received messages. |
BHandler(const char *name = NULL)
Initializes the BHandler by assigning it a name and registering it with the messaging system.
virtual ~BHandler(void)
Removes the BHandler's registration and frees the memory allocated for its name.
virtual void HandlersRequested(BMessage *message)
Implemented by derived classes to send a B_HANDLERS_INFO message in reply to the received B_HANDLERS_REQUESTED message passed as an argument. The request is for BMessenger objects corresponding to BHandler objects in the application; the BMessengers will permit the requester to direct messages to those BHandlers. This function should place the BMessengers in a "handlers" entry in the reply message --or, failing that, to place an error code in an entry named "error".
Since, by default, BHandlers are not associated with other BHandlers, this base version of the function doesn't supply any BMessengers; it simply puts the B_ERROR constant in an "error" entry and sends the reply.
For more information on the protocols that the kits currently use for B_HANDLERS_INFO and B_HANDLERS_REQUESTED messages, see the versions of this function defined in derived classes.
See also: BLooper::HandlersRequested(), BApplication::HandlersRequested(), BWindow::HandlersRequested(), BView::HandlersRequested(), B_HANDLERS_REQUESTED in the Message Protocols appendix
virtual BLooper *Looper(void) const
Returns the BLooper object that the BHandler is associated with, or NULL if it's not associated with any BLooper. A BHandler must be associated with a BLooper before the BLooper can call upon it to handle any messages it dispatches. (However, strictly speaking, this restriction is imposed when the message is posted or when the BMessenger that will send it is constructed, rather than when it's dispatched.)
BLooper objects are automatically associated with themselves; they can act as handlers only for messages that they receive in their own message loops. All other BHandlers must be explicitly tied to a particular BLooper by calling that BLooper's AddHandler() function. A BHandler can be associated with only one BLooper at a time.
In the Interface Kit, when a BView is added to a window's view hierarchy, it's also added as a BHandler to the BWindow object.
See also: BLooper::AddHandler() , BLooper::PostMessage() , the BMessenger constructor
virtual void MessageReceived(BMessage *message)
Implemented by derived classes to respond to messages that are dispatched to the BHandler. The default (BHandler) implementation of this function doesn't respond to any messages; it simply calls the next handler's version of MessageReceived() to pass it the message.
You must implement MessageReceived() to handle the variety of messages that might be dispatched to the BHandler. It can distinguish between messages by the value recorded in the what data member of the BMessage object. For example:
void MyHandler::MessageReceived(BMessage *message)
{
switch ( message->what ) {
case COMMAND_ONE:
. . .
break;
case COMMAND_TWO:
. . .
break;
case COMMAND_THREE:
. . .
break;
default:
inherited::MessageReceived(message);
break;
. . .
}
}
When defining a version of MessageReceived(), it's always a good idea to incorporate the inherited version as well, as shown in the example above. This ensures, first, that any messages handled by base versions of the function are not overlooked and, second, that the message is passed to the BHandler's next handler if even the inherited functions don't recognize it.
If the message comes to the end of the line--if it's not recognized and there is no next handler--the BHandler version of this function sends a B_MESSAGE_NOT_UNDERSTOOD reply to notify the message source.
See also: SetNextHandler() , BLooper::PostMessage() , BLooper::DispatchMessage()
virtual void SetFilterList(BList *list)
BList *FilterList(void) const
virtual void AddFilter(BMessageFilter *filter)
virtual bool RemoveFilter(BMessageFilter *filter)
These functions manage a list of BMessageFilter objects associated with the BHandler.
SetFilterList() assigns the BHandler a new list , replacing any list previously assigned. The list must contain pointers to instances of the BMessageFilter class or, more usefully, to instances of classes that derive from BMessageFilter. If list is NULL, the current list is removed. FilterList() returns the current list of filters.
AddFilter() adds a filter to the end of the BHandler's list of filters. It creates the BList object if it doesn't already exist. By default, BHandlers don't maintain a BList of filters until one is assigned or the first BMessageFilter is added. RemoveFilter() removes a filter from the list. It returns TRUE if successful, and FALSE if it can't find the specified filter in the list (or the list doesn't exist). It leaves the BList in place even after removing the last filter.
For SetFilterList(), AddFilter(), and RemoveFilter() to work, the BHandler must be assigned to a BLooper object and the BLooper must be locked.
See also: BLooper::SetCommonFilterList(), BLooper::Lock(), the BMessageFilter class
void SetName(const char *string)
const char *Name(void) const
These functions set and return the name that identifies the BHandler. The name is originally set by the constructor. SetName() assigns the BHandler a new name, and Name() returns the current name. The string returned by Name() belongs to the BHandler object; it shouldn't be altered or freed.
See also: the BHandler constructor, BView::FindView() in the Interface Kit
void SetNextHandler(BHandler *handler)
BHandler *NextHandler(void) const
These functions set and return the BHandler object that's linked to this BHandler. By default, the MessageReceived() function passes any messages that a BHandler can't understand to its next handler.
When a BHandler object is added to a BLooper, the BLooper becomes its next handler by default. The default next handler for a BLooper is the BApplication object; the next handler for the BApplication object is NULL. The handler chain for an ordinary BHandler object is therefore BHandler to BLooper to BApplication object.
However, when a BView object is added to a window, the Interface Kit assigns the BView's parent as its next handler (unless the parent is the window's top view, in which case the BWindow object is assigned as the next handler). The handler chain for BViews is therefore BView to BView, up the view hierarchy, to the BWindow to the BApplication object.
SetNextHandler() can alter any of these default assignments. For it to work, the BHandler must be assigned to a BLooper object and the BLooper must be locked.
See also: MessageReceived()
The Be Book, HTML Edition, for Developer Release 8 of the Be Operating System.
Copyright © 1996 Be, Inc. All rights reserved.
Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.
Last modified September 6, 1996.