1/*
2 * Copyright © 2018 Benjamin Otte
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
16 *
17 * Authors: Benjamin Otte <otte@gnome.org>
18 */
19
20#include "config.h"
21
22#include "gtklistitemfactoryprivate.h"
23
24#include "gtklistitemprivate.h"
25
26/**
27 * GtkListItemFactory:
28 *
29 * A `GtkListItemFactory` creates widgets for the items taken from a `GListModel`.
30 *
31 * This is one of the core concepts of handling list widgets such
32 * as [class@Gtk.ListView] or [class@Gtk.GridView].
33 *
34 * The `GtkListItemFactory` is tasked with creating widgets for items
35 * taken from the model when the views need them and updating them as
36 * the items displayed by the view change.
37 *
38 * A view is usually only able to display anything after both a factory
39 * and a model have been set on the view. So it is important that you do
40 * not skip this step when setting up your first view.
41 *
42 * Because views do not display the whole list at once but only a few
43 * items, they only need to maintain a few widgets at a time. They will
44 * instruct the `GtkListItemFactory` to create these widgets and bind them
45 * to the items that are currently displayed.
46 *
47 * As the list model changes or the user scrolls to the list, the items will
48 * change and the view will instruct the factory to bind the widgets to those
49 * new items.
50 *
51 * The actual widgets used for displaying those widgets is provided by you.
52 *
53 * When the factory needs widgets created, it will create a `GtkListItem`
54 * and hand it to your code to set up a widget for. This list item will provide
55 * various properties with information about what item to display and provide
56 * you with some opportunities to configure its behavior. See the
57 * [class@Gtk.ListItem] documentation for further details.
58 *
59 * Various implementations of `GtkListItemFactory` exist to allow you different
60 * ways to provide those widgets. The most common implementations are
61 * [class@Gtk.BuilderListItemFactory] which takes a `GtkBuilder` .ui file
62 * and then creates widgets and manages everything automatically from the
63 * information in that file and [class@Gtk.SignalListItemFactory] which allows
64 * you to connect to signals with your own code and retain full control over
65 * how the widgets are setup and managed.
66 *
67 * A `GtkListItemFactory` is supposed to be final - that means its behavior should
68 * not change and the first widget created from it should behave the same way as
69 * the last widget created from it.
70 * If you intend to do changes to the behavior, it is recommended that you create
71 * a new `GtkListItemFactory` which will allow the views to recreate its widgets.
72 *
73 * Once you have chosen your factory and created it, you need to set it
74 * on the view widget you want to use it with, such as via
75 * [method@Gtk.ListView.set_factory]. Reusing factories across different
76 * views is allowed, but very uncommon.
77 */
78
79G_DEFINE_TYPE (GtkListItemFactory, gtk_list_item_factory, G_TYPE_OBJECT)
80
81static void
82gtk_list_item_factory_default_setup (GtkListItemFactory *self,
83 GtkListItemWidget *widget,
84 GtkListItem *list_item)
85{
86 gtk_list_item_widget_default_setup (self: widget, list_item);
87}
88
89static void
90gtk_list_item_factory_default_teardown (GtkListItemFactory *self,
91 GtkListItemWidget *widget,
92 GtkListItem *list_item)
93{
94 gtk_list_item_widget_default_teardown (self: widget, list_item);
95
96 gtk_list_item_set_child (self: list_item, NULL);
97}
98
99static void
100gtk_list_item_factory_default_update (GtkListItemFactory *self,
101 GtkListItemWidget *widget,
102 GtkListItem *list_item,
103 guint position,
104 gpointer item,
105 gboolean selected)
106{
107 gtk_list_item_widget_default_update (self: widget, list_item, position, item, selected);
108}
109
110static void
111gtk_list_item_factory_class_init (GtkListItemFactoryClass *klass)
112{
113 klass->setup = gtk_list_item_factory_default_setup;
114 klass->teardown = gtk_list_item_factory_default_teardown;
115 klass->update = gtk_list_item_factory_default_update;
116}
117
118static void
119gtk_list_item_factory_init (GtkListItemFactory *self)
120{
121}
122
123void
124gtk_list_item_factory_setup (GtkListItemFactory *self,
125 GtkListItemWidget *widget)
126{
127 GtkListItem *list_item;
128
129 g_return_if_fail (GTK_IS_LIST_ITEM_FACTORY (self));
130
131 list_item = gtk_list_item_new ();
132
133 GTK_LIST_ITEM_FACTORY_GET_CLASS (self)->setup (self, widget, list_item);
134}
135
136void
137gtk_list_item_factory_teardown (GtkListItemFactory *self,
138 GtkListItemWidget *widget)
139{
140 GtkListItem *list_item;
141
142 g_return_if_fail (GTK_IS_LIST_ITEM_FACTORY (self));
143
144 list_item = gtk_list_item_widget_get_list_item (self: widget);
145
146 GTK_LIST_ITEM_FACTORY_GET_CLASS (self)->teardown (self, widget, list_item);
147
148 g_object_unref (object: list_item);
149}
150
151void
152gtk_list_item_factory_update (GtkListItemFactory *self,
153 GtkListItemWidget *widget,
154 guint position,
155 gpointer item,
156 gboolean selected)
157{
158 GtkListItem *list_item;
159
160 g_return_if_fail (GTK_IS_LIST_ITEM_FACTORY (self));
161 g_return_if_fail (GTK_IS_LIST_ITEM_WIDGET (widget));
162
163 list_item = gtk_list_item_widget_get_list_item (self: widget);
164
165 GTK_LIST_ITEM_FACTORY_GET_CLASS (self)->update (self, widget, list_item, position, item, selected);
166}
167

source code of gtk/gtk/gtklistitemfactory.c