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 "gactiongroup.h"
26 #include "gactionmap.h"
32 * @short_description: Interface for action containers
34 * The GActionMap interface is implemented by #GActionGroup
35 * implementations that operate by containing a number of
36 * named #GAction instances, such as #GSimpleActionGroup.
38 * One useful application of this interface is to map the
39 * names of actions from various action groups to unique,
40 * prefixed names (e.g. by prepending "app." or "win.").
41 * This is the motivation for the 'Map' part of the interface
48 * GActionMapInterface:
49 * @lookup_action: the virtual function pointer for g_action_map_lookup_action()
50 * @add_action: the virtual function pointer for g_action_map_add_action()
51 * @remove_action: the virtual function pointer for g_action_map_remove_action()
53 * The virtual function table for #GActionMap.
58 G_DEFINE_INTERFACE (GActionMap
, g_action_map
, G_TYPE_ACTION_GROUP
)
61 g_action_map_default_init (GActionMapInterface
*iface
)
66 * g_action_map_lookup_action:
67 * @action_map: a #GActionMap
68 * @action_name: the name of an action
70 * Looks up the action with the name @action_name in @action_map.
72 * If no such action exists, returns %NULL.
74 * Returns: (transfer none): a #GAction, or %NULL
79 g_action_map_lookup_action (GActionMap
*action_map
,
80 const gchar
*action_name
)
82 return G_ACTION_MAP_GET_IFACE (action_map
)
83 ->lookup_action (action_map
, action_name
);
87 * g_action_map_add_action:
88 * @action_map: a #GActionMap
91 * Adds an action to the @action_map.
93 * If the action map already contains an action with the same name
94 * as @action then the old action is dropped from the action map.
96 * The action map takes its own reference on @action.
101 g_action_map_add_action (GActionMap
*action_map
,
104 return G_ACTION_MAP_GET_IFACE (action_map
)
105 ->add_action (action_map
, action
);
109 * g_action_map_remove_action:
110 * @action_map: a #GActionMap
111 * @action_name: the name of the action
113 * Removes the named action from the action map.
115 * If no action of this name is in the map then nothing happens.
120 g_action_map_remove_action (GActionMap
*action_map
,
121 const gchar
*action_name
)
123 return G_ACTION_MAP_GET_IFACE (action_map
)
124 ->remove_action (action_map
, action_name
);
129 * @name: the name of the action
130 * @activate: the callback to connect to the "activate" signal of the
132 * @parameter_type: the type of the parameter that must be passed to the
133 * activate function for this action, given as a single
134 * GVariant type string (or %NULL for no parameter)
135 * @state: the initial state for this action, given in GVariant text
136 * format. The state is parsed with no extra type information,
137 * so type tags must be added to the string if they are
139 * @change_state: the callback to connect to the "change-state" signal
142 * This struct defines a single action. It is for use with
143 * g_action_map_add_action_entries().
145 * The order of the items in the structure are intended to reflect
146 * frequency of use. It is permissible to use an incomplete initialiser
147 * in order to leave some of the later values as %NULL. All values
148 * after @name are optional. Additional optional fields may be added in
151 * See g_action_map_add_action_entries() for an example.
155 * g_action_map_add_action_entries:
156 * @action_map: a #GActionMap
157 * @entries: a pointer to the first item in an array of #GActionEntry
159 * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated
160 * @user_data: the user data for signal connections
162 * A convenience function for creating multiple #GSimpleAction instances
163 * and adding them to a #GActionMap.
165 * Each action is constructed as per one #GActionEntry.
168 * <title>Using g_action_map_add_action_entries()</title>
171 * activate_quit (GSimpleAction *simple,
172 * GVariant *parameter,
173 * gpointer user_data)
179 * activate_print_string (GSimpleAction *simple,
180 * GVariant *parameter,
181 * gpointer user_data)
183 * g_print ("%s\n", g_variant_get_string (parameter, NULL));
186 * static GActionGroup *
187 * create_action_group (void)
189 * const GActionEntry entries[] = {
190 * { "quit", activate_quit },
191 * { "print-string", activate_print_string, "s" }
193 * GSimpleActionGroup *group;
195 * group = g_simple_action_group_new ();
196 * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
198 * return G_ACTION_GROUP (group);
206 g_action_map_add_action_entries (GActionMap
*action_map
,
207 const GActionEntry
*entries
,
213 g_return_if_fail (G_IS_ACTION_MAP (action_map
));
214 g_return_if_fail (entries
!= NULL
|| n_entries
== 0);
216 for (i
= 0; n_entries
== -1 ? entries
[i
].name
!= NULL
: i
< n_entries
; i
++)
218 const GActionEntry
*entry
= &entries
[i
];
219 const GVariantType
*parameter_type
;
220 GSimpleAction
*action
;
222 if (entry
->parameter_type
)
224 if (!g_variant_type_string_is_valid (entry
->parameter_type
))
226 g_critical ("g_simple_action_group_add_entries: the type "
227 "string '%s' given as the parameter type for "
228 "action '%s' is not a valid GVariant type "
229 "string. This action will not be added.",
230 entry
->parameter_type
, entry
->name
);
234 parameter_type
= G_VARIANT_TYPE (entry
->parameter_type
);
237 parameter_type
= NULL
;
241 GError
*error
= NULL
;
244 state
= g_variant_parse (NULL
, entry
->state
, NULL
, NULL
, &error
);
247 g_critical ("g_simple_action_group_add_entries: GVariant could "
248 "not parse the state value given for action '%s' "
249 "('%s'): %s. This action will not be added.",
250 entry
->name
, entry
->state
, error
->message
);
251 g_error_free (error
);
255 action
= g_simple_action_new_stateful (entry
->name
,
259 g_variant_unref (state
);
263 action
= g_simple_action_new (entry
->name
,
267 if (entry
->activate
!= NULL
)
268 g_signal_connect (action
, "activate",
269 G_CALLBACK (entry
->activate
), user_data
);
271 if (entry
->change_state
!= NULL
)
272 g_signal_connect (action
, "change-state",
273 G_CALLBACK (entry
->change_state
), user_data
);
275 g_action_map_add_action (action_map
, G_ACTION (action
));
276 g_object_unref (action
);