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

source code of gtk/gtk/gtkactionobserver.c