gio/gsimpleaction.c

   1 /*
   2  * Copyright © 2010 Codethink Limited
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-or-later
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General
  17  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  *
  19  * Authors: Ryan Lortie <desrt@desrt.ca>
  20  */
  21
  22 #include "config.h"
  23
  24 #include "gsimpleaction.h"
  25
  26 #include "gaction.h"
  27 #include "glibintl.h"
  28
  29 /**
  30  * SECTION:gsimpleaction
  31  * @title: GSimpleAction
  32  * @short_description: A simple GAction implementation
  33  * @include: gio/gio.h
  34  *
  35  * A #GSimpleAction is the obvious simple implementation of the #GAction
  36  * interface. This is the easiest way to create an action for purposes of
  37  * adding it to a #GSimpleActionGroup.
  38  *
  39  * See also #GtkAction.
  40  */
  41
  42 /**
  43  * GSimpleAction:
  44  *
  45  * #GSimpleAction is an opaque data structure and can only be accessed
  46  * using the following functions.
  47  **/
  48
  49 struct _GSimpleAction
  50 {
  51   GObject       parent_instance;
  52
  53   gchar        *name;
  54   GVariantType *parameter_type;
  55   gboolean      enabled;
  56   GVariant     *state;
  57   GVariant     *state_hint;
  58   gboolean      state_set_already;
  59 };
  60
  61 typedef GObjectClass GSimpleActionClass;
  62
  63 static void g_simple_action_iface_init (GActionInterface *iface);
  64 G_DEFINE_TYPE_WITH_CODE (GSimpleAction, g_simple_action, G_TYPE_OBJECT,
  65   G_IMPLEMENT_INTERFACE (G_TYPE_ACTION, g_simple_action_iface_init))
  66
  67 enum
  68 {
  69   PROP_NONE,
  70   PROP_NAME,
  71   PROP_PARAMETER_TYPE,
  72   PROP_ENABLED,
  73   PROP_STATE_TYPE,
  74   PROP_STATE
  75 };
  76
  77 enum
  78 {
  79   SIGNAL_CHANGE_STATE,
  80   SIGNAL_ACTIVATE,
  81   NR_SIGNALS
  82 };
  83
  84 static guint g_simple_action_signals[NR_SIGNALS];
  85
  86 static const gchar *
  87 g_simple_action_get_name (GAction *action)
  88 {
  89   GSimpleAction *simple = G_SIMPLE_ACTION (action);
  90
  91   return simple->name;
  92 }
  93
  94 static const GVariantType *
  95 g_simple_action_get_parameter_type (GAction *action)
  96 {
  97   GSimpleAction *simple = G_SIMPLE_ACTION (action);
  98
  99   return simple->parameter_type;
 100 }
 101
 102 static const GVariantType *
 103 g_simple_action_get_state_type (GAction *action)
 104 {
 105   GSimpleAction *simple = G_SIMPLE_ACTION (action);
 106
 107   if (simple->state != NULL)
 108     return g_variant_get_type (simple->state);
 109   else
 110     return NULL;
 111 }
 112
 113 static GVariant *
 114 g_simple_action_get_state_hint (GAction *action)
 115 {
 116   GSimpleAction *simple = G_SIMPLE_ACTION (action);
 117
 118   if (simple->state_hint != NULL)
 119     return g_variant_ref (simple->state_hint);
 120   else
 121     return NULL;
 122 }
 123
 124 static gboolean
 125 g_simple_action_get_enabled (GAction *action)
 126 {
 127   GSimpleAction *simple = G_SIMPLE_ACTION (action);
 128
 129   return simple->enabled;
 130 }
 131
 132 static void
 133 g_simple_action_change_state (GAction  *action,
 134                               GVariant *value)
 135 {
 136   GSimpleAction *simple = G_SIMPLE_ACTION (action);
 137
 138   /* If the user connected a signal handler then they are responsible
 139    * for handling state changes.
 140    */
 141   if (g_signal_has_handler_pending (action, g_simple_action_signals[SIGNAL_CHANGE_STATE], 0, TRUE))
 142     g_signal_emit (action, g_simple_action_signals[SIGNAL_CHANGE_STATE], 0, value);
 143
 144   /* If not, then the default behaviour is to just set the state. */
 145   else
 146     g_simple_action_set_state (simple, value);
 147 }
 148
 149 /**
 150  * g_simple_action_set_state:
 151  * @simple: a #GSimpleAction
 152  * @value: the new #GVariant for the state
 153  *
 154  * Sets the state of the action.
 155  *
 156  * This directly updates the 'state' property to the given value.
 157  *
 158  * This should only be called by the implementor of the action.  Users
 159  * of the action should not attempt to directly modify the 'state'
 160  * property.  Instead, they should call g_action_change_state() to
 161  * request the change.
 162  *
 163  * If the @value GVariant is floating, it is consumed.
 164  *
 165  * Since: 2.30
 166  **/
 167 void
 168 g_simple_action_set_state (GSimpleAction *simple,
 169                            GVariant      *value)
 170 {
 171   g_return_if_fail (G_IS_SIMPLE_ACTION (simple));
 172   g_return_if_fail (value != NULL);
 173
 174   {
 175     const GVariantType *state_type;
 176
 177     state_type = simple->state ?
 178                    g_variant_get_type (simple->state) : NULL;
 179     g_return_if_fail (state_type != NULL);
 180     g_return_if_fail (g_variant_is_of_type (value, state_type));
 181   }
 182
 183   g_variant_ref_sink (value);
 184
 185   if (!simple->state || !g_variant_equal (simple->state, value))
 186     {
 187       if (simple->state)
 188         g_variant_unref (simple->state);
 189
 190       simple->state = g_variant_ref (value);
 191
 192       g_object_notify (G_OBJECT (simple), "state");
 193     }
 194
 195   g_variant_unref (value);
 196 }
 197
 198 static GVariant *
 199 g_simple_action_get_state (GAction *action)
 200 {
 201   GSimpleAction *simple = G_SIMPLE_ACTION (action);
 202
 203   return simple->state ? g_variant_ref (simple->state) : NULL;
 204 }
 205
 206 static void
 207 g_simple_action_activate (GAction  *action,
 208                           GVariant *parameter)
 209 {
 210   GSimpleAction *simple = G_SIMPLE_ACTION (action);
 211
 212   g_return_if_fail (simple->parameter_type == NULL ?
 213                       parameter == NULL :
 214                     (parameter != NULL &&
 215                      g_variant_is_of_type (parameter,
 216                                            simple->parameter_type)));
 217
 218   if (parameter != NULL)
 219     g_variant_ref_sink (parameter);
 220
 221   if (simple->enabled)
 222     {
 223       /* If the user connected a signal handler then they are responsible
 224        * for handling activation.
 225        */
 226       if (g_signal_has_handler_pending (action, g_simple_action_signals[SIGNAL_ACTIVATE], 0, TRUE))
 227         g_signal_emit (action, g_simple_action_signals[SIGNAL_ACTIVATE], 0, parameter);
 228
 229       /* If not, do some reasonable defaults for stateful actions. */
 230       else if (simple->state)
 231         {
 232           /* If we have no parameter and this is a boolean action, toggle. */
 233           if (parameter == NULL && g_variant_is_of_type (simple->state, G_VARIANT_TYPE_BOOLEAN))
 234             {
 235               gboolean was_enabled = g_variant_get_boolean (simple->state);
 236               g_simple_action_change_state (action, g_variant_new_boolean (!was_enabled));
 237             }
 238
 239           /* else, if the parameter and state type are the same, do a change-state */
 240           else if (g_variant_is_of_type (simple->state, g_variant_get_type (parameter)))
 241             g_simple_action_change_state (action, parameter);
 242         }
 243     }
 244
 245   if (parameter != NULL)
 246     g_variant_unref (parameter);
 247 }
 248
 249 static void
 250 g_simple_action_set_property (GObject    *object,
 251                               guint       prop_id,
 252                               const GValue     *value,
 253                               GParamSpec *pspec)
 254 {
 255   GSimpleAction *action = G_SIMPLE_ACTION (object);
 256
 257   switch (prop_id)
 258     {
 259     case PROP_NAME:
 260       action->name = g_strdup (g_value_get_string (value));
 261       break;
 262
 263     case PROP_PARAMETER_TYPE:
 264       action->parameter_type = g_value_dup_boxed (value);
 265       break;
 266
 267     case PROP_ENABLED:
 268       action->enabled = g_value_get_boolean (value);
 269       break;
 270
 271     case PROP_STATE:
 272       /* The first time we see this (during construct) we should just
 273        * take the state as it was handed to us.
 274        *
 275        * After that, we should make sure we go through the same checks
 276        * as the C API.
 277        */
 278       if (!action->state_set_already)
 279         {
 280           action->state = g_value_dup_variant (value);
 281           action->state_set_already = TRUE;
 282         }
 283       else
 284         g_simple_action_set_state (action, g_value_get_variant (value));
 285
 286       break;
 287
 288     default:
 289       g_assert_not_reached ();
 290     }
 291 }
 292
 293 static void
 294 g_simple_action_get_property (GObject    *object,
 295                               guint       prop_id,
 296                               GValue     *value,
 297                               GParamSpec *pspec)
 298 {
 299   GAction *action = G_ACTION (object);
 300
 301   switch (prop_id)
 302     {
 303     case PROP_NAME:
 304       g_value_set_string (value, g_simple_action_get_name (action));
 305       break;
 306
 307     case PROP_PARAMETER_TYPE:
 308       g_value_set_boxed (value, g_simple_action_get_parameter_type (action));
 309       break;
 310
 311     case PROP_ENABLED:
 312       g_value_set_boolean (value, g_simple_action_get_enabled (action));
 313       break;
 314
 315     case PROP_STATE_TYPE:
 316       g_value_set_boxed (value, g_simple_action_get_state_type (action));
 317       break;
 318
 319     case PROP_STATE:
 320       g_value_take_variant (value, g_simple_action_get_state (action));
 321       break;
 322
 323     default:
 324       g_assert_not_reached ();
 325     }
 326 }
 327
 328 static void
 329 g_simple_action_finalize (GObject *object)
 330 {
 331   GSimpleAction *simple = G_SIMPLE_ACTION (object);
 332
 333   g_free (simple->name);
 334   if (simple->parameter_type)
 335     g_variant_type_free (simple->parameter_type);
 336   if (simple->state)
 337     g_variant_unref (simple->state);
 338   if (simple->state_hint)
 339     g_variant_unref (simple->state_hint);
 340
 341   G_OBJECT_CLASS (g_simple_action_parent_class)
 342     ->finalize (object);
 343 }
 344
 345 void
 346 g_simple_action_init (GSimpleAction *simple)
 347 {
 348   simple->enabled = TRUE;
 349 }
 350
 351 void
 352 g_simple_action_iface_init (GActionInterface *iface)
 353 {
 354   iface->get_name = g_simple_action_get_name;
 355   iface->get_parameter_type = g_simple_action_get_parameter_type;
 356   iface->get_state_type = g_simple_action_get_state_type;
 357   iface->get_state_hint = g_simple_action_get_state_hint;
 358   iface->get_enabled = g_simple_action_get_enabled;
 359   iface->get_state = g_simple_action_get_state;
 360   iface->change_state = g_simple_action_change_state;
 361   iface->activate = g_simple_action_activate;
 362 }
 363
 364 void
 365 g_simple_action_class_init (GSimpleActionClass *class)
 366 {
 367   GObjectClass *object_class = G_OBJECT_CLASS (class);
 368
 369   object_class->set_property = g_simple_action_set_property;
 370   object_class->get_property = g_simple_action_get_property;
 371   object_class->finalize = g_simple_action_finalize;
 372
 373   /**
 374    * GSimpleAction::activate:
 375    * @simple: the #GSimpleAction
 376    * @parameter: (nullable): the parameter to the activation, or %NULL if it has
 377    *   no parameter
 378    *
 379    * Indicates that the action was just activated.
 380    *
 381    * @parameter will always be of the expected type, i.e. the parameter type
 382    * specified when the action was created. If an incorrect type is given when
 383    * activating the action, this signal is not emitted.
 384    *
 385    * Since GLib 2.40, if no handler is connected to this signal then the
 386    * default behaviour for boolean-stated actions with a %NULL parameter
 387    * type is to toggle them via the #GSimpleAction::change-state signal.
 388    * For stateful actions where the state type is equal to the parameter
 389    * type, the default is to forward them directly to
 390    * #GSimpleAction::change-state.  This should allow almost all users
 391    * of #GSimpleAction to connect only one handler or the other.
 392    *
 393    * Since: 2.28
 394    */
 395   g_simple_action_signals[SIGNAL_ACTIVATE] =
 396     g_signal_new (I_("activate"),
 397                   G_TYPE_SIMPLE_ACTION,
 398                   G_SIGNAL_RUN_LAST | G_SIGNAL_MUST_COLLECT,
 399                   0, NULL, NULL,
 400                   NULL,
 401                   G_TYPE_NONE, 1,
 402                   G_TYPE_VARIANT);
 403
 404   /**
 405    * GSimpleAction::change-state:
 406    * @simple: the #GSimpleAction
 407    * @value: (nullable): the requested value for the state
 408    *
 409    * Indicates that the action just received a request to change its
 410    * state.
 411    *
 412    * @value will always be of the correct state type, i.e. the type of the
 413    * initial state passed to g_simple_action_new_stateful(). If an incorrect
 414    * type is given when requesting to change the state, this signal is not
 415    * emitted.
 416    *
 417    * If no handler is connected to this signal then the default
 418    * behaviour is to call g_simple_action_set_state() to set the state
 419    * to the requested value. If you connect a signal handler then no
 420    * default action is taken. If the state should change then you must
 421    * call g_simple_action_set_state() from the handler.
 422    *
 423    * An example of a 'change-state' handler:
 424    * |[<!-- language="C" -->
 425    * static void
 426    * change_volume_state (GSimpleAction *action,
 427    *                      GVariant      *value,
 428    *                      gpointer       user_data)
 429    * {
 430    *   gint requested;
 431    *
 432    *   requested = g_variant_get_int32 (value);
 433    *
 434    *   // Volume only goes from 0 to 10
 435    *   if (0 <= requested && requested <= 10)
 436    *     g_simple_action_set_state (action, value);
 437    * }
 438    * ]|
 439    *
 440    * The handler need not set the state to the requested value.
 441    * It could set it to any value at all, or take some other action.
 442    *
 443    * Since: 2.30
 444    */
 445   g_simple_action_signals[SIGNAL_CHANGE_STATE] =
 446     g_signal_new (I_("change-state"),
 447                   G_TYPE_SIMPLE_ACTION,
 448                   G_SIGNAL_RUN_LAST | G_SIGNAL_MUST_COLLECT,
 449                   0, NULL, NULL,
 450                   NULL,
 451                   G_TYPE_NONE, 1,
 452                   G_TYPE_VARIANT);
 453
 454   /**
 455    * GSimpleAction:name:
 456    *
 457    * The name of the action. This is mostly meaningful for identifying
 458    * the action once it has been added to a #GSimpleActionGroup.
 459    *
 460    * Since: 2.28
 461    **/
 462   g_object_class_install_property (object_class, PROP_NAME,
 463                                    g_param_spec_string ("name",
 464                                                         P_("Action Name"),
 465                                                         P_("The name used to invoke the action"),
 466                                                         NULL,
 467                                                         G_PARAM_READWRITE |
 468                                                         G_PARAM_CONSTRUCT_ONLY |
 469                                                         G_PARAM_STATIC_STRINGS));
 470
 471   /**
 472    * GSimpleAction:parameter-type:
 473    *
 474    * The type of the parameter that must be given when activating the
 475    * action.
 476    *
 477    * Since: 2.28
 478    **/
 479   g_object_class_install_property (object_class, PROP_PARAMETER_TYPE,
 480                                    g_param_spec_boxed ("parameter-type",
 481                                                        P_("Parameter Type"),
 482                                                        P_("The type of GVariant passed to activate()"),
 483                                                        G_TYPE_VARIANT_TYPE,
 484                                                        G_PARAM_READWRITE |
 485                                                        G_PARAM_CONSTRUCT_ONLY |
 486                                                        G_PARAM_STATIC_STRINGS));
 487
 488   /**
 489    * GSimpleAction:enabled:
 490    *
 491    * If @action is currently enabled.
 492    *
 493    * If the action is disabled then calls to g_action_activate() and
 494    * g_action_change_state() have no effect.
 495    *
 496    * Since: 2.28
 497    **/
 498   g_object_class_install_property (object_class, PROP_ENABLED,
 499                                    g_param_spec_boolean ("enabled",
 500                                                          P_("Enabled"),
 501                                                          P_("If the action can be activated"),
 502                                                          TRUE,
 503                                                          G_PARAM_READWRITE |
 504                                                          G_PARAM_STATIC_STRINGS));
 505
 506   /**
 507    * GSimpleAction:state-type:
 508    *
 509    * The #GVariantType of the state that the action has, or %NULL if the
 510    * action is stateless.
 511    *
 512    * Since: 2.28
 513    **/
 514   g_object_class_install_property (object_class, PROP_STATE_TYPE,
 515                                    g_param_spec_boxed ("state-type",
 516                                                        P_("State Type"),
 517                                                        P_("The type of the state kept by the action"),
 518                                                        G_TYPE_VARIANT_TYPE,
 519                                                        G_PARAM_READABLE |
 520                                                        G_PARAM_STATIC_STRINGS));
 521
 522   /**
 523    * GSimpleAction:state:
 524    *
 525    * The state of the action, or %NULL if the action is stateless.
 526    *
 527    * Since: 2.28
 528    **/
 529   g_object_class_install_property (object_class, PROP_STATE,
 530                                    g_param_spec_variant ("state",
 531                                                          P_("State"),
 532                                                          P_("The state the action is in"),
 533                                                          G_VARIANT_TYPE_ANY,
 534                                                          NULL,
 535                                                          G_PARAM_READWRITE | G_PARAM_CONSTRUCT |
 536                                                          G_PARAM_STATIC_STRINGS));
 537 }
 538
 539 /**
 540  * g_simple_action_set_enabled:
 541  * @simple: a #GSimpleAction
 542  * @enabled: whether the action is enabled
 543  *
 544  * Sets the action as enabled or not.
 545  *
 546  * An action must be enabled in order to be activated or in order to
 547  * have its state changed from outside callers.
 548  *
 549  * This should only be called by the implementor of the action.  Users
 550  * of the action should not attempt to modify its enabled flag.
 551  *
 552  * Since: 2.28
 553  **/
 554 void
 555 g_simple_action_set_enabled (GSimpleAction *simple,
 556                              gboolean       enabled)
 557 {
 558   g_return_if_fail (G_IS_SIMPLE_ACTION (simple));
 559
 560   enabled = !!enabled;
 561
 562   if (simple->enabled != enabled)
 563     {
 564       simple->enabled = enabled;
 565       g_object_notify (G_OBJECT (simple), "enabled");
 566     }
 567 }
 568
 569 /**
 570  * g_simple_action_set_state_hint:
 571  * @simple: a #GSimpleAction
 572  * @state_hint: (nullable): a #GVariant representing the state hint
 573  *
 574  * Sets the state hint for the action.
 575  *
 576  * See g_action_get_state_hint() for more information about
 577  * action state hints.
 578  *
 579  * Since: 2.44
 580  **/
 581 void
 582 g_simple_action_set_state_hint (GSimpleAction *simple,
 583                                 GVariant      *state_hint)
 584 {
 585   g_return_if_fail (G_IS_SIMPLE_ACTION (simple));
 586
 587   if (simple->state_hint != NULL)
 588     {
 589       g_variant_unref (simple->state_hint);
 590       simple->state_hint = NULL;
 591     }
 592
 593   if (state_hint != NULL)
 594     simple->state_hint = g_variant_ref (state_hint);
 595 }
 596
 597 /**
 598  * g_simple_action_new:
 599  * @name: the name of the action
 600  * @parameter_type: (nullable): the type of parameter that will be passed to
 601  *   handlers for the #GSimpleAction::activate signal, or %NULL for no parameter
 602  *
 603  * Creates a new action.
 604  *
 605  * The created action is stateless. See g_simple_action_new_stateful() to create
 606  * an action that has state.
 607  *
 608  * Returns: a new #GSimpleAction
 609  *
 610  * Since: 2.28
 611  **/
 612 GSimpleAction *
 613 g_simple_action_new (const gchar        *name,
 614                      const GVariantType *parameter_type)
 615 {
 616   g_return_val_if_fail (name != NULL, NULL);
 617
 618   return g_object_new (G_TYPE_SIMPLE_ACTION,
 619                        "name", name,
 620                        "parameter-type", parameter_type,
 621                        NULL);
 622 }
 623
 624 /**
 625  * g_simple_action_new_stateful:
 626  * @name: the name of the action
 627  * @parameter_type: (nullable): the type of the parameter that will be passed to
 628  *   handlers for the #GSimpleAction::activate signal, or %NULL for no parameter
 629  * @state: the initial state of the action
 630  *
 631  * Creates a new stateful action.
 632  *
 633  * All future state values must have the same #GVariantType as the initial
 634  * @state.
 635  *
 636  * If the @state #GVariant is floating, it is consumed.
 637  *
 638  * Returns: a new #GSimpleAction
 639  *
 640  * Since: 2.28
 641  **/
 642 GSimpleAction *
 643 g_simple_action_new_stateful (const gchar        *name,
 644                               const GVariantType *parameter_type,
 645                               GVariant           *state)
 646 {
 647   return g_object_new (G_TYPE_SIMPLE_ACTION,
 648                        "name", name,
 649                        "parameter-type", parameter_type,
 650                        "state", state,
 651                        NULL);
 652 }