The Application Kit: BMessageFilter

The Application Kit Table of Contents | The Application Kit Index

# BMessageFilter

Derived from: none

Declared in: be/app/MessageFilter.h

Library: libbe.so

Allocation: Constructor only

###### Summary

A BMessageFilter is a message-screening function that you "attach" to a BLooper or BHandler. The message filter sees messages just before they're dispatched (i.e. just before `BLooper::DispatchMessage()`), and can modify or reject the message, change the message's designated handler, or whatever else it wants to do—the implementation of the filter function isn't restricted.

To define a message filter, you have to provide a message-filtering function. You do this by implementing the `Filter()` hook function in a BMessageFilter subclass, or by supplying a `filter_hook` function to the BMessageFilter constructor. Only one filter function per object is called. If you implement `Filter()` and provide a `filter_hook` function, the `filter_hook` will win.

To attach a message filter to a looper, call `BLooper::AddCommonFilter()`. To add it to a handler, call `BHandler::AddFilter()`. Looper filters see all incoming messages; handler filters see only those messages that are targetted for that particular handler.

A BLooper or BHandler can have more than one message filter. Furthermore, a looper can have two sets of filters: a looper set and a handler set (keep in mind that BLooper is derived from BHandler). Looper filters are applied before handler filters.

A BMessageFilter object can be assigned to only one BHandler or BLooper at a time.

| The BMessageFilter class is intended to be used as part of the system-defined messaging system. If you try to use one outside this system, your results may not be what you expect.

## Hook Functions

`Filter()`

## 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:

- 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.

## Member Functions

### Command() , FiltersAnyCommand()

`uint32` `Command(void``)` `const `
`bool` `FiltersAnyCommand(void``)` `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`.

### Filter()

`virtual` `filter_result` `Filter(BMessage *`message, `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:

- `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 `Filter()` 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.

### FiltersAnyCommand() see Command()

### Looper()

`BLooper *``Looper(void``)` `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(void``)` `const `
`message_source` `MessageSource(void``)` `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&`)`

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

## Constants and Defined Types

### filter_hook

`filter_result` (*`filter_hook`)(`BMessage *`message, `BHandler **`target, `BMessageFilter *`messageFilter)

`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 must be one of these two values:

- `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_source

### message_delivery

### filter_result

The Application Kit Table of Contents | The Application Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..