gsimpleaction.c 19.5 KB
Newer Older
1 2 3
/*
 * Copyright © 2010 Codethink Limited
 *
4 5 6 7
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
8 9 10 11 12 13 14
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General
15
 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
16 17 18 19 20 21 22 23 24 25 26 27 28 29
 *
 * Authors: Ryan Lortie <desrt@desrt.ca>
 */

#include "config.h"

#include "gsimpleaction.h"

#include "gaction.h"
#include "glibintl.h"

/**
 * SECTION:gsimpleaction
 * @title: GSimpleAction
Matthias Clasen's avatar
Matthias Clasen committed
30
 * @short_description: A simple GAction implementation
31
 * @include: gio/gio.h
32
 *
33
 * A #GSimpleAction is the obvious simple implementation of the #GAction
Matthias Clasen's avatar
Matthias Clasen committed
34
 * interface. This is the easiest way to create an action for purposes of
35 36 37
 * adding it to a #GSimpleActionGroup.
 *
 * See also #GtkAction.
Matthias Clasen's avatar
Matthias Clasen committed
38
 */
39 40 41 42 43 44 45 46

/**
 * GSimpleAction:
 *
 * #GSimpleAction is an opaque data structure and can only be accessed
 * using the following functions.
 **/

47
struct _GSimpleAction
48
{
49 50
  GObject       parent_instance;

51 52
  gchar        *name;
  GVariantType *parameter_type;
53
  gboolean      enabled;
54
  GVariant     *state;
55
  GVariant     *state_hint;
56
  gboolean      state_set_already;
57 58
};

59 60 61 62 63 64
typedef GObjectClass GSimpleActionClass;

static void g_simple_action_iface_init (GActionInterface *iface);
G_DEFINE_TYPE_WITH_CODE (GSimpleAction, g_simple_action, G_TYPE_OBJECT,
  G_IMPLEMENT_INTERFACE (G_TYPE_ACTION, g_simple_action_iface_init))

65 66 67 68 69 70 71 72 73 74 75 76
enum
{
  PROP_NONE,
  PROP_NAME,
  PROP_PARAMETER_TYPE,
  PROP_ENABLED,
  PROP_STATE_TYPE,
  PROP_STATE
};

enum
{
77
  SIGNAL_CHANGE_STATE,
78 79 80 81 82 83 84 85 86 87 88
  SIGNAL_ACTIVATE,
  NR_SIGNALS
};

static guint g_simple_action_signals[NR_SIGNALS];

static const gchar *
g_simple_action_get_name (GAction *action)
{
  GSimpleAction *simple = G_SIMPLE_ACTION (action);

89
  return simple->name;
90 91
}

Allison Karlitskaya's avatar
Allison Karlitskaya committed
92
static const GVariantType *
93 94 95 96
g_simple_action_get_parameter_type (GAction *action)
{
  GSimpleAction *simple = G_SIMPLE_ACTION (action);

97
  return simple->parameter_type;
98 99 100 101 102 103 104
}

static const GVariantType *
g_simple_action_get_state_type (GAction *action)
{
  GSimpleAction *simple = G_SIMPLE_ACTION (action);

105 106
  if (simple->state != NULL)
    return g_variant_get_type (simple->state);
107 108 109 110 111 112 113
  else
    return NULL;
}

static GVariant *
g_simple_action_get_state_hint (GAction *action)
{
114 115 116 117 118 119
  GSimpleAction *simple = G_SIMPLE_ACTION (action);

  if (simple->state_hint != NULL)
    return g_variant_ref (simple->state_hint);
  else
    return NULL;
120 121 122 123 124 125 126
}

static gboolean
g_simple_action_get_enabled (GAction *action)
{
  GSimpleAction *simple = G_SIMPLE_ACTION (action);

127
  return simple->enabled;
128 129 130
}

static void
131 132
g_simple_action_change_state (GAction  *action,
                              GVariant *value)
133 134 135
{
  GSimpleAction *simple = G_SIMPLE_ACTION (action);

136 137 138 139 140 141 142 143 144
  /* If the user connected a signal handler then they are responsible
   * for handling state changes.
   */
  if (g_signal_has_handler_pending (action, g_simple_action_signals[SIGNAL_CHANGE_STATE], 0, TRUE))
    g_signal_emit (action, g_simple_action_signals[SIGNAL_CHANGE_STATE], 0, value);

  /* If not, then the default behaviour is to just set the state. */
  else
    g_simple_action_set_state (simple, value);
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160
}

