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
63G_DEFINE_INTERFACE (GActionMap, g_action_map, G_TYPE_OBJECT)
64
65static void
66g_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 */
83GAction *
84g_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 */
105void
106g_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 */
123void
124g_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 */
212void
213g_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

source code of gtk/subprojects/glib/gio/gactionmap.c