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>
23 #include "gactiongroup.h"
25 #include "gio-marshal.h"
29 * SECTION:gactiongroup
30 * @title: GActionGroup
31 * @short_description: a group of actions
33 * #GActionGroup represents a group of actions.
35 * Each action in the group has a unique name (which is a string). All
36 * method calls, except g_action_group_list_actions() take the name of
37 * an action as an argument.
39 * The #GActionGroup API is meant to be the 'public' API to the action
40 * group. The calls here are exactly the interaction that 'external
41 * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
42 * with actions. 'Internal' APIs (ie: ones meant only to be accessed by
43 * the action group implementation) are found on subclasses. This is
44 * why you will find -- for example -- g_action_group_get_enabled() but
45 * not an equivalent <function>set()</function> call.
47 * Signals are emitted on the action group in response to state changes
48 * on individual actions.
51 G_DEFINE_INTERFACE (GActionGroup, g_action_group, G_TYPE_OBJECT)
56 SIGNAL_ACTION_REMOVED,
57 SIGNAL_ACTION_ENABLED_CHANGED,
58 SIGNAL_ACTION_STATE_CHANGED,
62 static guint g_action_group_signals[NR_SIGNALS];
65 g_action_group_default_init (GActionGroupInterface *class)
68 * GActionGroup::action-added:
69 * @action_group: the #GActionGroup that changed
70 * @action_name: the name of the action in @action_group
72 * Signals that a new action was just added to the group. This signal
73 * is emitted after the action has been added and is now visible.
77 g_action_group_signals[SIGNAL_ACTION_ADDED] =
78 g_signal_new (I_("action-added"),
80 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
81 G_STRUCT_OFFSET (GActionGroupInterface, action_added),
83 g_cclosure_marshal_VOID__STRING,
88 * GActionGroup::action-removed:
89 * @action_group: the #GActionGroup that changed
90 * @action_name: the name of the action in @action_group
92 * Signals that an action is just about to be removed from the group.
93 * This signal is emitted before the action is removed, so the action
94 * is still visible and can be queried from the signal handler.
98 g_action_group_signals[SIGNAL_ACTION_REMOVED] =
99 g_signal_new (I_("action-removed"),
101 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
102 G_STRUCT_OFFSET (GActionGroupInterface, action_removed),
104 g_cclosure_marshal_VOID__STRING,
110 * GActionGroup::action-enabled-changed:
111 * @action_group: the #GActionGroup that changed
112 * @action_name: the name of the action in @action_group
113 * @enabled: whether the action is enabled or not
115 * Signals that the enabled status of the named action has changed.
119 g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED] =
120 g_signal_new (I_("action-enabled-changed"),
122 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
123 G_STRUCT_OFFSET (GActionGroupInterface,
124 action_enabled_changed),
126 _gio_marshal_VOID__STRING_BOOLEAN,
132 * GActionGroup::action-state-changed:
133 * @action_group: the #GActionGroup that changed
134 * @action_name: the name of the action in @action_group
135 * @value: the new value of the state
137 * Signals that the state of the named action has changed.
141 g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED] =
142 g_signal_new (I_("action-state-changed"),
144 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
145 G_STRUCT_OFFSET (GActionGroupInterface,
146 action_state_changed),
148 _gio_marshal_VOID__STRING_VARIANT,
155 * g_action_group_list_actions:
156 * @action_group: a #GActionGroup
158 * Lists the actions contained within @action_group.
160 * The caller is responsible for freeing the list with g_strfreev() when
161 * it is no longer required.
163 * Returns: a %NULL-terminated array of the names of the actions in the group
168 g_action_group_list_actions (GActionGroup *action_group)
170 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
172 return G_ACTION_GROUP_GET_IFACE (action_group)
173 ->list_actions (action_group);
177 * g_action_group_has_action:
178 * @action_group: a #GActionGroup
179 * @action_name: the name of the action to check for
181 * Checks if the named action exists within @action_group.
183 * Returns: whether the named action exists
188 g_action_group_has_action (GActionGroup *action_group,
189 const gchar *action_name)
191 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
193 return G_ACTION_GROUP_GET_IFACE (action_group)
194 ->has_action (action_group, action_name);
198 * g_action_group_get_parameter_type:
199 * @action_group: a #GActionGroup
200 * @action_name: the name of the action to query
202 * Queries the type of the parameter that must be given when activating
203 * the named action within @action_group.
205 * When activating the action using g_action_group_activate(), the
206 * #GVariant given to that function must be of the type returned by this
209 * In the case that this function returns %NULL, you must not give any
210 * #GVariant, but %NULL instead.
212 * The parameter type of a particular action will never change but it is
213 * possible for an action to be removed and for a new action to be added
214 * with the same name but a different parameter type.
216 * Return value: the parameter type
221 g_action_group_get_parameter_type (GActionGroup *action_group,
222 const gchar *action_name)
224 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
226 return G_ACTION_GROUP_GET_IFACE (action_group)
227 ->get_parameter_type (action_group, action_name);
231 * g_action_group_get_state_type:
232 * @action_group: a #GActionGroup
233 * @action_name: the name of the action to query
235 * Queries the type of the state of the named action within
238 * If the action is stateful then this function returns the
239 * #GVariantType of the state. All calls to g_action_group_set_state()
240 * must give a #GVariant of this type and g_action_group_get_state()
241 * will return a #GVariant of the same type.
243 * If the action is not stateful then this function will return %NULL.
244 * In that case, g_action_group_get_state() will return %NULL and you
245 * must not call g_action_group_set_state().
247 * The state type of a particular action will never change but it is
248 * possible for an action to be removed and for a new action to be added
249 * with the same name but a different state type.
251 * Returns: (allow-none): the state type, if the action is stateful
256 g_action_group_get_state_type (GActionGroup *action_group,
257 const gchar *action_name)
259 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
261 return G_ACTION_GROUP_GET_IFACE (action_group)
262 ->get_state_type (action_group, action_name);
266 * g_action_group_get_state_hint:
267 * @action_group: a #GActionGroup
268 * @action_name: the name of the action to query
270 * Requests a hint about the valid range of values for the state of the
271 * named action within @action_group.
273 * If %NULL is returned it either means that the action is not stateful
274 * or that there is no hint about the valid range of values for the
275 * state of the action.
277 * If a #GVariant array is returned then each item in the array is a
278 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
279 * returned then the tuple specifies the inclusive lower and upper bound
280 * of valid values for the state.
282 * In any case, the information is merely a hint. It may be possible to
283 * have a state value outside of the hinted range and setting a value
284 * within the range may fail.
286 * The return value (if non-%NULL) should be freed with
287 * g_variant_unref() when it is no longer required.
289 * Return value: the state range hint
294 g_action_group_get_state_hint (GActionGroup *action_group,
295 const gchar *action_name)
297 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
299 return G_ACTION_GROUP_GET_IFACE (action_group)
300 ->get_state_hint (action_group, action_name);
304 * g_action_group_get_enabled:
305 * @action_group: a #GActionGroup
306 * @action_name: the name of the action to query
308 * Checks if the named action within @action_group is currently enabled.
310 * An action must be enabled in order to be activated or in order to
311 * have its state changed from outside callers.
313 * Return value: whether or not the action is currently enabled
318 g_action_group_get_enabled (GActionGroup *action_group,
319 const gchar *action_name)
321 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
323 return G_ACTION_GROUP_GET_IFACE (action_group)
324 ->get_enabled (action_group, action_name);
328 * g_action_group_get_state:
329 * @action_group: a #GActionGroup
330 * @action_name: the name of the action to query
332 * Queries the current state of the named action within @action_group.
334 * If the action is not stateful then %NULL will be returned. If the
335 * action is stateful then the type of the return value is the type
336 * given by g_action_group_get_state_type().
338 * The return value (if non-%NULL) should be freed with
339 * g_variant_unref() when it is no longer required.
341 * Return value: (allow-none): the current state of the action
346 g_action_group_get_state (GActionGroup *action_group,
347 const gchar *action_name)
349 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
351 return G_ACTION_GROUP_GET_IFACE (action_group)
352 ->get_state (action_group, action_name);
356 * g_action_group_set_state:
357 * @action_group: a #GActionGroup
358 * @action_name: the name of the action to request the change on
359 * @value: the new state
361 * Request for the state of the named action within @action_group to be
364 * The action must be stateful and @value must be of the correct type.
365 * See g_action_group_get_state_type().
367 * This call merely requests a change. The action may refuse to change
368 * its state or may change its state to something other than @value.
369 * See g_action_group_get_state_hint().
371 * If the @value GVariant is floating, it is consumed.
376 g_action_group_set_state (GActionGroup *action_group,
377 const gchar *action_name,
380 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
381 g_return_if_fail (action_name != NULL);
382 g_return_if_fail (value != NULL);
384 G_ACTION_GROUP_GET_IFACE (action_group)
385 ->set_state (action_group, action_name, value);
389 * g_action_group_activate:
390 * @action_group: a #GActionGroup
391 * @action_name: the name of the action to activate
392 * @parameter: (allow-none): parameters to the activation
394 * Activate the named action within @action_group.
396 * If the action is expecting a parameter, then the correct type of
397 * parameter must be given as @parameter. If the action is expecting no
398 * parameters then @parameter must be %NULL. See
399 * g_action_group_get_parameter_type().
404 g_action_group_activate (GActionGroup *action_group,
405 const gchar *action_name,
408 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
409 g_return_if_fail (action_name != NULL);
411 G_ACTION_GROUP_GET_IFACE (action_group)
412 ->activate (action_group, action_name, parameter);
416 * g_action_group_action_added:
417 * @action_group: a #GActionGroup
418 * @action_name: the name of an action in the group
420 * Emits the #GActionGroup::action-added signal on @action_group.
422 * This function should only be called by #GActionGroup implementations.
427 g_action_group_action_added (GActionGroup *action_group,
428 const gchar *action_name)
430 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
431 g_return_if_fail (action_name != NULL);
433 g_signal_emit (action_group,
434 g_action_group_signals[SIGNAL_ACTION_ADDED],
435 g_quark_try_string (action_name),
440 * g_action_group_action_removed:
441 * @action_group: a #GActionGroup
442 * @action_name: the name of an action in the group
444 * Emits the #GActionGroup::action-removed signal on @action_group.
446 * This function should only be called by #GActionGroup implementations.
451 g_action_group_action_removed (GActionGroup *action_group,
452 const gchar *action_name)
454 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
455 g_return_if_fail (action_name != NULL);
457 g_signal_emit (action_group,
458 g_action_group_signals[SIGNAL_ACTION_REMOVED],
459 g_quark_try_string (action_name),
464 * g_action_group_action_enabled_changed:
465 * @action_group: a #GActionGroup
466 * @action_name: the name of an action in the group
467 * @enabled: whether or not the action is now enabled
469 * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
471 * This function should only be called by #GActionGroup implementations.
476 g_action_group_action_enabled_changed (GActionGroup *action_group,
477 const gchar *action_name,
480 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
481 g_return_if_fail (action_name != NULL);
485 g_signal_emit (action_group,
486 g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED],
487 g_quark_try_string (action_name),
493 * g_action_group_action_state_changed:
494 * @action_group: a #GActionGroup
495 * @action_name: the name of an action in the group
496 * @state: the new state of the named action
498 * Emits the #GActionGroup::action-state-changed signal on @action_group.
500 * This function should only be called by #GActionGroup implementations.
505 g_action_group_action_state_changed (GActionGroup *action_group,
506 const gchar *action_name,
509 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
510 g_return_if_fail (action_name != NULL);
512 g_signal_emit (action_group,
513 g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED],
514 g_quark_try_string (action_name),