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"
28 * SECTION:gactiongroup
29 * @title: GActionGroup
30 * @short_description: A group of actions
33 * #GActionGroup represents a group of actions. Actions can be used to
34 * expose functionality in a structured way, either from one part of a
35 * program to another, or to the outside world. Action groups are often
36 * used together with a #GMenuModel that provides additional
37 * representation data for displaying the actions to the user, e.g. in
40 * The main way to interact with the actions in a GActionGroup is to
41 * activate them with g_action_group_activate_action(). Activating an
42 * action may require a #GVariant parameter. The required type of the
43 * parameter can be inquired with g_action_group_get_action_parameter_type().
44 * Actions may be disabled, see g_action_group_get_action_enabled().
45 * Activating a disabled action has no effect.
47 * Actions may optionally have a state in the form of a #GVariant. The
48 * current state of an action can be inquired with
49 * g_action_group_get_action_state(). Activating a stateful action may
50 * change its state, but it is also possible to set the state by calling
51 * g_action_group_change_action_state().
53 * As typical example, consider a text editing application which has an
54 * option to change the current font to 'bold'. A good way to represent
55 * this would be a stateful action, with a boolean state. Activating the
56 * action would toggle the state.
58 * Each action in the group has a unique name (which is a string). All
59 * method calls, except g_action_group_list_actions() take the name of
60 * an action as an argument.
62 * The #GActionGroup API is meant to be the 'public' API to the action
63 * group. The calls here are exactly the interaction that 'external
64 * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
65 * with actions. 'Internal' APIs (ie: ones meant only to be accessed by
66 * the action group implementation) are found on subclasses. This is
67 * why you will find - for example - g_action_group_get_action_enabled()
68 * but not an equivalent <function>set()</function> call.
70 * Signals are emitted on the action group in response to state changes
71 * on individual actions.
73 * Implementations of #GActionGroup should provide implementations for
74 * the virtual functions g_action_group_list_actions() and
75 * g_action_group_query_action(). The other virtual functions should
76 * not be implemented - their "wrappers" are actually implemented with
77 * calls to g_action_group_query_action().
81 * GActionGroupInterface:
82 * @has_action: the virtual function pointer for g_action_group_has_action()
83 * @list_actions: the virtual function pointer for g_action_group_list_actions()
84 * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type()
85 * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type()
86 * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
87 * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
88 * @get_action_state: the virtual function pointer for g_action_group_get_action_state()
89 * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
90 * @query_action: the virtual function pointer for g_action_group_query_action()
91 * @activate_action: the virtual function pointer for g_action_group_activate_action()
92 * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
93 * @action_added: the class closure for the #GActionGroup::action-added signal
94 * @action_removed: the class closure for the #GActionGroup::action-removed signal
95 * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
96 * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal
98 * The virtual function table for #GActionGroup.
103 G_DEFINE_INTERFACE (GActionGroup, g_action_group, G_TYPE_OBJECT)
108 SIGNAL_ACTION_REMOVED,
109 SIGNAL_ACTION_ENABLED_CHANGED,
110 SIGNAL_ACTION_STATE_CHANGED,
114 static guint g_action_group_signals[NR_SIGNALS];
117 g_action_group_real_has_action (GActionGroup *action_group,
118 const gchar *action_name)
120 return g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, NULL, NULL);
124 g_action_group_real_get_action_enabled (GActionGroup *action_group,
125 const gchar *action_name)
127 gboolean enabled = FALSE;
129 g_action_group_query_action (action_group, action_name, &enabled, NULL, NULL, NULL, NULL);
134 static const GVariantType *
135 g_action_group_real_get_action_parameter_type (GActionGroup *action_group,
136 const gchar *action_name)
138 const GVariantType *type = NULL;
140 g_action_group_query_action (action_group, action_name, NULL, &type, NULL, NULL, NULL);
145 static const GVariantType *
146 g_action_group_real_get_action_state_type (GActionGroup *action_group,
147 const gchar *action_name)
149 const GVariantType *type = NULL;
151 g_action_group_query_action (action_group, action_name, NULL, NULL, &type, NULL, NULL);
157 g_action_group_real_get_action_state_hint (GActionGroup *action_group,
158 const gchar *action_name)
160 GVariant *hint = NULL;
162 g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, &hint, NULL);
168 g_action_group_real_get_action_state (GActionGroup *action_group,
169 const gchar *action_name)
171 GVariant *state = NULL;
173 g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, NULL, &state);
179 g_action_group_real_query_action (GActionGroup *action_group,
180 const gchar *action_name,
182 const GVariantType **parameter_type,
183 const GVariantType **state_type,
184 GVariant **state_hint,
187 GActionGroupInterface *iface = G_ACTION_GROUP_GET_IFACE (action_group);
189 /* we expect implementations to override this method, but we also
190 * allow for implementations that existed before this method was
191 * introduced to override the individual accessors instead.
193 * detect the case that neither has happened and report it.
195 if G_UNLIKELY (iface->has_action == g_action_group_real_has_action ||
196 iface->get_action_enabled == g_action_group_real_get_action_enabled ||
197 iface->get_action_parameter_type == g_action_group_real_get_action_parameter_type ||
198 iface->get_action_state_type == g_action_group_real_get_action_state_type ||
199 iface->get_action_state_hint == g_action_group_real_get_action_state_hint ||
200 iface->get_action_state == g_action_group_real_get_action_state)
202 g_critical ("Class '%s' implements GActionGroup interface without overriding "
203 "query_action() method -- bailing out to avoid infinite recursion.",
204 G_OBJECT_TYPE_NAME (action_group));
208 if (!(* iface->has_action) (action_group, action_name))
212 *enabled = (* iface->get_action_enabled) (action_group, action_name);
214 if (parameter_type != NULL)
215 *parameter_type = (* iface->get_action_parameter_type) (action_group, action_name);
217 if (state_type != NULL)
218 *state_type = (* iface->get_action_state_type) (action_group, action_name);
220 if (state_hint != NULL)
221 *state_hint = (* iface->get_action_state_hint) (action_group, action_name);
224 *state = (* iface->get_action_state) (action_group, action_name);
230 g_action_group_default_init (GActionGroupInterface *iface)
232 iface->has_action = g_action_group_real_has_action;
233 iface->get_action_enabled = g_action_group_real_get_action_enabled;
234 iface->get_action_parameter_type = g_action_group_real_get_action_parameter_type;
235 iface->get_action_state_type = g_action_group_real_get_action_state_type;
236 iface->get_action_state_hint = g_action_group_real_get_action_state_hint;
237 iface->get_action_state = g_action_group_real_get_action_state;
238 iface->query_action = g_action_group_real_query_action;
241 * GActionGroup::action-added:
242 * @action_group: the #GActionGroup that changed
243 * @action_name: the name of the action in @action_group
245 * Signals that a new action was just added to the group.
246 * This signal is emitted after the action has been added
247 * and is now visible.
251 g_action_group_signals[SIGNAL_ACTION_ADDED] =
252 g_signal_new (I_("action-added"),
254 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
255 G_STRUCT_OFFSET (GActionGroupInterface, action_added),
257 g_cclosure_marshal_VOID__STRING,
262 * GActionGroup::action-removed:
263 * @action_group: the #GActionGroup that changed
264 * @action_name: the name of the action in @action_group
266 * Signals that an action is just about to be removed from the group.
267 * This signal is emitted before the action is removed, so the action
268 * is still visible and can be queried from the signal handler.
272 g_action_group_signals[SIGNAL_ACTION_REMOVED] =
273 g_signal_new (I_("action-removed"),
275 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
276 G_STRUCT_OFFSET (GActionGroupInterface, action_removed),
278 g_cclosure_marshal_VOID__STRING,
284 * GActionGroup::action-enabled-changed:
285 * @action_group: the #GActionGroup that changed
286 * @action_name: the name of the action in @action_group
287 * @enabled: whether the action is enabled or not
289 * Signals that the enabled status of the named action has changed.
293 g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED] =
294 g_signal_new (I_("action-enabled-changed"),
296 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
297 G_STRUCT_OFFSET (GActionGroupInterface,
298 action_enabled_changed),
306 * GActionGroup::action-state-changed:
307 * @action_group: the #GActionGroup that changed
308 * @action_name: the name of the action in @action_group
309 * @value: the new value of the state
311 * Signals that the state of the named action has changed.
315 g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED] =
316 g_signal_new (I_("action-state-changed"),
320 G_SIGNAL_MUST_COLLECT,
321 G_STRUCT_OFFSET (GActionGroupInterface,
322 action_state_changed),
331 * g_action_group_list_actions:
332 * @action_group: a #GActionGroup
334 * Lists the actions contained within @action_group.
336 * The caller is responsible for freeing the list with g_strfreev() when
337 * it is no longer required.
339 * Returns: (transfer full): a %NULL-terminated array of the names of the
340 * actions in the groupb
345 g_action_group_list_actions (GActionGroup *action_group)
347 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
349 return G_ACTION_GROUP_GET_IFACE (action_group)
350 ->list_actions (action_group);
354 * g_action_group_has_action:
355 * @action_group: a #GActionGroup
356 * @action_name: the name of the action to check for
358 * Checks if the named action exists within @action_group.
360 * Returns: whether the named action exists
365 g_action_group_has_action (GActionGroup *action_group,
366 const gchar *action_name)
368 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
370 return G_ACTION_GROUP_GET_IFACE (action_group)
371 ->has_action (action_group, action_name);
375 * g_action_group_get_action_parameter_type:
376 * @action_group: a #GActionGroup
377 * @action_name: the name of the action to query
379 * Queries the type of the parameter that must be given when activating
380 * the named action within @action_group.
382 * When activating the action using g_action_group_activate_action(),
383 * the #GVariant given to that function must be of the type returned
386 * In the case that this function returns %NULL, you must not give any
387 * #GVariant, but %NULL instead.
389 * The parameter type of a particular action will never change but it is
390 * possible for an action to be removed and for a new action to be added
391 * with the same name but a different parameter type.
393 * Return value: the parameter type
398 g_action_group_get_action_parameter_type (GActionGroup *action_group,
399 const gchar *action_name)
401 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
403 return G_ACTION_GROUP_GET_IFACE (action_group)
404 ->get_action_parameter_type (action_group, action_name);
408 * g_action_group_get_action_state_type:
409 * @action_group: a #GActionGroup
410 * @action_name: the name of the action to query
412 * Queries the type of the state of the named action within
415 * If the action is stateful then this function returns the
416 * #GVariantType of the state. All calls to
417 * g_action_group_change_action_state() must give a #GVariant of this
418 * type and g_action_group_get_action_state() will return a #GVariant
421 * If the action is not stateful then this function will return %NULL.
422 * In that case, g_action_group_get_action_state() will return %NULL
423 * and you must not call g_action_group_change_action_state().
425 * The state type of a particular action will never change but it is
426 * possible for an action to be removed and for a new action to be added
427 * with the same name but a different state type.
429 * Returns: (transfer full): the state type, if the action is stateful
434 g_action_group_get_action_state_type (GActionGroup *action_group,
435 const gchar *action_name)
437 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
439 return G_ACTION_GROUP_GET_IFACE (action_group)
440 ->get_action_state_type (action_group, action_name);
444 * g_action_group_get_action_state_hint:
445 * @action_group: a #GActionGroup
446 * @action_name: the name of the action to query
448 * Requests a hint about the valid range of values for the state of the
449 * named action within @action_group.
451 * If %NULL is returned it either means that the action is not stateful
452 * or that there is no hint about the valid range of values for the
453 * state of the action.
455 * If a #GVariant array is returned then each item in the array is a
456 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
457 * returned then the tuple specifies the inclusive lower and upper bound
458 * of valid values for the state.
460 * In any case, the information is merely a hint. It may be possible to
461 * have a state value outside of the hinted range and setting a value
462 * within the range may fail.
464 * The return value (if non-%NULL) should be freed with
465 * g_variant_unref() when it is no longer required.
467 * Return value: (transfer full): the state range hint
472 g_action_group_get_action_state_hint (GActionGroup *action_group,
473 const gchar *action_name)
475 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
477 return G_ACTION_GROUP_GET_IFACE (action_group)
478 ->get_action_state_hint (action_group, action_name);
482 * g_action_group_get_action_enabled:
483 * @action_group: a #GActionGroup
484 * @action_name: the name of the action to query
486 * Checks if the named action within @action_group is currently enabled.
488 * An action must be enabled in order to be activated or in order to
489 * have its state changed from outside callers.
491 * Return value: whether or not the action is currently enabled
496 g_action_group_get_action_enabled (GActionGroup *action_group,
497 const gchar *action_name)
499 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
501 return G_ACTION_GROUP_GET_IFACE (action_group)
502 ->get_action_enabled (action_group, action_name);
506 * g_action_group_get_action_state:
507 * @action_group: a #GActionGroup
508 * @action_name: the name of the action to query
510 * Queries the current state of the named action within @action_group.
512 * If the action is not stateful then %NULL will be returned. If the
513 * action is stateful then the type of the return value is the type
514 * given by g_action_group_get_action_state_type().
516 * The return value (if non-%NULL) should be freed with
517 * g_variant_unref() when it is no longer required.
519 * Return value: (allow-none): the current state of the action
524 g_action_group_get_action_state (GActionGroup *action_group,
525 const gchar *action_name)
527 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
529 return G_ACTION_GROUP_GET_IFACE (action_group)
530 ->get_action_state (action_group, action_name);
534 * g_action_group_change_action_state:
535 * @action_group: a #GActionGroup
536 * @action_name: the name of the action to request the change on
537 * @value: the new state
539 * Request for the state of the named action within @action_group to be
542 * The action must be stateful and @value must be of the correct type.
543 * See g_action_group_get_action_state_type().
545 * This call merely requests a change. The action may refuse to change
546 * its state or may change its state to something other than @value.
547 * See g_action_group_get_action_state_hint().
549 * If the @value GVariant is floating, it is consumed.
554 g_action_group_change_action_state (GActionGroup *action_group,
555 const gchar *action_name,
558 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
559 g_return_if_fail (action_name != NULL);
560 g_return_if_fail (value != NULL);
562 G_ACTION_GROUP_GET_IFACE (action_group)
563 ->change_action_state (action_group, action_name, value);
567 * g_action_group_activate_action:
568 * @action_group: a #GActionGroup
569 * @action_name: the name of the action to activate
570 * @parameter: (allow-none): parameters to the activation
572 * Activate the named action within @action_group.
574 * If the action is expecting a parameter, then the correct type of
575 * parameter must be given as @parameter. If the action is expecting no
576 * parameters then @parameter must be %NULL. See
577 * g_action_group_get_action_parameter_type().
582 g_action_group_activate_action (GActionGroup *action_group,
583 const gchar *action_name,
586 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
587 g_return_if_fail (action_name != NULL);
589 G_ACTION_GROUP_GET_IFACE (action_group)
590 ->activate_action (action_group, action_name, parameter);
594 * g_action_group_action_added:
595 * @action_group: a #GActionGroup
596 * @action_name: the name of an action in the group
598 * Emits the #GActionGroup::action-added signal on @action_group.
600 * This function should only be called by #GActionGroup implementations.
605 g_action_group_action_added (GActionGroup *action_group,
606 const gchar *action_name)
608 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
609 g_return_if_fail (action_name != NULL);
611 g_signal_emit (action_group,
612 g_action_group_signals[SIGNAL_ACTION_ADDED],
613 g_quark_try_string (action_name),
618 * g_action_group_action_removed:
619 * @action_group: a #GActionGroup
620 * @action_name: the name of an action in the group
622 * Emits the #GActionGroup::action-removed signal on @action_group.
624 * This function should only be called by #GActionGroup implementations.
629 g_action_group_action_removed (GActionGroup *action_group,
630 const gchar *action_name)
632 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
633 g_return_if_fail (action_name != NULL);
635 g_signal_emit (action_group,
636 g_action_group_signals[SIGNAL_ACTION_REMOVED],
637 g_quark_try_string (action_name),
642 * g_action_group_action_enabled_changed:
643 * @action_group: a #GActionGroup
644 * @action_name: the name of an action in the group
645 * @enabled: whether or not the action is now enabled
647 * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
649 * This function should only be called by #GActionGroup implementations.
654 g_action_group_action_enabled_changed (GActionGroup *action_group,
655 const gchar *action_name,
658 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
659 g_return_if_fail (action_name != NULL);
663 g_signal_emit (action_group,
664 g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED],
665 g_quark_try_string (action_name),
671 * g_action_group_action_state_changed:
672 * @action_group: a #GActionGroup
673 * @action_name: the name of an action in the group
674 * @state: the new state of the named action
676 * Emits the #GActionGroup::action-state-changed signal on @action_group.
678 * This function should only be called by #GActionGroup implementations.
683 g_action_group_action_state_changed (GActionGroup *action_group,
684 const gchar *action_name,
687 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
688 g_return_if_fail (action_name != NULL);
690 g_signal_emit (action_group,
691 g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED],
692 g_quark_try_string (action_name),
698 * g_action_group_query_action:
699 * @action_group: a #GActionGroup
700 * @action_name: the name of an action in the group
701 * @enabled: (out): if the action is presently enabled
702 * @parameter_type: (out): the parameter type, or %NULL if none needed
703 * @state_type: (out): the state type, or %NULL if stateless
704 * @state_hint: (out): the state hint, or %NULL if none
705 * @state: (out): the current state, or %NULL if stateless
707 * Queries all aspects of the named action within an @action_group.
709 * This function acquires the information available from
710 * g_action_group_has_action(), g_action_group_get_action_enabled(),
711 * g_action_group_get_action_parameter_type(),
712 * g_action_group_get_action_state_type(),
713 * g_action_group_get_action_state_hint() and
714 * g_action_group_get_action_state() with a single function call.
716 * This provides two main benefits.
718 * The first is the improvement in efficiency that comes with not having
719 * to perform repeated lookups of the action in order to discover
720 * different things about it. The second is that implementing
721 * #GActionGroup can now be done by only overriding this one virtual
724 * The interface provides a default implementation of this function that
725 * calls the individual functions, as required, to fetch the
726 * information. The interface also provides default implementations of
727 * those functions that call this function. All implementations,
728 * therefore, must override either this function or all of the others.
730 * If the action exists, %TRUE is returned and any of the requested
731 * fields (as indicated by having a non-%NULL reference passed in) are
732 * filled. If the action doesn't exist, %FALSE is returned and the
733 * fields may or may not have been modified.
735 * Returns: %TRUE if the action exists, else %FALSE
740 g_action_group_query_action (GActionGroup *action_group,
741 const gchar *action_name,
743 const GVariantType **parameter_type,
744 const GVariantType **state_type,
745 GVariant **state_hint,
748 return G_ACTION_GROUP_GET_IFACE (action_group)
749 ->query_action (action_group, action_name, enabled, parameter_type, state_type, state_hint, state);