/**
 * g_simple_action_set_state:
 * @simple: a #GSimpleAction
 * @value: the new #GVariant for the state
 *
 * Sets the state of the action.
 *
 * This directly updates the 'state' property to the given value.
 *
 * This should only be called by the implementor of the action.  Users
 * of the action should not attempt to directly modify the 'state'
 * property.  Instead, they should call g_action_change_state() to
 * request the change.
 *
161 162
 * If the @value GVariant is floating, it is consumed.
 *
163 164 165 166 167 168 169
 * Since: 2.30
 **/
void
g_simple_action_set_state (GSimpleAction *simple,
                           GVariant      *value)
{
  g_return_if_fail (G_IS_SIMPLE_ACTION (simple));
170 171 172 173 174
  g_return_if_fail (value != NULL);

  {
    const GVariantType *state_type;

175 176
    state_type = simple->state ?
                   g_variant_get_type (simple->state) : NULL;
177 178 179 180 181 182
    g_return_if_fail (state_type != NULL);
    g_return_if_fail (g_variant_is_of_type (value, state_type));
  }

  g_variant_ref_sink (value);

183
  if (!simple->state || !g_variant_equal (simple->state, value))
184
    {
185 186
      if (simple->state)
        g_variant_unref (simple->state);
187

188
      simple->state = g_variant_ref (value);
189 190 191 192 193 194 195 196 197 198 199 200

      g_object_notify (G_OBJECT (simple), "state");
    }

  g_variant_unref (value);
}

static GVariant *
g_simple_action_get_state (GAction *action)
{
  GSimpleAction *simple = G_SIMPLE_ACTION (action);

201
  return simple->state ? g_variant_ref (simple->state) : NULL;
202 203 204 205 206 207 208 209
}

static void
g_simple_action_activate (GAction  *action,
                          GVariant *parameter)
{
  GSimpleAction *simple = G_SIMPLE_ACTION (action);

210
  g_return_if_fail (simple->parameter_type == NULL ?
211 212 213
                      parameter == NULL :
                    (parameter != NULL &&
                     g_variant_is_of_type (parameter,
214
                                           simple->parameter_type)));
215 216 217 218

  if (parameter != NULL)
    g_variant_ref_sink (parameter);

219
  if (simple->enabled)
220 221 222 223 224
    {
      /* If the user connected a signal handler then they are responsible
       * for handling activation.
       */
      if (g_signal_has_handler_pending (action, g_simple_action_signals[SIGNAL_ACTIVATE], 0, TRUE))
225
        g_signal_emit (action, g_simple_action_signals[SIGNAL_ACTIVATE], 0, parameter);
226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241

      /* If not, do some reasonable defaults for stateful actions. */
      else if (simple->state)
        {
          /* If we have no parameter and this is a boolean action, toggle. */
          if (parameter == NULL && g_variant_is_of_type (simple->state, G_VARIANT_TYPE_BOOLEAN))
            {
              gboolean was_enabled = g_variant_get_boolean (simple->state);
              g_simple_action_change_state (action, g_variant_new_boolean (!was_enabled));
            }

          /* else, if the parameter and state type are the same, do a change-state */
          else if (g_variant_is_of_type (simple->state, g_variant_get_type (parameter)))
            g_simple_action_change_state (action, parameter);
        }
    }
242 243 244 245 246

  if (parameter != NULL)
    g_variant_unref (parameter);
}

247 248 249 250 251 252 253 254 255 256 257 258 259
static void
g_simple_action_set_property (GObject    *object,
                              guint       prop_id,
                              const GValue     *value,
                              GParamSpec *pspec)
{
  GSimpleAction *action = G_SIMPLE_ACTION (object);

  switch (prop_id)
    {
    case PROP_NAME:
      action->name = g_strdup (g_value_get_string (value));
      break;
260

261 262 263 264 265 266 267 268 269
    case PROP_PARAMETER_TYPE:
      action->parameter_type = g_value_dup_boxed (value);
      break;

    case PROP_ENABLED:
      action->enabled = g_value_get_boolean (value);
      break;

    case PROP_STATE:
270 271 272 273 274 275 276 277 278 279 280 281 282 283
      /* The first time we see this (during construct) we should just
       * take the state as it was handed to us.
       *
       * After that, we should make sure we go through the same checks
       * as the C API.
       */
      if (!action->state_set_already)
        {
          action->state = g_value_dup_variant (value);
          action->state_set_already = TRUE;
        }
      else
        g_simple_action_set_state (action, g_value_get_variant (value));

284 285 286 287 288 289 290
      break;

    default:
      g_assert_not_reached ();
    }
}

