AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

filterlistmodel: Convert docs

Browse Source
This commit is contained in:
Matthias Clasen 2021-02-28 13:08:50 -05:00 committed by Emmanuele Bassi
parent 8696b78e59
commit 36f6a76272
1 changed files with 50 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
gtk/gtkfilterlistmodel.c
View File

@ -26,19 +26,17 @@
#include "gtkprivate.h" #include "gtkprivate.h"
/** /**
* SECTION:gtkfilterlistmodel * GtkFilterListModel:
* @title: GtkFilterListModel *
* @short_description: A list model that filters its items * `GtkFilterListModel` is a list model that filters the elements of
* @see_also: #GListModel, #GtkFilter * the underlying model according to a `GtkFilter`.
* *
* #GtkFilterListModel is a list model that filters a given other
* listmodel.
* It hides some elements from the other model according to * It hides some elements from the other model according to
* criteria given by a #GtkFilter. * criteria given by a `GtkFilter`.
* *
* The model can be set up to do incremental searching, so that * The model can be set up to do incremental searching, so that
* filtering long lists doesn't block the UI. See * filtering long lists doesn't block the UI. See
* gtk_filter_list_model_set_incremental() for details. * [method@Gtk.FilterListModel.set_incremental] for details.
*/ */
enum { enum {
@ -556,9 +554,9 @@ gtk_filter_list_model_class_init (GtkFilterListModelClass *class)
gobject_class->dispose = gtk_filter_list_model_dispose; gobject_class->dispose = gtk_filter_list_model_dispose;
/** /**
* GtkFilterListModel:filter: * GtkFilterListModel:filter: (attributes org.gtk.Property.get=gtk_filter_list_model_get_filter org.gtk.Property.set=gtk_filter_list_model_set_filter)
* *
* The filter for this model * The filter for this model.
*/ */
properties[PROP_FILTER] = properties[PROP_FILTER] =
g_param_spec_object ("filter", g_param_spec_object ("filter",
@ -568,9 +566,9 @@ gtk_filter_list_model_class_init (GtkFilterListModelClass *class)
GTK_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY); GTK_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
/** /**
* GtkFilterListModel:incremental: * GtkFilterListModel:incremental: (attributes org.gtk.Property.get=gtk_filter_list_model_get_incremental org.gtk.Property.set=gtk_filter_list_model_set_incremental)
* *
* If the model should filter items incrementally * If the model should filter items incrementally.
*/ */
properties[PROP_INCREMENTAL] = properties[PROP_INCREMENTAL] =
g_param_spec_boolean ("incremental", g_param_spec_boolean ("incremental",
@ -580,9 +578,9 @@ gtk_filter_list_model_class_init (GtkFilterListModelClass *class)
GTK_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY); GTK_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
/** /**
* GtkFilterListModel:model: * GtkFilterListModel:model: (attributes org.gtk.Property.get=gtk_filter_list_model_get_model org.gtk.Property.set=gtk_filter_list_model_set_model)
* *
* The model being filtered * The model being filtered.
*/ */
properties[PROP_MODEL] = properties[PROP_MODEL] =
g_param_spec_object ("model", g_param_spec_object ("model",
@ -592,9 +590,9 @@ gtk_filter_list_model_class_init (GtkFilterListModelClass *class)
GTK_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY); GTK_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
/** /**
* GtkFilterListModel:pending: * GtkFilterListModel:pending: (attributes org.gtk.Property.get=gtk_filter_list_model_get_pending)
* *
* Number of items not yet filtered * Number of items not yet filtered.
*/ */
properties[PROP_PENDING] = properties[PROP_PENDING] =
g_param_spec_uint ("pending", g_param_spec_uint ("pending",
@ -617,10 +615,10 @@ gtk_filter_list_model_init (GtkFilterListModel *self)
* @model: (allow-none) (transfer full): the model to sort, or %NULL * @model: (allow-none) (transfer full): the model to sort, or %NULL
* @filter: (allow-none) (transfer full): filter or %NULL to not filter items * @filter: (allow-none) (transfer full): filter or %NULL to not filter items
* *
* Creates a new #GtkFilterListModel that will filter @model using the given * Creates a new `GtkFilterListModel` that will filter @model using the given
* @filter. * @filter.
* *
* Returns: a new #GtkFilterListModel * Returns: a new `GtkFilterListModel`
**/ **/
GtkFilterListModel * GtkFilterListModel *
gtk_filter_list_model_new (GListModel *model, gtk_filter_list_model_new (GListModel *model,
@ -644,8 +642,8 @@ gtk_filter_list_model_new (GListModel *model,
} }
/** /**
* gtk_filter_list_model_set_filter: * gtk_filter_list_model_set_filter: (attributes org.gtk.Method.set_property=filter)
* @self: a #GtkFilterListModel * @self: a `GtkFilterListModel`
* @filter: (allow-none) (transfer none): filter to use or %NULL to not filter items * @filter: (allow-none) (transfer none): filter to use or %NULL to not filter items
* *
* Sets the filter used to filter items. * Sets the filter used to filter items.
@ -677,14 +675,14 @@ gtk_filter_list_model_set_filter (GtkFilterListModel *self,
} }
/** /**
* gtk_filter_list_model_get_filter: * gtk_filter_list_model_get_filter: (attributes org.gtk.Method.get_property=filter)
* @self: a #GtkFilterListModel * @self: a `GtkFilterListModel`
* *
* Gets the #GtkFilter currently set on @self. * Gets the `GtkFilter` currently set on @self.
* *
* Returns: (nullable) (transfer none): The filter currently in use * Returns: (nullable) (transfer none): The filter currently in use
* or %NULL if the list isn't filtered * or %NULL if the list isn't filtered
**/ */
GtkFilter * GtkFilter *
gtk_filter_list_model_get_filter (GtkFilterListModel *self) gtk_filter_list_model_get_filter (GtkFilterListModel *self)
{ {
@ -694,8 +692,8 @@ gtk_filter_list_model_get_filter (GtkFilterListModel *self)
} }
/** /**
* gtk_filter_list_model_set_model: * gtk_filter_list_model_set_model: (attributes org.gtk.Method.set_property=model)
* @self: a #GtkFilterListModel * @self: a `GtkFilterListModel`
* @model: (allow-none): The model to be filtered * @model: (allow-none): The model to be filtered
* *
* Sets the model to be filtered. * Sets the model to be filtered.
@ -704,7 +702,7 @@ gtk_filter_list_model_get_filter (GtkFilterListModel *self)
* the item type of @self. It assumes that the caller knows what they * the item type of @self. It assumes that the caller knows what they
* are doing and have set up an appropriate filter to ensure that item * are doing and have set up an appropriate filter to ensure that item
* types match. * types match.
**/ */
void void
gtk_filter_list_model_set_model (GtkFilterListModel *self, gtk_filter_list_model_set_model (GtkFilterListModel *self,
GListModel *model) GListModel *model)
@ -755,13 +753,13 @@ gtk_filter_list_model_set_model (GtkFilterListModel *self,
} }
/** /**
* gtk_filter_list_model_get_model: * gtk_filter_list_model_get_model: (attributes org.gtk.Method.get_property=model)
* @self: a #GtkFilterListModel * @self: a `GtkFilterListModel`
* *
* Gets the model currently filtered or %NULL if none. * Gets the model currently filtered or %NULL if none.
* *
* Returns: (nullable) (transfer none): The model that gets filtered * Returns: (nullable) (transfer none): The model that gets filtered
**/ */
GListModel * GListModel *
gtk_filter_list_model_get_model (GtkFilterListModel *self) gtk_filter_list_model_get_model (GtkFilterListModel *self)
{ {
@ -771,11 +769,13 @@ gtk_filter_list_model_get_model (GtkFilterListModel *self)
} }
/** /**
* gtk_filter_list_model_set_incremental: * gtk_filter_list_model_set_incremental: (attributes org.gtk.Method.set_property=incremental)
* @self: a #GtkFilterListModel * @self: a `GtkFilterListModel`
* @incremental: %TRUE to enable incremental filtering * @incremental: %TRUE to enable incremental filtering
* *
* When incremental filtering is enabled, the GtkFilterListModel will not * Sets the filter model to do an incremental sort.
*
* When incremental filtering is enabled, the `GtkFilterListModel` will not
* run filters immediately, but will instead queue an idle handler that * run filters immediately, but will instead queue an idle handler that
* incrementally filters the items and adds them to the list. This of course * incrementally filters the items and adds them to the list. This of course
* means that items are not instantly added to the list, but only appear * means that items are not instantly added to the list, but only appear
@ -787,7 +787,7 @@ gtk_filter_list_model_get_model (GtkFilterListModel *self)
* *
* By default, incremental filtering is disabled. * By default, incremental filtering is disabled.
* *
* See gtk_filter_list_model_get_pending() for progress information * See [method@Gtk.FilterListModel.get_pending] for progress information
* about an ongoing incremental filtering operation. * about an ongoing incremental filtering operation.
**/ **/
void void
@ -818,14 +818,15 @@ gtk_filter_list_model_set_incremental (GtkFilterListModel *self,
} }
/** /**
* gtk_filter_list_model_get_incremental: * gtk_filter_list_model_get_incremental: (attributes org.gtk.Method.get_property=incremental)
* @self: a #GtkFilterListModel * @self: a `GtkFilterListModel`
* *
* Returns whether incremental filtering was enabled via * Returns whether incremental filtering is enabled.
* gtk_filter_list_model_set_incremental(). *
* See [method@Gtk.FilterListModel.set_incremental].
* *
* Returns: %TRUE if incremental filtering is enabled * Returns: %TRUE if incremental filtering is enabled
**/ */
gboolean gboolean
gtk_filter_list_model_get_incremental (GtkFilterListModel *self) gtk_filter_list_model_get_incremental (GtkFilterListModel *self)
{ {
@ -835,8 +836,8 @@ gtk_filter_list_model_get_incremental (GtkFilterListModel *self)
} }
/** /**
* gtk_filter_list_model_get_pending: * gtk_filter_list_model_get_pending: (attributes org.gtk.Method.get_property=pending)
* @self: a #GtkFilterListModel * @self: a `GtkFilterListModel`
* *
* Returns the number of items that have not been filtered yet. * Returns the number of items that have not been filtered yet.
* *
@ -845,17 +846,18 @@ gtk_filter_list_model_get_incremental (GtkFilterListModel *self)
* of the filter remaining by dividing the return value by the total * of the filter remaining by dividing the return value by the total
* number of items in the underlying model: * number of items in the underlying model:
* *
* |[ * ```c
* pending = gtk_filter_list_model_get_pending (self); * pending = gtk_filter_list_model_get_pending (self);
* model = gtk_filter_list_model_get_model (self); * model = gtk_filter_list_model_get_model (self);
* percentage = pending / (double) g_list_model_get_n_items (model); * percentage = pending / (double) g_list_model_get_n_items (model);
* ]| * ```
* *
* If no filter operation is ongoing - in particular when * If no filter operation is ongoing - in particular when
* #GtkFilterListModel:incremental is %FALSE - this function returns 0. * [property@Gtk.FilterListModel:incremental] is %FALSE - this
* function returns 0.
* *
* Returns: The number of items not yet filtered * Returns: The number of items not yet filtered
**/ */
guint guint
gtk_filter_list_model_get_pending (GtkFilterListModel *self) gtk_filter_list_model_get_pending (GtkFilterListModel *self)
{ {