BMessageFilter

Derived From:
Mix-in Classes:
Declared In:app/MessageFilter.h
Library:libbe.so
Allocation:Constructor only
Class Overview

Constructor and Destructor

BMessageFilter()

BMessageFilter(message_delivery delivery,
               message_source source,
               uint32 command,
               filter_hook filter = NULL);
BMessageFilter(message_delivery delivery,
               message_source source,
               filter_hook filter = NULL);
BMessageFilter(uint32 command,
               filter_hook filter = NULL);
BMessageFilter(const BMessageFilter& object); BMessageFilter(const BMessageFilter* object);

Creates and returns a new BMessageFilter. The first three arguments define the types of messages that the object wants to see:

ParameterDescription

delivery

Specifies how the message must arrive: drag-and-drop (B_DROPPED_DELIVERY), programmatically (B_PROGRAMMED_DELIVERY), or either (B_ANY_DELIVERY). The default is B_ANY_DELIVERY.

source

Specifes whether the sender of the message must be local vis-a-vis this app (B_LOCAL_SOURCE), remote (B_REMOTE_SOURCE), or either (B_ANY_SOURCE). The default is B_ANY_SOURCE.

command

Is a command constant. If supplied, the what value of the incoming message must match this value.

Messages that don't fit the definition won't be sent to the object's filter function.

The filter argument is a pointer to a filter_hook function. This is the function that's invoked when a message needs to be examined (see filter_hook for the protocol). You don't have to supply a filter_hook function; instead, you can implement BMessageFilter's Filter() function in a subclass.

For more information, refer to the description of the member Filter() function.

~BMessageFilter()

virtual ~BMessageFilter()();

Does nothing.


Hook Functions

Filter()

virtual filter_result Filter(BMessagemessage,
                             BHandler** target);

Implemented by derived classes to examine an arriving message just before it's dispatched. The first two arguments are the message that's being considered, and the proposed BHandler target. You can alter the contents of the message, and alter or even replace the handler. If you replace the handler, the new handler must belong to the same looper as the original. The new handler is given an opportunity to filter the message before it's dispatched.

The return value must be one of these two values:

ConstantDescription

B_DISPATCH_MESSAGE.

The message and handler are passed (by the caller) to the looper's DispatchMessage() function.

B_SKIP_MESSAGE.

The message goes no further—it's immediately thrown away by the caller.

The default version of this function returns B_DISPATCH_MESSAGE.

It's possible to call your Filter() function yourself (i.e. outside the message-passing mechanism), but keep in mind that it's the caller's responsibility to interpret the return value.

Rather than implement the function, you can supply the BMessageFilter with a filter_hook callback when you construct the object. If you do both, the filter_hook (and not Filter()) will be invoked when the object is asked to examine a message.


Member Functions

Command(), FiltersAnyCommand()

uint32 Command() const;bool FiltersAnyCommand() const;

Command() returns the command constant (the BMessage what value) that an arriving message must match for the filter to apply. FiltersAnyCommand() returns true if the filter applies to all messages, and false if it's limited to a specific command.

Because all command constants are valid, including negative numbers and 0, Command() returns a reliable result only if FiltersAnyCommand() returns false.

Looper()

BLooperLooper() const;

Returns the BLooper whose messages this object filters, or NULL if the BMessageFilter hasn't yet been assigned to a BHandler or BLooper. To attach a BMessageFilter to a looper or handler, use BLooper::AddCommonFilter() or BHandler::AddFilter().

MessageDelivery(), MessageSource()

message_delivery MessageDelivery() const;message_source MessageSource() const;

These functions return constants, set when the BMessageFilter object was constructed, that describe the categories of messages that can be filtered. MessageDelivery() returns a constant that specifies how the message must be delivered (B_DROPPED_DELIVERY, B_PROGRAMMED_DELIVERY, or B_ANY_DELIVERY). MessageSource() returns how the source of the message is constrained (B_LOCAL_SOURCE, B_REMOTE_SOURCE, or B_ANY_SOURCE).


Operators

= (copy)

BMessageFilter operator=(const BMessageFilter& from);

Copies the filtering criteria and filter_hook pointer (if any) from the right-side object into the left-side object.


Defined Types

filter_hook, filter_result

filter_result (*filter_hook)(BMessagemessage,
                             BHandler** target,
                             BMessageFilter* messageFilter);
typedef enum filter_result {
    B_SKIP_MESSAGE,
    B_DISPATCH_MESSAGE
}

filter_hook defines the protocol for message-filtering functions. The first two arguments are the message that's being considered, and the proposed BHandler target. You can alter the contents of the message, and alter or even replace the handler. If you replace the handler, the new handler must belong to the same looper as the original. The new handler is given an opportunity to filter the message before it's dispatched.

messageFilter is a pointer to the object on whose behalf this function is being called; you mustn't delete this object. More than one BMessageFilter can use the same filter_hook function.

The return value of type filter_result must be one of these two values:

ConstantDescription

B_DISPATCH_MESSAGE.

The message and handler are passed (by the caller) to the looper's DispatchMessage() function.

B_SKIP_MESSAGE.

The message goes no further–it's immediately thrown away by the caller.

It's possible to call your filter function yourself (i.e. outside the message-passing mechanism), but keep in mind that it's the caller's responsibility to interpret the return value.

You supply a BMessageFilter with a filter_hook function when you constuct the object. Alternatively, you can subclass BMessageFilter and provide an implementation of Filter(). If you do both, the filter_hook (and not Filter()) will be invoked when the object is asked to examine a message.

message_delivery

typedef enum message_delivery {
    B_ANY_DELIVERY,
    B_DROPPED_DELIVERY,
    B_PROGRAMMED_DELIVERY
}

This type enumerates the delivery criteria for filtering a message.

See also: The BMessageFilter constructor

message_source

typedef enum message_source {
    B_ANY_SOURCE,
    B_REMOTE_SOURCE,
    B_LOCAL_SOURCE
}

This type enumerates the source criteria for filtering a message.

See also: The BMessageFilter constructor

Creative Commons License
Legal Notice
This work is licensed under a Creative Commons Attribution-Non commercial-No Derivative Works 3.0 License.