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 | |
79 | G_DEFINE_TYPE (GtkListItemFactory, gtk_list_item_factory, G_TYPE_OBJECT) |
80 | |
81 | static void |
82 | gtk_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 | |
89 | static void |
90 | gtk_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 | |
99 | static void |
100 | gtk_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 | |
110 | static void |
111 | gtk_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 | |
118 | static void |
119 | gtk_list_item_factory_init (GtkListItemFactory *self) |
120 | { |
121 | } |
122 | |
123 | void |
124 | gtk_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 | |
136 | void |
137 | gtk_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 | |
151 | void |
152 | gtk_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 | |