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, write to the
16 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
17 * Boston, MA 02111-1307, USA.
19 * Authors: Ryan Lortie <desrt@desrt.ca>
24 #include "gsimpleaction.h"
25 #include "gactionmap.h"
31 * @short_description: Interface for action containers
33 * The GActionMap interface is implemented by #GActionGroup
34 * implementations that operate by containing a number of
35 * named #GAction instances, such as #GSimpleActionGroup.
37 * One useful application of this interface is to map the
38 * names of actions from various action groups to unique,
39 * prefixed names (e.g. by prepending "app." or "win.").
40 * This is the motivation for the 'Map' part of the interface
47 * GActionMapInterface:
48 * @lookup_action: the virtual function pointer for g_action_map_lookup_action()
49 * @add_action: the virtual function pointer for g_action_map_add_action()
50 * @remove_action: the virtual function pointer for g_action_map_remove_action()
52 * The virtual function table for #GActionMap.
57 G_DEFINE_INTERFACE (GActionMap
, g_action_map
, G_TYPE_OBJECT
)
60 g_action_map_default_init (GActionMapInterface
*iface
)
65 * g_action_map_lookup_action:
66 * @action_map: a #GActionMap
67 * @action_name: the name of an action
69 * Looks up the action with the name @action_name in @action_map.
71 * If no such action exists, returns %NULL.
73 * Returns: (transfer none): a #GAction, or %NULL
78 g_action_map_lookup_action (GActionMap
*action_map
,
79 const gchar
*action_name
)
81 return G_ACTION_MAP_GET_IFACE (action_map
)
82 ->lookup_action (action_map
, action_name
);
86 * g_action_map_add_action:
87 * @action_map: a #GActionMap
90 * Adds an action to the @action_map.
92 * If the action map already contains an action with the same name
93 * as @action then the old action is dropped from the action map.
95 * The action map takes its own reference on @action.
100 g_action_map_add_action (GActionMap
*action_map
,
103 G_ACTION_MAP_GET_IFACE (action_map
)->add_action (action_map
, action
);
107 * g_action_map_remove_action:
108 * @action_map: a #GActionMap
109 * @action_name: the name of the action
111 * Removes the named action from the action map.
113 * If no action of this name is in the map then nothing happens.
118 g_action_map_remove_action (GActionMap
*action_map
,
119 const gchar
*action_name
)
121 G_ACTION_MAP_GET_IFACE (action_map
)->remove_action (action_map
, action_name
);
126 * @name: the name of the action
127 * @activate: the callback to connect to the "activate" signal of the
129 * @parameter_type: the type of the parameter that must be passed to the
130 * activate function for this action, given as a single
131 * GVariant type string (or %NULL for no parameter)
132 * @state: the initial state for this action, given in GVariant text
133 * format. The state is parsed with no extra type information,
134 * so type tags must be added to the string if they are
136 * @change_state: the callback to connect to the "change-state" signal
139 * This struct defines a single action. It is for use with
140 * g_action_map_add_action_entries().
142 * The order of the items in the structure are intended to reflect
143 * frequency of use. It is permissible to use an incomplete initialiser
144 * in order to leave some of the later values as %NULL. All values
145 * after @name are optional. Additional optional fields may be added in
148 * See g_action_map_add_action_entries() for an example.
152 * g_action_map_add_action_entries:
153 * @action_map: a #GActionMap
154 * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to
155 * the first item in an array of #GActionEntry structs
156 * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated
157 * @user_data: the user data for signal connections
159 * A convenience function for creating multiple #GSimpleAction instances
160 * and adding them to a #GActionMap.
162 * Each action is constructed as per one #GActionEntry.
165 * <title>Using g_action_map_add_action_entries()</title>
168 * activate_quit (GSimpleAction *simple,
169 * GVariant *parameter,
170 * gpointer user_data)
176 * activate_print_string (GSimpleAction *simple,
177 * GVariant *parameter,
178 * gpointer user_data)
180 * g_print ("%s\n", g_variant_get_string (parameter, NULL));
183 * static GActionGroup *
184 * create_action_group (void)
186 * const GActionEntry entries[] = {
187 * { "quit", activate_quit },
188 * { "print-string", activate_print_string, "s" }
190 * GSimpleActionGroup *group;
192 * group = g_simple_action_group_new ();
193 * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
195 * return G_ACTION_GROUP (group);
203 g_action_map_add_action_entries (GActionMap
*action_map
,
204 const GActionEntry
*entries
,
210 g_return_if_fail (G_IS_ACTION_MAP (action_map
));
211 g_return_if_fail (entries
!= NULL
|| n_entries
== 0);
213 for (i
= 0; n_entries
== -1 ? entries
[i
].name
!= NULL
: i
< n_entries
; i
++)
215 const GActionEntry
*entry
= &entries
[i
];
216 const GVariantType
*parameter_type
;
217 GSimpleAction
*action
;
219 if (entry
->parameter_type
)
221 if (!g_variant_type_string_is_valid (entry
->parameter_type
))
223 g_critical ("g_action_map_add_entries: the type "
224 "string '%s' given as the parameter type for "
225 "action '%s' is not a valid GVariant type "
226 "string. This action will not be added.",
227 entry
->parameter_type
, entry
->name
);
231 parameter_type
= G_VARIANT_TYPE (entry
->parameter_type
);
234 parameter_type
= NULL
;
238 GError
*error
= NULL
;
241 state
= g_variant_parse (NULL
, entry
->state
, NULL
, NULL
, &error
);
244 g_critical ("g_action_map_add_entries: GVariant could "
245 "not parse the state value given for action '%s' "
246 "('%s'): %s. This action will not be added.",
247 entry
->name
, entry
->state
, error
->message
);
248 g_error_free (error
);
252 action
= g_simple_action_new_stateful (entry
->name
,
256 g_variant_unref (state
);
260 action
= g_simple_action_new (entry
->name
,
264 if (entry
->activate
!= NULL
)
265 g_signal_connect (action
, "activate",
266 G_CALLBACK (entry
->activate
), user_data
);
268 if (entry
->change_state
!= NULL
)
269 g_signal_connect (action
, "change-state",
270 G_CALLBACK (entry
->change_state
), user_data
);
272 g_action_map_add_action (action_map
, G_ACTION (action
));
273 g_object_unref (action
);