## GtkFilter GtkFilter — Filtering items |

## Functions

gboolean | gtk_filter_match ()
GtkFilterMatch | gtk_filter_get_strictness ()
void | gtk_filter_changed ()

## Signals

void | changed | Run Last

## Types and Values

| GtkFilter
enum | GtkFilterMatch
enum | GtkFilterChange

## Object Hierarchy

        GObject
        ╰── GtkFilter
            ├── GtkMultiFilter
            ├── GtkBoolFilter
            ├── GtkCustomFilter
            ├── GtkFileFilter
            ╰── GtkStringFilter

## Includes

    #include <gtk/gtk.h>

## Description

A GtkFilter object describes the filtering to be performed by a GtkFilterListModel.

The model will use the filter to determine if it should include items or not by calling `gtk_filter_match()` for each item and only keeping the ones that the function returns `TRUE` for.

Filters may change what items they match through their lifetime. In that case, they will emit the “changed” signal to notify that previous filter results are no longer valid and that items should be checked again via `gtk_filter_match()`.

GTK provides various pre-made filter implementations for common filtering operations. These filters often include properties that can be linked to various widgets to easily allow searches.

However, in particular for large lists or complex search methods, it is also possible to subclass GtkFilter and provide one's own filter.

## Functions

### gtk_filter_match ()

    gboolean
    gtk_filter_match (GtkFilter *self,
                      gpointer item);

Checks if the given `item` is matched by the filter or not.

#### Parameters

self | a GtkFilter |
item | The item to check. | [type GObject][transfer none]

#### Returns

`TRUE` if the filter matches the item and a filter model should keep it, `FALSE` if not.

### gtk_filter_get_strictness ()

    GtkFilterMatch
    gtk_filter_get_strictness (GtkFilter *self);

Gets the known strictness of `filters` . If the strictness is not known, `GTK_FILTER_MATCH_SOME` is returned.

This value may change after emission of the “changed” signal.

This function is meant purely for optimization purposes, filters can choose to omit implementing it, but GtkFilterListModel uses it.

#### Parameters

self | a GtkFilter |

#### Returns

the strictness of `self`

### gtk_filter_changed ()

    void
    gtk_filter_changed (GtkFilter *self,
                        GtkFilterChange change);

Emits the “changed” signal to notify all users of the filter that the filter changed. Users of the filter should then check items again via `gtk_filter_match()`.

Depending on the `change` parameter, not all items need to be changed, but only some. Refer to the GtkFilterChange documentation for details.

This function is intended for implementors of GtkFilter subclasses and should not be called from other functions.

#### Parameters

self | a GtkFilter |
change | How the filter changed |

## Types and Values

### GtkFilter

    typedef struct _GtkFilter GtkFilter;

The object describing a filter.

### enum GtkFilterMatch

Describes the known strictness of a filter.

Note that for filters where the strictness is not known, `GTK_FILTER_MATCH_SOME` is always an acceptable value, even if a filter does match all or no items.

#### Members

GTK_FILTER_MATCH_SOME | The filter matches some items, `gtk_filter_match()` may return `TRUE` or `FALSE` |
GTK_FILTER_MATCH_NONE | The filter does not match any item, `gtk_filter_match()` will always return `FALSE`. |
GTK_FILTER_MATCH_ALL | The filter matches all items, `gtk_filter_match()` will alays return `TRUE`. |

### enum GtkFilterChange

Describes changes in a filter in more detail and allows objects using the filter to optimize refiltering items.

If you are writing an implementation and are not sure which value to pass, `GTK_FILTER_CHANGE_DIFFERENT` is always a correct choice.

#### Members

GTK_FILTER_CHANGE_DIFFERENT | The filter change cannot be described with any of the other enumeration values. |
GTK_FILTER_CHANGE_LESS_STRICT | The filter is less strict than it was before: All items that it used to return `TRUE` for still return `TRUE`, others now may, too. |
GTK_FILTER_CHANGE_MORE_STRICT | The filter is more strict than it was before: All items that it used to return `FALSE` for still return `FALSE`, others now may, too. |

## Signal Details

### The `“changed”` signal

    void
    user_function (GtkFilter      *self,
                   GtkFilterChange change,
                   gpointer        user_data)

This signal is emitted whenever the filter changed. Users of the filter should then check items again via `gtk_filter_match()`.

GtkFilterListModel handles this signal automatically.

Depending on the `change` parameter, not all items need to be changed, but only some. Refer to the GtkFilterChange documentation for details.

#### Parameters

self | The GtkFilter |
change | how the filter changed |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

## See Also

GtkFilterListModel