GtkFilter

GtkFilter — Filtering items

Functions

Signals

void changed Run Last

Types and Values

Object Hierarchy

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

Includes

#include <gtk/gtk.h>

Description

GtkFilter is the way to describe filters to be used in GtkFilterListModel.

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

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

GTK provides various premade 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 GtkFilter: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

 

gtk_custom_filter_new ()

GtkFilter *
gtk_custom_filter_new (GtkCustomFilterFunc match_func,
                       gpointer user_data,
                       GDestroyNotify user_destroy);

Creates a new filter using the given match_func to filter items.

If the filter func changes its filtering behavior, gtk_filter_changed() needs to be called.

Parameters

match_func

function to filter items.

[nullable]

user_data

user data to pass to match_func .

[nullable]

user_destroy

destory notify

 

Returns

a new GtkFilter

Types and Values

GtkFilter

typedef struct _GtkFilter GtkFilter;

The object describing a filter.


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      *filter,
               GtkFilterChange arg1,
               gpointer        user_data)

Flags: Run Last

See Also

GtkFilerListModel