gaction.c 18 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
 *
 * Authors: Ryan Lortie <desrt@desrt.ca>
 */

Emmanuele Bassi's avatar
Emmanuele Bassi committed
20
#include "config.h"
21
#include "gaction.h"
Emmanuele Bassi's avatar
Emmanuele Bassi committed
22
#include "glibintl.h"
23

24 25
#include <string.h>

26
G_DEFINE_INTERFACE (GAction, g_action, G_TYPE_OBJECT)
27 28 29 30

/**
 * SECTION:gaction
 * @title: GAction
Matthias Clasen's avatar
Matthias Clasen committed
31
 * @short_description: An action interface
32
 * @include: gio/gio.h
33 34 35 36 37 38 39 40 41 42
 *
 * #GAction represents a single named action.
 *
 * The main interface to an action is that it can be activated with
 * g_action_activate().  This results in the 'activate' signal being
 * emitted.  An activation has a #GVariant parameter (which may be
 * %NULL).  The correct type for the parameter is determined by a static
 * parameter type (which is given at construction time).
 *
 * An action may optionally have a state, in which case the state may be
43
 * set with g_action_change_state().  This call takes a #GVariant.  The
44 45 46 47 48 49
 * correct type for the state is determined by a static state type
 * (which is given at construction time).
 *
 * The state may have a hint associated with it, specifying its valid
 * range.
 *
50 51
 * #GAction is merely the interface to the concept of an action, as
 * described above.  Various implementations of actions exist, including
Matthias Clasen's avatar
Matthias Clasen committed
52
 * #GSimpleAction.
53
 *
54 55 56
 * In all cases, the implementing class is responsible for storing the
 * name of the action, the parameter type, the enabled state, the
 * optional state type and the state and emitting the appropriate
57
 * signals when these change.  The implementor is responsible for filtering
58 59
 * calls to g_action_activate() and g_action_change_state() for type
 * safety and for the state being enabled.
60 61 62 63 64
 *
 * Probably the only useful thing to do with a #GAction is to put it
 * inside of a #GSimpleActionGroup.
 **/

65 66 67 68 69 70 71
/**
 * GAction:
 *
 * #GAction is an opaque data structure and can only be accessed
 * using the following functions.
 **/

72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
/**
 * GActionInterface:
 * @get_name: the virtual function pointer for g_action_get_name()
 * @get_parameter_type: the virtual function pointer for g_action_get_parameter_type()
 * @get_state_type: the virtual function pointer for g_action_get_state_type()
 * @get_state_hint: the virtual function pointer for g_action_get_state_hint()
 * @get_enabled: the virtual function pointer for g_action_get_enabled()
 * @get_state: the virtual function pointer for g_action_get_state()
 * @change_state: the virtual function pointer for g_action_change_state()
 * @activate: the virtual function pointer for g_action_activate().  Note that #GAction does not have an
 *            'activate' signal but that implementations of it may have one.
 *
 * The virtual function table for #GAction.
 *
 * Since: 2.28
 */

89
void
90
g_action_default_init (GActionInterface *iface)
91 92 93 94 95
{
  /**
   * GAction:name:
   *
   * The name of the action.  This is mostly meaningful for identifying
96
   * the action once it has been added to a #GActionGroup. It is immutable.
Emmanuele Bassi's avatar
Emmanuele Bassi committed
97
   *
98
   * Since: 2.28
99
   **/
100 101 102 103 104
  g_object_interface_install_property (iface,
                                       g_param_spec_string ("name",
                                                            P_("Action Name"),
                                                            P_("The name used to invoke the action"),
                                                            NULL,
105
                                                            G_PARAM_READABLE |
106
                                                            G_PARAM_STATIC_STRINGS));
107 108 109 110 111

  /**
   * GAction:parameter-type:
   *
   * The type of the parameter that must be given when activating the
112 113
   * action. This is immutable, and may be %NULL if no parameter is needed when
   * activating the action.
Emmanuele Bassi's avatar
Emmanuele Bassi committed
114
   *
115
   * Since: 2.28
116
   **/
117 118 119 120 121
  g_object_interface_install_property (iface,
                                       g_param_spec_boxed ("parameter-type",
                                                           P_("Parameter Type"),
                                                           P_("The type of GVariant passed to activate()"),
                                                           G_TYPE_VARIANT_TYPE,
122
                                                           G_PARAM_READABLE |
123
                                                           G_PARAM_STATIC_STRINGS));
124 125 126 127 128 129 130

  /**
   * GAction:enabled:
   *
   * If @action is currently enabled.
   *
   * If the action is disabled then calls to g_action_activate() and
131
   * g_action_change_state() have no effect.
Emmanuele Bassi's avatar
Emmanuele Bassi committed
132
   *
133
   * Since: 2.28
134
   **/
135 136 137 138 139
  g_object_interface_install_property (iface,
                                       g_param_spec_boolean ("enabled",
                                                             P_("Enabled"),
                                                             P_("If the action can be activated"),
                                                             TRUE,
140
                                                             G_PARAM_READABLE |
141
                                                             G_PARAM_STATIC_STRINGS));
142 143 144 145 146

  /**
   * GAction:state-type:
   *
   * The #GVariantType of the state that the action has, or %NULL if the
147
   * action is stateless. This is immutable.
Emmanuele Bassi's avatar
Emmanuele Bassi committed
148
   *
149
   * Since: 2.28
150
   **/
151 152 153 154 155 156 157
  g_object_interface_install_property (iface,
                                       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));
