gio/gactiongroup.c

   1 /*
   2  * Copyright © 2010 Codethink Limited
   3  *
   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.
   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, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  17  * Boston, MA 02111-1307, USA.
  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
  27 /**
  28  * SECTION:gactiongroup
  29  * @title: GActionGroup
  30  * @short_description: A group of actions
  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 <function>set()</function> 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  * 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
  97  *
  98  * The virtual function table for #GActionGroup.
  99  *
 100  * Since: 2.28
 101  **/
 102
 103 G_DEFINE_INTERFACE (GActionGroup, g_action_group, G_TYPE_OBJECT)
 104
 105 enum
 106 {
 107   SIGNAL_ACTION_ADDED,
 108   SIGNAL_ACTION_REMOVED,
 109   SIGNAL_ACTION_ENABLED_CHANGED,
 110   SIGNAL_ACTION_STATE_CHANGED,
 111   NR_SIGNALS
 112 };
 113
 114 static guint g_action_group_signals[NR_SIGNALS];
 115
 116 static gboolean
 117 g_action_group_real_has_action (GActionGroup *action_group,
 118                                 const gchar  *action_name)
 119 {
 120   return g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, NULL, NULL);
 121 }
 122
 123 static gboolean
 124 g_action_group_real_get_action_enabled (GActionGroup *action_group,
 125                                         const gchar  *action_name)
 126 {
 127   gboolean enabled = FALSE;
 128
 129   g_action_group_query_action (action_group, action_name, &enabled, NULL, NULL, NULL, NULL);
 130
 131   return enabled;
 132 }
 133
 134 static const GVariantType *
 135 g_action_group_real_get_action_parameter_type (GActionGroup *action_group,
 136                                                const gchar  *action_name)
 137 {
 138   const GVariantType *type = NULL;
 139
 140   g_action_group_query_action (action_group, action_name, NULL, &type, NULL, NULL, NULL);
 141
 142   return type;
 143 }
 144
 145 static const GVariantType *
 146 g_action_group_real_get_action_state_type (GActionGroup *action_group,
 147                                            const gchar  *action_name)
 148 {
 149   const GVariantType *type = NULL;
 150
 151   g_action_group_query_action (action_group, action_name, NULL, NULL, &type, NULL, NULL);
 152
 153   return type;
 154 }
 155
 156 static GVariant *
 157 g_action_group_real_get_action_state_hint (GActionGroup *action_group,
 158                                            const gchar  *action_name)
 159 {
 160   GVariant *hint = NULL;
 161
 162   g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, &hint, NULL);
 163
 164   return hint;
 165 }
 166
 167 static GVariant *
 168 g_action_group_real_get_action_state (GActionGroup *action_group,
 169                                       const gchar  *action_name)
 170 {
 171   GVariant *state = NULL;
 172
 173   g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, NULL, &state);
 174
 175   return state;
 176 }
 177
 178 static gboolean
 179 g_action_group_real_query_action (GActionGroup        *action_group,
 180                                   const gchar         *action_name,
 181                                   gboolean            *enabled,
 182                                   const GVariantType **parameter_type,
 183                                   const GVariantType **state_type,
 184                                   GVariant           **state_hint,
 185                                   GVariant           **state)
 186 {
 187   GActionGroupInterface *iface = G_ACTION_GROUP_GET_IFACE (action_group);
 188
 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.
 192    *
 193    * detect the case that neither has happened and report it.
 194    */
 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)
 201     {
 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));
 205       return FALSE;
 206     }
 207
 208   if (!(* iface->has_action) (action_group, action_name))
 209     return FALSE;
 210
 211   if (enabled != NULL)
 212     *enabled = (* iface->get_action_enabled) (action_group, action_name);
 213
 214   if (parameter_type != NULL)
 215     *parameter_type = (* iface->get_action_parameter_type) (action_group, action_name);
 216
 217   if (state_type != NULL)
 218     *state_type = (* iface->get_action_state_type) (action_group, action_name);
 219
 220   if (state_hint != NULL)
 221     *state_hint = (* iface->get_action_state_hint) (action_group, action_name);
 222
 223   if (state != NULL)
 224     *state = (* iface->get_action_state) (action_group, action_name);
 225
 226   return TRUE;
 227 }
 228
 229 static void
 230 g_action_group_default_init (GActionGroupInterface *iface)
 231 {
 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;
 239
 240   /**
 241    * GActionGroup::action-added:
 242    * @action_group: the #GActionGroup that changed
 243    * @action_name: the name of the action in @action_group
 244    *
 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.
 248    *
 249    * Since: 2.28
 250    **/
 251   g_action_group_signals[SIGNAL_ACTION_ADDED] =
 252     g_signal_new (I_("action-added"),
 253                   G_TYPE_ACTION_GROUP,
 254                   G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
 255                   G_STRUCT_OFFSET (GActionGroupInterface, action_added),
 256                   NULL, NULL,
 257                   g_cclosure_marshal_VOID__STRING,
 258                   G_TYPE_NONE, 1,
 259                   G_TYPE_STRING);
 260
 261   /**
 262    * GActionGroup::action-removed:
 263    * @action_group: the #GActionGroup that changed
 264    * @action_name: the name of the action in @action_group
 265    *
 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.
 269    *
 270    * Since: 2.28
 271    **/
 272   g_action_group_signals[SIGNAL_ACTION_REMOVED] =
 273     g_signal_new (I_("action-removed"),
 274                   G_TYPE_ACTION_GROUP,
 275                   G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
 276                   G_STRUCT_OFFSET (GActionGroupInterface, action_removed),
 277                   NULL, NULL,
 278                   g_cclosure_marshal_VOID__STRING,
 279                   G_TYPE_NONE, 1,
 280                   G_TYPE_STRING);
 281
 282
 283   /**
 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
 288    *
 289    * Signals that the enabled status of the named action has changed.
 290    *
 291    * Since: 2.28
 292    **/
 293   g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED] =
 294     g_signal_new (I_("action-enabled-changed"),
 295                   G_TYPE_ACTION_GROUP,
 296                   G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
 297                   G_STRUCT_OFFSET (GActionGroupInterface,
 298                                    action_enabled_changed),
 299                   NULL, NULL,
 300                   NULL,
 301                   G_TYPE_NONE, 2,
 302                   G_TYPE_STRING,
 303                   G_TYPE_BOOLEAN);
 304
 305   /**
 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
 310    *
 311    * Signals that the state of the named action has changed.
 312    *
 313    * Since: 2.28
 314    **/
 315   g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED] =
 316     g_signal_new (I_("action-state-changed"),
 317                   G_TYPE_ACTION_GROUP,
 318                   G_SIGNAL_RUN_LAST |
 319                   G_SIGNAL_DETAILED |
 320                   G_SIGNAL_MUST_COLLECT,
 321                   G_STRUCT_OFFSET (GActionGroupInterface,
 322                                    action_state_changed),
 323                   NULL, NULL,
 324                   NULL,
 325                   G_TYPE_NONE, 2,
 326                   G_TYPE_STRING,
 327                   G_TYPE_VARIANT);
 328 }
 329
 330 /**
 331  * g_action_group_list_actions:
 332  * @action_group: a #GActionGroup
 333  *
 334  * Lists the actions contained within @action_group.
 335  *
 336  * The caller is responsible for freeing the list with g_strfreev() when
 337  * it is no longer required.
 338  *
 339  * Returns: (transfer full): a %NULL-terminated array of the names of the
 340  * actions in the groupb
 341  *
 342  * Since: 2.28
 343  **/
 344 gchar **
 345 g_action_group_list_actions (GActionGroup *action_group)
 346 {
 347   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
 348
 349   return G_ACTION_GROUP_GET_IFACE (action_group)
 350     ->list_actions (action_group);
 351 }
 352
 353 /**
 354  * g_action_group_has_action:
 355  * @action_group: a #GActionGroup
 356  * @action_name: the name of the action to check for
 357  *
 358  * Checks if the named action exists within @action_group.
 359  *
 360  * Returns: whether the named action exists
 361  *
 362  * Since: 2.28
 363  **/
 364 gboolean
 365 g_action_group_has_action (GActionGroup *action_group,
 366                            const gchar  *action_name)
 367 {
 368   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
 369
 370   return G_ACTION_GROUP_GET_IFACE (action_group)
 371     ->has_action (action_group, action_name);
 372 }
 373
 374 /**
 375  * g_action_group_get_action_parameter_type:
 376  * @action_group: a #GActionGroup
 377  * @action_name: the name of the action to query
 378  *
 379  * Queries the type of the parameter that must be given when activating
 380  * the named action within @action_group.
 381  *
 382  * When activating the action using g_action_group_activate_action(),
 383  * the #GVariant given to that function must be of the type returned
 384  * by this function.
 385  *
 386  * In the case that this function returns %NULL, you must not give any
 387  * #GVariant, but %NULL instead.
 388  *
 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.
 392  *
 393  * Return value: the parameter type
 394  *
 395  * Since: 2.28
 396  **/
 397 const GVariantType *
 398 g_action_group_get_action_parameter_type (GActionGroup *action_group,
 399                                           const gchar  *action_name)
 400 {
 401   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
 402
 403   return G_ACTION_GROUP_GET_IFACE (action_group)
 404     ->get_action_parameter_type (action_group, action_name);
 405 }
 406
 407 /**
 408  * g_action_group_get_action_state_type:
 409  * @action_group: a #GActionGroup
 410  * @action_name: the name of the action to query
 411  *
 412  * Queries the type of the state of the named action within
 413  * @action_group.
 414  *
 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
 419  * of the same type.
 420  *
 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().
 424  *
 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.
 428  *
 429  * Returns: (transfer full): the state type, if the action is stateful
 430  *
 431  * Since: 2.28
 432  **/
 433 const GVariantType *
 434 g_action_group_get_action_state_type (GActionGroup *action_group,
 435                                       const gchar  *action_name)
 436 {
 437   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
 438
 439   return G_ACTION_GROUP_GET_IFACE (action_group)
 440     ->get_action_state_type (action_group, action_name);
 441 }
 442
 443 /**
 444  * g_action_group_get_action_state_hint:
 445  * @action_group: a #GActionGroup
 446  * @action_name: the name of the action to query
 447  *
 448  * Requests a hint about the valid range of values for the state of the
 449  * named action within @action_group.
 450  *
 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.
 454  *
 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.
 459  *
 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.
 463  *
 464  * The return value (if non-%NULL) should be freed with
 465  * g_variant_unref() when it is no longer required.
 466  *
 467  * Return value: (transfer full): the state range hint
 468  *
 469  * Since: 2.28
 470  **/
 471 GVariant *
 472 g_action_group_get_action_state_hint (GActionGroup *action_group,
 473                                       const gchar  *action_name)
 474 {
 475   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
 476
 477   return G_ACTION_GROUP_GET_IFACE (action_group)
 478     ->get_action_state_hint (action_group, action_name);
 479 }
 480
 481 /**
 482  * g_action_group_get_action_enabled:
 483  * @action_group: a #GActionGroup
 484  * @action_name: the name of the action to query
 485  *
 486  * Checks if the named action within @action_group is currently enabled.
 487  *
 488  * An action must be enabled in order to be activated or in order to
 489  * have its state changed from outside callers.
 490  *
 491  * Return value: whether or not the action is currently enabled
 492  *
 493  * Since: 2.28
 494  **/
 495 gboolean
 496 g_action_group_get_action_enabled (GActionGroup *action_group,
 497                                    const gchar  *action_name)
 498 {
 499   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
 500
 501   return G_ACTION_GROUP_GET_IFACE (action_group)
 502     ->get_action_enabled (action_group, action_name);
 503 }
 504
 505 /**
 506  * g_action_group_get_action_state:
 507  * @action_group: a #GActionGroup
 508  * @action_name: the name of the action to query
 509  *
 510  * Queries the current state of the named action within @action_group.
 511  *
 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().
 515  *
 516  * The return value (if non-%NULL) should be freed with
 517  * g_variant_unref() when it is no longer required.
 518  *
 519  * Return value: (allow-none): the current state of the action
 520  *
 521  * Since: 2.28
 522  **/
 523 GVariant *
 524 g_action_group_get_action_state (GActionGroup *action_group,
 525                                  const gchar  *action_name)
 526 {
 527   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
 528
 529   return G_ACTION_GROUP_GET_IFACE (action_group)
 530     ->get_action_state (action_group, action_name);
 531 }
 532
 533 /**
 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
 538  *
 539  * Request for the state of the named action within @action_group to be
 540  * changed to @value.
 541  *
 542  * The action must be stateful and @value must be of the correct type.
 543  * See g_action_group_get_action_state_type().
 544  *
 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().
 548  *
 549  * If the @value GVariant is floating, it is consumed.
 550  *
 551  * Since: 2.28
 552  **/
 553 void
 554 g_action_group_change_action_state (GActionGroup *action_group,
 555                                     const gchar  *action_name,
 556                                     GVariant     *value)
 557 {
 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);
 561
 562   G_ACTION_GROUP_GET_IFACE (action_group)
 563     ->change_action_state (action_group, action_name, value);
 564 }
 565
 566 /**
 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
 571  *
 572  * Activate the named action within @action_group.
 573  *
 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().
 578  *
 579  * Since: 2.28
 580  **/
 581 void
 582 g_action_group_activate_action (GActionGroup *action_group,
 583                                 const gchar  *action_name,
 584                                 GVariant     *parameter)
 585 {
 586   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 587   g_return_if_fail (action_name != NULL);
 588
 589   G_ACTION_GROUP_GET_IFACE (action_group)
 590     ->activate_action (action_group, action_name, parameter);
 591 }
 592
 593 /**
 594  * g_action_group_action_added:
 595  * @action_group: a #GActionGroup
 596  * @action_name: the name of an action in the group
 597  *
 598  * Emits the #GActionGroup::action-added signal on @action_group.
 599  *
 600  * This function should only be called by #GActionGroup implementations.
 601  *
 602  * Since: 2.28
 603  **/
 604 void
 605 g_action_group_action_added (GActionGroup *action_group,
 606                              const gchar  *action_name)
 607 {
 608   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 609   g_return_if_fail (action_name != NULL);
 610
 611   g_signal_emit (action_group,
 612                  g_action_group_signals[SIGNAL_ACTION_ADDED],
 613                  g_quark_try_string (action_name),
 614                  action_name);
 615 }
 616
 617 /**
 618  * g_action_group_action_removed:
 619  * @action_group: a #GActionGroup
 620  * @action_name: the name of an action in the group
 621  *
 622  * Emits the #GActionGroup::action-removed signal on @action_group.
 623  *
 624  * This function should only be called by #GActionGroup implementations.
 625  *
 626  * Since: 2.28
 627  **/
 628 void
 629 g_action_group_action_removed (GActionGroup *action_group,
 630                                const gchar  *action_name)
 631 {
 632   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 633   g_return_if_fail (action_name != NULL);
 634
 635   g_signal_emit (action_group,
 636                  g_action_group_signals[SIGNAL_ACTION_REMOVED],
 637                  g_quark_try_string (action_name),
 638                  action_name);
 639 }
 640
 641 /**
 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
 646  *
 647  * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
 648  *
 649  * This function should only be called by #GActionGroup implementations.
 650  *
 651  * Since: 2.28
 652  **/
 653 void
 654 g_action_group_action_enabled_changed (GActionGroup *action_group,
 655                                        const gchar  *action_name,
 656                                        gboolean      enabled)
 657 {
 658   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 659   g_return_if_fail (action_name != NULL);
 660
 661   enabled = !!enabled;
 662
 663   g_signal_emit (action_group,
 664                  g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED],
 665                  g_quark_try_string (action_name),
 666                  action_name,
 667                  enabled);
 668 }
 669
 670 /**
 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
 675  *
 676  * Emits the #GActionGroup::action-state-changed signal on @action_group.
 677  *
 678  * This function should only be called by #GActionGroup implementations.
 679  *
 680  * Since: 2.28
 681  **/
 682 void
 683 g_action_group_action_state_changed (GActionGroup *action_group,
 684                                      const gchar  *action_name,
 685                                      GVariant     *state)
 686 {
 687   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 688   g_return_if_fail (action_name != NULL);
 689
 690   g_signal_emit (action_group,
 691                  g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED],
 692                  g_quark_try_string (action_name),
 693                  action_name,
 694                  state);
 695 }
 696
 697 /**
 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
 706  *
 707  * Queries all aspects of the named action within an @action_group.
 708  *
 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.
 715  *
 716  * This provides two main benefits.
 717  *
 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
 722  * function.
 723  *
 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.
 729  *
 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.
 734  *
 735  * Returns: %TRUE if the action exists, else %FALSE
 736  *
 737  * Since: 2.32
 738  **/
 739 gboolean
 740 g_action_group_query_action (GActionGroup        *action_group,
 741                              const gchar         *action_name,
 742                              gboolean            *enabled,
 743                              const GVariantType **parameter_type,
 744                              const GVariantType **state_type,
 745                              GVariant           **state_hint,
 746                              GVariant           **state)
 747 {
 748   return G_ACTION_GROUP_GET_IFACE (action_group)
 749     ->query_action (action_group, action_name, enabled, parameter_type, state_type, state_hint, state);
 750 }