291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330
static void
g_simple_action_get_property (GObject    *object,
                              guint       prop_id,
                              GValue     *value,
                              GParamSpec *pspec)
{
  GAction *action = G_ACTION (object);

  switch (prop_id)
    {
    case PROP_NAME:
      g_value_set_string (value, g_simple_action_get_name (action));
      break;

    case PROP_PARAMETER_TYPE:
      g_value_set_boxed (value, g_simple_action_get_parameter_type (action));
      break;

    case PROP_ENABLED:
      g_value_set_boolean (value, g_simple_action_get_enabled (action));
      break;

    case PROP_STATE_TYPE:
      g_value_set_boxed (value, g_simple_action_get_state_type (action));
      break;

    case PROP_STATE:
      g_value_take_variant (value, g_simple_action_get_state (action));
      break;

    default:
      g_assert_not_reached ();
    }
}

static void
g_simple_action_finalize (GObject *object)
{
  GSimpleAction *simple = G_SIMPLE_ACTION (object);

331 332 333 334 335
  g_free (simple->name);
  if (simple->parameter_type)
    g_variant_type_free (simple->parameter_type);
  if (simple->state)
    g_variant_unref (simple->state);
336 337
  if (simple->state_hint)
    g_variant_unref (simple->state_hint);
338 339 340 341 342 343 344 345

  G_OBJECT_CLASS (g_simple_action_parent_class)
    ->finalize (object);
}

void
g_simple_action_init (GSimpleAction *simple)
{
346
  simple->enabled = TRUE;
347 348 349 350 351 352 353 354 355 356 357
}

void
g_simple_action_iface_init (GActionInterface *iface)
{
  iface->get_name = g_simple_action_get_name;
  iface->get_parameter_type = g_simple_action_get_parameter_type;
  iface->get_state_type = g_simple_action_get_state_type;
  iface->get_state_hint = g_simple_action_get_state_hint;
  iface->get_enabled = g_simple_action_get_enabled;
  iface->get_state = g_simple_action_get_state;
358
  iface->change_state = g_simple_action_change_state;
359 360 361 362 363 364 365 366
  iface->activate = g_simple_action_activate;
}

