GActionGroup is now an interface
[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 "gio-marshal.h"
26 #include "glibintl.h"
27
28 /**
29  * SECTION:gactiongroup
30  * @title: GActionGroup
31  * @short_description: a group of actions
32  *
33  * #GActionGroup represents a group of actions.
34  *
35  * Each action in the group has a unique name (which is a string).  All
36  * method calls, except g_action_group_list_actions() take the name of
37  * an action as an argument.
38  *
39  * The #GActionGroup API is meant to be the 'public' API to the action
40  * group.  The calls here are exactly the interaction that 'external
41  * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
42  * with actions.  'Internal' APIs (ie: ones meant only to be accessed by
43  * the action group implementation) are found on subclasses.  This is
44  * why you will find -- for example -- g_action_group_get_enabled() but
45  * not an equivalent <function>set()</function> call.
46  *
47  * Signals are emitted on the action group in response to state changes
48  * on individual actions.
49  **/
50
51 G_DEFINE_INTERFACE (GActionGroup, g_action_group, G_TYPE_OBJECT)
52
53 enum
54 {
55   SIGNAL_ACTION_ADDED,
56   SIGNAL_ACTION_REMOVED,
57   SIGNAL_ACTION_ENABLED_CHANGED,
58   SIGNAL_ACTION_STATE_CHANGED,
59   NR_SIGNALS
60 };
61
62 static guint g_action_group_signals[NR_SIGNALS];
63
64 static void
65 g_action_group_default_init (GActionGroupInterface *class)
66 {
67   /**
68    * GActionGroup::action-added:
69    * @action_group: the #GActionGroup that changed
70    * @action_name: the name of the action in @action_group
71    *
72    * Signals that a new action was just added to the group.  This signal
73    * is emitted after the action has been added and is now visible.
74    *
75    * Since: 2.26
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.26
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.26
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                   _gio_marshal_VOID__STRING_BOOLEAN,
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.26
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 | G_SIGNAL_DETAILED,
145                   G_STRUCT_OFFSET (GActionGroupInterface,
146                                    action_state_changed),
147                   NULL, NULL,
148                   _gio_marshal_VOID__STRING_VARIANT,
149                   G_TYPE_NONE, 2,
150                   G_TYPE_STRING,
151                   G_TYPE_VARIANT);
152 }
153
154 /**
155  * g_action_group_list_actions:
156  * @action_group: a #GActionGroup
157  *
158  * Lists the actions contained within @action_group.
159  *
160  * The caller is responsible for freeing the list with g_strfreev() when
161  * it is no longer required.
162  *
163  * Returns: a %NULL-terminated array of the names of the actions in the group
164  *
165  * Since: 2.26
166  **/
167 gchar **
168 g_action_group_list_actions (GActionGroup *action_group)
169 {
170   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
171
172   return G_ACTION_GROUP_GET_IFACE (action_group)
173     ->list_actions (action_group);
174 }
175
176 /**
177  * g_action_group_has_action:
178  * @action_group: a #GActionGroup
179  * @action_name: the name of the action to check for
180  *
181  * Checks if the named action exists within @action_group.
182  *
183  * Returns: whether the named action exists
184  *
185  * Since: 2.26
186  **/
187 gboolean
188 g_action_group_has_action (GActionGroup *action_group,
189                            const gchar  *action_name)
190 {
191   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
192
193   return G_ACTION_GROUP_GET_IFACE (action_group)
194     ->has_action (action_group, action_name);
195 }
196
197 /**
198  * g_action_group_get_parameter_type:
199  * @action_group: a #GActionGroup
200  * @action_name: the name of the action to query
201  *
202  * Queries the type of the parameter that must be given when activating
203  * the named action within @action_group.
204  *
205  * When activating the action using g_action_group_activate(), the
206  * #GVariant given to that function must be of the type returned by this
207  * function.
208  *
209  * In the case that this function returns %NULL, you must not give any
210  * #GVariant, but %NULL instead.
211  *
212  * The parameter type of a particular action will never change but it is
213  * possible for an action to be removed and for a new action to be added
214  * with the same name but a different parameter type.
215  *
216  * Return value: the parameter type
217  *
218  * Since: 2.26
219  **/
220 const GVariantType *
221 g_action_group_get_parameter_type (GActionGroup *action_group,
222                                    const gchar  *action_name)
223 {
224   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
225
226   return G_ACTION_GROUP_GET_IFACE (action_group)
227     ->get_parameter_type (action_group, action_name);
228 }
229
230 /**
231  * g_action_group_get_state_type:
232  * @action_group: a #GActionGroup
233  * @action_name: the name of the action to query
234  *
235  * Queries the type of the state of the named action within
236  * @action_group.
237  *
238  * If the action is stateful then this function returns the
239  * #GVariantType of the state.  All calls to g_action_group_set_state()
240  * must give a #GVariant of this type and g_action_group_get_state()
241  * will return a #GVariant of the same type.
242  *
243  * If the action is not stateful then this function will return %NULL.
244  * In that case, g_action_group_get_state() will return %NULL and you
245  * must not call g_action_group_set_state().
246  *
247  * The state type of a particular action will never change but it is
248  * possible for an action to be removed and for a new action to be added
249  * with the same name but a different state type.
250  *
251  * Returns: (allow-none): the state type, if the action is stateful
252  *
253  * Since: 2.26
254  **/
255 const GVariantType *
256 g_action_group_get_state_type (GActionGroup *action_group,
257                                const gchar  *action_name)
258 {
259   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
260
261   return G_ACTION_GROUP_GET_IFACE (action_group)
262     ->get_state_type (action_group, action_name);
263 }
264
265 /**
266  * g_action_group_get_state_hint:
267  * @action_group: a #GActionGroup
268  * @action_name: the name of the action to query
269  *
270  * Requests a hint about the valid range of values for the state of the
271  * named action within @action_group.
272  *
273  * If %NULL is returned it either means that the action is not stateful
274  * or that there is no hint about the valid range of values for the
275  * state of the action.
276  *
277  * If a #GVariant array is returned then each item in the array is a
278  * possible value for the state.  If a #GVariant pair (ie: two-tuple) is
279  * returned then the tuple specifies the inclusive lower and upper bound
280  * of valid values for the state.
281  *
282  * In any case, the information is merely a hint.  It may be possible to
283  * have a state value outside of the hinted range and setting a value
284  * within the range may fail.
285  *
286  * The return value (if non-%NULL) should be freed with
287  * g_variant_unref() when it is no longer required.
288  *
289  * Return value: the state range hint
290  *
291  * Since: 2.26
292  **/
293 GVariant *
294 g_action_group_get_state_hint (GActionGroup *action_group,
295                                const gchar  *action_name)
296 {
297   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
298
299   return G_ACTION_GROUP_GET_IFACE (action_group)
300     ->get_state_hint (action_group, action_name);
301 }
302
303 /**
304  * g_action_group_get_enabled:
305  * @action_group: a #GActionGroup
306  * @action_name: the name of the action to query
307  *
308  * Checks if the named action within @action_group is currently enabled.
309  *
310  * An action must be enabled in order to be activated or in order to
311  * have its state changed from outside callers.
312  *
313  * Return value: whether or not the action is currently enabled
314  *
315  * Since: 2.26
316  **/
317 gboolean
318 g_action_group_get_enabled (GActionGroup *action_group,
319                             const gchar  *action_name)
320 {
321   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
322
323   return G_ACTION_GROUP_GET_IFACE (action_group)
324     ->get_enabled (action_group, action_name);
325 }
326
327 /**
328  * g_action_group_get_state:
329  * @action_group: a #GActionGroup
330  * @action_name: the name of the action to query
331  *
332  * Queries the current state of the named action within @action_group.
333  *
334  * If the action is not stateful then %NULL will be returned.  If the
335  * action is stateful then the type of the return value is the type
336  * given by g_action_group_get_state_type().
337  *
338  * The return value (if non-%NULL) should be freed with
339  * g_variant_unref() when it is no longer required.
340  *
341  * Return value: (allow-none) (transfer-none): the current state of the action
342  *
343  * Since: 2.26
344  **/
345 GVariant *
346 g_action_group_get_state (GActionGroup *action_group,
347                           const gchar  *action_name)
348 {
349   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
350
351   return G_ACTION_GROUP_GET_IFACE (action_group)
352     ->get_state (action_group, action_name);
353 }
354
355 /**
356  * g_action_group_set_state:
357  * @action_group: a #GActionGroup
358  * @action_name: the name of the action to request the change on
359  * @value: the new state
360  *
361  * Request for the state of the named action within @action_group to be
362  * changed to @value.
363  *
364  * The action must be stateful and @value must be of the correct type.
365  * See g_action_group_get_state_type().
366  *
367  * This call merely requests a change.  The action may refuse to change
368  * its state or may change its state to something other than @value.
369  * See g_action_group_get_state_hint().
370  *
371  * If the @value GVariant is floating, it is consumed.
372  *
373  * Since: 2.26
374  **/
375 void
376 g_action_group_set_state (GActionGroup *action_group,
377                           const gchar  *action_name,
378                           GVariant     *value)
379 {
380   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
381   g_return_if_fail (action_name != NULL);
382   g_return_if_fail (value != NULL);
383
384   G_ACTION_GROUP_GET_IFACE (action_group)
385     ->set_state (action_group, action_name, value);
386 }
387
388 /**
389  * g_action_group_activate:
390  * @action_group: a #GActionGroup
391  * @action_name: the name of the action to activate
392  * @parameter: (allow-none): parameters to the activation
393  *
394  * Activate the named action within @action_group.
395  *
396  * If the action is expecting a parameter, then the correct type of
397  * parameter must be given as @parameter.  If the action is expecting no
398  * parameters then @parameter must be %NULL.  See
399  * g_action_group_get_parameter_type().
400  *
401  * Since: 2.26
402  **/
403 void
404 g_action_group_activate (GActionGroup *action_group,
405                          const gchar  *action_name,
406                          GVariant     *parameter)
407 {
408   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
409   g_return_if_fail (action_name != NULL);
410
411   G_ACTION_GROUP_GET_IFACE (action_group)
412     ->activate (action_group, action_name, parameter);
413 }
414
415 /**
416  * g_action_group_action_added:
417  * @action_group: a #GActionGroup
418  * @action_name: the name of an action in the group
419  *
420  * Emits the #GActionGroup::action-added signal on @action_group.
421  *
422  * This function should only be called by #GActionGroup implementations.
423  *
424  * Since: 2.26
425  **/
426 void
427 g_action_group_action_added (GActionGroup *action_group,
428                              const gchar  *action_name)
429 {
430   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
431   g_return_if_fail (action_name != NULL);
432
433   g_signal_emit (action_group,
434                  g_action_group_signals[SIGNAL_ACTION_ADDED],
435                  g_quark_try_string (action_name),
436                  action_name);
437 }
438
439 /**
440  * g_action_group_action_removed:
441  * @action_group: a #GActionGroup
442  * @action_name: the name of an action in the group
443  *
444  * Emits the #GActionGroup::action-removed signal on @action_group.
445  *
446  * This function should only be called by #GActionGroup implementations.
447  *
448  * Since: 2.26
449  **/
450 void
451 g_action_group_action_removed (GActionGroup *action_group,
452                                const gchar  *action_name)
453 {
454   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
455   g_return_if_fail (action_name != NULL);
456
457   g_signal_emit (action_group,
458                  g_action_group_signals[SIGNAL_ACTION_REMOVED],
459                  g_quark_try_string (action_name),
460                  action_name);
461 }
462
463 /**
464  * g_action_group_action_enabled_changed:
465  * @action_group: a #GActionGroup
466  * @action_name: the name of an action in the group
467  * @enabled: whether or not the action is now enabled
468  *
469  * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
470  *
471  * This function should only be called by #GActionGroup implementations.
472  *
473  * Since: 2.26
474  **/
475 void
476 g_action_group_action_enabled_changed (GActionGroup *action_group,
477                                        const gchar  *action_name,
478                                        gboolean      enabled)
479 {
480   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
481   g_return_if_fail (action_name != NULL);
482
483   enabled = !!enabled;
484
485   g_signal_emit (action_group,
486                  g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED],
487                  g_quark_try_string (action_name),
488                  action_name,
489                  enabled);
490 }
491
492 /**
493  * g_action_group_action_state_changed:
494  * @action_group: a #GActionGroup
495  * @action_name: the name of an action in the group
496  * @state: the new state of the named action
497  *
498  * Emits the #GActionGroup::action-state-changed signal on @action_group.
499  *
500  * This function should only be called by #GActionGroup implementations.
501  *
502  * Since: 2.26
503  **/
504 void
505 g_action_group_action_state_changed (GActionGroup *action_group,
506                                      const gchar  *action_name,
507                                      GVariant     *state)
508 {
509   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
510   g_return_if_fail (action_name != NULL);
511
512   g_signal_emit (action_group,
513                  g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED],
514                  g_quark_try_string (action_name),
515                  action_name,
516                  state);
517 }