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