Merge remote-tracking branch 'gvdb/master'
[platform/upstream/glib.git] / gio / gactiongroup.c
1 /*
2  * Copyright © 2010 Codethink Limited
3  *
4  * This program is free software: you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License as published
6  * by the Free Software Foundation; either version 2 of the licence or (at
7  * 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, write to the
16  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
17  * Boston, MA 02111-1307, USA.
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
27 /**
28  * SECTION:gactiongroup
29  * @title: GActionGroup
30  * @short_description: A group of actions
31  *
32  * #GActionGroup represents a group of actions.
33  *
34  * Each action in the group has a unique name (which is a string).  All
35  * method calls, except g_action_group_list_actions() take the name of
36  * an action as an argument.
37  *
38  * The #GActionGroup API is meant to be the 'public' API to the action
39  * group.  The calls here are exactly the interaction that 'external
40  * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
41  * with actions.  'Internal' APIs (ie: ones meant only to be accessed by
42  * the action group implementation) are found on subclasses.  This is
43  * why you will find -- for example -- g_action_group_get_action_enabled()
44  * but not an equivalent <function>set()</function> call.
45  *
46  * Signals are emitted on the action group in response to state changes
47  * on individual actions.
48  **/
49
50 G_DEFINE_INTERFACE (GActionGroup, g_action_group, G_TYPE_OBJECT)
51
52 enum
53 {
54   SIGNAL_ACTION_ADDED,
55   SIGNAL_ACTION_REMOVED,
56   SIGNAL_ACTION_ENABLED_CHANGED,
57   SIGNAL_ACTION_STATE_CHANGED,
58   NR_SIGNALS
59 };
60
61 static guint g_action_group_signals[NR_SIGNALS];
62
63 static void
64 g_action_group_default_init (GActionGroupInterface *class)
65 {
66   /**
67    * GActionGroup::action-added:
68    * @action_group: the #GActionGroup that changed
69    * @action_name: the name of the action in @action_group
70    *
71    * Signals that a new action was just added to the group.
72    * This signal is emitted after the action has been added
73    * and is now visible.
74    *
75    * Since: 2.28
76    **/
77   g_action_group_signals[SIGNAL_ACTION_ADDED] =
78     g_signal_new (I_("action-added"),
79                   G_TYPE_ACTION_GROUP,
80                   G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
81                   G_STRUCT_OFFSET (GActionGroupInterface, action_added),
82                   NULL, NULL,
83                   g_cclosure_marshal_VOID__STRING,
84                   G_TYPE_NONE, 1,
85                   G_TYPE_STRING);
86
87   /**
88    * GActionGroup::action-removed:
89    * @action_group: the #GActionGroup that changed
90    * @action_name: the name of the action in @action_group
91    *
92    * Signals that an action is just about to be removed from the group.
93    * This signal is emitted before the action is removed, so the action
94    * is still visible and can be queried from the signal handler.
95    *
96    * Since: 2.28
97    **/
98   g_action_group_signals[SIGNAL_ACTION_REMOVED] =
99     g_signal_new (I_("action-removed"),
100                   G_TYPE_ACTION_GROUP,
101                   G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
102                   G_STRUCT_OFFSET (GActionGroupInterface, action_removed),
103                   NULL, NULL,
104                   g_cclosure_marshal_VOID__STRING,
105                   G_TYPE_NONE, 1,
106                   G_TYPE_STRING);
107
108
109   /**
110    * GActionGroup::action-enabled-changed:
111    * @action_group: the #GActionGroup that changed
112    * @action_name: the name of the action in @action_group
113    * @enabled: whether the action is enabled or not
114    *
115    * Signals that the enabled status of the named action has changed.
116    *
117    * Since: 2.28
118    **/
119   g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED] =
120     g_signal_new (I_("action-enabled-changed"),
121                   G_TYPE_ACTION_GROUP,
122                   G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
123                   G_STRUCT_OFFSET (GActionGroupInterface,
124                                    action_enabled_changed),
125                   NULL, NULL,
126                   NULL,
127                   G_TYPE_NONE, 2,
128                   G_TYPE_STRING,
129                   G_TYPE_BOOLEAN);
130
131   /**
132    * GActionGroup::action-state-changed:
133    * @action_group: the #GActionGroup that changed
134    * @action_name: the name of the action in @action_group
135    * @value: the new value of the state
136    *
137    * Signals that the state of the named action has changed.
138    *
139    * Since: 2.28
140    **/
141   g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED] =
142     g_signal_new (I_("action-state-changed"),
143                   G_TYPE_ACTION_GROUP,
144                   G_SIGNAL_RUN_LAST |
145                   G_SIGNAL_DETAILED |
146                   G_SIGNAL_MUST_COLLECT,
147                   G_STRUCT_OFFSET (GActionGroupInterface,
148                                    action_state_changed),
149                   NULL, NULL,
150                   NULL,
151                   G_TYPE_NONE, 2,
152                   G_TYPE_STRING,
153                   G_TYPE_VARIANT);
154 }
155
156 /**
157  * g_action_group_list_actions:
158  * @action_group: a #GActionGroup
159  *
160  * Lists the actions contained within @action_group.
161  *
162  * The caller is responsible for freeing the list with g_strfreev() when
163  * it is no longer required.
164  *
165  * Returns: (transfer full): a %NULL-terminated array of the names of the
166  * actions in the groupb
167  *
168  * Since: 2.28
169  **/
170 gchar **
171 g_action_group_list_actions (GActionGroup *action_group)
172 {
173   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
174
175   return G_ACTION_GROUP_GET_IFACE (action_group)
176     ->list_actions (action_group);
177 }
178
179 /**
180  * g_action_group_has_action:
181  * @action_group: a #GActionGroup
182  * @action_name: the name of the action to check for
183  *
184  * Checks if the named action exists within @action_group.
185  *
186  * Returns: whether the named action exists
187  *
188  * Since: 2.28
189  **/
190 gboolean
191 g_action_group_has_action (GActionGroup *action_group,
192                            const gchar  *action_name)
193 {
194   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
195
196   return G_ACTION_GROUP_GET_IFACE (action_group)
197     ->has_action (action_group, action_name);
198 }
199
200 /**
201  * g_action_group_get_action_parameter_type:
202  * @action_group: a #GActionGroup
203  * @action_name: the name of the action to query
204  *
205  * Queries the type of the parameter that must be given when activating
206  * the named action within @action_group.
207  *
208  * When activating the action using g_action_group_activate_action(),
209  * the #GVariant given to that function must be of the type returned
210  * by this function.
211  *
212  * In the case that this function returns %NULL, you must not give any
213  * #GVariant, but %NULL instead.
214  *
215  * The parameter type of a particular action will never change but it is
216  * possible for an action to be removed and for a new action to be added
217  * with the same name but a different parameter type.
218  *
219  * Return value: the parameter type
220  *
221  * Since: 2.28
222  **/
223 const GVariantType *
224 g_action_group_get_action_parameter_type (GActionGroup *action_group,
225                                           const gchar  *action_name)
226 {
227   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
228
229   return G_ACTION_GROUP_GET_IFACE (action_group)
230     ->get_action_parameter_type (action_group, action_name);
231 }
232
233 /**
234  * g_action_group_get_action_state_type:
235  * @action_group: a #GActionGroup
236  * @action_name: the name of the action to query
237  *
238  * Queries the type of the state of the named action within
239  * @action_group.
240  *
241  * If the action is stateful then this function returns the
242  * #GVariantType of the state.  All calls to
243  * g_action_group_change_action_state() must give a #GVariant of this
244  * type and g_action_group_get_action_state() will return a #GVariant
245  * of the same type.
246  *
247  * If the action is not stateful then this function will return %NULL.
248  * In that case, g_action_group_get_action_state() will return %NULL
249  * and you must not call g_action_group_change_action_state().
250  *
251  * The state type of a particular action will never change but it is
252  * possible for an action to be removed and for a new action to be added
253  * with the same name but a different state type.
254  *
255  * Returns: (transfer full): the state type, if the action is stateful
256  *
257  * Since: 2.28
258  **/
259 const GVariantType *
260 g_action_group_get_action_state_type (GActionGroup *action_group,
261                                       const gchar  *action_name)
262 {
263   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
264
265   return G_ACTION_GROUP_GET_IFACE (action_group)
266     ->get_action_state_type (action_group, action_name);
267 }
268
269 /**
270  * g_action_group_get_action_state_hint:
271  * @action_group: a #GActionGroup
272  * @action_name: the name of the action to query
273  *
274  * Requests a hint about the valid range of values for the state of the
275  * named action within @action_group.
276  *
277  * If %NULL is returned it either means that the action is not stateful
278  * or that there is no hint about the valid range of values for the
279  * state of the action.
280  *
281  * If a #GVariant array is returned then each item in the array is a
282  * possible value for the state.  If a #GVariant pair (ie: two-tuple) is
283  * returned then the tuple specifies the inclusive lower and upper bound
284  * of valid values for the state.
285  *
286  * In any case, the information is merely a hint.  It may be possible to
287  * have a state value outside of the hinted range and setting a value
288  * within the range may fail.
289  *
290  * The return value (if non-%NULL) should be freed with
291  * g_variant_unref() when it is no longer required.
292  *
293  * Return value: (transfer full): the state range hint
294  *
295  * Since: 2.28
296  **/
297 GVariant *
298 g_action_group_get_action_state_hint (GActionGroup *action_group,
299                                       const gchar  *action_name)
300 {
301   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
302
303   return G_ACTION_GROUP_GET_IFACE (action_group)
304     ->get_action_state_hint (action_group, action_name);
305 }
306
307 /**
308  * g_action_group_get_action_enabled:
309  * @action_group: a #GActionGroup
310  * @action_name: the name of the action to query
311  *
312  * Checks if the named action within @action_group is currently enabled.
313  *
314  * An action must be enabled in order to be activated or in order to
315  * have its state changed from outside callers.
316  *
317  * Return value: whether or not the action is currently enabled
318  *
319  * Since: 2.28
320  **/
321 gboolean
322 g_action_group_get_action_enabled (GActionGroup *action_group,
323                                    const gchar  *action_name)
324 {
325   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
326
327   return G_ACTION_GROUP_GET_IFACE (action_group)
328     ->get_action_enabled (action_group, action_name);
329 }
330
331 /**
332  * g_action_group_get_action_state:
333  * @action_group: a #GActionGroup
334  * @action_name: the name of the action to query
335  *
336  * Queries the current state of the named action within @action_group.
337  *
338  * If the action is not stateful then %NULL will be returned.  If the
339  * action is stateful then the type of the return value is the type
340  * given by g_action_group_get_action_state_type().
341  *
342  * The return value (if non-%NULL) should be freed with
343  * g_variant_unref() when it is no longer required.
344  *
345  * Return value: (allow-none): the current state of the action
346  *
347  * Since: 2.28
348  **/
349 GVariant *
350 g_action_group_get_action_state (GActionGroup *action_group,
351                                  const gchar  *action_name)
352 {
353   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
354
355   return G_ACTION_GROUP_GET_IFACE (action_group)
356     ->get_action_state (action_group, action_name);
357 }
358
359 /**
360  * g_action_group_change_action_state:
361  * @action_group: a #GActionGroup
362  * @action_name: the name of the action to request the change on
363  * @value: the new state
364  *
365  * Request for the state of the named action within @action_group to be
366  * changed to @value.
367  *
368  * The action must be stateful and @value must be of the correct type.
369  * See g_action_group_get_action_state_type().
370  *
371  * This call merely requests a change.  The action may refuse to change
372  * its state or may change its state to something other than @value.
373  * See g_action_group_get_action_state_hint().
374  *
375  * If the @value GVariant is floating, it is consumed.
376  *
377  * Since: 2.28
378  **/
379 void
380 g_action_group_change_action_state (GActionGroup *action_group,
381                                     const gchar  *action_name,
382                                     GVariant     *value)
383 {
384   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
385   g_return_if_fail (action_name != NULL);
386   g_return_if_fail (value != NULL);
387
388   G_ACTION_GROUP_GET_IFACE (action_group)
389     ->change_action_state (action_group, action_name, value);
390 }
391
392 /**
393  * g_action_group_activate_action:
394  * @action_group: a #GActionGroup
395  * @action_name: the name of the action to activate
396  * @parameter: (allow-none): parameters to the activation
397  *
398  * Activate the named action within @action_group.
399  *
400  * If the action is expecting a parameter, then the correct type of
401  * parameter must be given as @parameter.  If the action is expecting no
402  * parameters then @parameter must be %NULL.  See
403  * g_action_group_get_action_parameter_type().
404  *
405  * Since: 2.28
406  **/
407 void
408 g_action_group_activate_action (GActionGroup *action_group,
409                                 const gchar  *action_name,
410                                 GVariant     *parameter)
411 {
412   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
413   g_return_if_fail (action_name != NULL);
414
415   G_ACTION_GROUP_GET_IFACE (action_group)
416     ->activate_action (action_group, action_name, parameter);
417 }
418
419 /**
420  * g_action_group_action_added:
421  * @action_group: a #GActionGroup
422  * @action_name: the name of an action in the group
423  *
424  * Emits the #GActionGroup::action-added signal on @action_group.
425  *
426  * This function should only be called by #GActionGroup implementations.
427  *
428  * Since: 2.28
429  **/
430 void
431 g_action_group_action_added (GActionGroup *action_group,
432                              const gchar  *action_name)
433 {
434   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
435   g_return_if_fail (action_name != NULL);
436
437   g_signal_emit (action_group,
438                  g_action_group_signals[SIGNAL_ACTION_ADDED],
439                  g_quark_try_string (action_name),
440                  action_name);
441 }
442
443 /**
444  * g_action_group_action_removed:
445  * @action_group: a #GActionGroup
446  * @action_name: the name of an action in the group
447  *
448  * Emits the #GActionGroup::action-removed signal on @action_group.
449  *
450  * This function should only be called by #GActionGroup implementations.
451  *
452  * Since: 2.28
453  **/
454 void
455 g_action_group_action_removed (GActionGroup *action_group,
456                                const gchar  *action_name)
457 {
458   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
459   g_return_if_fail (action_name != NULL);
460
461   g_signal_emit (action_group,
462                  g_action_group_signals[SIGNAL_ACTION_REMOVED],
463                  g_quark_try_string (action_name),
464                  action_name);
465 }
466
467 /**
468  * g_action_group_action_enabled_changed:
469  * @action_group: a #GActionGroup
470  * @action_name: the name of an action in the group
471  * @enabled: whether or not the action is now enabled
472  *
473  * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
474  *
475  * This function should only be called by #GActionGroup implementations.
476  *
477  * Since: 2.28
478  **/
479 void
480 g_action_group_action_enabled_changed (GActionGroup *action_group,
481                                        const gchar  *action_name,
482                                        gboolean      enabled)
483 {
484   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
485   g_return_if_fail (action_name != NULL);
486
487   enabled = !!enabled;
488
489   g_signal_emit (action_group,
490                  g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED],
491                  g_quark_try_string (action_name),
492                  action_name,
493                  enabled);
494 }
495
496 /**
497  * g_action_group_action_state_changed:
498  * @action_group: a #GActionGroup
499  * @action_name: the name of an action in the group
500  * @state: the new state of the named action
501  *
502  * Emits the #GActionGroup::action-state-changed signal on @action_group.
503  *
504  * This function should only be called by #GActionGroup implementations.
505  *
506  * Since: 2.28
507  **/
508 void
509 g_action_group_action_state_changed (GActionGroup *action_group,
510                                      const gchar  *action_name,
511                                      GVariant     *state)
512 {
513   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
514   g_return_if_fail (action_name != NULL);
515
516   g_signal_emit (action_group,
517                  g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED],
518                  g_quark_try_string (action_name),
519                  action_name,
520                  state);
521 }