Coverage Report

Created: 2025-06-13 06:55

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