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  * Since: 2.26
 367  **/
 368 void
 369 g_action_set_state (GAction  *action,
 370                     GVariant *value)
 371 {
 372   const GVariantType *state_type;
 373
 374   g_return_if_fail (G_IS_ACTION (action));
 375   g_return_if_fail (value != NULL);
 376   state_type = g_action_get_state_type (action);
 377   g_return_if_fail (state_type != NULL);
 378   g_return_if_fail (g_variant_is_of_type (value, state_type));
 379
 380   g_variant_ref_sink (value);
 381
 382   if (action->priv->enabled)
 383     G_ACTION_GET_CLASS (action)
 384       ->set_state (action, value);
 385
 386   g_variant_unref (value);
 387 }
 388
 389 /**
 390  * g_action_get_state:
 391  * @action: a #GAction
 392  *
 393  * Queries the current state of @action.
 394  *
 395  * If the action is not stateful then %NULL will be returned.  If the
 396  * action is stateful then the type of the return value is the type
 397  * given by g_action_get_state_type().
 398  *
 399  * Returns: (allow-none) (transfer none): the current state of the action
 400  *
 401  * Since: 2.26
 402  **/
 403 GVariant *
 404 g_action_get_state (GAction *action)
 405 {
 406   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 407
 408   return action->priv->state;
 409 }
 410
 411 /**
 412  * g_action_get_name:
 413  * @action: a #GAction
 414  *
 415  * Queries the name of @action.
 416  *
 417  * Returns: the name of the action
 418  *
 419  * Since: 2.26
 420  **/
 421 const gchar *
 422 g_action_get_name (GAction *action)
 423 {
 424   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 425
 426   return action->priv->name;
 427 }
 428
 429 /**
 430  * g_action_get_parameter_type:
 431  * @action: a #GAction
 432  *
 433  * Queries the type of the parameter that must be given when activating
 434  * @action.
 435  *
 436  * When activating the action using g_action_activate(), the #GVariant
 437  * given to that function must be of the type returned by this function.
 438  *
 439  * In the case that this function returns %NULL, you must not give any
 440  * #GVariant, but %NULL instead.
 441  *
 442  * Returns: (allow-none): the parameter type
 443  *
 444  * Since: 2.26
 445  **/
 446 const GVariantType *
 447 g_action_get_parameter_type (GAction *action)
 448 {
 449   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 450
 451   return action->priv->parameter_type;
 452 }
 453
 454 /**
 455  * g_action_get_state_type:
 456  * @action: a #GAction
 457  *
 458  * Queries the type of the state of @action.
 459  *
 460  * If the action is stateful (ie: was created with
 461  * g_action_new_stateful()) then this function returns the #GVariantType
 462  * of the state.  This is the type of the initial value given as the
 463  * state.  All calls to g_action_set_state() must give a #GVariant of
 464  * this type and g_action_get_state() will return a #GVariant of the
 465  * same type.
 466  *
 467  * If the action is not stateful (ie: created with g_action_new()) then
 468  * this function will return %NULL.  In that case, g_action_get_state()
 469  * will return %NULL and you must not call g_action_set_state().
 470  *
 471  * Returns: (allow-none): the state type, if the action is stateful
 472  *
 473  * Since: 2.26
 474  **/
 475 const GVariantType *
 476 g_action_get_state_type (GAction *action)
 477 {
 478   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 479
 480   if (action->priv->state != NULL)
 481     return g_variant_get_type (action->priv->state);
 482   else
 483     return NULL;
 484 }
 485
 486 /**
 487  * g_action_get_state_hint:
 488  * @action: a #GAction
 489  *
 490  * Requests a hint about the valid range of values for the state of
 491  * @action.
 492  *
 493  * If %NULL is returned it either means that the action is not stateful
 494  * or that there is no hint about the valid range of values for the
 495  * state of the action.
 496  *
 497  * If a #GVariant array is returned then each item in the array is a
 498  * possible value for the state.  If a #GVariant pair (ie: two-tuple) is
 499  * returned then the tuple specifies the inclusive lower and upper bound
 500  * of valid values for the state.
 501  *
 502  * In any case, the information is merely a hint.  It may be possible to
 503  * have a state value outside of the hinted range and setting a value
 504  * within the range may fail.
 505  *
 506  * The return value (if non-%NULL) should be freed with
 507  * g_variant_unref() when it is no longer required.
 508  *
 509  * Returns: (allow-none): the state range hint
 510  *
 511  * Since: 2.26
 512  **/
 513 GVariant *
 514 g_action_get_state_hint (GAction *action)
 515 {
 516   g_return_val_if_fail (G_IS_ACTION (action), NULL);
 517
 518   return G_ACTION_GET_CLASS (action)->get_state_hint (action);
 519 }
 520
 521 /**
 522  * g_action_get_enabled:
 523  * @action: a #GAction
 524  *
 525  * Checks if @action is currently enabled.
 526  *
 527  * An action must be enabled in order to be activated or in order to
 528  * have its state changed from outside callers.
 529  *
 530  * Returns: whether the action is enabled
 531  *
 532  * Since: 2.26
 533  **/
 534 gboolean
 535 g_action_get_enabled (GAction *action)
 536 {
 537   g_return_val_if_fail (G_IS_ACTION (action), FALSE);
 538
 539   return action->priv->enabled;
 540 }
 541
 542 /**
 543  * g_action_set_enabled:
 544  * @action: a #GAction
 545  * @enabled: whether the action is enabled
 546  *
 547  * Sets the action as enabled or not.
 548  *
 549  * An action must be enabled in order to be activated or in order to
 550  * have its state changed from outside callers.
 551  *
 552  * Since: 2.26
 553  **/
 554 void
 555 g_action_set_enabled (GAction  *action,
 556                       gboolean  enabled)
 557 {
 558   g_return_if_fail (G_IS_ACTION (action));
 559
 560   enabled = !!enabled;
 561
 562   if (action->priv->enabled != enabled)
 563     {
 564       action->priv->enabled = enabled;
 565       g_object_notify (G_OBJECT (action), "enabled");
 566     }
 567 }
 568
 569 /**
 570  * g_action_activate:
 571  * @action: a #GAction
 572  * @parameter: (allow-none): the parameter to the activation
 573  *
 574  * Activates the action.
 575  *
 576  * @parameter must be the correct type of parameter for the action (ie:
 577  * the parameter type given at construction time).  If the parameter
 578  * type was %NULL then @parameter must also be %NULL.
 579  *
 580  * Since: 2.26
 581  **/
 582 void
 583 g_action_activate (GAction  *action,
 584                    GVariant *parameter)
 585 {
 586   g_return_if_fail (G_IS_ACTION (action));
 587
 588   g_return_if_fail (action->priv->parameter_type == NULL ?
 589                       parameter == NULL :
 590                     (parameter != NULL &&
 591                      g_variant_is_of_type (parameter,
 592                                            action->priv->parameter_type)));
 593
 594   if (parameter != NULL)
 595     g_variant_ref_sink (parameter);
 596
 597   if (action->priv->enabled)
 598     g_signal_emit (action, g_action_signals[SIGNAL_ACTIVATE], 0, parameter);
 599
 600   if (parameter != NULL)
 601     g_variant_unref (parameter);
 602 }
 603
 604 /**
 605  * g_action_new:
 606  * @name: the name of the action
 607  * @parameter_type: (allow-none): the type of parameter to the activate function
 608  *
 609  * Creates a new action.
 610  *
 611  * The created action is stateless.  See g_action_new_stateful().
 612  *
 613  * Returns: a new #GAction
 614  *
 615  * Since: 2.26
 616  **/
 617 GAction *
 618 g_action_new (const gchar        *name,
 619               const GVariantType *parameter_type)
 620 {
 621   return g_object_new (G_TYPE_ACTION,
 622                        "name", name,
 623                        "parameter-type", parameter_type,
 624                        NULL);
 625 }
 626
 627 /**
 628  * g_action_new_stateful:
 629  * @name: the name of the action
 630  * @parameter_type: (allow-none): the type of the parameter to the activate function
 631  * @state: the initial state of the action
 632  *
 633  * Creates a new stateful action.
 634  *
 635  * @state is the initial state of the action.  All future state values
 636  * must have the same #GVariantType as the initial state.
 637  *
 638  * Returns: a new #GAction
 639  *
 640  * Since: 2.26
 641  **/
 642 GAction *
 643 g_action_new_stateful (const gchar        *name,
 644                        const GVariantType *parameter_type,
 645                        GVariant           *state)
 646 {
 647   return g_object_new (G_TYPE_ACTION,
 648                        "name", name,
 649                        "parameter-type", parameter_type,
 650                        "state", state,
 651                        NULL);
 652 }