2 * Copyright © 2010 Codethink Limited
4 * This program is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published
6 * by the Free Software Foundation; either version 2 of the licence or (at
7 * your option) any later version.
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.
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/>.
17 * Authors: Ryan Lortie <desrt@desrt.ca>
22 #include "gsimpleaction.h"
23 #include "gactionmap.h"
30 * @short_description: Interface for action containers
32 * The GActionMap interface is implemented by #GActionGroup
33 * implementations that operate by containing a number of
34 * named #GAction instances, such as #GSimpleActionGroup.
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
46 * GActionMapInterface:
47 * @lookup_action: the virtual function pointer for g_action_map_lookup_action()
48 * @add_action: the virtual function pointer for g_action_map_add_action()
49 * @remove_action: the virtual function pointer for g_action_map_remove_action()
51 * The virtual function table for #GActionMap.
56 G_DEFINE_INTERFACE (GActionMap, g_action_map, G_TYPE_OBJECT)
59 g_action_map_default_init (GActionMapInterface *iface)
64 * g_action_map_lookup_action:
65 * @action_map: a #GActionMap
66 * @action_name: the name of an action
68 * Looks up the action with the name @action_name in @action_map.
70 * If no such action exists, returns %NULL.
72 * Returns: (transfer none): a #GAction, or %NULL
77 g_action_map_lookup_action (GActionMap *action_map,
78 const gchar *action_name)
80 return G_ACTION_MAP_GET_IFACE (action_map)
81 ->lookup_action (action_map, action_name);
85 * g_action_map_add_action:
86 * @action_map: a #GActionMap
89 * Adds an action to the @action_map.
91 * If the action map already contains an action with the same name
92 * as @action then the old action is dropped from the action map.
94 * The action map takes its own reference on @action.
99 g_action_map_add_action (GActionMap *action_map,
102 G_ACTION_MAP_GET_IFACE (action_map)->add_action (action_map, action);
106 * g_action_map_remove_action:
107 * @action_map: a #GActionMap
108 * @action_name: the name of the action
110 * Removes the named action from the action map.
112 * If no action of this name is in the map then nothing happens.
117 g_action_map_remove_action (GActionMap *action_map,
118 const gchar *action_name)
120 G_ACTION_MAP_GET_IFACE (action_map)->remove_action (action_map, action_name);
125 * @name: the name of the action
126 * @activate: the callback to connect to the "activate" signal of the
128 * @parameter_type: the type of the parameter that must be passed to the
129 * activate function for this action, given as a single
130 * GVariant type string (or %NULL for no parameter)
131 * @state: the initial state for this action, given in GVariant text
132 * format. The state is parsed with no extra type information,
133 * so type tags must be added to the string if they are
135 * @change_state: the callback to connect to the "change-state" signal
138 * This struct defines a single action. It is for use with
139 * g_action_map_add_action_entries().
141 * The order of the items in the structure are intended to reflect
142 * frequency of use. It is permissible to use an incomplete initialiser
143 * in order to leave some of the later values as %NULL. All values
144 * after @name are optional. Additional optional fields may be added in
147 * See g_action_map_add_action_entries() for an example.
151 * g_action_map_add_action_entries:
152 * @action_map: a #GActionMap
153 * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to
154 * the first item in an array of #GActionEntry structs
155 * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated
156 * @user_data: the user data for signal connections
158 * A convenience function for creating multiple #GSimpleAction instances
159 * and adding them to a #GActionMap.
161 * Each action is constructed as per one #GActionEntry.
163 * |[<!-- language="C" -->
165 * activate_quit (GSimpleAction *simple,
166 * GVariant *parameter,
167 * gpointer user_data)
173 * activate_print_string (GSimpleAction *simple,
174 * GVariant *parameter,
175 * gpointer user_data)
177 * g_print ("%s\n", g_variant_get_string (parameter, NULL));
180 * static GActionGroup *
181 * create_action_group (void)
183 * const GActionEntry entries[] = {
184 * { "quit", activate_quit },
185 * { "print-string", activate_print_string, "s" }
187 * GSimpleActionGroup *group;
189 * group = g_simple_action_group_new ();
190 * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
192 * return G_ACTION_GROUP (group);
199 g_action_map_add_action_entries (GActionMap *action_map,
200 const GActionEntry *entries,
206 g_return_if_fail (G_IS_ACTION_MAP (action_map));
207 g_return_if_fail (entries != NULL || n_entries == 0);
209 for (i = 0; n_entries == -1 ? entries[i].name != NULL : i < n_entries; i++)
211 const GActionEntry *entry = &entries[i];
212 const GVariantType *parameter_type;
213 GSimpleAction *action;
215 if (entry->parameter_type)
217 if (!g_variant_type_string_is_valid (entry->parameter_type))
219 g_critical ("g_action_map_add_entries: the type "
220 "string '%s' given as the parameter type for "
221 "action '%s' is not a valid GVariant type "
222 "string. This action will not be added.",
223 entry->parameter_type, entry->name);
227 parameter_type = G_VARIANT_TYPE (entry->parameter_type);
230 parameter_type = NULL;
234 GError *error = NULL;
237 state = g_variant_parse (NULL, entry->state, NULL, NULL, &error);
240 g_critical ("g_action_map_add_entries: GVariant could "
241 "not parse the state value given for action '%s' "
242 "('%s'): %s. This action will not be added.",
243 entry->name, entry->state, error->message);
244 g_error_free (error);
248 action = g_simple_action_new_stateful (entry->name,
252 g_variant_unref (state);
256 action = g_simple_action_new (entry->name,
260 if (entry->activate != NULL)
261 g_signal_connect (action, "activate",
262 G_CALLBACK (entry->activate), user_data);
264 if (entry->change_state != NULL)
265 g_signal_connect (action, "change-state",
266 G_CALLBACK (entry->change_state), user_data);
268 g_action_map_add_action (action_map, G_ACTION (action));
269 g_object_unref (action);