diff options
author | Benjamin Otte <otte@redhat.com> | 2018-09-18 07:27:48 +0200 |
---|---|---|
committer | Benjamin Otte <otte@redhat.com> | 2018-09-18 08:02:21 +0200 |
commit | 29c700d1c73094715ec510f8677934f27952fcc3 (patch) | |
tree | 13d7ceb5a1186d2bde65221beafcfe7a7dc44391 | |
parent | 0d7c987b1af7b08aa6c6dc5727ed0ecac35037aa (diff) | |
download | gtk+-29c700d1c73094715ec510f8677934f27952fcc3.tar.gz |
listmodels: Clarify documentation for function prototypes
Fixes #1341
-rw-r--r-- | gtk/gtkfilterlistmodel.h | 11 | ||||
-rw-r--r-- | gtk/gtkmaplistmodel.c | 5 | ||||
-rw-r--r-- | gtk/gtkmaplistmodel.h | 11 | ||||
-rw-r--r-- | gtk/gtktreelistmodel.h | 10 |
4 files changed, 33 insertions, 4 deletions
diff --git a/gtk/gtkfilterlistmodel.h b/gtk/gtkfilterlistmodel.h index 3ab1601ff5..e1f256ac2d 100644 --- a/gtk/gtkfilterlistmodel.h +++ b/gtk/gtkfilterlistmodel.h @@ -36,6 +36,17 @@ G_BEGIN_DECLS GDK_AVAILABLE_IN_ALL G_DECLARE_FINAL_TYPE (GtkFilterListModel, gtk_filter_list_model, GTK, FILTER_LIST_MODEL, GObject) +/** + * GtkFilterListModelFilterFunc: + * @item: (type GObject): The item that may be filtered + * @user_data: user data + * + * User function that is called to determine if the @item of the original model should be visible. + * If it should be visible, this function must return %TRUE. If the model should filter out the + * @item, %FALSE must be returned. + * + * Returns: %TRUE to keep the item around + */ typedef gboolean (* GtkFilterListModelFilterFunc) (gpointer item, gpointer user_data); GDK_AVAILABLE_IN_ALL diff --git a/gtk/gtkmaplistmodel.c b/gtk/gtkmaplistmodel.c index 6a3de78f8b..6f5e331d80 100644 --- a/gtk/gtkmaplistmodel.c +++ b/gtk/gtkmaplistmodel.c @@ -180,6 +180,11 @@ gtk_map_list_model_get_item (GListModel *list, } node->item = self->map_func (g_list_model_get_item (self->model, position), self->user_data); + if (!G_TYPE_CHECK_INSTANCE_TYPE (node->item, self->item_type)) + { + g_critical ("Map function returned a %s, but it is not a subtype of the model's type %s", + G_OBJECT_TYPE_NAME (node->item), g_type_name (self->item_type)); + } g_object_add_weak_pointer (node->item, &node->item); return node->item; diff --git a/gtk/gtkmaplistmodel.h b/gtk/gtkmaplistmodel.h index e5c637297a..f0ddcc9524 100644 --- a/gtk/gtkmaplistmodel.h +++ b/gtk/gtkmaplistmodel.h @@ -38,12 +38,17 @@ G_DECLARE_FINAL_TYPE (GtkMapListModel, gtk_map_list_model, GTK, MAP_LIST_MODEL, /** * GtkMapListModelMapFunc: - * @item: (transfer full): The item to map + * @item: (type GObject) (transfer full): The item to map * @user_data: user data * - * User function that is called to map an @item of the original model. + * User function that is called to map an @item of the original model to + * an item expected by the map model. * - * Returns: (transfer full): The item to map to. This function may not return %NULL + * The returned items must conform to the item type of the model they are + * used with. + * + * Returns: (type GObject) (transfer full): The item to map to. + * This function may not return %NULL */ typedef gpointer (* GtkMapListModelMapFunc) (gpointer item, gpointer user_data); diff --git a/gtk/gtktreelistmodel.h b/gtk/gtktreelistmodel.h index fd9585e2be..40c4d57262 100644 --- a/gtk/gtktreelistmodel.h +++ b/gtk/gtktreelistmodel.h @@ -41,11 +41,19 @@ G_DECLARE_FINAL_TYPE (GtkTreeListRow, gtk_tree_list_row, GTK, TREE_LIST_ROW, GOb /** * GtkTreeListModelCreateModelFunc: - * @item: The item that is expaned + * @item: (type GObject): The item that is being expanded * @user_data: User data passed when registering the function * * Prototype of the function called to create new child models when * gtk_tree_list_row_set_expanded() is called. + * + * This function can return %NULL to indicate that @item is guaranteed to be + * a leave node and will never have children. + * If it does not have children but may get children later, it should return + * an empty model that is filled once children arrive. + * + * Returns: (nullable): The model tracking the children of @item or %NULL if + * @item can never have children */ typedef GListModel * (* GtkTreeListModelCreateModelFunc) (gpointer item, gpointer user_data); |