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