1/*
2 * Copyright © 2010 Codethink Limited
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
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.
13 *
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/>.
16 *
17 * Authors: Ryan Lortie <desrt@desrt.ca>
18 */
19
20#include "config.h"
21#include "gactiongroup.h"
22#include "gaction.h"
23#include "glibintl.h"
24#include "gmarshal-internal.h"
25
26/**
27 * SECTION:gactiongroup
28 * @title: GActionGroup
29 * @short_description: A group of actions
30 * @include: gio/gio.h
31 * @see_also: #GAction
32 *
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
38 * a menu.
39 *
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.
46 *
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().
52 *
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.
57 *
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.
61 *
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 set() call.
69 *
70 * Signals are emitted on the action group in response to state changes
71 * on individual actions.
72 *
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().
78 */
79
80/**
81 * GActionGroup:
82 *
83 * #GActionGroup is an opaque data structure and can only be accessed
84 * using the following functions.
85 **/
86
87/**
88 * GActionGroupInterface:
89 * @has_action: the virtual function pointer for g_action_group_has_action()
90 * @list_actions: the virtual function pointer for g_action_group_list_actions()
91 * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type()
92 * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type()
93 * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
94 * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
95 * @get_action_state: the virtual function pointer for g_action_group_get_action_state()
96 * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
97 * @query_action: the virtual function pointer for g_action_group_query_action()
98 * @activate_action: the virtual function pointer for g_action_group_activate_action()
99 * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
100 * @action_added: the class closure for the #GActionGroup::action-added signal
101 * @action_removed: the class closure for the #GActionGroup::action-removed signal
102 * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
103 * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal
104 *
105 * The virtual function table for #GActionGroup.
106 *
107 * Since: 2.28
108 **/
109
110G_DEFINE_INTERFACE (GActionGroup, g_action_group, G_TYPE_OBJECT)
111
112enum
113{
114 SIGNAL_ACTION_ADDED,
115 SIGNAL_ACTION_REMOVED,
116 SIGNAL_ACTION_ENABLED_CHANGED,
117 SIGNAL_ACTION_STATE_CHANGED,
118 NR_SIGNALS
119};
120
121static guint g_action_group_signals[NR_SIGNALS];
122
123static gboolean
124g_action_group_real_has_action (GActionGroup *action_group,
125 const gchar *action_name)
126{
127 return g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, NULL, NULL);
128}
129
130static gboolean
131g_action_group_real_get_action_enabled (GActionGroup *action_group,
132 const gchar *action_name)
133{
134 gboolean enabled = FALSE;
135
136 g_action_group_query_action (action_group, action_name, enabled: &enabled, NULL, NULL, NULL, NULL);
137
138 return enabled;
139}
140
141static const GVariantType *
142g_action_group_real_get_action_parameter_type (GActionGroup *action_group,
143 const gchar *action_name)
144{
145 const GVariantType *type = NULL;
146
147 g_action_group_query_action (action_group, action_name, NULL, parameter_type: &type, NULL, NULL, NULL);
148
149 return type;
150}
151
152static const GVariantType *
153g_action_group_real_get_action_state_type (GActionGroup *action_group,
154 const gchar *action_name)
155{
156 const GVariantType *type = NULL;
157
158 g_action_group_query_action (action_group, action_name, NULL, NULL, state_type: &type, NULL, NULL);
159
160 return type;
161}
162
163static GVariant *
164g_action_group_real_get_action_state_hint (GActionGroup *action_group,
165 const gchar *action_name)
166{
167 GVariant *hint = NULL;
168
169 g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, state_hint: &hint, NULL);
170
171 return hint;
172}
173
174static GVariant *
175g_action_group_real_get_action_state (GActionGroup *action_group,
176 const gchar *action_name)
177{
178 GVariant *state = NULL;
179
180 g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, NULL, state: &state);
181
182 return state;
183}
184
185static gboolean
186g_action_group_real_query_action (GActionGroup *action_group,
187 const gchar *action_name,
188 gboolean *enabled,
189 const GVariantType **parameter_type,
190 const GVariantType **state_type,
191 GVariant **state_hint,
192 GVariant **state)
193{
194 GActionGroupInterface *iface = G_ACTION_GROUP_GET_IFACE (action_group);
195
196 /* we expect implementations to override this method, but we also
197 * allow for implementations that existed before this method was
198 * introduced to override the individual accessors instead.
199 *
200 * detect the case that neither has happened and report it.
201 */
202 if G_UNLIKELY (iface->has_action == g_action_group_real_has_action ||
203 iface->get_action_enabled == g_action_group_real_get_action_enabled ||
204 iface->get_action_parameter_type == g_action_group_real_get_action_parameter_type ||
205 iface->get_action_state_type == g_action_group_real_get_action_state_type ||
206 iface->get_action_state_hint == g_action_group_real_get_action_state_hint ||
207 iface->get_action_state == g_action_group_real_get_action_state)
208 {
209 g_critical ("Class '%s' implements GActionGroup interface without overriding "
210 "query_action() method -- bailing out to avoid infinite recursion.",
211 G_OBJECT_TYPE_NAME (action_group));
212 return FALSE;
213 }
214
215 if (!(* iface->has_action) (action_group, action_name))
216 return FALSE;
217
218 if (enabled != NULL)
219 *enabled = (* iface->get_action_enabled) (action_group, action_name);
220
221 if (parameter_type != NULL)
222 *parameter_type = (* iface->get_action_parameter_type) (action_group, action_name);
223
224 if (state_type != NULL)
225 *state_type = (* iface->get_action_state_type) (action_group, action_name);
226
227 if (state_hint != NULL)
228 *state_hint = (* iface->get_action_state_hint) (action_group, action_name);
229
230 if (state != NULL)
231 *state = (* iface->get_action_state) (action_group, action_name);
232
233 return TRUE;
234}
235
236static void
237g_action_group_default_init (GActionGroupInterface *iface)
238{
239 iface->has_action = g_action_group_real_has_action;
240 iface->get_action_enabled = g_action_group_real_get_action_enabled;
241 iface->get_action_parameter_type = g_action_group_real_get_action_parameter_type;
242 iface->get_action_state_type = g_action_group_real_get_action_state_type;
243 iface->get_action_state_hint = g_action_group_real_get_action_state_hint;
244 iface->get_action_state = g_action_group_real_get_action_state;
245 iface->query_action = g_action_group_real_query_action;
246
247 /**
248 * GActionGroup::action-added:
249 * @action_group: the #GActionGroup that changed
250 * @action_name: the name of the action in @action_group
251 *
252 * Signals that a new action was just added to the group.
253 * This signal is emitted after the action has been added
254 * and is now visible.
255 *
256 * Since: 2.28
257 **/
258 g_action_group_signals[SIGNAL_ACTION_ADDED] =
259 g_signal_new (I_("action-added"),
260 G_TYPE_ACTION_GROUP,
261 signal_flags: G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
262 G_STRUCT_OFFSET (GActionGroupInterface, action_added),
263 NULL, NULL,
264 NULL,
265 G_TYPE_NONE, n_params: 1,
266 G_TYPE_STRING);
267
268 /**
269 * GActionGroup::action-removed:
270 * @action_group: the #GActionGroup that changed
271 * @action_name: the name of the action in @action_group
272 *
273 * Signals that an action is just about to be removed from the group.
274 * This signal is emitted before the action is removed, so the action
275 * is still visible and can be queried from the signal handler.
276 *
277 * Since: 2.28
278 **/
279 g_action_group_signals[SIGNAL_ACTION_REMOVED] =
280 g_signal_new (I_("action-removed"),
281 G_TYPE_ACTION_GROUP,
282 signal_flags: G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
283 G_STRUCT_OFFSET (GActionGroupInterface, action_removed),
284 NULL, NULL,
285 NULL,
286 G_TYPE_NONE, n_params: 1,
287 G_TYPE_STRING);
288
289
290 /**
291 * GActionGroup::action-enabled-changed:
292 * @action_group: the #GActionGroup that changed
293 * @action_name: the name of the action in @action_group
294 * @enabled: whether the action is enabled or not
295 *
296 * Signals that the enabled status of the named action has changed.
297 *
298 * Since: 2.28
299 **/
300 g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED] =
301 g_signal_new (I_("action-enabled-changed"),
302 G_TYPE_ACTION_GROUP,
303 signal_flags: G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
304 G_STRUCT_OFFSET (GActionGroupInterface,
305 action_enabled_changed),
306 NULL, NULL,
307 c_marshaller: _g_cclosure_marshal_VOID__STRING_BOOLEAN,
308 G_TYPE_NONE, n_params: 2,
309 G_TYPE_STRING,
310 G_TYPE_BOOLEAN);
311 g_signal_set_va_marshaller (signal_id: g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED],
312 G_TYPE_FROM_INTERFACE (iface),
313 va_marshaller: _g_cclosure_marshal_VOID__STRING_BOOLEANv);
314
315 /**
316 * GActionGroup::action-state-changed:
317 * @action_group: the #GActionGroup that changed
318 * @action_name: the name of the action in @action_group
319 * @value: the new value of the state
320 *
321 * Signals that the state of the named action has changed.
322 *
323 * Since: 2.28
324 **/
325 g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED] =
326 g_signal_new (I_("action-state-changed"),
327 G_TYPE_ACTION_GROUP,
328 signal_flags: G_SIGNAL_RUN_LAST |
329 G_SIGNAL_DETAILED |
330 G_SIGNAL_MUST_COLLECT,
331 G_STRUCT_OFFSET (GActionGroupInterface,
332 action_state_changed),
333 NULL, NULL,
334 c_marshaller: _g_cclosure_marshal_VOID__STRING_VARIANT,
335 G_TYPE_NONE, n_params: 2,
336 G_TYPE_STRING,
337 G_TYPE_VARIANT);
338 g_signal_set_va_marshaller (signal_id: g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED],
339 G_TYPE_FROM_INTERFACE (iface),
340 va_marshaller: _g_cclosure_marshal_VOID__STRING_VARIANTv);
341}
342
343/**
344 * g_action_group_list_actions:
345 * @action_group: a #GActionGroup
346 *
347 * Lists the actions contained within @action_group.
348 *
349 * The caller is responsible for freeing the list with g_strfreev() when
350 * it is no longer required.
351 *
352 * Returns: (transfer full): a %NULL-terminated array of the names of the
353 * actions in the group
354 *
355 * Since: 2.28
356 **/
357gchar **
358g_action_group_list_actions (GActionGroup *action_group)
359{
360 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
361
362 return G_ACTION_GROUP_GET_IFACE (action_group)
363 ->list_actions (action_group);
364}
365
366/**
367 * g_action_group_has_action:
368 * @action_group: a #GActionGroup
369 * @action_name: the name of the action to check for
370 *
371 * Checks if the named action exists within @action_group.
372 *
373 * Returns: whether the named action exists
374 *
375 * Since: 2.28
376 **/
377gboolean
378g_action_group_has_action (GActionGroup *action_group,
379 const gchar *action_name)
380{
381 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
382
383 return G_ACTION_GROUP_GET_IFACE (action_group)
384 ->has_action (action_group, action_name);
385}
386
387/**
388 * g_action_group_get_action_parameter_type:
389 * @action_group: a #GActionGroup
390 * @action_name: the name of the action to query
391 *
392 * Queries the type of the parameter that must be given when activating
393 * the named action within @action_group.
394 *
395 * When activating the action using g_action_group_activate_action(),
396 * the #GVariant given to that function must be of the type returned
397 * by this function.
398 *
399 * In the case that this function returns %NULL, you must not give any
400 * #GVariant, but %NULL instead.
401 *
402 * The parameter type of a particular action will never change but it is
403 * possible for an action to be removed and for a new action to be added
404 * with the same name but a different parameter type.
405 *
406 * Returns: (nullable): the parameter type
407 *
408 * Since: 2.28
409 **/
410const GVariantType *
411g_action_group_get_action_parameter_type (GActionGroup *action_group,
412 const gchar *action_name)
413{
414 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
415
416 return G_ACTION_GROUP_GET_IFACE (action_group)
417 ->get_action_parameter_type (action_group, action_name);
418}
419
420/**
421 * g_action_group_get_action_state_type:
422 * @action_group: a #GActionGroup
423 * @action_name: the name of the action to query
424 *
425 * Queries the type of the state of the named action within
426 * @action_group.
427 *
428 * If the action is stateful then this function returns the
429 * #GVariantType of the state. All calls to
430 * g_action_group_change_action_state() must give a #GVariant of this
431 * type and g_action_group_get_action_state() will return a #GVariant
432 * of the same type.
433 *
434 * If the action is not stateful then this function will return %NULL.
435 * In that case, g_action_group_get_action_state() will return %NULL
436 * and you must not call g_action_group_change_action_state().
437 *
438 * The state type of a particular action will never change but it is
439 * possible for an action to be removed and for a new action to be added
440 * with the same name but a different state type.
441 *
442 * Returns: (nullable): the state type, if the action is stateful
443 *
444 * Since: 2.28
445 **/
446const GVariantType *
447g_action_group_get_action_state_type (GActionGroup *action_group,
448 const gchar *action_name)
449{
450 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
451
452 return G_ACTION_GROUP_GET_IFACE (action_group)
453 ->get_action_state_type (action_group, action_name);
454}
455
456/**
457 * g_action_group_get_action_state_hint:
458 * @action_group: a #GActionGroup
459 * @action_name: the name of the action to query
460 *
461 * Requests a hint about the valid range of values for the state of the
462 * named action within @action_group.
463 *
464 * If %NULL is returned it either means that the action is not stateful
465 * or that there is no hint about the valid range of values for the
466 * state of the action.
467 *
468 * If a #GVariant array is returned then each item in the array is a
469 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
470 * returned then the tuple specifies the inclusive lower and upper bound
471 * of valid values for the state.
472 *
473 * In any case, the information is merely a hint. It may be possible to
474 * have a state value outside of the hinted range and setting a value
475 * within the range may fail.
476 *
477 * The return value (if non-%NULL) should be freed with
478 * g_variant_unref() when it is no longer required.
479 *
480 * Returns: (nullable) (transfer full): the state range hint
481 *
482 * Since: 2.28
483 **/
484GVariant *
485g_action_group_get_action_state_hint (GActionGroup *action_group,
486 const gchar *action_name)
487{
488 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
489
490 return G_ACTION_GROUP_GET_IFACE (action_group)
491 ->get_action_state_hint (action_group, action_name);
492}
493
494/**
495 * g_action_group_get_action_enabled:
496 * @action_group: a #GActionGroup
497 * @action_name: the name of the action to query
498 *
499 * Checks if the named action within @action_group is currently enabled.
500 *
501 * An action must be enabled in order to be activated or in order to
502 * have its state changed from outside callers.
503 *
504 * Returns: whether or not the action is currently enabled
505 *
506 * Since: 2.28
507 **/
508gboolean
509g_action_group_get_action_enabled (GActionGroup *action_group,
510 const gchar *action_name)
511{
512 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
513
514 return G_ACTION_GROUP_GET_IFACE (action_group)
515 ->get_action_enabled (action_group, action_name);
516}
517
518/**
519 * g_action_group_get_action_state:
520 * @action_group: a #GActionGroup
521 * @action_name: the name of the action to query
522 *
523 * Queries the current state of the named action within @action_group.
524 *
525 * If the action is not stateful then %NULL will be returned. If the
526 * action is stateful then the type of the return value is the type
527 * given by g_action_group_get_action_state_type().
528 *
529 * The return value (if non-%NULL) should be freed with
530 * g_variant_unref() when it is no longer required.
531 *
532 * Returns: (nullable) (transfer full): the current state of the action
533 *
534 * Since: 2.28
535 **/
536GVariant *
537g_action_group_get_action_state (GActionGroup *action_group,
538 const gchar *action_name)
539{
540 g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
541
542 return G_ACTION_GROUP_GET_IFACE (action_group)
543 ->get_action_state (action_group, action_name);
544}
545
546/**
547 * g_action_group_change_action_state:
548 * @action_group: a #GActionGroup
549 * @action_name: the name of the action to request the change on
550 * @value: the new state
551 *
552 * Request for the state of the named action within @action_group to be
553 * changed to @value.
554 *
555 * The action must be stateful and @value must be of the correct type.
556 * See g_action_group_get_action_state_type().
557 *
558 * This call merely requests a change. The action may refuse to change
559 * its state or may change its state to something other than @value.
560 * See g_action_group_get_action_state_hint().
561 *
562 * If the @value GVariant is floating, it is consumed.
563 *
564 * Since: 2.28
565 **/
566void
567g_action_group_change_action_state (GActionGroup *action_group,
568 const gchar *action_name,
569 GVariant *value)
570{
571 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
572 g_return_if_fail (action_name != NULL);
573 g_return_if_fail (value != NULL);
574
575 G_ACTION_GROUP_GET_IFACE (action_group)
576 ->change_action_state (action_group, action_name, value);
577}
578
579/**
580 * g_action_group_activate_action:
581 * @action_group: a #GActionGroup
582 * @action_name: the name of the action to activate
583 * @parameter: (nullable): parameters to the activation
584 *
585 * Activate the named action within @action_group.
586 *
587 * If the action is expecting a parameter, then the correct type of
588 * parameter must be given as @parameter. If the action is expecting no
589 * parameters then @parameter must be %NULL. See
590 * g_action_group_get_action_parameter_type().
591 *
592 * If the #GActionGroup implementation supports asynchronous remote
593 * activation over D-Bus, this call may return before the relevant
594 * D-Bus traffic has been sent, or any replies have been received. In
595 * order to block on such asynchronous activation calls,
596 * g_dbus_connection_flush() should be called prior to the code, which
597 * depends on the result of the action activation. Without flushing
598 * the D-Bus connection, there is no guarantee that the action would
599 * have been activated.
600 *
601 * The following code which runs in a remote app instance, shows an
602 * example of a "quit" action being activated on the primary app
603 * instance over D-Bus. Here g_dbus_connection_flush() is called
604 * before `exit()`. Without g_dbus_connection_flush(), the "quit" action
605 * may fail to be activated on the primary instance.
606 *
607 * |[<!-- language="C" -->
608 * // call "quit" action on primary instance
609 * g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);
610 *
611 * // make sure the action is activated now
612 * g_dbus_connection_flush (...);
613 *
614 * g_debug ("application has been terminated. exiting.");
615 *
616 * exit (0);
617 * ]|
618 *
619 * Since: 2.28
620 **/
621void
622g_action_group_activate_action (GActionGroup *action_group,
623 const gchar *action_name,
624 GVariant *parameter)
625{
626 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
627 g_return_if_fail (action_name != NULL);
628
629 G_ACTION_GROUP_GET_IFACE (action_group)
630 ->activate_action (action_group, action_name, parameter);
631}
632
633/**
634 * g_action_group_action_added:
635 * @action_group: a #GActionGroup
636 * @action_name: the name of an action in the group
637 *
638 * Emits the #GActionGroup::action-added signal on @action_group.
639 *
640 * This function should only be called by #GActionGroup implementations.
641 *
642 * Since: 2.28
643 **/
644void
645g_action_group_action_added (GActionGroup *action_group,
646 const gchar *action_name)
647{
648 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
649 g_return_if_fail (action_name != NULL);
650
651 g_signal_emit (instance: action_group,
652 signal_id: g_action_group_signals[SIGNAL_ACTION_ADDED],
653 detail: g_quark_try_string (string: action_name),
654 action_name);
655}
656
657/**
658 * g_action_group_action_removed:
659 * @action_group: a #GActionGroup
660 * @action_name: the name of an action in the group
661 *
662 * Emits the #GActionGroup::action-removed signal on @action_group.
663 *
664 * This function should only be called by #GActionGroup implementations.
665 *
666 * Since: 2.28
667 **/
668void
669g_action_group_action_removed (GActionGroup *action_group,
670 const gchar *action_name)
671{
672 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
673 g_return_if_fail (action_name != NULL);
674
675 g_signal_emit (instance: action_group,
676 signal_id: g_action_group_signals[SIGNAL_ACTION_REMOVED],
677 detail: g_quark_try_string (string: action_name),
678 action_name);
679}
680
681/**
682 * g_action_group_action_enabled_changed:
683 * @action_group: a #GActionGroup
684 * @action_name: the name of an action in the group
685 * @enabled: whether or not the action is now enabled
686 *
687 * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
688 *
689 * This function should only be called by #GActionGroup implementations.
690 *
691 * Since: 2.28
692 **/
693void
694g_action_group_action_enabled_changed (GActionGroup *action_group,
695 const gchar *action_name,
696 gboolean enabled)
697{
698 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
699 g_return_if_fail (action_name != NULL);
700
701 enabled = !!enabled;
702
703 g_signal_emit (instance: action_group,
704 signal_id: g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED],
705 detail: g_quark_try_string (string: action_name),
706 action_name,
707 enabled);
708}
709
710/**
711 * g_action_group_action_state_changed:
712 * @action_group: a #GActionGroup
713 * @action_name: the name of an action in the group
714 * @state: the new state of the named action
715 *
716 * Emits the #GActionGroup::action-state-changed signal on @action_group.
717 *
718 * This function should only be called by #GActionGroup implementations.
719 *
720 * Since: 2.28
721 **/
722void
723g_action_group_action_state_changed (GActionGroup *action_group,
724 const gchar *action_name,
725 GVariant *state)
726{
727 g_return_if_fail (G_IS_ACTION_GROUP (action_group));
728 g_return_if_fail (action_name != NULL);
729
730 g_signal_emit (instance: action_group,
731 signal_id: g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED],
732 detail: g_quark_try_string (string: action_name),
733 action_name,
734 state);
735}
736
737/**
738 * g_action_group_query_action:
739 * @action_group: a #GActionGroup
740 * @action_name: the name of an action in the group
741 * @enabled: (out): if the action is presently enabled
742 * @parameter_type: (out) (optional): the parameter type, or %NULL if none needed
743 * @state_type: (out) (optional): the state type, or %NULL if stateless
744 * @state_hint: (out) (optional): the state hint, or %NULL if none
745 * @state: (out) (optional): the current state, or %NULL if stateless
746 *
747 * Queries all aspects of the named action within an @action_group.
748 *
749 * This function acquires the information available from
750 * g_action_group_has_action(), g_action_group_get_action_enabled(),
751 * g_action_group_get_action_parameter_type(),
752 * g_action_group_get_action_state_type(),
753 * g_action_group_get_action_state_hint() and
754 * g_action_group_get_action_state() with a single function call.
755 *
756 * This provides two main benefits.
757 *
758 * The first is the improvement in efficiency that comes with not having
759 * to perform repeated lookups of the action in order to discover
760 * different things about it. The second is that implementing
761 * #GActionGroup can now be done by only overriding this one virtual
762 * function.
763 *
764 * The interface provides a default implementation of this function that
765 * calls the individual functions, as required, to fetch the
766 * information. The interface also provides default implementations of
767 * those functions that call this function. All implementations,
768 * therefore, must override either this function or all of the others.
769 *
770 * If the action exists, %TRUE is returned and any of the requested
771 * fields (as indicated by having a non-%NULL reference passed in) are
772 * filled. If the action doesn't exist, %FALSE is returned and the
773 * fields may or may not have been modified.
774 *
775 * Returns: %TRUE if the action exists, else %FALSE
776 *
777 * Since: 2.32
778 **/
779gboolean
780g_action_group_query_action (GActionGroup *action_group,
781 const gchar *action_name,
782 gboolean *enabled,
783 const GVariantType **parameter_type,
784 const GVariantType **state_type,
785 GVariant **state_hint,
786 GVariant **state)
787{
788 return G_ACTION_GROUP_GET_IFACE (action_group)
789 ->query_action (action_group, action_name, enabled, parameter_type, state_type, state_hint, state);
790}
791

source code of gtk/subprojects/glib/gio/gactiongroup.c