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 | |
24 | G_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 | |
50 | void |
51 | gtk_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 | */ |
70 | void |
71 | gtk_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 | */ |
97 | void |
98 | gtk_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 | */ |
122 | void |
123 | gtk_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 | */ |
146 | void |
147 | gtk_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 | */ |
173 | void |
174 | gtk_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 | |