1 | /* |
2 | * Copyright © 2010 Codethink Limited |
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 |
15 | * Public License along with this library; if not, see <http://www.gnu.org/licenses/>. |
16 | * |
17 | * Authors: Ryan Lortie <desrt@desrt.ca> |
18 | */ |
19 | |
20 | #include "config.h" |
21 | |
22 | #include "gsimpleaction.h" |
23 | #include "gactionmap.h" |
24 | #include "gaction.h" |
25 | |
26 | /** |
27 | * SECTION:gactionmap |
28 | * @title: GActionMap |
29 | * @include: gio/gio.h |
30 | * @short_description: Interface for action containers |
31 | * |
32 | * The GActionMap interface is implemented by #GActionGroup |
33 | * implementations that operate by containing a number of |
34 | * named #GAction instances, such as #GSimpleActionGroup. |
35 | * |
36 | * One useful application of this interface is to map the |
37 | * names of actions from various action groups to unique, |
38 | * prefixed names (e.g. by prepending "app." or "win."). |
39 | * This is the motivation for the 'Map' part of the interface |
40 | * name. |
41 | * |
42 | * Since: 2.32 |
43 | **/ |
44 | |
45 | /** |
46 | * GActionMap: |
47 | * |
48 | * #GActionMap is an opaque data structure and can only be accessed |
49 | * using the following functions. |
50 | **/ |
51 | |
52 | /** |
53 | * GActionMapInterface: |
54 | * @lookup_action: the virtual function pointer for g_action_map_lookup_action() |
55 | * @add_action: the virtual function pointer for g_action_map_add_action() |
56 | * @remove_action: the virtual function pointer for g_action_map_remove_action() |
57 | * |
58 | * The virtual function table for #GActionMap. |
59 | * |
60 | * Since: 2.32 |
61 | **/ |
62 | |
63 | G_DEFINE_INTERFACE (GActionMap, g_action_map, G_TYPE_OBJECT) |
64 | |
65 | static void |
66 | g_action_map_default_init (GActionMapInterface *iface) |
67 | { |
68 | } |
69 | |
70 | /** |
71 | * g_action_map_lookup_action: |
72 | * @action_map: a #GActionMap |
73 | * @action_name: the name of an action |
74 | * |
75 | * Looks up the action with the name @action_name in @action_map. |
76 | * |
77 | * If no such action exists, returns %NULL. |
78 | * |
79 | * Returns: (nullable) (transfer none): a #GAction, or %NULL |
80 | * |
81 | * Since: 2.32 |
82 | */ |
83 | GAction * |
84 | g_action_map_lookup_action (GActionMap *action_map, |
85 | const gchar *action_name) |
86 | { |
87 | return G_ACTION_MAP_GET_IFACE (action_map) |
88 | ->lookup_action (action_map, action_name); |
89 | } |
90 | |
91 | /** |
92 | * g_action_map_add_action: |
93 | * @action_map: a #GActionMap |
94 | * @action: a #GAction |
95 | * |
96 | * Adds an action to the @action_map. |
97 | * |
98 | * If the action map already contains an action with the same name |
99 | * as @action then the old action is dropped from the action map. |
100 | * |
101 | * The action map takes its own reference on @action. |
102 | * |
103 | * Since: 2.32 |
104 | */ |
105 | void |
106 | g_action_map_add_action (GActionMap *action_map, |
107 | GAction *action) |
108 | { |
109 | G_ACTION_MAP_GET_IFACE (action_map)->add_action (action_map, action); |
110 | } |
111 | |
112 | /** |
113 | * g_action_map_remove_action: |
114 | * @action_map: a #GActionMap |
115 | * @action_name: the name of the action |
116 | * |
117 | * Removes the named action from the action map. |
118 | * |
119 | * If no action of this name is in the map then nothing happens. |
120 | * |
121 | * Since: 2.32 |
122 | */ |
123 | void |
124 | g_action_map_remove_action (GActionMap *action_map, |
125 | const gchar *action_name) |
126 | { |
127 | G_ACTION_MAP_GET_IFACE (action_map)->remove_action (action_map, action_name); |
128 | } |
129 | |
130 | /** |
131 | * GActionEntry: |
132 | * @name: the name of the action |
133 | * @activate: the callback to connect to the "activate" signal of the |
134 | * action. Since GLib 2.40, this can be %NULL for stateful |
135 | * actions, in which case the default handler is used. For |
136 | * boolean-stated actions with no parameter, this is a |
137 | * toggle. For other state types (and parameter type equal |
138 | * to the state type) this will be a function that |
139 | * just calls @change_state (which you should provide). |
140 | * @parameter_type: the type of the parameter that must be passed to the |
141 | * activate function for this action, given as a single |
142 | * GVariant type string (or %NULL for no parameter) |
143 | * @state: the initial state for this action, given in |
144 | * [GVariant text format][gvariant-text]. The state is parsed |
145 | * with no extra type information, so type tags must be added to |
146 | * the string if they are necessary. Stateless actions should |
147 | * give %NULL here. |
148 | * @change_state: the callback to connect to the "change-state" signal |
149 | * of the action. All stateful actions should provide a |
150 | * handler here; stateless actions should not. |
151 | * |
152 | * This struct defines a single action. It is for use with |
153 | * g_action_map_add_action_entries(). |
154 | * |
155 | * The order of the items in the structure are intended to reflect |
156 | * frequency of use. It is permissible to use an incomplete initialiser |
157 | * in order to leave some of the later values as %NULL. All values |
158 | * after @name are optional. Additional optional fields may be added in |
159 | * the future. |
160 | * |
161 | * See g_action_map_add_action_entries() for an example. |
162 | **/ |
163 | |
164 | /** |
165 | * g_action_map_add_action_entries: |
166 | * @action_map: a #GActionMap |
167 | * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to |
168 | * the first item in an array of #GActionEntry structs |
169 | * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated |
170 | * @user_data: the user data for signal connections |
171 | * |
172 | * A convenience function for creating multiple #GSimpleAction instances |
173 | * and adding them to a #GActionMap. |
174 | * |
175 | * Each action is constructed as per one #GActionEntry. |
176 | * |
177 | * |[<!-- language="C" --> |
178 | * static void |
179 | * activate_quit (GSimpleAction *simple, |
180 | * GVariant *parameter, |
181 | * gpointer user_data) |
182 | * { |
183 | * exit (0); |
184 | * } |
185 | * |
186 | * static void |
187 | * activate_print_string (GSimpleAction *simple, |
188 | * GVariant *parameter, |
189 | * gpointer user_data) |
190 | * { |
191 | * g_print ("%s\n", g_variant_get_string (parameter, NULL)); |
192 | * } |
193 | * |
194 | * static GActionGroup * |
195 | * create_action_group (void) |
196 | * { |
197 | * const GActionEntry entries[] = { |
198 | * { "quit", activate_quit }, |
199 | * { "print-string", activate_print_string, "s" } |
200 | * }; |
201 | * GSimpleActionGroup *group; |
202 | * |
203 | * group = g_simple_action_group_new (); |
204 | * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL); |
205 | * |
206 | * return G_ACTION_GROUP (group); |
207 | * } |
208 | * ]| |
209 | * |
210 | * Since: 2.32 |
211 | */ |
212 | void |
213 | g_action_map_add_action_entries (GActionMap *action_map, |
214 | const GActionEntry *entries, |
215 | gint n_entries, |
216 | gpointer user_data) |
217 | { |
218 | gint i; |
219 | |
220 | g_return_if_fail (G_IS_ACTION_MAP (action_map)); |
221 | g_return_if_fail (entries != NULL || n_entries == 0); |
222 | |
223 | for (i = 0; n_entries == -1 ? entries[i].name != NULL : i < n_entries; i++) |
224 | { |
225 | const GActionEntry *entry = &entries[i]; |
226 | const GVariantType *parameter_type; |
227 | GSimpleAction *action; |
228 | |
229 | if (entry->parameter_type) |
230 | { |
231 | if (!g_variant_type_string_is_valid (type_string: entry->parameter_type)) |
232 | { |
233 | g_critical ("g_action_map_add_entries: the type " |
234 | "string '%s' given as the parameter type for " |
235 | "action '%s' is not a valid GVariant type " |
236 | "string. This action will not be added." , |
237 | entry->parameter_type, entry->name); |
238 | return; |
239 | } |
240 | |
241 | parameter_type = G_VARIANT_TYPE (entry->parameter_type); |
242 | } |
243 | else |
244 | parameter_type = NULL; |
245 | |
246 | if (entry->state) |
247 | { |
248 | GError *error = NULL; |
249 | GVariant *state; |
250 | |
251 | state = g_variant_parse (NULL, text: entry->state, NULL, NULL, error: &error); |
252 | if (state == NULL) |
253 | { |
254 | g_critical ("g_action_map_add_entries: GVariant could " |
255 | "not parse the state value given for action '%s' " |
256 | "('%s'): %s. This action will not be added." , |
257 | entry->name, entry->state, error->message); |
258 | g_error_free (error); |
259 | continue; |
260 | } |
261 | |
262 | action = g_simple_action_new_stateful (name: entry->name, |
263 | parameter_type, |
264 | state); |
265 | |
266 | g_variant_unref (value: state); |
267 | } |
268 | else |
269 | { |
270 | action = g_simple_action_new (name: entry->name, |
271 | parameter_type); |
272 | } |
273 | |
274 | if (entry->activate != NULL) |
275 | g_signal_connect (action, "activate" , |
276 | G_CALLBACK (entry->activate), user_data); |
277 | |
278 | if (entry->change_state != NULL) |
279 | g_signal_connect (action, "change-state" , |
280 | G_CALLBACK (entry->change_state), user_data); |
281 | |
282 | g_action_map_add_action (action_map, G_ACTION (action)); |
283 | g_object_unref (object: action); |
284 | } |
285 | } |
286 | |