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 "gactiongroup.h" |
22 | #include "gaction.h" |
23 | #include "glibintl.h" |
24 | #include "gmarshal-internal.h" |
25 | |
26 | /** |
27 | * SECTION:gactiongroup |
28 | * @title: GActionGroup |
29 | * @short_description: A group of actions |
30 | * @include: gio/gio.h |
31 | * @see_also: #GAction |
32 | * |
33 | * #GActionGroup represents a group of actions. Actions can be used to |
34 | * expose functionality in a structured way, either from one part of a |
35 | * program to another, or to the outside world. Action groups are often |
36 | * used together with a #GMenuModel that provides additional |
37 | * representation data for displaying the actions to the user, e.g. in |
38 | * a menu. |
39 | * |
40 | * The main way to interact with the actions in a GActionGroup is to |
41 | * activate them with g_action_group_activate_action(). Activating an |
42 | * action may require a #GVariant parameter. The required type of the |
43 | * parameter can be inquired with g_action_group_get_action_parameter_type(). |
44 | * Actions may be disabled, see g_action_group_get_action_enabled(). |
45 | * Activating a disabled action has no effect. |
46 | * |
47 | * Actions may optionally have a state in the form of a #GVariant. The |
48 | * current state of an action can be inquired with |
49 | * g_action_group_get_action_state(). Activating a stateful action may |
50 | * change its state, but it is also possible to set the state by calling |
51 | * g_action_group_change_action_state(). |
52 | * |
53 | * As typical example, consider a text editing application which has an |
54 | * option to change the current font to 'bold'. A good way to represent |
55 | * this would be a stateful action, with a boolean state. Activating the |
56 | * action would toggle the state. |
57 | * |
58 | * Each action in the group has a unique name (which is a string). All |
59 | * method calls, except g_action_group_list_actions() take the name of |
60 | * an action as an argument. |
61 | * |
62 | * The #GActionGroup API is meant to be the 'public' API to the action |
63 | * group. The calls here are exactly the interaction that 'external |
64 | * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have |
65 | * with actions. 'Internal' APIs (ie: ones meant only to be accessed by |
66 | * the action group implementation) are found on subclasses. This is |
67 | * why you will find - for example - g_action_group_get_action_enabled() |
68 | * but not an equivalent set() call. |
69 | * |
70 | * Signals are emitted on the action group in response to state changes |
71 | * on individual actions. |
72 | * |
73 | * Implementations of #GActionGroup should provide implementations for |
74 | * the virtual functions g_action_group_list_actions() and |
75 | * g_action_group_query_action(). The other virtual functions should |
76 | * not be implemented - their "wrappers" are actually implemented with |
77 | * calls to g_action_group_query_action(). |
78 | */ |
79 | |
80 | /** |
81 | * GActionGroup: |
82 | * |
83 | * #GActionGroup is an opaque data structure and can only be accessed |
84 | * using the following functions. |
85 | **/ |
86 | |
87 | /** |
88 | * GActionGroupInterface: |
89 | * @has_action: the virtual function pointer for g_action_group_has_action() |
90 | * @list_actions: the virtual function pointer for g_action_group_list_actions() |
91 | * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type() |
92 | * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type() |
93 | * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint() |
94 | * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled() |
95 | * @get_action_state: the virtual function pointer for g_action_group_get_action_state() |
96 | * @change_action_state: the virtual function pointer for g_action_group_change_action_state() |
97 | * @query_action: the virtual function pointer for g_action_group_query_action() |
98 | * @activate_action: the virtual function pointer for g_action_group_activate_action() |
99 | * @change_action_state: the virtual function pointer for g_action_group_change_action_state() |
100 | * @action_added: the class closure for the #GActionGroup::action-added signal |
101 | * @action_removed: the class closure for the #GActionGroup::action-removed signal |
102 | * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal |
103 | * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal |
104 | * |
105 | * The virtual function table for #GActionGroup. |
106 | * |
107 | * Since: 2.28 |
108 | **/ |
109 | |
110 | G_DEFINE_INTERFACE (GActionGroup, g_action_group, G_TYPE_OBJECT) |
111 | |
112 | enum |
113 | { |
114 | SIGNAL_ACTION_ADDED, |
115 | SIGNAL_ACTION_REMOVED, |
116 | SIGNAL_ACTION_ENABLED_CHANGED, |
117 | SIGNAL_ACTION_STATE_CHANGED, |
118 | NR_SIGNALS |
119 | }; |
120 | |
121 | static guint g_action_group_signals[NR_SIGNALS]; |
122 | |
123 | static gboolean |
124 | g_action_group_real_has_action (GActionGroup *action_group, |
125 | const gchar *action_name) |
126 | { |
127 | return g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, NULL, NULL); |
128 | } |
129 | |
130 | static gboolean |
131 | g_action_group_real_get_action_enabled (GActionGroup *action_group, |
132 | const gchar *action_name) |
133 | { |
134 | gboolean enabled = FALSE; |
135 | |
136 | g_action_group_query_action (action_group, action_name, enabled: &enabled, NULL, NULL, NULL, NULL); |
137 | |
138 | return enabled; |
139 | } |
140 | |
141 | static const GVariantType * |
142 | g_action_group_real_get_action_parameter_type (GActionGroup *action_group, |
143 | const gchar *action_name) |
144 | { |
145 | const GVariantType *type = NULL; |
146 | |
147 | g_action_group_query_action (action_group, action_name, NULL, parameter_type: &type, NULL, NULL, NULL); |
148 | |
149 | return type; |
150 | } |
151 | |
152 | static const GVariantType * |
153 | g_action_group_real_get_action_state_type (GActionGroup *action_group, |
154 | const gchar *action_name) |
155 | { |
156 | const GVariantType *type = NULL; |
157 | |
158 | g_action_group_query_action (action_group, action_name, NULL, NULL, state_type: &type, NULL, NULL); |
159 | |
160 | return type; |
161 | } |
162 | |
163 | static GVariant * |
164 | g_action_group_real_get_action_state_hint (GActionGroup *action_group, |
165 | const gchar *action_name) |
166 | { |
167 | GVariant *hint = NULL; |
168 | |
169 | g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, state_hint: &hint, NULL); |
170 | |
171 | return hint; |
172 | } |
173 | |
174 | static GVariant * |
175 | g_action_group_real_get_action_state (GActionGroup *action_group, |
176 | const gchar *action_name) |
177 | { |
178 | GVariant *state = NULL; |
179 | |
180 | g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, NULL, state: &state); |
181 | |
182 | return state; |
183 | } |
184 | |
185 | static gboolean |
186 | g_action_group_real_query_action (GActionGroup *action_group, |
187 | const gchar *action_name, |
188 | gboolean *enabled, |
189 | const GVariantType **parameter_type, |
190 | const GVariantType **state_type, |
191 | GVariant **state_hint, |
192 | GVariant **state) |
193 | { |
194 | GActionGroupInterface *iface = G_ACTION_GROUP_GET_IFACE (action_group); |
195 | |
196 | /* we expect implementations to override this method, but we also |
197 | * allow for implementations that existed before this method was |
198 | * introduced to override the individual accessors instead. |
199 | * |
200 | * detect the case that neither has happened and report it. |
201 | */ |
202 | if G_UNLIKELY (iface->has_action == g_action_group_real_has_action || |
203 | iface->get_action_enabled == g_action_group_real_get_action_enabled || |
204 | iface->get_action_parameter_type == g_action_group_real_get_action_parameter_type || |
205 | iface->get_action_state_type == g_action_group_real_get_action_state_type || |
206 | iface->get_action_state_hint == g_action_group_real_get_action_state_hint || |
207 | iface->get_action_state == g_action_group_real_get_action_state) |
208 | { |
209 | g_critical ("Class '%s' implements GActionGroup interface without overriding " |
210 | "query_action() method -- bailing out to avoid infinite recursion." , |
211 | G_OBJECT_TYPE_NAME (action_group)); |
212 | return FALSE; |
213 | } |
214 | |
215 | if (!(* iface->has_action) (action_group, action_name)) |
216 | return FALSE; |
217 | |
218 | if (enabled != NULL) |
219 | *enabled = (* iface->get_action_enabled) (action_group, action_name); |
220 | |
221 | if (parameter_type != NULL) |
222 | *parameter_type = (* iface->get_action_parameter_type) (action_group, action_name); |
223 | |
224 | if (state_type != NULL) |
225 | *state_type = (* iface->get_action_state_type) (action_group, action_name); |
226 | |
227 | if (state_hint != NULL) |
228 | *state_hint = (* iface->get_action_state_hint) (action_group, action_name); |
229 | |
230 | if (state != NULL) |
231 | *state = (* iface->get_action_state) (action_group, action_name); |
232 | |
233 | return TRUE; |
234 | } |
235 | |
236 | static void |
237 | g_action_group_default_init (GActionGroupInterface *iface) |
238 | { |
239 | iface->has_action = g_action_group_real_has_action; |
240 | iface->get_action_enabled = g_action_group_real_get_action_enabled; |
241 | iface->get_action_parameter_type = g_action_group_real_get_action_parameter_type; |
242 | iface->get_action_state_type = g_action_group_real_get_action_state_type; |
243 | iface->get_action_state_hint = g_action_group_real_get_action_state_hint; |
244 | iface->get_action_state = g_action_group_real_get_action_state; |
245 | iface->query_action = g_action_group_real_query_action; |
246 | |
247 | /** |
248 | * GActionGroup::action-added: |
249 | * @action_group: the #GActionGroup that changed |
250 | * @action_name: the name of the action in @action_group |
251 | * |
252 | * Signals that a new action was just added to the group. |
253 | * This signal is emitted after the action has been added |
254 | * and is now visible. |
255 | * |
256 | * Since: 2.28 |
257 | **/ |
258 | g_action_group_signals[SIGNAL_ACTION_ADDED] = |
259 | g_signal_new (I_("action-added" ), |
260 | G_TYPE_ACTION_GROUP, |
261 | signal_flags: G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED, |
262 | G_STRUCT_OFFSET (GActionGroupInterface, action_added), |
263 | NULL, NULL, |
264 | NULL, |
265 | G_TYPE_NONE, n_params: 1, |
266 | G_TYPE_STRING); |
267 | |
268 | /** |
269 | * GActionGroup::action-removed: |
270 | * @action_group: the #GActionGroup that changed |
271 | * @action_name: the name of the action in @action_group |
272 | * |
273 | * Signals that an action is just about to be removed from the group. |
274 | * This signal is emitted before the action is removed, so the action |
275 | * is still visible and can be queried from the signal handler. |
276 | * |
277 | * Since: 2.28 |
278 | **/ |
279 | g_action_group_signals[SIGNAL_ACTION_REMOVED] = |
280 | g_signal_new (I_("action-removed" ), |
281 | G_TYPE_ACTION_GROUP, |
282 | signal_flags: G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED, |
283 | G_STRUCT_OFFSET (GActionGroupInterface, action_removed), |
284 | NULL, NULL, |
285 | NULL, |
286 | G_TYPE_NONE, n_params: 1, |
287 | G_TYPE_STRING); |
288 | |
289 | |
290 | /** |
291 | * GActionGroup::action-enabled-changed: |
292 | * @action_group: the #GActionGroup that changed |
293 | * @action_name: the name of the action in @action_group |
294 | * @enabled: whether the action is enabled or not |
295 | * |
296 | * Signals that the enabled status of the named action has changed. |
297 | * |
298 | * Since: 2.28 |
299 | **/ |
300 | g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED] = |
301 | g_signal_new (I_("action-enabled-changed" ), |
302 | G_TYPE_ACTION_GROUP, |
303 | signal_flags: G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED, |
304 | G_STRUCT_OFFSET (GActionGroupInterface, |
305 | action_enabled_changed), |
306 | NULL, NULL, |
307 | c_marshaller: _g_cclosure_marshal_VOID__STRING_BOOLEAN, |
308 | G_TYPE_NONE, n_params: 2, |
309 | G_TYPE_STRING, |
310 | G_TYPE_BOOLEAN); |
311 | g_signal_set_va_marshaller (signal_id: g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED], |
312 | G_TYPE_FROM_INTERFACE (iface), |
313 | va_marshaller: _g_cclosure_marshal_VOID__STRING_BOOLEANv); |
314 | |
315 | /** |
316 | * GActionGroup::action-state-changed: |
317 | * @action_group: the #GActionGroup that changed |
318 | * @action_name: the name of the action in @action_group |
319 | * @value: the new value of the state |
320 | * |
321 | * Signals that the state of the named action has changed. |
322 | * |
323 | * Since: 2.28 |
324 | **/ |
325 | g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED] = |
326 | g_signal_new (I_("action-state-changed" ), |
327 | G_TYPE_ACTION_GROUP, |
328 | signal_flags: G_SIGNAL_RUN_LAST | |
329 | G_SIGNAL_DETAILED | |
330 | G_SIGNAL_MUST_COLLECT, |
331 | G_STRUCT_OFFSET (GActionGroupInterface, |
332 | action_state_changed), |
333 | NULL, NULL, |
334 | c_marshaller: _g_cclosure_marshal_VOID__STRING_VARIANT, |
335 | G_TYPE_NONE, n_params: 2, |
336 | G_TYPE_STRING, |
337 | G_TYPE_VARIANT); |
338 | g_signal_set_va_marshaller (signal_id: g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED], |
339 | G_TYPE_FROM_INTERFACE (iface), |
340 | va_marshaller: _g_cclosure_marshal_VOID__STRING_VARIANTv); |
341 | } |
342 | |
343 | /** |
344 | * g_action_group_list_actions: |
345 | * @action_group: a #GActionGroup |
346 | * |
347 | * Lists the actions contained within @action_group. |
348 | * |
349 | * The caller is responsible for freeing the list with g_strfreev() when |
350 | * it is no longer required. |
351 | * |
352 | * Returns: (transfer full): a %NULL-terminated array of the names of the |
353 | * actions in the group |
354 | * |
355 | * Since: 2.28 |
356 | **/ |
357 | gchar ** |
358 | g_action_group_list_actions (GActionGroup *action_group) |
359 | { |
360 | g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL); |
361 | |
362 | return G_ACTION_GROUP_GET_IFACE (action_group) |
363 | ->list_actions (action_group); |
364 | } |
365 | |
366 | /** |
367 | * g_action_group_has_action: |
368 | * @action_group: a #GActionGroup |
369 | * @action_name: the name of the action to check for |
370 | * |
371 | * Checks if the named action exists within @action_group. |
372 | * |
373 | * Returns: whether the named action exists |
374 | * |
375 | * Since: 2.28 |
376 | **/ |
377 | gboolean |
378 | g_action_group_has_action (GActionGroup *action_group, |
379 | const gchar *action_name) |
380 | { |
381 | g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE); |
382 | |
383 | return G_ACTION_GROUP_GET_IFACE (action_group) |
384 | ->has_action (action_group, action_name); |
385 | } |
386 | |
387 | /** |
388 | * g_action_group_get_action_parameter_type: |
389 | * @action_group: a #GActionGroup |
390 | * @action_name: the name of the action to query |
391 | * |
392 | * Queries the type of the parameter that must be given when activating |
393 | * the named action within @action_group. |
394 | * |
395 | * When activating the action using g_action_group_activate_action(), |
396 | * the #GVariant given to that function must be of the type returned |
397 | * by this function. |
398 | * |
399 | * In the case that this function returns %NULL, you must not give any |
400 | * #GVariant, but %NULL instead. |
401 | * |
402 | * The parameter type of a particular action will never change but it is |
403 | * possible for an action to be removed and for a new action to be added |
404 | * with the same name but a different parameter type. |
405 | * |
406 | * Returns: (nullable): the parameter type |
407 | * |
408 | * Since: 2.28 |
409 | **/ |
410 | const GVariantType * |
411 | g_action_group_get_action_parameter_type (GActionGroup *action_group, |
412 | const gchar *action_name) |
413 | { |
414 | g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL); |
415 | |
416 | return G_ACTION_GROUP_GET_IFACE (action_group) |
417 | ->get_action_parameter_type (action_group, action_name); |
418 | } |
419 | |
420 | /** |
421 | * g_action_group_get_action_state_type: |
422 | * @action_group: a #GActionGroup |
423 | * @action_name: the name of the action to query |
424 | * |
425 | * Queries the type of the state of the named action within |
426 | * @action_group. |
427 | * |
428 | * If the action is stateful then this function returns the |
429 | * #GVariantType of the state. All calls to |
430 | * g_action_group_change_action_state() must give a #GVariant of this |
431 | * type and g_action_group_get_action_state() will return a #GVariant |
432 | * of the same type. |
433 | * |
434 | * If the action is not stateful then this function will return %NULL. |
435 | * In that case, g_action_group_get_action_state() will return %NULL |
436 | * and you must not call g_action_group_change_action_state(). |
437 | * |
438 | * The state type of a particular action will never change but it is |
439 | * possible for an action to be removed and for a new action to be added |
440 | * with the same name but a different state type. |
441 | * |
442 | * Returns: (nullable): the state type, if the action is stateful |
443 | * |
444 | * Since: 2.28 |
445 | **/ |
446 | const GVariantType * |
447 | g_action_group_get_action_state_type (GActionGroup *action_group, |
448 | const gchar *action_name) |
449 | { |
450 | g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL); |
451 | |
452 | return G_ACTION_GROUP_GET_IFACE (action_group) |
453 | ->get_action_state_type (action_group, action_name); |
454 | } |
455 | |
456 | /** |
457 | * g_action_group_get_action_state_hint: |
458 | * @action_group: a #GActionGroup |
459 | * @action_name: the name of the action to query |
460 | * |
461 | * Requests a hint about the valid range of values for the state of the |
462 | * named action within @action_group. |
463 | * |
464 | * If %NULL is returned it either means that the action is not stateful |
465 | * or that there is no hint about the valid range of values for the |
466 | * state of the action. |
467 | * |
468 | * If a #GVariant array is returned then each item in the array is a |
469 | * possible value for the state. If a #GVariant pair (ie: two-tuple) is |
470 | * returned then the tuple specifies the inclusive lower and upper bound |
471 | * of valid values for the state. |
472 | * |
473 | * In any case, the information is merely a hint. It may be possible to |
474 | * have a state value outside of the hinted range and setting a value |
475 | * within the range may fail. |
476 | * |
477 | * The return value (if non-%NULL) should be freed with |
478 | * g_variant_unref() when it is no longer required. |
479 | * |
480 | * Returns: (nullable) (transfer full): the state range hint |
481 | * |
482 | * Since: 2.28 |
483 | **/ |
484 | GVariant * |
485 | g_action_group_get_action_state_hint (GActionGroup *action_group, |
486 | const gchar *action_name) |
487 | { |
488 | g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL); |
489 | |
490 | return G_ACTION_GROUP_GET_IFACE (action_group) |
491 | ->get_action_state_hint (action_group, action_name); |
492 | } |
493 | |
494 | /** |
495 | * g_action_group_get_action_enabled: |
496 | * @action_group: a #GActionGroup |
497 | * @action_name: the name of the action to query |
498 | * |
499 | * Checks if the named action within @action_group is currently enabled. |
500 | * |
501 | * An action must be enabled in order to be activated or in order to |
502 | * have its state changed from outside callers. |
503 | * |
504 | * Returns: whether or not the action is currently enabled |
505 | * |
506 | * Since: 2.28 |
507 | **/ |
508 | gboolean |
509 | g_action_group_get_action_enabled (GActionGroup *action_group, |
510 | const gchar *action_name) |
511 | { |
512 | g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE); |
513 | |
514 | return G_ACTION_GROUP_GET_IFACE (action_group) |
515 | ->get_action_enabled (action_group, action_name); |
516 | } |
517 | |
518 | /** |
519 | * g_action_group_get_action_state: |
520 | * @action_group: a #GActionGroup |
521 | * @action_name: the name of the action to query |
522 | * |
523 | * Queries the current state of the named action within @action_group. |
524 | * |
525 | * If the action is not stateful then %NULL will be returned. If the |
526 | * action is stateful then the type of the return value is the type |
527 | * given by g_action_group_get_action_state_type(). |
528 | * |
529 | * The return value (if non-%NULL) should be freed with |
530 | * g_variant_unref() when it is no longer required. |
531 | * |
532 | * Returns: (nullable) (transfer full): the current state of the action |
533 | * |
534 | * Since: 2.28 |
535 | **/ |
536 | GVariant * |
537 | g_action_group_get_action_state (GActionGroup *action_group, |
538 | const gchar *action_name) |
539 | { |
540 | g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL); |
541 | |
542 | return G_ACTION_GROUP_GET_IFACE (action_group) |
543 | ->get_action_state (action_group, action_name); |
544 | } |
545 | |
546 | /** |
547 | * g_action_group_change_action_state: |
548 | * @action_group: a #GActionGroup |
549 | * @action_name: the name of the action to request the change on |
550 | * @value: the new state |
551 | * |
552 | * Request for the state of the named action within @action_group to be |
553 | * changed to @value. |
554 | * |
555 | * The action must be stateful and @value must be of the correct type. |
556 | * See g_action_group_get_action_state_type(). |
557 | * |
558 | * This call merely requests a change. The action may refuse to change |
559 | * its state or may change its state to something other than @value. |
560 | * See g_action_group_get_action_state_hint(). |
561 | * |
562 | * If the @value GVariant is floating, it is consumed. |
563 | * |
564 | * Since: 2.28 |
565 | **/ |
566 | void |
567 | g_action_group_change_action_state (GActionGroup *action_group, |
568 | const gchar *action_name, |
569 | GVariant *value) |
570 | { |
571 | g_return_if_fail (G_IS_ACTION_GROUP (action_group)); |
572 | g_return_if_fail (action_name != NULL); |
573 | g_return_if_fail (value != NULL); |
574 | |
575 | G_ACTION_GROUP_GET_IFACE (action_group) |
576 | ->change_action_state (action_group, action_name, value); |
577 | } |
578 | |
579 | /** |
580 | * g_action_group_activate_action: |
581 | * @action_group: a #GActionGroup |
582 | * @action_name: the name of the action to activate |
583 | * @parameter: (nullable): parameters to the activation |
584 | * |
585 | * Activate the named action within @action_group. |
586 | * |
587 | * If the action is expecting a parameter, then the correct type of |
588 | * parameter must be given as @parameter. If the action is expecting no |
589 | * parameters then @parameter must be %NULL. See |
590 | * g_action_group_get_action_parameter_type(). |
591 | * |
592 | * If the #GActionGroup implementation supports asynchronous remote |
593 | * activation over D-Bus, this call may return before the relevant |
594 | * D-Bus traffic has been sent, or any replies have been received. In |
595 | * order to block on such asynchronous activation calls, |
596 | * g_dbus_connection_flush() should be called prior to the code, which |
597 | * depends on the result of the action activation. Without flushing |
598 | * the D-Bus connection, there is no guarantee that the action would |
599 | * have been activated. |
600 | * |
601 | * The following code which runs in a remote app instance, shows an |
602 | * example of a "quit" action being activated on the primary app |
603 | * instance over D-Bus. Here g_dbus_connection_flush() is called |
604 | * before `exit()`. Without g_dbus_connection_flush(), the "quit" action |
605 | * may fail to be activated on the primary instance. |
606 | * |
607 | * |[<!-- language="C" --> |
608 | * // call "quit" action on primary instance |
609 | * g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL); |
610 | * |
611 | * // make sure the action is activated now |
612 | * g_dbus_connection_flush (...); |
613 | * |
614 | * g_debug ("application has been terminated. exiting."); |
615 | * |
616 | * exit (0); |
617 | * ]| |
618 | * |
619 | * Since: 2.28 |
620 | **/ |
621 | void |
622 | g_action_group_activate_action (GActionGroup *action_group, |
623 | const gchar *action_name, |
624 | GVariant *parameter) |
625 | { |
626 | g_return_if_fail (G_IS_ACTION_GROUP (action_group)); |
627 | g_return_if_fail (action_name != NULL); |
628 | |
629 | G_ACTION_GROUP_GET_IFACE (action_group) |
630 | ->activate_action (action_group, action_name, parameter); |
631 | } |
632 | |
633 | /** |
634 | * g_action_group_action_added: |
635 | * @action_group: a #GActionGroup |
636 | * @action_name: the name of an action in the group |
637 | * |
638 | * Emits the #GActionGroup::action-added signal on @action_group. |
639 | * |
640 | * This function should only be called by #GActionGroup implementations. |
641 | * |
642 | * Since: 2.28 |
643 | **/ |
644 | void |
645 | g_action_group_action_added (GActionGroup *action_group, |
646 | const gchar *action_name) |
647 | { |
648 | g_return_if_fail (G_IS_ACTION_GROUP (action_group)); |
649 | g_return_if_fail (action_name != NULL); |
650 | |
651 | g_signal_emit (instance: action_group, |
652 | signal_id: g_action_group_signals[SIGNAL_ACTION_ADDED], |
653 | detail: g_quark_try_string (string: action_name), |
654 | action_name); |
655 | } |
656 | |
657 | /** |
658 | * g_action_group_action_removed: |
659 | * @action_group: a #GActionGroup |
660 | * @action_name: the name of an action in the group |
661 | * |
662 | * Emits the #GActionGroup::action-removed signal on @action_group. |
663 | * |
664 | * This function should only be called by #GActionGroup implementations. |
665 | * |
666 | * Since: 2.28 |
667 | **/ |
668 | void |
669 | g_action_group_action_removed (GActionGroup *action_group, |
670 | const gchar *action_name) |
671 | { |
672 | g_return_if_fail (G_IS_ACTION_GROUP (action_group)); |
673 | g_return_if_fail (action_name != NULL); |
674 | |
675 | g_signal_emit (instance: action_group, |
676 | signal_id: g_action_group_signals[SIGNAL_ACTION_REMOVED], |
677 | detail: g_quark_try_string (string: action_name), |
678 | action_name); |
679 | } |
680 | |
681 | /** |
682 | * g_action_group_action_enabled_changed: |
683 | * @action_group: a #GActionGroup |
684 | * @action_name: the name of an action in the group |
685 | * @enabled: whether or not the action is now enabled |
686 | * |
687 | * Emits the #GActionGroup::action-enabled-changed signal on @action_group. |
688 | * |
689 | * This function should only be called by #GActionGroup implementations. |
690 | * |
691 | * Since: 2.28 |
692 | **/ |
693 | void |
694 | g_action_group_action_enabled_changed (GActionGroup *action_group, |
695 | const gchar *action_name, |
696 | gboolean enabled) |
697 | { |
698 | g_return_if_fail (G_IS_ACTION_GROUP (action_group)); |
699 | g_return_if_fail (action_name != NULL); |
700 | |
701 | enabled = !!enabled; |
702 | |
703 | g_signal_emit (instance: action_group, |
704 | signal_id: g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED], |
705 | detail: g_quark_try_string (string: action_name), |
706 | action_name, |
707 | enabled); |
708 | } |
709 | |
710 | /** |
711 | * g_action_group_action_state_changed: |
712 | * @action_group: a #GActionGroup |
713 | * @action_name: the name of an action in the group |
714 | * @state: the new state of the named action |
715 | * |
716 | * Emits the #GActionGroup::action-state-changed signal on @action_group. |
717 | * |
718 | * This function should only be called by #GActionGroup implementations. |
719 | * |
720 | * Since: 2.28 |
721 | **/ |
722 | void |
723 | g_action_group_action_state_changed (GActionGroup *action_group, |
724 | const gchar *action_name, |
725 | GVariant *state) |
726 | { |
727 | g_return_if_fail (G_IS_ACTION_GROUP (action_group)); |
728 | g_return_if_fail (action_name != NULL); |
729 | |
730 | g_signal_emit (instance: action_group, |
731 | signal_id: g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED], |
732 | detail: g_quark_try_string (string: action_name), |
733 | action_name, |
734 | state); |
735 | } |
736 | |
737 | /** |
738 | * g_action_group_query_action: |
739 | * @action_group: a #GActionGroup |
740 | * @action_name: the name of an action in the group |
741 | * @enabled: (out): if the action is presently enabled |
742 | * @parameter_type: (out) (optional): the parameter type, or %NULL if none needed |
743 | * @state_type: (out) (optional): the state type, or %NULL if stateless |
744 | * @state_hint: (out) (optional): the state hint, or %NULL if none |
745 | * @state: (out) (optional): the current state, or %NULL if stateless |
746 | * |
747 | * Queries all aspects of the named action within an @action_group. |
748 | * |
749 | * This function acquires the information available from |
750 | * g_action_group_has_action(), g_action_group_get_action_enabled(), |
751 | * g_action_group_get_action_parameter_type(), |
752 | * g_action_group_get_action_state_type(), |
753 | * g_action_group_get_action_state_hint() and |
754 | * g_action_group_get_action_state() with a single function call. |
755 | * |
756 | * This provides two main benefits. |
757 | * |
758 | * The first is the improvement in efficiency that comes with not having |
759 | * to perform repeated lookups of the action in order to discover |
760 | * different things about it. The second is that implementing |
761 | * #GActionGroup can now be done by only overriding this one virtual |
762 | * function. |
763 | * |
764 | * The interface provides a default implementation of this function that |
765 | * calls the individual functions, as required, to fetch the |
766 | * information. The interface also provides default implementations of |
767 | * those functions that call this function. All implementations, |
768 | * therefore, must override either this function or all of the others. |
769 | * |
770 | * If the action exists, %TRUE is returned and any of the requested |
771 | * fields (as indicated by having a non-%NULL reference passed in) are |
772 | * filled. If the action doesn't exist, %FALSE is returned and the |
773 | * fields may or may not have been modified. |
774 | * |
775 | * Returns: %TRUE if the action exists, else %FALSE |
776 | * |
777 | * Since: 2.32 |
778 | **/ |
779 | gboolean |
780 | g_action_group_query_action (GActionGroup *action_group, |
781 | const gchar *action_name, |
782 | gboolean *enabled, |
783 | const GVariantType **parameter_type, |
784 | const GVariantType **state_type, |
785 | GVariant **state_hint, |
786 | GVariant **state) |
787 | { |
788 | return G_ACTION_GROUP_GET_IFACE (action_group) |
789 | ->query_action (action_group, action_name, enabled, parameter_type, state_type, state_hint, state); |
790 | } |
791 | |