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,
 119                        guint         prop_id,
 120                        const GValue *value,
 121                        GParamSpec   *pspec)
 122 {
 123   GAction *action = G_ACTION (object);
 124
 125   switch (prop_id)
 126     {
 127     case PROP_NAME:
 128       g_assert (action->priv->name == NULL);
 129       action->priv->name = g_value_dup_string (value);
 130       break;
 131
 132     case PROP_PARAMETER_TYPE:
 133       g_assert (action->priv->parameter_type == NULL);
 134       action->priv->parameter_type = g_value_dup_boxed (value);
 135       break;
 136
 137     case PROP_ENABLED:
 138       g_action_set_enabled (action, g_value_get_boolean (value));
 139       break;
 140
 141     case PROP_STATE:
 142       /* PROP_STATE is marked as G_PARAM_CONSTRUCT so we always get a
 143        * call during object construction, even if it is NULL.  We treat
 144        * that first call differently, for a number of reasons.
 145        *
 146        * First, we don't want the value to be rejected by the
 147        * possibly-overridden .set_state() function.  Second, we don't
 148        * want to be tripped by the assertions in g_action_set_state()
 149        * that would enforce the catch22 that we only provide a value of
 150        * the same type as the existing value (when there is not yet an
 151        * existing value).
 152        */
 153       if (action->priv->state_set)
 154         g_action_set_state (action, g_value_get_variant (value));
 155
 156       else /* this is the special case */
 157         {
 158           /* only do it the first time. */
 159           action->priv->state_set = TRUE;
 160
 161           /* blindly set it. */
 162           action->priv->state = g_value_dup_variant (value);
 163         }
 164       break;
 165
 166     default:
 167       g_assert_not_reached ();
 168     }
 169 }
 170
 171 static void
 172 g_action_get_property (GObject    *object,
 173                        guint       prop_id,
 174                        GValue     *value,
 175                        GParamSpec *pspec)
 176 {
 177   GAction *action = G_ACTION (object);
 178
 179   switch (prop_id)
 180     {
 181     case PROP_NAME:
 182       g_value_set_string (value, g_action_get_name (action));
 183       break;
 184
 185     case PROP_PARAMETER_TYPE:
 186       g_value_set_boxed (value, g_action_get_parameter_type (action));
 187       break;
 188
 189     case PROP_ENABLED:
 190       g_value_set_boolean (value, g_action_get_enabled (action));
 191       break;
 192
 193     case PROP_STATE_TYPE:
 194       g_value_set_boxed (value, g_action_get_state_type (action));
 195       break;
 196
 197     case PROP_STATE:
 198       g_value_set_variant (value, g_action_get_state (action));
 199       break;
 200
 201     default:
 202       g_assert_not_reached ();
 203     }
 204 }
 205
 206 static void
 207 g_action_finalize (GObject *object)
 208 {
 209   GAction *action = G_ACTION (object);
 210
 211   g_free (action->priv->name);
 212   if (action->priv->parameter_type)
 213     g_variant_type_free (action->priv->parameter_type);
 214   if (action->priv->state)
 215     g_variant_unref (action->priv->state);
 216
 217   G_OBJECT_CLASS (g_action_parent_class)
 218     ->finalize (object);
 219 }
 220
 221 void
 222 g_action_init (GAction *action)
 223 {
 224   action->priv = G_TYPE_INSTANCE_GET_PRIVATE (action,
 225                                               G_TYPE_ACTION,
 226                                               GActionPrivate);
 227 }
 228
 229 void
 230 g_action_class_init (GActionClass *class)
 231 {
 232   GObjectClass *object_class = G_OBJECT_CLASS (class);
 233
 234   class->get_state_hint = g_action_real_get_state_hint;
 235   class->set_state = g_action_real_set_state;
 236
 237   object_class->get_property = g_action_get_property;
 238   object_class->set_property = g_action_set_property;
 239   object_class->finalize = g_action_finalize;
 240
 241   /**
 242    * GAction::activate:
 243    * @action: the #GAction
 244    * @parameter: (allow-none): the parameter to the activation
 245    *
 246    * Indicates that the action was just activated.
 247    *
 248    * @parameter will always be of the expected type.  In the event that
 249    * an incorrect type was given, no signal will be emitted.
 250    *
 251    * Since: 2.26
 252    */
 253   g_action_signals[SIGNAL_ACTIVATE] =
 254     g_signal_new (I_("activate"),
 255                   G_TYPE_ACTION,
 256                   G_SIGNAL_RUN_LAST,
 257                   G_STRUCT_OFFSET (GActionClass, activate),
 258                   NULL, NULL,
 259                   g_cclosure_marshal_VOID__VARIANT,
 260                   G_TYPE_NONE, 1,
 261                   G_TYPE_VARIANT);
 262
 263   /**
 264    * GAction:name:
 265    *
 266    * The name of the action.  This is mostly meaningful for identifying
 267    * the action once it has been added to a #GActionGroup.
 268    *
 269    * Since: 2.26
 270    **/
 271   g_object_class_install_property (object_class, PROP_NAME,
 272                                    g_param_spec_string ("name",
 273                                                         P_("Action Name"),
 274                                                         P_("The name used to invoke the action"),
 275                                                         NULL,
 276                                                         G_PARAM_READWRITE |
 277                                                         G_PARAM_CONSTRUCT_ONLY |
 278                                                         G_PARAM_STATIC_STRINGS));
 279
 280   /**
 281    * GAction:parameter-type:
 282    *
 283    * The type of the parameter that must be given when activating the
 284    * action.
 285    *
 286    * Since: 2.26
 287    **/
 288   g_object_class_install_property (object_class, PROP_PARAMETER_TYPE,
 289                                    g_param_spec_boxed ("parameter-type",
 290                                                        P_("Parameter Type"),
 291                                                        P_("The type of GVariant passed to activate()"),
 292                                                        G_TYPE_VARIANT_TYPE,
 293                                                        G_PARAM_READWRITE |
 294                                                        G_PARAM_CONSTRUCT_ONLY |
 295                                                        G_PARAM_STATIC_STRINGS));
 296
 297   /**
 298    * GAction:enabled:
 299    *
 300    * If @action is currently enabled.
 301    *
 302    * If the action is disabled then calls to g_action_activate() and
 303    * g_action_set_state() have no effect.
 304    *
 305    * Since: 2.26
 306    **/
 307   g_object_class_install_property (object_class, PROP_ENABLED,
 308                                    g_param_spec_boolean ("enabled",
 309                                                          P_("Enabled"),
 310                                                          P_("If the action can be activated"),
 311                                                          TRUE,
 312                                                          G_PARAM_CONSTRUCT |
 313                                                          G_PARAM_READWRITE |
 314                                                          G_PARAM_STATIC_STRINGS));
 315
 316   /**
 317    * GAction:state-type:
 318    *
 319    * The #GVariantType of the state that the action has, or %NULL if the
 320    * action is stateless.
 321    *
 322    * Since: 2.26
 323    **/
 324   g_object_class_install_property (object_class, PROP_STATE_TYPE,
 325                                    g_param_spec_boxed ("state-type",
 326                                                        P_("State Type"),
 327                                                        P_("The type of the state kept by the action"),
 328                                                        G_TYPE_VARIANT_TYPE,
 329                                                        G_PARAM_READABLE |
 330                                                        G_PARAM_STATIC_STRINGS));
 331
 332   /**
 333    * GAction:state:
 334    *
 335    * The state of the action, or %NULL if the action is stateless.
 336    *
 337    * Since: 2.26
 338    **/
 339   g_object_class_install_property (object_class, PROP_STATE,
 340                                    g_param_spec_variant ("state",
 341                                                          P_("State"),
 342                                                          P_("The state the action is in"),
 343                                                          G_VARIANT_TYPE_ANY,
 344                                                          NULL,
 345                                                          G_PARAM_CONSTRUCT |
 346                                                          G_PARAM_READWRITE |
 347                                                          G_PARAM_STATIC_STRINGS));
 348
 349   g_type_class_add_private (class, sizeof (GActionPrivate));
 350 }
 351
 352 /**
 353  * g_action_set_state:
 354  * @action: a #GAction
 355  * @value: the new state
 356  *
 357  * Request for the state of @action to be changed to @value.
 358  *
 359  * The action must be stateful and @value must be of the correct type.
 360  * See g_action_get_state_type().
 361  *
 362  * This call merely requests a change.  The action may refuse to change
 363  * its state or may change its state to something other than @value.
 364  * See g_action_get_state_hint().
 365  *
 366  * If the @value GVariant is floating, it is consumed.
 367  *
 368  * Since: 2.26
 369  **/
 370 void
 371 g_action_set_state (GAction  *action,
 372                     GVariant *value)
 373 {
 374   const GVariantType *state_type;
 375
 376   g_return_if_fail (G_IS_ACTION (action));
 377   g_return_if_fail (value != NULL);
 378   state_type = g_action_get_state_type (action);
 379   g_return_if_fail (state_type != NULL);
 380   g_return_if_fail (g_variant_is_of_type (value, state_type));
 381
 382   g_variant_ref_sink (value);
 383
 384   if (action->priv->enabled)
 385     G_ACTION_GET_CLASS (action)
 386       ->set_state (action, value);
 387
 388   g_variant_unref (value);
 389 }
 390
 391 /**
 392  * g_action_get_state:
 393  * @action: a #GAction
 394  *
 395  * Queries the current state of @action.
 396  *
 397  * If the action is not stateful then %NULL will be returned.  If the
 398  * action is stateful then the type of the return value is the type
 399  * given by g_action_get_state_type().
 400  *
 401  * Returns: (allow-none) (transfer none): the current state of the action
 402  *
 403  * Since: 2.26
 404  **/
 405 GVariant *
 406 g_action_get_state (GAction *action)
 407 {
 408   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 409
 410   return action->priv->state;
 411 }
 412
 413 /**
 414  * g_action_get_name:
 415  * @action: a #GAction
 416  *
 417  * Queries the name of @action.
 418  *
 419  * Returns: the name of the action
 420  *
 421  * Since: 2.26
 422  **/
 423 const gchar *
 424 g_action_get_name (GAction *action)
 425 {
 426   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 427
 428   return action->priv->name;
 429 }
 430
 431 /**
 432  * g_action_get_parameter_type:
 433  * @action: a #GAction
 434  *
 435  * Queries the type of the parameter that must be given when activating
 436  * @action.
 437  *
 438  * When activating the action using g_action_activate(), the #GVariant
 439  * given to that function must be of the type returned by this function.
 440  *
 441  * In the case that this function returns %NULL, you must not give any
 442  * #GVariant, but %NULL instead.
 443  *
 444  * Returns: (allow-none): the parameter type
 445  *
 446  * Since: 2.26
 447  **/
 448 const GVariantType *
 449 g_action_get_parameter_type (GAction *action)
 450 {
 451   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 452
 453   return action->priv->parameter_type;
 454 }
 455
 456 /**
 457  * g_action_get_state_type:
 458  * @action: a #GAction
 459  *
 460  * Queries the type of the state of @action.
 461  *
 462  * If the action is stateful (ie: was created with
 463  * g_action_new_stateful()) then this function returns the #GVariantType
 464  * of the state.  This is the type of the initial value given as the
 465  * state.  All calls to g_action_set_state() must give a #GVariant of
 466  * this type and g_action_get_state() will return a #GVariant of the
 467  * same type.
 468  *
 469  * If the action is not stateful (ie: created with g_action_new()) then
 470  * this function will return %NULL.  In that case, g_action_get_state()
 471  * will return %NULL and you must not call g_action_set_state().
 472  *
 473  * Returns: (allow-none): the state type, if the action is stateful
 474  *
 475  * Since: 2.26
 476  **/
 477 const GVariantType *
 478 g_action_get_state_type (GAction *action)
 479 {
 480   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 481
 482   if (action->priv->state != NULL)
 483     return g_variant_get_type (action->priv->state);
 484   else
 485     return NULL;
 486 }
 487
 488 /**
 489  * g_action_get_state_hint:
 490  * @action: a #GAction
 491  *
 492  * Requests a hint about the valid range of values for the state of
 493  * @action.
 494  *
 495  * If %NULL is returned it either means that the action is not stateful
 496  * or that there is no hint about the valid range of values for the
 497  * state of the action.
 498  *
 499  * If a #GVariant array is returned then each item in the array is a
 500  * possible value for the state.  If a #GVariant pair (ie: two-tuple) is
 501  * returned then the tuple specifies the inclusive lower and upper bound
 502  * of valid values for the state.
 503  *
 504  * In any case, the information is merely a hint.  It may be possible to
 505  * have a state value outside of the hinted range and setting a value
 506  * within the range may fail.
 507  *
 508  * The return value (if non-%NULL) should be freed with
 509  * g_variant_unref() when it is no longer required.
 510  *
 511  * Returns: (allow-none): the state range hint
 512  *
 513  * Since: 2.26
 514  **/
 515 GVariant *
 516 g_action_get_state_hint (GAction *action)
 517 {
 518   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 519
 520   return G_ACTION_GET_CLASS (action)->get_state_hint (action);
 521 }
 522
 523 /**
 524  * g_action_get_enabled:
 525  * @action: a #GAction
 526  *
 527  * Checks if @action is currently enabled.
 528  *
 529  * An action must be enabled in order to be activated or in order to
 530  * have its state changed from outside callers.
 531  *
 532  * Returns: whether the action is enabled
 533  *
 534  * Since: 2.26
 535  **/
 536 gboolean
 537 g_action_get_enabled (GAction *action)
 538 {
 539   g_return_val_if_fail (G_IS_ACTION (action), FALSE);
 540
 541   return action->priv->enabled;
 542 }
 543
 544 /**
 545  * g_action_set_enabled:
 546  * @action: a #GAction
 547  * @enabled: whether the action is enabled
 548  *
 549  * Sets the action as enabled or not.
 550  *
 551  * An action must be enabled in order to be activated or in order to
 552  * have its state changed from outside callers.
 553  *
 554  * Since: 2.26
 555  **/
 556 void
 557 g_action_set_enabled (GAction  *action,
 558                       gboolean  enabled)
 559 {
 560   g_return_if_fail (G_IS_ACTION (action));
 561
 562   enabled = !!enabled;
 563
 564   if (action->priv->enabled != enabled)
 565     {
 566       action->priv->enabled = enabled;
 567       g_object_notify (G_OBJECT (action), "enabled");
 568     }
 569 }
 570
 571 /**
 572  * g_action_activate:
 573  * @action: a #GAction
 574  * @parameter: (allow-none): the parameter to the activation
 575  *
 576  * Activates the action.
 577  *
 578  * @parameter must be the correct type of parameter for the action (ie:
 579  * the parameter type given at construction time).  If the parameter
 580  * type was %NULL then @parameter must also be %NULL.
 581  *
 582  * Since: 2.26
 583  **/
 584 void
 585 g_action_activate (GAction  *action,
 586                    GVariant *parameter)
 587 {
 588   g_return_if_fail (G_IS_ACTION (action));
 589
 590   g_return_if_fail (action->priv->parameter_type == NULL ?
 591                       parameter == NULL :
 592                     (parameter != NULL &&
 593                      g_variant_is_of_type (parameter,
 594                                            action->priv->parameter_type)));
 595
 596   if (parameter != NULL)
 597     g_variant_ref_sink (parameter);
 598
 599   if (action->priv->enabled)
 600     g_signal_emit (action, g_action_signals[SIGNAL_ACTIVATE], 0, parameter);
 601
 602   if (parameter != NULL)
 603     g_variant_unref (parameter);
 604 }
 605
 606 /**
 607  * g_action_new:
 608  * @name: the name of the action
 609  * @parameter_type: (allow-none): the type of parameter to the activate function
 610  *
 611  * Creates a new action.
 612  *
 613  * The created action is stateless.  See g_action_new_stateful().
 614  *
 615  * Returns: a new #GAction
 616  *
 617  * Since: 2.26
 618  **/
 619 GAction *
 620 g_action_new (const gchar        *name,
 621               const GVariantType *parameter_type)
 622 {
 623   return g_object_new (G_TYPE_ACTION,
 624                        "name", name,
 625                        "parameter-type", parameter_type,
 626                        NULL);
 627 }
 628
 629 /**
 630  * g_action_new_stateful:
 631  * @name: the name of the action
 632  * @parameter_type: (allow-none): the type of the parameter to the activate function
 633  * @state: the initial state of the action
 634  *
 635  * Creates a new stateful action.
 636  *
 637  * @state is the initial state of the action.  All future state values
 638  * must have the same #GVariantType as the initial state.
 639  *
 640  * If the @state GVariant is floating, it is consumed.
 641  *
 642  * Returns: a new #GAction
 643  *
 644  * Since: 2.26
 645  **/
 646 GAction *
 647 g_action_new_stateful (const gchar        *name,
 648                        const GVariantType *parameter_type,
 649                        GVariant           *state)
 650 {
 651   return g_object_new (G_TYPE_ACTION,
 652                        "name", name,
 653                        "parameter-type", parameter_type,
 654                        "state", state,
 655                        NULL);
 656 }