void
g_simple_action_class_init (GSimpleActionClass *class)
{
  GObjectClass *object_class = G_OBJECT_CLASS (class);

367
  object_class->set_property = g_simple_action_set_property;
368 369 370 371 372 373
  object_class->get_property = g_simple_action_get_property;
  object_class->finalize = g_simple_action_finalize;

  /**
   * GSimpleAction::activate:
   * @simple: the #GSimpleAction
374 375
   * @parameter: (nullable): the parameter to the activation, or %NULL if it has
   *   no parameter
376 377 378
   *
   * Indicates that the action was just activated.
   *
379 380 381
   * @parameter will always be of the expected type, i.e. the parameter type
   * specified when the action was created. If an incorrect type is given when
   * activating the action, this signal is not emitted.
382
   *
383 384 385 386 387 388 389 390
   * Since GLib 2.40, if no handler is connected to this signal then the
   * default behaviour for boolean-stated actions with a %NULL parameter
   * type is to toggle them via the #GSimpleAction::change-state signal.
   * For stateful actions where the state type is equal to the parameter
   * type, the default is to forward them directly to
   * #GSimpleAction::change-state.  This should allow almost all users
   * of #GSimpleAction to connect only one handler or the other.
   *
391
   * Since: 2.28
392 393 394 395
   */
  g_simple_action_signals[SIGNAL_ACTIVATE] =
    g_signal_new (I_("activate"),
                  G_TYPE_SIMPLE_ACTION,
396
                  G_SIGNAL_RUN_LAST | G_SIGNAL_MUST_COLLECT,
397
                  0, NULL, NULL,
398 399 400 401
                  g_cclosure_marshal_VOID__VARIANT,
                  G_TYPE_NONE, 1,
                  G_TYPE_VARIANT);

402 403 404
  /**
   * GSimpleAction::change-state:
   * @simple: the #GSimpleAction
405
   * @value: (nullable): the requested value for the state
406 407 408 409
   *
   * Indicates that the action just received a request to change its
   * state.
   *
410 411 412 413
   * @value will always be of the correct state type, i.e. the type of the
   * initial state passed to g_simple_action_new_stateful(). If an incorrect
   * type is given when requesting to change the state, this signal is not
   * emitted.
414 415 416
   *
   * If no handler is connected to this signal then the default
   * behaviour is to call g_simple_action_set_state() to set the state
417 418
   * to the requested value. If you connect a signal handler then no
   * default action is taken. If the state should change then you must
419 420
   * call g_simple_action_set_state() from the handler.
   *
421
   * An example of a 'change-state' handler:
422
   * |[<!-- language="C" -->
423 424 425 426 427 428 429 430 431
   * static void
   * change_volume_state (GSimpleAction *action,
   *                      GVariant      *value,
   *                      gpointer       user_data)
   * {
   *   gint requested;
   *
   *   requested = g_variant_get_int32 (value);
   *
Matthias Clasen's avatar
Matthias Clasen committed
432
   *   // Volume only goes from 0 to 10
433 434 435
   *   if (0 <= requested && requested <= 10)
   *     g_simple_action_set_state (action, value);
   * }
436
   * ]|
437
   *
438 439
   * The handler need not set the state to the requested value.
   * It could set it to any value at all, or take some other action.
440
   *
441 442 443 444 445 446 447 448 449 450 451
   * Since: 2.30
   */
  g_simple_action_signals[SIGNAL_CHANGE_STATE] =
    g_signal_new (I_("change-state"),
                  G_TYPE_SIMPLE_ACTION,
                  G_SIGNAL_RUN_LAST | G_SIGNAL_MUST_COLLECT,
                  0, NULL, NULL,
                  g_cclosure_marshal_VOID__VARIANT,
                  G_TYPE_NONE, 1,
                  G_TYPE_VARIANT);

452 453 454
  /**
   * GSimpleAction:name:
   *
455
   * The name of the action. This is mostly meaningful for identifying
456 457
   * the action once it has been added to a #GSimpleActionGroup.
   *
458
   * Since: 2.28
459 460 461 462 463 464
   **/
  g_object_class_install_property (object_class, PROP_NAME,
                                   g_param_spec_string ("name",
                                                        P_("Action Name"),
                                                        P_("The name used to invoke the action"),
                                                        NULL,
465
                                                        G_PARAM_READWRITE |
466
                                                        G_PARAM_CONSTRUCT_ONLY |
467 468 469 470 471 472 473 474
                                                        G_PARAM_STATIC_STRINGS));

  /**
   * GSimpleAction:parameter-type:
   *
   * The type of the parameter that must be given when activating the
   * action.
   *
475
   * Since: 2.28
476 477 478 479 480 481
   **/
  g_object_class_install_property (object_class, PROP_PARAMETER_TYPE,
                                   g_param_spec_boxed ("parameter-type",
                                                       P_("Parameter Type"),
                                                       P_("The type of GVariant passed to activate()"),
                                                       G_TYPE_VARIANT_TYPE,
482
                                                       G_PARAM_READWRITE |
483
                                                       G_PARAM_CONSTRUCT_ONLY |
484 485 486 487 488 489 490
                                                       G_PARAM_STATIC_STRINGS));

  /**
   * GSimpleAction:enabled:
   *
   * If @action is currently enabled.
   *
491 492
   * If the action is disabled then calls to g_action_activate() and
   * g_action_change_state() have no effect.
493
   *
494
   * Since: 2.28
495 496 497 498 499 500
   **/
  g_object_class_install_property (object_class, PROP_ENABLED,
                                   g_param_spec_boolean ("enabled",
                                                         P_("Enabled"),
                                                         P_("If the action can be activated"),
                                                         TRUE,
501
                                                         G_PARAM_READWRITE |
502 503 504 505 506 507 508 509
                                                         G_PARAM_STATIC_STRINGS));

  /**
   * GSimpleAction:state-type:
   *
   * The #GVariantType of the state that the action has, or %NULL if the
   * action is stateless.
   *
510
   * Since: 2.28
511 512 513 514 515 516 517 518 519 520 521 522 523 524
   **/
  g_object_class_install_property (object_class, PROP_STATE_TYPE,
                                   g_param_spec_boxed ("state-type",
                                                       P_("State Type"),
                                                       P_("The type of the state kept by the action"),
                                                       G_TYPE_VARIANT_TYPE,
                                                       G_PARAM_READABLE |
                                                       G_PARAM_STATIC_STRINGS));

  /**
   * GSimpleAction:state:
   *
   * The state of the action, or %NULL if the action is stateless.
   *
525
   * Since: 2.28
526 527 528 529 530 531 532
   **/
  g_object_class_install_property (object_class, PROP_STATE,
                                   g_param_spec_variant ("state",
                                                         P_("State"),
                                                         P_("The state the action is in"),
                                                         G_VARIANT_TYPE_ANY,
                                                         NULL,
533
                                                         G_PARAM_READWRITE | G_PARAM_CONSTRUCT |
534 535 536 537 538 539 540 541 542 543 544 545 546
                                                         G_PARAM_STATIC_STRINGS));
}