158 159 160 161 162

  /**
   * GAction:state:
   *
   * The state of the action, or %NULL if the action is stateless.
Emmanuele Bassi's avatar
Emmanuele Bassi committed
163
   *
164
   * Since: 2.28
165
   **/
166 167 168 169 170 171
  g_object_interface_install_property (iface,
                                       g_param_spec_variant ("state",
                                                             P_("State"),
                                                             P_("The state the action is in"),
                                                             G_VARIANT_TYPE_ANY,
                                                             NULL,
172
                                                             G_PARAM_READABLE |
173
                                                             G_PARAM_STATIC_STRINGS));
174 175 176
}

/**
177
 * g_action_change_state:
178 179 180 181 182 183 184 185 186 187 188 189
 * @action: a #GAction
 * @value: the new state
 *
 * Request for the state of @action to be changed to @value.
 *
 * The action must be stateful and @value must be of the correct type.
 * See g_action_get_state_type().
 *
 * This call merely requests a change.  The action may refuse to change
 * its state or may change its state to something other than @value.
 * See g_action_get_state_hint().
 *
190 191
 * If the @value GVariant is floating, it is consumed.
 *
192
 * Since: 2.30
193 194
 **/
void
195 196
g_action_change_state (GAction  *action,
                       GVariant *value)
197
{
198 199
  const GVariantType *state_type;

200
  g_return_if_fail (G_IS_ACTION (action));
201 202 203 204
  g_return_if_fail (value != NULL);
  state_type = g_action_get_state_type (action);
  g_return_if_fail (state_type != NULL);
  g_return_if_fail (g_variant_is_of_type (value, state_type));
205 206 207

  g_variant_ref_sink (value);

208
  G_ACTION_GET_IFACE (action)
209
    ->change_state (action, value);
210 211 212 213 214 215 216 217 218 219 220 221 222 223

  g_variant_unref (value);
}

/**
 * g_action_get_state:
 * @action: a #GAction
 *
 * Queries the current state of @action.
 *
 * If the action is not stateful then %NULL will be returned.  If the
 * action is stateful then the type of the return value is the type
 * given by g_action_get_state_type().
 *
224 225
 * The return value (if non-%NULL) should be freed with
 * g_variant_unref() when it is no longer required.
226
 *
227
 * Returns: (transfer full): the current state of the action
228
 *
229
 * Since: 2.28
230 231 232 233 234 235
 **/
GVariant *
g_action_get_state (GAction *action)
{
  g_return_val_if_fail (G_IS_ACTION (action), NULL);

236 237
  return G_ACTION_GET_IFACE (action)
    ->get_state (action);
238 239 240 241 242 243 244 245 246 247
}

/**
 * g_action_get_name:
 * @action: a #GAction
 *
 * Queries the name of @action.
 *
 * Returns: the name of the action
 *
248
 * Since: 2.28
249 250 251 252 253 254
 **/
const gchar *
g_action_get_name (GAction *action)
{
  g_return_val_if_fail (G_IS_ACTION (action), NULL);

255 256
  return G_ACTION_GET_IFACE (action)
    ->get_name (action);
257 258 259 260 261 262 263 264 265 266 267 268 269 270 271
}

/**
 * g_action_get_parameter_type:
 * @action: a #GAction
 *
 * Queries the type of the parameter that must be given when activating
 * @action.
 *
 * When activating the action using g_action_activate(), the #GVariant
 * given to that function must be of the type returned by this function.
 *
 * In the case that this function returns %NULL, you must not give any
 * #GVariant, but %NULL instead.
 *
272
 * Returns: (nullable): the parameter type
273
 *
274
 * Since: 2.28
275 276 277 278 279 280
 **/
const GVariantType *
g_action_get_parameter_type (GAction *action)
{
  g_return_val_if_fail (G_IS_ACTION (action), NULL);

281 282
  return G_ACTION_GET_IFACE (action)
    ->get_parameter_type (action);
283 284 285 286 287 288 289 290
}

