summaryrefslogtreecommitdiff
path: root/gtk/gactionobserver.c
blob: 3f05c4a389c80e786f6efff86c6c1ffef0801e29 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
/*
 * Copyright © 2011 Canonical Limited
 *
 * This library is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * licence or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
 *
 * Authors: Ryan Lortie <desrt@desrt.ca>
 */

#include "config.h"

#include "gactionobserver.h"

G_DEFINE_INTERFACE (GActionObserver, g_action_observer, G_TYPE_OBJECT)

/**
 * SECTION:gactionobserver
 * @short_description: an interface implemented by objects that are
 *                     interested in monitoring actions for changes
 *
 * GActionObserver is a simple interface allowing objects that wish to
 * be notified of changes to actions to be notified of those changes.
 *
 * It is also possible to monitor changes to action groups using
 * #GObject signals, but there are a number of reasons that this
 * approach could become problematic:
 *
 *  - there are four separate signals that must be manually connected
 *    and disconnected
 *
 *  - when a large number of different observers wish to monitor a
 *    (usually disjoint) set of actions within the same action group,
 *    there is only one way to avoid having all notifications delivered
 *    to all observers: signal detail.  In order to use signal detail,
 *    each action name must be quarked, which is not always practical.
 *
 *  - even if quarking is acceptable, #GObject signal details are
 *    implemented by scanning a linked list, so there is no real
 *    decrease in complexity
 */

void
g_action_observer_default_init (GActionObserverInterface *class)
{
}

/*
 * g_action_observer_action_added:
 * @observer: a #GActionObserver
 * @observable: the source of the event
 * @action_name: the name of the action
 * @enabled: %TRUE if the action is now enabled
 * @parameter_type: the parameter type for action invocations, or %NULL
 *                  if no parameter is required
 * @state: the current state of the action, or %NULL if the action is
 *         stateless
 *
 * This function is called when an action that the observer is
 * registered to receive events for is added.
 *
 * This function should only be called by objects with which the
 * observer has explicitly registered itself to receive events.
 */
void
g_action_observer_action_added (GActionObserver    *observer,
                                GActionObservable  *observable,
                                const gchar        *action_name,
                                const GVariantType *parameter_type,
                                gboolean            enabled,
                                GVariant           *state)
{
  g_return_if_fail (G_IS_ACTION_OBSERVER (observer));

  G_ACTION_OBSERVER_GET_IFACE (observer)
    ->action_added (observer, observable, action_name, parameter_type, enabled, state);
}

/*
 * g_action_observer_action_enabled_changed:
 * @observer: a #GActionObserver
 * @observable: the source of the event
 * @action_name: the name of the action
 * @enabled: %TRUE if the action is now enabled
 *
 * This function is called when an action that the observer is
 * registered to receive events for becomes enabled or disabled.
 *
 * This function should only be called by objects with which the
 * observer has explicitly registered itself to receive events.
 */
void
g_action_observer_action_enabled_changed (GActionObserver   *observer,
                                          GActionObservable *observable,
                                          const gchar       *action_name,
                                          gboolean           enabled)
{
  g_return_if_fail (G_IS_ACTION_OBSERVER (observer));

  G_ACTION_OBSERVER_GET_IFACE (observer)
    ->action_enabled_changed (observer, observable, action_name, enabled);
}

/*
 * g_action_observer_action_state_changed:
 * @observer: a #GActionObserver
 * @observable: the source of the event
 * @action_name: the name of the action
 * @state: the new state of the action
 *
 * This function is called when an action that the observer is
 * registered to receive events for changes to its state.
 *
 * This function should only be called by objects with which the
 * observer has explicitly registered itself to receive events.
 */
void
g_action_observer_action_state_changed (GActionObserver   *observer,
                                        GActionObservable *observable,
                                        const gchar       *action_name,
                                        GVariant          *state)
{
  g_return_if_fail (G_IS_ACTION_OBSERVER (observer));

  G_ACTION_OBSERVER_GET_IFACE (observer)
    ->action_state_changed (observer, observable, action_name, state);
}

/*
 * g_action_observer_action_removed:
 * @observer: a #GActionObserver
 * @observable: the source of the event
 * @action_name: the name of the action
 *
 * This function is called when an action that the observer is
 * registered to receive events for is removed.
 *
 * This function should only be called by objects with which the
 * observer has explicitly registered itself to receive events.
 */
void
g_action_observer_action_removed (GActionObserver   *observer,
                                  GActionObservable *observable,
                                  const gchar       *action_name)
{
  g_return_if_fail (G_IS_ACTION_OBSERVER (observer));

  G_ACTION_OBSERVER_GET_IFACE (observer)
    ->action_removed (observer, observable, action_name);
}