Public Member Functions | |
| BMessageFilter (const BMessageFilter *filter) | |
| Create a new object based on criteria of another object. | |
| BMessageFilter (const BMessageFilter &filter) | |
| Copy constructor. Copy the criteria from another object. | |
| BMessageFilter (message_delivery delivery, message_source source, uint32 what, filter_hook func=NULL) | |
| Construct a new object that filters on delivery method, message source and specific message constants. | |
| BMessageFilter (message_delivery delivery, message_source source, filter_hook func=NULL) | |
| Construct a new object that filters on delivery method and message source. | |
| BMessageFilter (uint32 what, filter_hook func=NULL) | |
| Construct a new object that filters on a message constant. | |
| uint32 | Command () const |
| Return the accepted message constant. | |
| virtual filter_result | Filter (BMessage *message, BHandler **_target) |
| Filter the message according to custom criteria. | |
| bool | FiltersAnyCommand () const |
| Return whether or not this filter has a message command criterium. | |
| BLooper * | Looper () const |
| Return the looper this filter is associated with. | |
| message_delivery | MessageDelivery () const |
| Return the message_delivery criterium of this filter. | |
| message_source | MessageSource () const |
| Return the message_source criterium of this filter. | |
| BMessageFilter & | operator= (const BMessageFilter &from) |
| Assignment operator. Copies criteria from another filter. | |
| virtual | ~BMessageFilter () |
| Destructor. Does nothing. | |
Objects of this class serve as a description of properties that incoming messages should have in order to be processed by a handler or a looper. BMessageFilter provides three default filter criteria, the what constant, the message_source and the type of message_delivery, and an extendible filter_hook.
BMessageFilter's standard filter criteria can be extended in two ways:
Both methods have their merits, but please remember that you have to choose which one you want to use, since you can't use both. The order of processing the criteria is in this order: the source, the delivery method, the filter hook and then the overrided Filter() method. Additionally, if a filter_hook is registered, the Filter() method will not be called.
The BMessageFilter objects are used in two different classes. They can be associated with specific BHandlers. Using the BHandler::AddFilter() and the BHandler::SetFilterList() methods, you can add filters to the filter list. It is also possible to associate filters with BLoopers. In that case, all incoming messages of that looper are checked against the criteria. To perform filtering in loopers, have a look at the BLooper::AddCommonFilter() and the BLooper::SetCommonFilterList() methods.
An example of a filter that selects on the default criteria:
// Our window does not handle drop events. BMessageFilter *filter = new BMessageFilter(B_PROGRAMMED_DELIVERY, B_ANY_SOURCE); window->AddCommonFilter(filter);
An example of a filter that only allows one type of message:
BMessageFilter *filter = new BMessageFilter(kHappyMessages); handler->AddFilter(filter);
An example of a filter_hook:
// The handler depends on the what code of a message filter_result ScreenMessage(BMessage* message, BHandler** target, BMessageFilter* filter) { switch (message->what) { case kTcpEvent: target = &fTcpHandler; return B_DISPATCH_MESSAGE; case kUdpEvent: target = &fUdpHandler; return B_DISPATCH_MESSAGE; } return B_SKIP_MESSAGE; } BMessageFilter *filter = new BMessageFilter(B_ANY_DELIVERY, B_ANY_SOURCE, ScreenMessage); looper->AddCommonFilter(filter);
The two classes that use BMessageFilter are BLooper and BHandler. In the general messaging introduction, there is also a section on handling messages.
| BMessageFilter::BMessageFilter | ( | uint32 | inWhat, | |
| filter_hook | func = NULL | |||
| ) |
Construct a new object that filters on a message constant.
You can also specify a filter_hook, if you want apply custom filter criteria.
| BMessageFilter::BMessageFilter | ( | message_delivery | delivery, | |
| message_source | source, | |||
| filter_hook | func = NULL | |||
| ) |
Construct a new object that filters on delivery method and message source.
You can also specify a filter_hook, if you want to apply custom filter criteria.
| BMessageFilter::BMessageFilter | ( | message_delivery | delivery, | |
| message_source | source, | |||
| uint32 | inWhat, | |||
| filter_hook | func = NULL | |||
| ) |
Construct a new object that filters on delivery method, message source and specific message constants.
You can also specify a filter_hook, if you want to apply custom filter criteria.
| uint32 BMessageFilter::Command | ( | ) | const |
Return the accepted message constant.
This method returns zero (0) in case this filter does not filter based on the message constant.
| filter_result BMessageFilter::Filter | ( | BMessage * | message, | |
| BHandler ** | target | |||
| ) | [virtual] |
Filter the message according to custom criteria.
The default implementation of this method always returns B_DISPATCH_MESSAGE. You can override this method in subclasses to suit your own criteria. You receive two arguments.
| message | The message that needs to be filtered. | |
| target | If you want to, you can specify a handler that should handle this message. Note that you do have to pass a handler that is associated with the looper that received the message. |
B_DISPATCH_MESSAGE in case the message passes the tests, or B_SKIP_MESSAGE in case the message does not pass. | bool BMessageFilter::FiltersAnyCommand | ( | ) | const |