gio/gactiongroup.c

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