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