1/*
2 * Copyright © 2010 Codethink Limited
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at 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, see <http://www.gnu.org/licenses/>.
16 *
17 * Authors: Ryan Lortie <desrt@desrt.ca>
18 */
19
20#include "config.h"
21#include "gaction.h"
22#include "glibintl.h"
23
24#include <string.h>
25
26G_DEFINE_INTERFACE (GAction, g_action, G_TYPE_OBJECT)
27
28/**
29 * SECTION:gaction
30 * @title: GAction
31 * @short_description: An action interface
32 * @include: gio/gio.h
33 *
34 * #GAction represents a single named action.
35 *
36 * The main interface to an action is that it can be activated with
37 * g_action_activate(). This results in the 'activate' signal being
38 * emitted. An activation has a #GVariant parameter (which may be
39 * %NULL). The correct type for the parameter is determined by a static
40 * parameter type (which is given at construction time).
41 *
42 * 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 * correct type for the state is determined by a static state type
45 * (which is given at construction time).
46 *
47 * The state may have a hint associated with it, specifying its valid
48 * range.
49 *
50 * #GAction is merely the interface to the concept of an action, as
51 * described above. Various implementations of actions exist, including
52 * #GSimpleAction.
53 *
54 * In all cases, the implementing class is responsible for storing the
55 * name of the action, the parameter type, the enabled state, the
56 * optional state type and the state and emitting the appropriate
57 * signals when these change. The implementor is responsible for filtering
58 * calls to g_action_activate() and g_action_change_state() for type
59 * safety and for the state being enabled.
60 *
61 * Probably the only useful thing to do with a #GAction is to put it
62 * inside of a #GSimpleActionGroup.
63 **/
64
65/**
66 * GAction:
67 *
68 * #GAction is an opaque data structure and can only be accessed
69 * using the following functions.
70 **/
71
72/**
73 * GActionInterface:
74 * @get_name: the virtual function pointer for g_action_get_name()
75 * @get_parameter_type: the virtual function pointer for g_action_get_parameter_type()
76 * @get_state_type: the virtual function pointer for g_action_get_state_type()
77 * @get_state_hint: the virtual function pointer for g_action_get_state_hint()
78 * @get_enabled: the virtual function pointer for g_action_get_enabled()
79 * @get_state: the virtual function pointer for g_action_get_state()
80 * @change_state: the virtual function pointer for g_action_change_state()
81 * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an
82 * 'activate' signal but that implementations of it may have one.
83 *
84 * The virtual function table for #GAction.
85 *
86 * Since: 2.28
87 */
88
89void
90g_action_default_init (GActionInterface *iface)
91{
92 /**
93 * GAction:name:
94 *
95 * 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.
97 *
98 * Since: 2.28
99 **/
100 g_object_interface_install_property (g_iface: iface,
101 pspec: g_param_spec_string (name: "name",
102 P_("Action Name"),
103 P_("The name used to invoke the action"),
104 NULL,
105 flags: G_PARAM_READABLE |
106 G_PARAM_STATIC_STRINGS));
107
108 /**
109 * GAction:parameter-type:
110 *
111 * The type of the parameter that must be given when activating the
112 * action. This is immutable, and may be %NULL if no parameter is needed when
113 * activating the action.
114 *
115 * Since: 2.28
116 **/
117 g_object_interface_install_property (g_iface: iface,
118 pspec: g_param_spec_boxed (name: "parameter-type",
119 P_("Parameter Type"),
120 P_("The type of GVariant passed to activate()"),
121 G_TYPE_VARIANT_TYPE,
122 flags: G_PARAM_READABLE |
123 G_PARAM_STATIC_STRINGS));
124
125 /**
126 * GAction:enabled:
127 *
128 * If @action is currently enabled.
129 *
130 * If the action is disabled then calls to g_action_activate() and
131 * g_action_change_state() have no effect.
132 *
133 * Since: 2.28
134 **/
135 g_object_interface_install_property (g_iface: iface,
136 pspec: g_param_spec_boolean (name: "enabled",
137 P_("Enabled"),
138 P_("If the action can be activated"),
139 TRUE,
140 flags: G_PARAM_READABLE |
141 G_PARAM_STATIC_STRINGS));
142
143 /**
144 * GAction:state-type:
145 *
146 * The #GVariantType of the state that the action has, or %NULL if the
147 * action is stateless. This is immutable.
148 *
149 * Since: 2.28
150 **/
151 g_object_interface_install_property (g_iface: iface,
152 pspec: g_param_spec_boxed (name: "state-type",
153 P_("State Type"),
154 P_("The type of the state kept by the action"),
155 G_TYPE_VARIANT_TYPE,
156 flags: G_PARAM_READABLE |
157 G_PARAM_STATIC_STRINGS));
158
159 /**
160 * GAction:state:
161 *
162 * The state of the action, or %NULL if the action is stateless.
163 *
164 * Since: 2.28
165 **/
166 g_object_interface_install_property (g_iface: iface,
167 pspec: g_param_spec_variant (name: "state",
168 P_("State"),
169 P_("The state the action is in"),
170 G_VARIANT_TYPE_ANY,
171 NULL,
172 flags: G_PARAM_READABLE |
173 G_PARAM_STATIC_STRINGS));
174}
175
176/**
177 * g_action_change_state:
178 * @action: a #GAction
179 * @value: the new state
180 *
181 * Request for the state of @action to be changed to @value.
182 *
183 * The action must be stateful and @value must be of the correct type.
184 * See g_action_get_state_type().
185 *
186 * This call merely requests a change. The action may refuse to change
187 * its state or may change its state to something other than @value.
188 * See g_action_get_state_hint().
189 *
190 * If the @value GVariant is floating, it is consumed.
191 *
192 * Since: 2.30
193 **/
194void
195g_action_change_state (GAction *action,
196 GVariant *value)
197{
198 const GVariantType *state_type;
199
200 g_return_if_fail (G_IS_ACTION (action));
201 g_return_if_fail (value != NULL);
202 state_type = g_action_get_state_type (action);
203 g_return_if_fail (state_type != NULL);
204 g_return_if_fail (g_variant_is_of_type (value, state_type));
205
206 g_variant_ref_sink (value);
207
208 G_ACTION_GET_IFACE (action)
209 ->change_state (action, value);
210
211 g_variant_unref (value);
212}
213
214/**
215 * g_action_get_state:
216 * @action: a #GAction
217 *
218 * Queries the current state of @action.
219 *
220 * If the action is not stateful then %NULL will be returned. If the
221 * action is stateful then the type of the return value is the type
222 * given by g_action_get_state_type().
223 *
224 * The return value (if non-%NULL) should be freed with
225 * g_variant_unref() when it is no longer required.
226 *
227 * Returns: (nullable) (transfer full): the current state of the action
228 *
229 * Since: 2.28
230 **/
231GVariant *
232g_action_get_state (GAction *action)
233{
234 g_return_val_if_fail (G_IS_ACTION (action), NULL);
235
236 return G_ACTION_GET_IFACE (action)
237 ->get_state (action);
238}
239
240/**
241 * g_action_get_name:
242 * @action: a #GAction
243 *
244 * Queries the name of @action.
245 *
246 * Returns: the name of the action
247 *
248 * Since: 2.28
249 **/
250const gchar *
251g_action_get_name (GAction *action)
252{
253 g_return_val_if_fail (G_IS_ACTION (action), NULL);
254
255 return G_ACTION_GET_IFACE (action)
256 ->get_name (action);
257}
258
259/**
260 * g_action_get_parameter_type:
261 * @action: a #GAction
262 *
263 * Queries the type of the parameter that must be given when activating
264 * @action.
265 *
266 * When activating the action using g_action_activate(), the #GVariant
267 * given to that function must be of the type returned by this function.
268 *
269 * In the case that this function returns %NULL, you must not give any
270 * #GVariant, but %NULL instead.
271 *
272 * Returns: (nullable): the parameter type
273 *
274 * Since: 2.28
275 **/
276const GVariantType *
277g_action_get_parameter_type (GAction *action)
278{
279 g_return_val_if_fail (G_IS_ACTION (action), NULL);
280
281 return G_ACTION_GET_IFACE (action)
282 ->get_parameter_type (action);
283}
284
285/**
286 * g_action_get_state_type:
287 * @action: a #GAction
288 *
289 * Queries the type of the state of @action.
290 *
291 * If the action is stateful (e.g. created with
292 * g_simple_action_new_stateful()) then this function returns the
293 * #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
295 * #GVariant of this type and g_action_get_state() will return a
296 * #GVariant of the same type.
297 *
298 * If the action is not stateful (e.g. created with g_simple_action_new())
299 * 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 **/
306const GVariantType *
307g_action_get_state_type (GAction *action)
308{
309 g_return_val_if_fail (G_IS_ACTION (action), NULL);
310
311 return G_ACTION_GET_IFACE (action)
312 ->get_state_type (action);
313}
314
315/**
316 * g_action_get_state_hint:
317 * @action: a #GAction
318 *
319 * Requests a hint about the valid range of values for the state of
320 * @action.
321 *
322 * If %NULL is returned it either means that the action is not stateful
323 * or that there is no hint about the valid range of values for the
324 * state of the action.
325 *
326 * If a #GVariant array is returned then each item in the array is a
327 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
328 * returned then the tuple specifies the inclusive lower and upper bound
329 * of valid values for the state.
330 *
331 * In any case, the information is merely a hint. It may be possible to
332 * have a state value outside of the hinted range and setting a value
333 * within the range may fail.
334 *
335 * The return value (if non-%NULL) should be freed with
336 * g_variant_unref() when it is no longer required.
337 *
338 * Returns: (nullable) (transfer full): the state range hint
339 *
340 * Since: 2.28
341 **/
342GVariant *
343g_action_get_state_hint (GAction *action)
344{
345 g_return_val_if_fail (G_IS_ACTION (action), NULL);
346
347 return G_ACTION_GET_IFACE (action)
348 ->get_state_hint (action);
349}
350
351/**
352 * g_action_get_enabled:
353 * @action: a #GAction
354 *
355 * Checks if @action is currently enabled.
356 *
357 * An action must be enabled in order to be activated or in order to
358 * have its state changed from outside callers.
359 *
360 * Returns: whether the action is enabled
361 *
362 * Since: 2.28
363 **/
364gboolean
365g_action_get_enabled (GAction *action)
366{
367 g_return_val_if_fail (G_IS_ACTION (action), FALSE);
368
369 return G_ACTION_GET_IFACE (action)
370 ->get_enabled (action);
371}
372
373/**
374 * g_action_activate:
375 * @action: a #GAction
376 * @parameter: (nullable): the parameter to the activation
377 *
378 * Activates the action.
379 *
380 * @parameter must be the correct type of parameter for the action (ie:
381 * the parameter type given at construction time). If the parameter
382 * type was %NULL then @parameter must also be %NULL.
383 *
384 * If the @parameter GVariant is floating, it is consumed.
385 *
386 * Since: 2.28
387 **/
388void
389g_action_activate (GAction *action,
390 GVariant *parameter)
391{
392 g_return_if_fail (G_IS_ACTION (action));
393
394 if (parameter != NULL)
395 g_variant_ref_sink (value: parameter);
396
397 G_ACTION_GET_IFACE (action)
398 ->activate (action, parameter);
399
400 if (parameter != NULL)
401 g_variant_unref (value: parameter);
402}
403
404/**
405 * g_action_name_is_valid:
406 * @action_name: a potential action name
407 *
408 * Checks if @action_name is valid.
409 *
410 * @action_name is valid if it consists only of alphanumeric characters,
411 * plus '-' and '.'. The empty string is not a valid action name.
412 *
413 * It is an error to call this function with a non-utf8 @action_name.
414 * @action_name must not be %NULL.
415 *
416 * Returns: %TRUE if @action_name is valid
417 *
418 * Since: 2.38
419 **/
420gboolean
421g_action_name_is_valid (const gchar *action_name)
422{
423 gchar c;
424 gint i;
425
426 g_return_val_if_fail (action_name != NULL, FALSE);
427
428 for (i = 0; (c = action_name[i]); i++)
429 if (!g_ascii_isalnum (c) && c != '.' && c != '-')
430 return FALSE;
431
432 return i > 0;
433}
434
435/**
436 * g_action_parse_detailed_name:
437 * @detailed_name: a detailed action name
438 * @action_name: (out): the action name
439 * @target_value: (out): the target value, or %NULL for no target
440 * @error: a pointer to a %NULL #GError, or %NULL
441 *
442 * Parses a detailed action name into its separate name and target
443 * components.
444 *
445 * Detailed action names can have three formats.
446 *
447 * The first format is used to represent an action name with no target
448 * value and consists of just an action name containing no whitespace
449 * nor the characters ':', '(' or ')'. For example: "app.action".
450 *
451 * The second format is used to represent an action with a target value
452 * that is a non-empty string consisting only of alphanumerics, plus '-'
453 * and '.'. In that case, the action name and target value are
454 * separated by a double colon ("::"). For example:
455 * "app.action::target".
456 *
457 * The third format is used to represent an action with any type of
458 * target value, including strings. The target value follows the action
459 * name, surrounded in parens. For example: "app.action(42)". The
460 * target value is parsed using g_variant_parse(). If a tuple-typed
461 * value is desired, it must be specified in the same way, resulting in
462 * two sets of parens, for example: "app.action((1,2,3))". A string
463 * target can be specified this way as well: "app.action('target')".
464 * For strings, this third format must be used if * target value is
465 * empty or contains characters other than alphanumerics, '-' and '.'.
466 *
467 * Returns: %TRUE if successful, else %FALSE with @error set
468 *
469 * Since: 2.38
470 **/
471gboolean
472g_action_parse_detailed_name (const gchar *detailed_name,
473 gchar **action_name,
474 GVariant **target_value,
475 GError **error)
476{
477 const gchar *target;
478 gsize target_len;
479 gsize base_len;
480
481 /* For historical (compatibility) reasons, this function accepts some
482 * cases of invalid action names as long as they don't interfere with
483 * the separation of the action from the target value.
484 *
485 * We decide which format we have based on which we see first between
486 * '::' '(' and '\0'.
487 */
488
489 if (*detailed_name == '\0' || *detailed_name == ' ')
490 goto bad_fmt;
491
492 base_len = strcspn (s: detailed_name, reject: ": ()");
493 target = detailed_name + base_len;
494 target_len = strlen (s: target);
495
496 switch (target[0])
497 {
498 case ' ':
499 case ')':
500 goto bad_fmt;
501
502 case ':':
503 if (target[1] != ':')
504 goto bad_fmt;
505
506 *target_value = g_variant_ref_sink (value: g_variant_new_string (string: target + 2));
507 break;
508
509 case '(':
510 {
511 if (target[target_len - 1] != ')')
512 goto bad_fmt;
513
514 *target_value = g_variant_parse (NULL, text: target + 1, limit: target + target_len - 1, NULL, error);
515 if (*target_value == NULL)
516 goto bad_fmt;
517 }
518 break;
519
520 case '\0':
521 *target_value = NULL;
522 break;
523 }
524
525 *action_name = g_strndup (str: detailed_name, n: base_len);
526
527 return TRUE;
528
529bad_fmt:
530 if (error)
531 {
532 if (*error == NULL)
533 g_set_error (err: error, G_VARIANT_PARSE_ERROR, code: G_VARIANT_PARSE_ERROR_FAILED,
534 format: "Detailed action name '%s' has invalid format", detailed_name);
535 else
536 g_prefix_error (err: error, format: "Detailed action name '%s' has invalid format: ", detailed_name);
537 }
538
539 return FALSE;
540}
541
542/**
543 * g_action_print_detailed_name:
544 * @action_name: a valid action name
545 * @target_value: (nullable): a #GVariant target value, or %NULL
546 *
547 * Formats a detailed action name from @action_name and @target_value.
548 *
549 * It is an error to call this function with an invalid action name.
550 *
551 * This function is the opposite of g_action_parse_detailed_name().
552 * It will produce a string that can be parsed back to the @action_name
553 * and @target_value by that function.
554 *
555 * See that function for the types of strings that will be printed by
556 * this function.
557 *
558 * Returns: a detailed format string
559 *
560 * Since: 2.38
561 **/
562gchar *
563g_action_print_detailed_name (const gchar *action_name,
564 GVariant *target_value)
565{
566 g_return_val_if_fail (g_action_name_is_valid (action_name), NULL);
567
568 if (target_value == NULL)
569 return g_strdup (str: action_name);
570
571 if (g_variant_is_of_type (value: target_value, G_VARIANT_TYPE_STRING))
572 {
573 const gchar *str = g_variant_get_string (value: target_value, NULL);
574
575 if (g_action_name_is_valid (action_name: str))
576 return g_strconcat (string1: action_name, "::", str, NULL);
577 }
578
579 {
580 GString *result = g_string_new (init: action_name);
581 g_string_append_c (result, '(');
582 g_variant_print_string (value: target_value, string: result, TRUE);
583 g_string_append_c (result, ')');
584
585 return g_string_free (string: result, FALSE);
586 }
587}
588

source code of gtk/subprojects/glib/gio/gaction.c