No issues found
1 /*
2 * Copyright Š 2011 Canonical 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
6 * published by the Free Software Foundation; either version 2 of the
7 * licence or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful, but
10 * 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 Public
15 * License along with this library; if not, write to the Free Software
16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
17 * USA.
18 *
19 * Authors: Ryan Lortie <desrt@desrt.ca>
20 */
21
22 #include "config.h"
23
24 #include "gactionobserver.h"
25
26 G_DEFINE_INTERFACE (GActionObserver, g_action_observer, G_TYPE_OBJECT)
27
28 /**
29 * SECTION:gactionobserver
30 * @short_description: an interface implemented by objects that are
31 * interested in monitoring actions for changes
32 *
33 * GActionObserver is a simple interface allowing objects that wish to
34 * be notified of changes to actions to be notified of those changes.
35 *
36 * It is also possible to monitor changes to action groups using
37 * #GObject signals, but there are a number of reasons that this
38 * approach could become problematic:
39 *
40 * - there are four separate signals that must be manually connected
41 * and disconnected
42 *
43 * - when a large number of different observers wish to monitor a
44 * (usually disjoint) set of actions within the same action group,
45 * there is only one way to avoid having all notifications delivered
46 * to all observers: signal detail. In order to use signal detail,
47 * each action name must be quarked, which is not always practical.
48 *
49 * - even if quarking is acceptable, #GObject signal details are
50 * implemented by scanning a linked list, so there is no real
51 * decrease in complexity
52 */
53
54 void
55 g_action_observer_default_init (GActionObserverInterface *class)
56 {
57 }
58
59 /*
60 * g_action_observer_action_added:
61 * @observer: a #GActionObserver
62 * @observable: the source of the event
63 * @action_name: the name of the action
64 * @enabled: %TRUE if the action is now enabled
65 * @parameter_type: the parameter type for action invocations, or %NULL
66 * if no parameter is required
67 * @state: the current state of the action, or %NULL if the action is
68 * stateless
69 *
70 * This function is called when an action that the observer is
71 * registered to receive events for is added.
72 *
73 * This function should only be called by objects with which the
74 * observer has explicitly registered itself to receive events.
75 */
76 void
77 g_action_observer_action_added (GActionObserver *observer,
78 GActionObservable *observable,
79 const gchar *action_name,
80 const GVariantType *parameter_type,
81 gboolean enabled,
82 GVariant *state)
83 {
84 g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
85
86 G_ACTION_OBSERVER_GET_IFACE (observer)
87 ->action_added (observer, observable, action_name, parameter_type, enabled, state);
88 }
89
90 /*
91 * g_action_observer_action_enabled_changed:
92 * @observer: a #GActionObserver
93 * @observable: the source of the event
94 * @action_name: the name of the action
95 * @enabled: %TRUE if the action is now enabled
96 *
97 * This function is called when an action that the observer is
98 * registered to receive events for becomes enabled or disabled.
99 *
100 * This function should only be called by objects with which the
101 * observer has explicitly registered itself to receive events.
102 */
103 void
104 g_action_observer_action_enabled_changed (GActionObserver *observer,
105 GActionObservable *observable,
106 const gchar *action_name,
107 gboolean enabled)
108 {
109 g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
110
111 G_ACTION_OBSERVER_GET_IFACE (observer)
112 ->action_enabled_changed (observer, observable, action_name, enabled);
113 }
114
115 /*
116 * g_action_observer_action_state_changed:
117 * @observer: a #GActionObserver
118 * @observable: the source of the event
119 * @action_name: the name of the action
120 * @state: the new state of the action
121 *
122 * This function is called when an action that the observer is
123 * registered to receive events for changes its state.
124 *
125 * This function should only be called by objects with which the
126 * observer has explicitly registered itself to receive events.
127 */
128 void
129 g_action_observer_action_state_changed (GActionObserver *observer,
130 GActionObservable *observable,
131 const gchar *action_name,
132 GVariant *state)
133 {
134 g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
135
136 G_ACTION_OBSERVER_GET_IFACE (observer)
137 ->action_state_changed (observer, observable, action_name, state);
138 }
139
140 /*
141 * g_action_observer_action_removed:
142 * @observer: a #GActionObserver
143 * @observable: the source of the event
144 * @action_name: the name of the action
145 *
146 * This function is called when an action that the observer is
147 * registered to receive events for is removed.
148 *
149 * This function should only be called by objects with which the
150 * observer has explicitly registered itself to receive events.
151 */
152 void
153 g_action_observer_action_removed (GActionObserver *observer,
154 GActionObservable *observable,
155 const gchar *action_name)
156 {
157 g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
158
159 G_ACTION_OBSERVER_GET_IFACE (observer)
160 ->action_removed (observer, observable, action_name);
161 }