1 /*
2 * Copyright © 2011 Canonical Limited
3 *
4 * This library 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, see <http://www.gnu.org/licenses/>.
16 *
17 * Authors: Ryan Lortie <desrt@desrt.ca>
18 */
19
20 #include "config.h"
21
22 #include "gtkactionobserver.h"
23
G_DEFINE_INTERFACE(GtkActionObserver,gtk_action_observer,G_TYPE_OBJECT)24 G_DEFINE_INTERFACE (GtkActionObserver, gtk_action_observer, G_TYPE_OBJECT)
25
26 /*< private >
27 * SECTION:gtkactionobserver
28 * @short_description: an interface implemented by objects that are
29 * interested in monitoring actions for changes
30 *
31 * GtkActionObserver is a simple interface allowing objects that wish to
32 * be notified of changes to actions to be notified of those changes.
33 *
34 * It is also possible to monitor changes to action groups using
35 * #GObject signals, but there are a number of reasons that this
36 * approach could become problematic:
37 *
38 * - there are four separate signals that must be manually connected
39 * and disconnected
40 *
41 * - when a large number of different observers wish to monitor a
42 * (usually disjoint) set of actions within the same action group,
43 * there is only one way to avoid having all notifications delivered
44 * to all observers: signal detail. In order to use signal detail,
45 * each action name must be quarked, which is not always practical.
46 *
47 * - even if quarking is acceptable, #GObject signal details are
48 * implemented by scanning a linked list, so there is no real
49 * decrease in complexity
50 */
51
52 void
53 gtk_action_observer_default_init (GtkActionObserverInterface *class)
54 {
55 }
56
57 /*< private >
58 * gtk_action_observer_action_added:
59 * @observer: a #GtkActionObserver
60 * @observable: the source of the event
61 * @action_name: the name of the action
62 * @enabled: %TRUE if the action is now enabled
63 * @parameter_type: the parameter type for action invocations, or %NULL
64 * if no parameter is required
65 * @state: the current state of the action, or %NULL if the action is
66 * stateless
67 *
68 * This function is called when an action that the observer is
69 * registered to receive events for is added.
70 *
71 * This function should only be called by objects with which the
72 * observer has explicitly registered itself to receive events.
73 */
74 void
gtk_action_observer_action_added(GtkActionObserver * observer,GtkActionObservable * observable,const gchar * action_name,const GVariantType * parameter_type,gboolean enabled,GVariant * state)75 gtk_action_observer_action_added (GtkActionObserver *observer,
76 GtkActionObservable *observable,
77 const gchar *action_name,
78 const GVariantType *parameter_type,
79 gboolean enabled,
80 GVariant *state)
81 {
82 g_return_if_fail (GTK_IS_ACTION_OBSERVER (observer));
83
84 GTK_ACTION_OBSERVER_GET_IFACE (observer)
85 ->action_added (observer, observable, action_name, parameter_type, enabled, state);
86 }
87
88 /*< private >
89 * gtk_action_observer_action_enabled_changed:
90 * @observer: a #GtkActionObserver
91 * @observable: the source of the event
92 * @action_name: the name of the action
93 * @enabled: %TRUE if the action is now enabled
94 *
95 * This function is called when an action that the observer is
96 * registered to receive events for becomes enabled or disabled.
97 *
98 * This function should only be called by objects with which the
99 * observer has explicitly registered itself to receive events.
100 */
101 void
gtk_action_observer_action_enabled_changed(GtkActionObserver * observer,GtkActionObservable * observable,const gchar * action_name,gboolean enabled)102 gtk_action_observer_action_enabled_changed (GtkActionObserver *observer,
103 GtkActionObservable *observable,
104 const gchar *action_name,
105 gboolean enabled)
106 {
107 g_return_if_fail (GTK_IS_ACTION_OBSERVER (observer));
108
109 GTK_ACTION_OBSERVER_GET_IFACE (observer)
110 ->action_enabled_changed (observer, observable, action_name, enabled);
111 }
112
113 /*< private >
114 * gtk_action_observer_action_state_changed:
115 * @observer: a #GtkActionObserver
116 * @observable: the source of the event
117 * @action_name: the name of the action
118 * @state: the new state of the action
119 *
120 * This function is called when an action that the observer is
121 * registered to receive events for changes to its state.
122 *
123 * This function should only be called by objects with which the
124 * observer has explicitly registered itself to receive events.
125 */
126 void
gtk_action_observer_action_state_changed(GtkActionObserver * observer,GtkActionObservable * observable,const gchar * action_name,GVariant * state)127 gtk_action_observer_action_state_changed (GtkActionObserver *observer,
128 GtkActionObservable *observable,
129 const gchar *action_name,
130 GVariant *state)
131 {
132 g_return_if_fail (GTK_IS_ACTION_OBSERVER (observer));
133
134 GTK_ACTION_OBSERVER_GET_IFACE (observer)
135 ->action_state_changed (observer, observable, action_name, state);
136 }
137
138 /*< private >
139 * gtk_action_observer_action_removed:
140 * @observer: a #GtkActionObserver
141 * @observable: the source of the event
142 * @action_name: the name of the action
143 *
144 * This function is called when an action that the observer is
145 * registered to receive events for is removed.
146 *
147 * This function should only be called by objects with which the
148 * observer has explicitly registered itself to receive events.
149 */
150 void
gtk_action_observer_action_removed(GtkActionObserver * observer,GtkActionObservable * observable,const gchar * action_name)151 gtk_action_observer_action_removed (GtkActionObserver *observer,
152 GtkActionObservable *observable,
153 const gchar *action_name)
154 {
155 g_return_if_fail (GTK_IS_ACTION_OBSERVER (observer));
156
157 GTK_ACTION_OBSERVER_GET_IFACE (observer)
158 ->action_removed (observer, observable, action_name);
159 }
160
161 /*< private >
162 * gtk_action_observer_primary_accel_changed:
163 * @observer: a #GtkActionObserver
164 * @observable: the source of the event
165 * @action_name: the name of the action
166 * @action_and_target: detailed action of the changed accel, in “action and target” format
167 *
168 * This function is called when an action that the observer is
169 * registered to receive events for has one of its accelerators changed.
170 *
171 * Accelerator changes are reported for all targets associated with the
172 * action. The @action_and_target string should be used to check if the
173 * reported target is the one that the observer is interested in.
174 */
175 void
gtk_action_observer_primary_accel_changed(GtkActionObserver * observer,GtkActionObservable * observable,const gchar * action_name,const gchar * action_and_target)176 gtk_action_observer_primary_accel_changed (GtkActionObserver *observer,
177 GtkActionObservable *observable,
178 const gchar *action_name,
179 const gchar *action_and_target)
180 {
181 GtkActionObserverInterface *iface;
182
183 g_return_if_fail (GTK_IS_ACTION_OBSERVER (observer));
184
185 iface = GTK_ACTION_OBSERVER_GET_IFACE (observer);
186
187 if (iface->primary_accel_changed)
188 iface->primary_accel_changed (observer, observable, action_name, action_and_target);
189 }
190