2 * Copyright © 2011 Canonical Limited
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.
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.
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/>.
17 * Authors: Ryan Lortie <desrt@desrt.ca>
22 #include "gactionobserver.h"
24 G_DEFINE_INTERFACE (GActionObserver, g_action_observer, G_TYPE_OBJECT)
27 * SECTION:gactionobserver
28 * @short_description: an interface implemented by objects that are
29 * interested in monitoring actions for changes
31 * GActionObserver is a simple interface allowing objects that wish to
32 * be notified of changes to actions to be notified of those changes.
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:
38 * - there are four separate signals that must be manually connected
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.
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
53 g_action_observer_default_init (GActionObserverInterface *class)
58 * g_action_observer_action_added:
59 * @observer: a #GActionObserver
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
68 * This function is called when an action that the observer is
69 * registered to receive events for is added.
71 * This function should only be called by objects with which the
72 * observer has explicitly registered itself to receive events.
75 g_action_observer_action_added (GActionObserver *observer,
76 GActionObservable *observable,
77 const gchar *action_name,
78 const GVariantType *parameter_type,
82 g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
84 G_ACTION_OBSERVER_GET_IFACE (observer)
85 ->action_added (observer, observable, action_name, parameter_type, enabled, state);
89 * g_action_observer_action_enabled_changed:
90 * @observer: a #GActionObserver
91 * @observable: the source of the event
92 * @action_name: the name of the action
93 * @enabled: %TRUE if the action is now enabled
95 * This function is called when an action that the observer is
96 * registered to receive events for becomes enabled or disabled.
98 * This function should only be called by objects with which the
99 * observer has explicitly registered itself to receive events.
102 g_action_observer_action_enabled_changed (GActionObserver *observer,
103 GActionObservable *observable,
104 const gchar *action_name,
107 g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
109 G_ACTION_OBSERVER_GET_IFACE (observer)
110 ->action_enabled_changed (observer, observable, action_name, enabled);
114 * g_action_observer_action_state_changed:
115 * @observer: a #GActionObserver
116 * @observable: the source of the event
117 * @action_name: the name of the action
118 * @state: the new state of the action
120 * This function is called when an action that the observer is
121 * registered to receive events for changes its state.
123 * This function should only be called by objects with which the
124 * observer has explicitly registered itself to receive events.
127 g_action_observer_action_state_changed (GActionObserver *observer,
128 GActionObservable *observable,
129 const gchar *action_name,
132 g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
134 G_ACTION_OBSERVER_GET_IFACE (observer)
135 ->action_state_changed (observer, observable, action_name, state);
139 * g_action_observer_action_removed:
140 * @observer: a #GActionObserver
141 * @observable: the source of the event
142 * @action_name: the name of the action
144 * This function is called when an action that the observer is
145 * registered to receive events for is removed.
147 * This function should only be called by objects with which the
148 * observer has explicitly registered itself to receive events.
151 g_action_observer_action_removed (GActionObserver *observer,
152 GActionObservable *observable,
153 const gchar *action_name)
155 g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
157 G_ACTION_OBSERVER_GET_IFACE (observer)
158 ->action_removed (observer, observable, action_name);