/**
 * g_action_get_state_type:
 * @action: a #GAction
 *
 * Queries the type of the state of @action.
 *
Matthias Clasen's avatar
Matthias Clasen committed
291 292 293
 * If the action is stateful (e.g. created with
 * g_simple_action_new_stateful()) then this function returns the
 * #GVariantType of the state.  This is the type of the initial value
294
 * given as the state. All calls to g_action_change_state() must give a
Matthias Clasen's avatar
Matthias Clasen committed
295 296 297 298 299
 * #GVariant of this type and g_action_get_state() will return a
 * #GVariant of the same type.
 *
 * If the action is not stateful (e.g. created with g_simple_action_new())
 * then this function will return %NULL. In that case, g_action_get_state()
300
 * will return %NULL and you must not call g_action_change_state().
301
 *
302
 * Returns: (nullable): the state type, if the action is stateful
303
 *
304
 * Since: 2.28
305 306 307 308 309 310
 **/
const GVariantType *
g_action_get_state_type (GAction *action)
{
  g_return_val_if_fail (G_IS_ACTION (action), NULL);

311 312
  return G_ACTION_GET_IFACE (action)
    ->get_state_type (action);
313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337
}

/**
 * g_action_get_state_hint:
 * @action: a #GAction
 *
 * Requests a hint about the valid range of values for the state of
 * @action.
 *
 * If %NULL is returned it either means that the action is not stateful
 * or that there is no hint about the valid range of values for the
 * state of the action.
 *
 * If a #GVariant array is returned then each item in the array is a
 * possible value for the state.  If a #GVariant pair (ie: two-tuple) is
 * returned then the tuple specifies the inclusive lower and upper bound
 * of valid values for the state.
 *
 * In any case, the information is merely a hint.  It may be possible to
 * have a state value outside of the hinted range and setting a value
 * within the range may fail.
 *
 * The return value (if non-%NULL) should be freed with
 * g_variant_unref() when it is no longer required.
 *
338
 * Returns: (nullable) (transfer full): the state range hint
339
 *
340
 * Since: 2.28
341 342 343 344 345 346
 **/
GVariant *
g_action_get_state_hint (GAction *action)
{
  g_return_val_if_fail (G_IS_ACTION (action), NULL);

347 348
  return G_ACTION_GET_IFACE (action)
    ->get_state_hint (action);
349 350 351 352 353 354 355 356 357 358 359 360 361
}

/**
 * g_action_get_enabled:
 * @action: a #GAction
 *
 * Checks if @action is currently enabled.
 *
 * An action must be enabled in order to be activated or in order to
 * have its state changed from outside callers.
 *
 * Returns: whether the action is enabled
 *
362
 * Since: 2.28
363 364 365 366 367 368
 **/
gboolean
g_action_get_enabled (GAction *action)
{
  g_return_val_if_fail (G_IS_ACTION (action), FALSE);

369 370
  return G_ACTION_GET_IFACE (action)
    ->get_enabled (action);
371 372 373 374 375
}

/**
 * g_action_activate:
 * @action: a #GAction
376
 * @parameter: (nullable): the parameter to the activation
377 378 379 380 381 382 383
 *
 * Activates the action.
 *
 * @parameter must be the correct type of parameter for the action (ie:
 * the parameter type given at construction time).  If the parameter
 * type was %NULL then @parameter must also be %NULL.
 *
384 385
 * If the @parameter GVariant is floating, it is consumed.
 *
386
 * Since: 2.28
387 388 389 390 391 392 393
 **/
void
g_action_activate (GAction  *action,
                   GVariant *parameter)
{
  g_return_if_fail (G_IS_ACTION (action));

Emmanuele Bassi's avatar
Emmanuele Bassi committed
394
  if (parameter != NULL)
395 396
    g_variant_ref_sink (parameter);

397 398
  G_ACTION_GET_IFACE (action)
    ->activate (action, parameter);
399

Emmanuele Bassi's avatar
Emmanuele Bassi committed
400
  if (parameter != NULL)
401 402
    g_variant_unref (parameter);
}
403

404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425
/**
 * g_action_name_is_valid:
 * @action_name: an potential action name
 *
 * Checks if @action_name is valid.
 *
 * @action_name is valid if it consists only of alphanumeric characters,
 * plus '-' and '.'.  The empty string is not a valid action name.
 *
 * It is an error to call this function with a non-utf8 @action_name.
 * @action_name must not be %NULL.
 *
 * Returns: %TRUE if @action_name is valid
 *
 * Since: 2.38
 **/
gboolean
g_action_name_is_valid (const gchar *action_name)
{
  gchar c;
  gint i;

426
  g_return_val_if_fail (action_name != NULL, FALSE);
427 428 429 430 431 432 433 434

  for (i = 0; (c = action_name[i]); i++)
    if (!g_ascii_isalnum (c) && c != '.' && c != '-')
      return FALSE;

  return i > 0;
}

