# The Storage Kit: BRefFilter

Derived from: (none)

Declared in: be/storage/FilePanel.h

Library: (none)

## Overview

The BRefFilter class lets you filter the items that a file panel is about to display. This filtering is performed by the class' only function, `Filter()`. `Filter()` is a hook function; to use a BRefFilter, you have to create a derived class and implement the `Filter()` function.

To assign your BRefFilter object to a file panel, you invoke BFilePanel's `SetRefFilter()` function. (The BFilePanel constructor also lets you set the filter.) If you don't specifically assign a filter, the file panel will not have one--there is no "default" ref filter object. You maintain ownership of the BRefFilter that you assign to a file panel; the file panel doesn't delete or otherwise change your object.

You can assign the same filter to more than file panel. However, the `Filter()` function isn't told which panel it's being invoked for.

## Hook Functions

`Filter()
` Look down there.

## Member Functions

### Filter()

          virtual bool Filter(const entry_ref *ref,
             BNode *node,
             struct stat *st,
             const char *filetype)

`Filter()` is a hook function that's invoked whenever the file panel to which it's been assigned reads the entries in its "panel directory." The function is invoked once for each entry in the directory. All the arguments to the function refer to the entry currently under consideration. (Note that the function is never sent an abstract entry, so the node, st, and filetype arguments will always be valid.)

Your implementation of `Filter()` can use any or all of the arguments to figure out if the entry is a valid candidate for display in the file panel's file list. Simply return `true` or `false` to indicate if the entry is a winner or a loser.

Technically, `Filter()` is invoked when...

- ...the file panel's panel directory is set, either through the BFilePanel constructor or the `SetPanelDirectory()`, and when...

- ...the file panel's `Refresh()` function is called.

A BRefFilter can be assigned to more than one BFilePanel object (assignation is performed through BFilePanel's constructor or `SetRefFilter()` function). But it's not probably not a great idea to do so: At any particular invocation of `Filter()`, the BRefFilter doesn't which BFilePanel object it's working for.

You maintain ownership of the BRefFilter objects that you create. Assigning a ref filter to a file panel does not hand ownership of the BRefFilter to the BFilePanel. You shouldn't delete a BRefFilter while a BFilePanel is still using it; but it's your responsibility to delete it when it's done.

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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.