The Input Server: BInputServerFilter

The Input Server Table of Contents | The Input Server Index

# BInputServerFilter

Derived from: none

Declared in: be/add-ons/input_server/InputServerFilter.h

Library: libbe.so

Allocation: By the Input Server only

###### Summary

BInputServerFilter is a base class for input filters; these are instances of BInputServerFilter that modify, generate, or eat input events. An input filter add-on is privy to all the events that pass through the Input Server>s event stream. A filter is similar to the Interface Kit>s BMessageFilter, but at a much lower level. The BInputServerFilter also sees all events, while a BMessageFilter only sees the events targeted at its BLooper. BInputServerFilters can also generate additional events in place of, or in addition to, the original input event.

BInputServerFilter objects are created and deleted by the Input Server only—you never create or delete these objects in your code.

## Creating

To create a new input filter, you must:

- create a subclass of BInputServerFilter

- implement the `instantiate_input_filter()` C function to create an instance of your BInputServerFilter subclass

- compile the class and function as an add-on

- install the add-on in one of the input filter directories

At boot time (or whenever the Input Server is restarted; see "Loading" in The Input Server), the Input Server loads the add-ons it finds in the input filter directories. For each add-on it finds, the Server invokes `instantiate_input_filter()` to get a pointer to the add-ons>s BInputServerFilter object. After constructing the object, the Server calls `InitCheck()` to give the add-on a chance to bail out if the constructor failed.

## Installing an Input Filter

The input server looks for input filters in the "input_server/filters" subdirectories of `B_BEOS_ADDONS_DIRECTORY`, `B_COMMON_ADDONS_DIRECTORY,` and `B_USER_ADDONS_DIRECTORY`.

- You can install your input devices in the latter two directories—i.e. those under `B_COMMON_ADDONS_DIRECTORY`, and `B_USER_ADDONS_DIRECTORY`.

- The `B_BEOS_ADDONS_DIRECTORY` is reserved for add-ons that are supplied with BeOS.

## Hook Functions

- `Filter()

  `
- `InitCheck()

  `

## Constructor and Destructor

### BInputServerFilter()

BInputServerFilter(void)

Creates a new BInputServerFilter object. You can initialize the object—set initial values, spawn threads, etc.—either here or in the `InitCheck()` function, which is called immediately after the constructor.

### ~BInputServerFilter()

~BInputServerFilter()

Deletes the BInputServerFilter object. The destructor is invoked by the Input Server only—you never delete a BInputServerFilter object from your own code. If this object has spawned its own threads or allocated memory on the heap, it must clean up after itself here.

## Member Functions

### Filter()

virtual filter_result Filter(BMessage *message, BList *outList)

The `Filter()` hook function is invoked by the Input Server to filter the in-coming message. You can add fields to message, remove them, or otherwise modify the object. When you're finished with the message, your implementation of `Filter()` should return `B_SKIP_MESSAGE` if this input event message should be dropped (or replaced by outList), or `B_DISPATCH_MESSAGE` if it should continue through the Input Server towards its destination.

To insert new messages into the event stream, fill the empty outList with pointers to new BMessage objects filled in with the proper input event fields, and return `B_SKIP_MESSAGE`. The Input Server will ignore message if you use outList, so you'll need to make a copy if you want it to continue downstream:

       BMessage *new_message = new BMessage( message );
       outList->AddItem( new_message );

The Input Server owns all of the messages you pass back in outList, so don't delete them yourself. Events added via outList are processed in the order they appear in the list and are inserted into the event stream in place of message. If `Filter()` returns `B_DISPATCH_MESSAGE`, messages in outList are ignored.

The default implementation returns `B_DISPATCH_MESSAGE` without modifying the message.

### GetScreenRegion()

status_t GetScreenRegion(BRegion *region) const

The `GetScreenRegion()` function returns the screen's region in region. This is the most efficient way for an input filter to get the screen's region. The system screen saver's input filter uses this for its "sleep now"/"sleep never" corners.

`GetScreenRegion()` returns `B_OK`.

### InputCheck()

virtual status_t InitCheck(void)

Invoked by the Input Server immediately after the object is constructed to test the validity of the initialization. If the object is properly initialized (i.e. all required resources are located or allocated), this function should return `B_OK`. If the object returns non-`B_OK`, the object is deleted and the add-on is unloaded.

The default implementation returns `B_OK`.

The Input Server Table of Contents | The Input Server Index

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

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