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