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