/**
 * g_simple_action_set_enabled:
 * @simple: a #GSimpleAction
 * @enabled: whether the action is enabled
 *
 * Sets the action as enabled or not.
 *
 * An action must be enabled in order to be activated or in order to
 * have its state changed from outside callers.
 *
547 548 549
 * This should only be called by the implementor of the action.  Users
 * of the action should not attempt to modify its enabled flag.
 *
550
 * Since: 2.28
551 552 553 554 555 556 557 558 559
 **/
void
g_simple_action_set_enabled (GSimpleAction *simple,
                             gboolean       enabled)
{
  g_return_if_fail (G_IS_SIMPLE_ACTION (simple));

  enabled = !!enabled;

560
  if (simple->enabled != enabled)
561
    {
562
      simple->enabled = enabled;
563 564 565
      g_object_notify (G_OBJECT (simple), "enabled");
    }
}
566 567 568 569

/**
 * g_simple_action_set_state_hint:
 * @simple: a #GSimpleAction
570
 * @state_hint: (nullable): a #GVariant representing the state hint
571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594
 *
 * Sets the state hint for the action.
 *
 * See g_action_get_state_hint() for more information about
 * action state hints.
 *
 * Since: 2.44
 **/
void
g_simple_action_set_state_hint (GSimpleAction *simple,
                                GVariant      *state_hint)
{
  g_return_if_fail (G_IS_SIMPLE_ACTION (simple));

  if (simple->state_hint != NULL)
    {
      g_variant_unref (simple->state_hint);
      simple->state_hint = NULL;
    }

  if (state_hint != NULL)
    simple->state_hint = g_variant_ref (state_hint);
}

595 596 597
/**
 * g_simple_action_new:
 * @name: the name of the action
598 599
 * @parameter_type: (nullable): the type of parameter that will be passed to
 *   handlers for the #GSimpleAction::activate signal, or %NULL for no parameter
600 601 602
 *
 * Creates a new action.
 *
603 604
 * The created action is stateless. See g_simple_action_new_stateful() to create
 * an action that has state.
605 606 607
 *
 * Returns: a new #GSimpleAction
 *
608
 * Since: 2.28
609 610 611 612 613
 **/
GSimpleAction *
g_simple_action_new (const gchar        *name,
                     const GVariantType *parameter_type)
{
614 615
  g_return_val_if_fail (name != NULL, NULL);

616 617 618 619
  return g_object_new (G_TYPE_SIMPLE_ACTION,
                       "name", name,
                       "parameter-type", parameter_type,
                       NULL);
620 621 622 623 624
}

/**
 * g_simple_action_new_stateful:
 * @name: the name of the action
625 626
 * @parameter_type: (nullable): the type of the parameter that will be passed to
 *   handlers for the #GSimpleAction::activate signal, or %NULL for no parameter
627 628 629 630
 * @state: the initial state of the action
 *
 * Creates a new stateful action.
 *
631 632
 * All future state values must have the same #GVariantType as the initial
 * @state.
633
 *
634
 * If the @state #GVariant is floating, it is consumed.
635 636 637
 *
 * Returns: a new #GSimpleAction
 *
638
 * Since: 2.28
639 640 641 642 643 644
 **/
GSimpleAction *
g_simple_action_new_stateful (const gchar        *name,
                              const GVariantType *parameter_type,
                              GVariant           *state)
{
645 646 647 648 649
  return g_object_new (G_TYPE_SIMPLE_ACTION,
                       "name", name,
                       "parameter-type", parameter_type,
                       "state", state,
                       NULL);
650
}