gio/gaction.c

   1 /*
   2  * Copyright © 2010 Codethink Limited
   3  *
   4  * This program is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as published
   6  * by the Free Software Foundation; either version 2 of the licence or (at
   7  * your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General
  15  * Public License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  *
  19  * Authors: Ryan Lortie <desrt@desrt.ca>
  20  */
  21
  22 #include "config.h"
  23 #include "gaction.h"
  24 #include "glibintl.h"
  25
  26 G_DEFINE_TYPE (GAction, g_action, G_TYPE_OBJECT)
  27
  28 /**
  29  * SECTION:gaction
  30  * @title: GAction
  31  * @short_description: an action
  32  *
  33  * #GAction represents a single named action.
  34  *
  35  * The main interface to an action is that it can be activated with
  36  * g_action_activate().  This results in the 'activate' signal being
  37  * emitted.  An activation has a #GVariant parameter (which may be
  38  * %NULL).  The correct type for the parameter is determined by a static
  39  * parameter type (which is given at construction time).
  40  *
  41  * An action may optionally have a state, in which case the state may be
  42  * set with g_action_set_state().  This call takes a #GVariant.  The
  43  * correct type for the state is determined by a static state type
  44  * (which is given at construction time).
  45  *
  46  * The state may have a hint associated with it, specifying its valid
  47  * range.
  48  *
  49  * #GAction is intended to be used both as a simple action class and as
  50  * a base class for more complicated action types.  The base class
  51  * itself supports activation and state.  Not supported are state hints
  52  * and filtering requests to set the state based on the requested value.
  53  * You should subclass if you require either of these abilities.
  54  *
  55  * In all cases, the base class is responsible for storing the name of
  56  * the action, the parameter type, the enabled state, the optional state
  57  * type and the state and emitting the appropriate signals when these
  58  * change.  The base class is also responsbile for filtering calls to
  59  * g_action_activate() and g_action_set_state() for type safety and for
  60  * the state being enabled.
  61  *
  62  * Probably the only useful thing to do with a #GAction is to put it
  63  * inside of a #GSimpleActionGroup.
  64  **/
  65
  66 struct _GActionPrivate
  67 {
  68   gchar        *name;
  69   GVariantType *parameter_type;
  70   guint         enabled : 1;
  71   guint         state_set : 1;
  72   GVariant     *state;
  73 };
  74
  75 enum
  76 {
  77   PROP_NONE,
  78   PROP_NAME,
  79   PROP_PARAMETER_TYPE,
  80   PROP_ENABLED,
  81   PROP_STATE_TYPE,
  82   PROP_STATE
  83 };
  84
  85 enum
  86 {
  87   SIGNAL_ACTIVATE,
  88   NR_SIGNALS
  89 };
  90
  91 static guint g_action_signals[NR_SIGNALS];
  92
  93 static void
  94 g_action_real_set_state (GAction  *action,
  95                          GVariant *value)
  96 {
  97   if (action->priv->state == value)
  98     return;
  99
 100   if (!action->priv->state || !g_variant_equal (action->priv->state, value))
 101     {
 102       if (action->priv->state)
 103         g_variant_unref (action->priv->state);
 104
 105       action->priv->state = g_variant_ref (value);
 106
 107       g_object_notify (G_OBJECT (action), "state");
 108     }
 109 }
 110
 111 static GVariant *
 112 g_action_real_get_state_hint (GAction *action)
 113 {
 114   return NULL;
 115 }
 116
 117 static void
 118 g_action_set_property (GObject *object, guint prop_id,
 119                        const GValue *value, GParamSpec *pspec)
 120 {
 121   GAction *action = G_ACTION (object);
 122
 123   switch (prop_id)
 124     {
 125     case PROP_NAME:
 126       g_assert (action->priv->name == NULL);
 127       action->priv->name = g_value_dup_string (value);
 128       break;
 129
 130     case PROP_PARAMETER_TYPE:
 131       g_assert (action->priv->parameter_type == NULL);
 132       action->priv->parameter_type = g_value_dup_boxed (value);
 133       break;
 134
 135     case PROP_ENABLED:
 136       g_action_set_enabled (action, g_value_get_boolean (value));
 137       break;
 138
 139     case PROP_STATE:
 140       /* PROP_STATE is marked as G_PARAM_CONSTRUCT so we always get a
 141        * call during object construction, even if it is NULL.  We treat
 142        * that first call differently, for a number of reasons.
 143        *
 144        * First, we don't want the value to be rejected by the
 145        * possibly-overridden .set_state() function.  Second, we don't
 146        * want to be tripped by the assertions in g_action_set_state()
 147        * that would enforce the catch22 that we only provide a value of
 148        * the same type as the existing value (when there is not yet an
 149        * existing value).
 150        */
 151       if (action->priv->state_set)
 152         g_action_set_state (action, g_value_get_variant (value));
 153
 154       else /* this is the special case */
 155         {
 156           /* only do it the first time. */
 157           action->priv->state_set = TRUE;
 158
 159           /* blindly set it. */
 160           action->priv->state = g_value_dup_variant (value);
 161         }
 162       break;
 163
 164     default:
 165       g_assert_not_reached ();
 166     }
 167 }
 168
 169 static void
 170 g_action_get_property (GObject *object, guint prop_id,
 171                        GValue *value, GParamSpec *pspec)
 172 {
 173   GAction *action = G_ACTION (object);
 174
 175   switch (prop_id)
 176     {
 177     case PROP_NAME:
 178       g_value_set_string (value, g_action_get_name (action));
 179       break;
 180
 181     case PROP_PARAMETER_TYPE:
 182       g_value_set_boxed (value, g_action_get_parameter_type (action));
 183       break;
 184
 185     case PROP_ENABLED:
 186       g_value_set_boolean (value, g_action_get_enabled (action));
 187       break;
 188
 189     case PROP_STATE_TYPE:
 190       g_value_set_boxed (value, g_action_get_state_type (action));
 191       break;
 192
 193     case PROP_STATE:
 194       g_value_set_variant (value, g_action_get_state (action));
 195       break;
 196
 197     default:
 198       g_assert_not_reached ();
 199     }
 200 }
 201
 202 static void
 203 g_action_finalize (GObject *object)
 204 {
 205   GAction *action = G_ACTION (object);
 206
 207   g_free (action->priv->name);
 208   if (action->priv->parameter_type)
 209     g_variant_type_free (action->priv->parameter_type);
 210   if (action->priv->state)
 211     g_variant_unref (action->priv->state);
 212
 213   G_OBJECT_CLASS (g_action_parent_class)
 214     ->finalize (object);
 215 }
 216
 217 void
 218 g_action_init (GAction *action)
 219 {
 220   action->priv = G_TYPE_INSTANCE_GET_PRIVATE (action,
 221                                               G_TYPE_ACTION,
 222                                               GActionPrivate);
 223 }
 224
 225 void
 226 g_action_class_init (GActionClass *class)
 227 {
 228   GObjectClass *object_class = G_OBJECT_CLASS (class);
 229
 230   class->get_state_hint = g_action_real_get_state_hint;
 231   class->set_state = g_action_real_set_state;
 232
 233   object_class->get_property = g_action_get_property;
 234   object_class->set_property = g_action_set_property;
 235   object_class->finalize = g_action_finalize;
 236
 237   /**
 238    * GAction::activate:
 239    * @action: the #GAction
 240    * @parameter: (allow-none): the parameter to the activation
 241    *
 242    * Indicates that the action was just activated.
 243    *
 244    * @parameter will always be of the expected type.  In the event that
 245    * an incorrect type was given, no signal will be emitted.
 246    *
 247    * Since: 2.26
 248    */
 249   g_action_signals[SIGNAL_ACTIVATE] =
 250     g_signal_new (I_("activate"),
 251                   G_TYPE_ACTION,
 252                   G_SIGNAL_RUN_LAST,
 253                   G_STRUCT_OFFSET (GActionClass, activate),
 254                   NULL, NULL,
 255                   g_cclosure_marshal_VOID__VARIANT,
 256                   G_TYPE_NONE, 1,
 257                   G_TYPE_VARIANT);
 258
 259   /**
 260    * GAction:name:
 261    *
 262    * The name of the action.  This is mostly meaningful for identifying
 263    * the action once it has been added to a #GActionGroup.
 264    *
 265    * Since: 2.26
 266    **/
 267   g_object_class_install_property (object_class, PROP_NAME,
 268                                    g_param_spec_string ("name",
 269                                                         P_("Action Name"),
 270                                                         P_("The name used to invoke the action"),
 271                                                         NULL,
 272                                                         G_PARAM_READWRITE |
 273                                                         G_PARAM_CONSTRUCT_ONLY |
 274                                                         G_PARAM_STATIC_STRINGS));
 275
 276   /**
 277    * GAction:parameter-type:
 278    *
 279    * The type of the parameter that must be given when activating the
 280    * action.
 281    *
 282    * Since: 2.26
 283    **/
 284   g_object_class_install_property (object_class, PROP_PARAMETER_TYPE,
 285                                    g_param_spec_boxed ("parameter-type",
 286                                                        P_("Parameter Type"),
 287                                                        P_("The type of GVariant passed to activate()"),
 288                                                        G_TYPE_VARIANT_TYPE,
 289                                                        G_PARAM_READWRITE |
 290                                                        G_PARAM_CONSTRUCT_ONLY |
 291                                                        G_PARAM_STATIC_STRINGS));
 292
 293   /**
 294    * GAction:enabled:
 295    *
 296    * If @action is currently enabled.
 297    *
 298    * If the action is disabled then calls to g_action_activate() and
 299    * g_action_set_state() have no effect.
 300    *
 301    * Since: 2.26
 302    **/
 303   g_object_class_install_property (object_class, PROP_ENABLED,
 304                                    g_param_spec_boolean ("enabled",
 305                                                          P_("Enabled"),
 306                                                          P_("If the action can be activated"),
 307                                                          TRUE,
 308                                                          G_PARAM_CONSTRUCT |
 309                                                          G_PARAM_READWRITE |
 310                                                          G_PARAM_STATIC_STRINGS));
 311
 312   /**
 313    * GAction:state-type:
 314    *
 315    * The #GVariantType of the state that the action has, or %NULL if the
 316    * action is stateless.
 317    *
 318    * Since: 2.26
 319    **/
 320   g_object_class_install_property (object_class, PROP_STATE_TYPE,
 321                                    g_param_spec_boxed ("state-type",
 322                                                        P_("State Type"),
 323                                                        P_("The type of the state kept by the action"),
 324                                                        G_TYPE_VARIANT_TYPE,
 325                                                        G_PARAM_READABLE |
 326                                                        G_PARAM_STATIC_STRINGS));
 327
 328   /**
 329    * GAction:state:
 330    *
 331    * The state of the action, or %NULL if the action is stateless.
 332    *
 333    * Since: 2.26
 334    **/
 335   g_object_class_install_property (object_class, PROP_STATE,
 336                                    g_param_spec_variant ("state",
 337                                                          P_("State"),
 338                                                          P_("The state the action is in"),
 339                                                          G_VARIANT_TYPE_ANY,
 340                                                          NULL,
 341                                                          G_PARAM_CONSTRUCT |
 342                                                          G_PARAM_READWRITE |
 343                                                          G_PARAM_STATIC_STRINGS));
 344
 345   g_type_class_add_private (class, sizeof (GActionPrivate));
 346 }
 347
 348 /**
 349  * g_action_set_state:
 350  * @action: a #GAction
 351  * @value: the new state
 352  *
 353  * Request for the state of @action to be changed to @value.
 354  *
 355  * The action must be stateful and @value must be of the correct type.
 356  * See g_action_get_state_type().
 357  *
 358  * This call merely requests a change.  The action may refuse to change
 359  * its state or may change its state to something other than @value.
 360  * See g_action_get_state_hint().
 361  *
 362  * Since: 2.26
 363  **/
 364 void
 365 g_action_set_state (GAction  *action,
 366                     GVariant *value)
 367 {
 368   const GVariantType *state_type;
 369
 370   g_return_if_fail (G_IS_ACTION (action));
 371   g_return_if_fail (value != NULL);
 372   state_type = g_action_get_state_type (action);
 373   g_return_if_fail (state_type != NULL);
 374   g_return_if_fail (g_variant_is_of_type (value, state_type));
 375
 376   g_variant_ref_sink (value);
 377
 378   if (action->priv->enabled)
 379     G_ACTION_GET_CLASS (action)
 380       ->set_state (action, value);
 381
 382   g_variant_unref (value);
 383 }
 384
 385 /**
 386  * g_action_get_state:
 387  * @action: a #GAction
 388  *
 389  * Queries the current state of @action.
 390  *
 391  * If the action is not stateful then %NULL will be returned.  If the
 392  * action is stateful then the type of the return value is the type
 393  * given by g_action_get_state_type().
 394  *
 395  * Returns: (allow-none) (transfer none): the current state of the action
 396  *
 397  * Since: 2.26
 398  **/
 399 GVariant *
 400 g_action_get_state (GAction *action)
 401 {
 402   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 403
 404   return action->priv->state;
 405 }
 406
 407 /**
 408  * g_action_get_name:
 409  * @action: a #GAction
 410  *
 411  * Queries the name of @action.
 412  *
 413  * Returns: the name of the action
 414  *
 415  * Since: 2.26
 416  **/
 417 const gchar *
 418 g_action_get_name (GAction *action)
 419 {
 420   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 421
 422   return action->priv->name;
 423 }
 424
 425 /**
 426  * g_action_get_parameter_type:
 427  * @action: a #GAction
 428  *
 429  * Queries the type of the parameter that must be given when activating
 430  * @action.
 431  *
 432  * When activating the action using g_action_activate(), the #GVariant
 433  * given to that function must be of the type returned by this function.
 434  *
 435  * In the case that this function returns %NULL, you must not give any
 436  * #GVariant, but %NULL instead.
 437  *
 438  * Returns: (allow-none): the parameter type
 439  *
 440  * Since: 2.26
 441  **/
 442 const GVariantType *
 443 g_action_get_parameter_type (GAction *action)
 444 {
 445   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 446
 447   return action->priv->parameter_type;
 448 }
 449
 450 /**
 451  * g_action_get_state_type:
 452  * @action: a #GAction
 453  *
 454  * Queries the type of the state of @action.
 455  *
 456  * If the action is stateful (ie: was created with
 457  * g_action_new_stateful()) then this function returns the #GVariantType
 458  * of the state.  This is the type of the initial value given as the
 459  * state.  All calls to g_action_set_state() must give a #GVariant of
 460  * this type and g_action_get_state() will return a #GVariant of the
 461  * same type.
 462  *
 463  * If the action is not stateful (ie: created with g_action_new()) then
 464  * this function will return %NULL.  In that case, g_action_get_state()
 465  * will return %NULL and you must not call g_action_set_state().
 466  *
 467  * Returns: (allow-none): the state type, if the action is stateful
 468  *
 469  * Since: 2.26
 470  **/
 471 const GVariantType *
 472 g_action_get_state_type (GAction *action)
 473 {
 474   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 475
 476   if (action->priv->state != NULL)
 477     return g_variant_get_type (action->priv->state);
 478   else
 479     return NULL;
 480 }
 481
 482 /**
 483  * g_action_get_state_hint:
 484  * @action: a #GAction
 485  *
 486  * Requests a hint about the valid range of values for the state of
 487  * @action.
 488  *
 489  * If %NULL is returned it either means that the action is not stateful
 490  * or that there is no hint about the valid range of values for the
 491  * state of the action.
 492  *
 493  * If a #GVariant array is returned then each item in the array is a
 494  * possible value for the state.  If a #GVariant pair (ie: two-tuple) is
 495  * returned then the tuple specifies the inclusive lower and upper bound
 496  * of valid values for the state.
 497  *
 498  * In any case, the information is merely a hint.  It may be possible to
 499  * have a state value outside of the hinted range and setting a value
 500  * within the range may fail.
 501  *
 502  * The return value (if non-%NULL) should be freed with
 503  * g_variant_unref() when it is no longer required.
 504  *
 505  * Returns: (allow-none): the state range hint
 506  *
 507  * Since: 2.26
 508  **/
 509 GVariant *
 510 g_action_get_state_hint (GAction *action)
 511 {
 512   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 513
 514   return G_ACTION_GET_CLASS (action)->get_state_hint (action);
 515 }
 516
 517 /**
 518  * g_action_get_enabled:
 519  * @action: a #GAction
 520  *
 521  * Checks if @action is currently enabled.
 522  *
 523  * An action must be enabled in order to be activated or in order to
 524  * have its state changed from outside callers.
 525  *
 526  * Returns: whether the action is enabled
 527  *
 528  * Since: 2.26
 529  **/
 530 gboolean
 531 g_action_get_enabled (GAction *action)
 532 {
 533   g_return_val_if_fail (G_IS_ACTION (action), FALSE);
 534
 535   return action->priv->enabled;
 536 }
 537
 538 /**
 539  * g_action_set_enabled:
 540  * @action: a #GAction
 541  * @enabled: whether the action is enabled
 542  *
 543  * Sets the action as enabled or not.
 544  *
 545  * An action must be enabled in order to be activated or in order to
 546  * have its state changed from outside callers.
 547  *
 548  * Since: 2.26
 549  **/
 550 void
 551 g_action_set_enabled (GAction  *action,
 552                       gboolean  enabled)
 553 {
 554   g_return_if_fail (G_IS_ACTION (action));
 555
 556   enabled = !!enabled;
 557
 558   if (action->priv->enabled != enabled)
 559     {
 560       action->priv->enabled = enabled;
 561       g_object_notify (G_OBJECT (action), "enabled");
 562     }
 563 }
 564
 565 /**
 566  * g_action_activate:
 567  * @action: a #GAction
 568  * @parameter: the parameter to the activation
 569  *
 570  * Activates the action.
 571  *
 572  * @parameter must be the correct type of parameter for the action (ie:
 573  * the parameter type given at construction time).  If the parameter
 574  * type was %NULL then @parameter must also be %NULL.
 575  *
 576  * Since: 2.26
 577  **/
 578 void
 579 g_action_activate (GAction  *action,
 580                    GVariant *parameter)
 581 {
 582   g_return_if_fail (G_IS_ACTION (action));
 583
 584   g_return_if_fail (action->priv->parameter_type == NULL ?
 585                       parameter == NULL :
 586                     (parameter != NULL &&
 587                      g_variant_is_of_type (parameter,
 588                                            action->priv->parameter_type)));
 589
 590   if (parameter != NULL)
 591     g_variant_ref_sink (parameter);
 592
 593   if (action->priv->enabled)
 594     g_signal_emit (action, g_action_signals[SIGNAL_ACTIVATE], 0, parameter);
 595
 596   if (parameter != NULL)
 597     g_variant_unref (parameter);
 598 }
 599
 600 /**
 601  * g_action_new:
 602  * @name: the name of the action
 603  * @parameter_type: the type of parameter to the activate function
 604  *
 605  * Creates a new action.
 606  *
 607  * The created action is stateless.  See g_action_new_stateful().
 608  *
 609  * Returns: a new #GAction
 610  *
 611  * Since: 2.26
 612  **/
 613 GAction *
 614 g_action_new (const gchar        *name,
 615               const GVariantType *parameter_type)
 616 {
 617   return g_object_new (G_TYPE_ACTION,
 618                        "name", name,
 619                        "parameter-type", parameter_type,
 620                        NULL);
 621 }
 622
 623 /**
 624  * g_action_new_stateful:
 625  * @name: the name of the action
 626  * @parameter_type: the type of the parameter to the activate function
 627  * @state: the initial state of the action
 628  *
 629  * Creates a new stateful action.
 630  *
 631  * @state is the initial state of the action.  All future state values
 632  * must have the same #GVariantType as the initial state.
 633  *
 634  * Returns: a new #GAction
 635  *
 636  * Since: 2.26
 637  **/
 638 GAction *
 639 g_action_new_stateful (const gchar        *name,
 640                        const GVariantType *parameter_type,
 641                        GVariant           *state)
 642 {
 643   return g_object_new (G_TYPE_ACTION,
 644                        "name", name,
 645                        "parameter-type", parameter_type,
 646                        "state", state,
 647                        NULL);
 648 }