Derived from: public BObject
Declared in: <app/MessageFilter.h>
A BMessageFilter is an object that holds a hook function, Filter(), that can look at incoming messages before they're dispatched to their designated handlers. The object also keeps the conditions that must be met for the function to be called. Applications implement the Filter() function in classes derived from BMessageFilter.
A BMessageFilter can be attached to a message loop in one of two ways:
All applicable filters in both categories are applied to a message before it's dispatched to the target BHandler. Common filters are applied before handler-specific filters.
The same BMessageFilter object can be assigned to more than one BHandler or BLooper object; it will not be destroyed when the BHandler or BLooper is deleted.
See also: BHandler::SetFilterList(), BLooper::SetCommonFilterList()
Filter() | Implemented by derived classes to respond to a incoming message before the message is dispatched to a target BHandler. |
BMessageFilter(message_delivery delivery, message_source source) BMessageFilter(message_delivery delivery, message_source source, ulong command)
Initializes the BMessageFilter object so that its Filter() function will be called for every incoming message that meets the specified delivery, source, and command criteria. The first argument, delivery, is a constant that specifies how the message must arrive:
B_DROPPED_DELIVERY | Only messages that were dragged and dropped should be filtered. |
B_PROGRAMMED_DELIVERY | Only messages that were posted or sent in application code (by calling PostMessage() or a Send...() function) should be filtered. |
B_ANY_DELIVERY | All messages, no matter how they were delivered, should be filtered. |
The second argument, source, specifies where the message must originate:
B_LOCAL_SOURCE | Only messages that originate locally, from within the application, should be filtered. |
B_REMOTE_SOURCE | Only messages that are delivered from a remote source should be filtered. |
B_ANY_SOURCE | All messages, no matter what their source, should be filtered. |
Filtering can also be limited to a particular type of message. If a command constant is specified, only messages that have what data members matching the constant will be filtered. If a command isn't specified, the command constant won't be a criterion in selecting which messages to filter; any message that meets the other criteria will be filtered, no matter what its what data member may be.
The filtering criteria are conjunctive; an arriving message must meet all the criteria specified for Filter() to be called.
See also: Filter()
virtual ~BMessageFilter(void)
Does nothing.
inline ulong Command(void) inline bool FiltersAnyCommand(void)
Command() returns the command constant (what data member) that an arriving message must match for the filter to apply. FiltersAnyCommand() returns TRUE if the filter applies to messages regardless of their what data members, and FALSE if it's limited to a certain type of message.
Because all command constants are valid, including negative numbers and 0, Command() returns a reliable result only if FiltersAnyCommand() returns FALSE.
See also: BMessageFilter() , the BMessage class
virtual filter_result Filter(BMessage *message, BHandler **target)
Implemented by derived classes to examine an arriving message just before it's dispatched. The message is passed as the first argument; the second argument indirectly points to the target BHandler object that's slated to respond to the message.
You can implement this function to do anything you please with the message, including replace the designated target with another BHandler object. For example:
filter_result MyFilter::Filter(BMessage *msg, BHandler **target) { . . . if ( *target->IsIndisposed() ) *target = *target->FindReplacement(); . . . return B_DISPATCH_MESSAGE; }
The replacement target must be associated with the same BLooper as the original target. If the new target has filters that apply to the message, those filtering functions will be called before the message is dispatched.
This function should return a constant that instructs the BLooper whether or not to dispatch the message as planned:
B_DISPATCH_MESSAGE | Dispatch the message. |
B_SKIP_MESSAGE | Don't dispatch the message and don't filter it any further; this function took care of handling it. |
The default (BMessageFilter) version of this function does nothing but return B_DISPATCH_MESSAGE .
See also: BMessageFilter()
inline message_delivery MessageDelivery(void)
Returns the constant, set when the BMessageFilter object was constructed, that describes the category of messages that can be filtered, based on how they were delivered.
See also: BMessageFilter()
inline message_source MessageSource(void)
Returns the constant, set when the BMessageFilter object was constructed, that describes the category of messages that can be filtered, based on the source of the message.
See also: BMessageFilter()
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.