435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450
/**
 * g_action_parse_detailed_name:
 * @detailed_name: a detailed action name
 * @action_name: (out): the action name
 * @target_value: (out): the target value, or %NULL for no target
 * @error: a pointer to a %NULL #GError, or %NULL
 *
 * Parses a detailed action name into its separate name and target
 * components.
 *
 * Detailed action names can have three formats.
 *
 * The first format is used to represent an action name with no target
 * value and consists of just an action name containing no whitespace
 * nor the characters ':', '(' or ')'.  For example: "app.action".
 *
451 452 453 454 455
 * The second format is used to represent an action with a target value
 * that is a non-empty string consisting only of alphanumerics, plus '-'
 * and '.'.  In that case, the action name and target value are
 * separated by a double colon ("::").  For example:
 * "app.action::target".
456
 *
457 458
 * The third format is used to represent an action with any type of
 * target value, including strings.  The target value follows the action
459 460 461
 * name, surrounded in parens.  For example: "app.action(42)".  The
 * target value is parsed using g_variant_parse().  If a tuple-typed
 * value is desired, it must be specified in the same way, resulting in
462 463 464 465
 * two sets of parens, for example: "app.action((1,2,3))".  A string
 * target can be specified this way as well: "app.action('target')".
 * For strings, this third format must be used if * target value is
 * empty or contains characters other than alphanumerics, '-' and '.'.
466 467 468 469 470 471 472 473 474 475 476 477 478 479 480
 *
 * Returns: %TRUE if successful, else %FALSE with @error set
 *
 * Since: 2.38
 **/
gboolean
g_action_parse_detailed_name (const gchar  *detailed_name,
                              gchar       **action_name,
                              GVariant    **target_value,
                              GError      **error)
{
  const gchar *target;
  gsize target_len;
  gsize base_len;

481 482 483 484 485
  /* For historical (compatibility) reasons, this function accepts some
   * cases of invalid action names as long as they don't interfere with
   * the separation of the action from the target value.
   *
   * We decide which format we have based on which we see first between
486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540
   * '::' '(' and '\0'.
   */

  if (*detailed_name == '\0' || *detailed_name == ' ')
    goto bad_fmt;

  base_len = strcspn (detailed_name, ": ()");
  target = detailed_name + base_len;
  target_len = strlen (target);

  switch (target[0])
    {
    case ' ':
    case ')':
      goto bad_fmt;

    case ':':
      if (target[1] != ':')
        goto bad_fmt;

      *target_value = g_variant_ref_sink (g_variant_new_string (target + 2));
      break;

    case '(':
      {
        if (target[target_len - 1] != ')')
          goto bad_fmt;

        *target_value = g_variant_parse (NULL, target + 1, target + target_len - 1, NULL, error);
        if (*target_value == NULL)
          goto bad_fmt;
      }
      break;

    case '\0':
      *target_value = NULL;
      break;
    }

  *action_name = g_strndup (detailed_name, base_len);

  return TRUE;

bad_fmt:
  if (error)
    {
      if (*error == NULL)
        g_set_error (error, G_VARIANT_PARSE_ERROR, G_VARIANT_PARSE_ERROR_FAILED,
                     "Detailed action name '%s' has invalid format", detailed_name);
      else
        g_prefix_error (error, "Detailed action name '%s' has invalid format: ", detailed_name);
    }

  return FALSE;
}
541 542 543 544

/**
 * g_action_print_detailed_name:
 * @action_name: a valid action name
545
 * @target_value: (nullable): a #GVariant target value, or %NULL
546 547 548 549 550
 *
 * Formats a detailed action name from @action_name and @target_value.
 *
 * It is an error to call this function with an invalid action name.
 *
551 552 553
 * This function is the opposite of g_action_parse_detailed_name().
 * It will produce a string that can be parsed back to the @action_name
 * and @target_value by that function.
554 555 556 557 558 559 560 561 562 563 564 565
 *
 * See that function for the types of strings that will be printed by
 * this function.
 *
 * Returns: a detailed format string
 *
 * Since: 2.38
 **/
gchar *
g_action_print_detailed_name (const gchar *action_name,
                              GVariant    *target_value)
{
566
  g_return_val_if_fail (g_action_name_is_valid (action_name), NULL);
567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587

  if (target_value == NULL)
    return g_strdup (action_name);

  if (g_variant_is_of_type (target_value, G_VARIANT_TYPE_STRING))
    {
      const gchar *str = g_variant_get_string (target_value, NULL);

      if (g_action_name_is_valid (str))
        return g_strconcat (action_name, "::", str, NULL);
    }

  {
    GString *result = g_string_new (action_name);
    g_string_append_c (result, '(');
    g_variant_print_string (target_value, result, TRUE);
    g_string_append_c (result, ')');

    return g_string_free (result, FALSE);
  }
}