gtkactionobserver.c 7.05 KB
Newer Older
1 2 3
/*
 * Copyright © 2011 Canonical Limited
 *
Javier Jardón's avatar
Javier Jardón committed
4
 * This library is free software: you can redistribute it and/or modify
5 6 7 8 9 10 11 12 13 14
 * 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
Javier Jardón's avatar
Javier Jardón committed
15
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
16 17 18 19 20 21
 *
 * Authors: Ryan Lortie <desrt@desrt.ca>
 */

#include "config.h"

22
#include "gtkactionobserver.h"
23

24
G_DEFINE_INTERFACE (GtkActionObserver, gtk_action_observer, G_TYPE_OBJECT)
25 26

/**
27
 * SECTION:gtkactionobserver
28 29 30
 * @short_description: an interface implemented by objects that are
 *                     interested in monitoring actions for changes
 *
31
 * GtkActionObserver is a simple interface allowing objects that wish to
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
 * 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
53
gtk_action_observer_default_init (GtkActionObserverInterface *class)
54 55 56
{
}

57
/**
58 59
 * gtk_action_observer_action_added:
 * @observer: a #GtkActionObserver
60 61 62 63 64 65 66 67 68 69 70 71 72
 * @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.
73
 */
74
void
75 76 77 78 79 80
gtk_action_observer_action_added (GtkActionObserver   *observer,
                                  GtkActionObservable *observable,
                                  const gchar         *action_name,
                                  const GVariantType  *parameter_type,
                                  gboolean             enabled,
                                  GVariant            *state)
81
{
82
  g_return_if_fail (GTK_IS_ACTION_OBSERVER (observer));
83

84
  GTK_ACTION_OBSERVER_GET_IFACE (observer)
85 86 87
    ->action_added (observer, observable, action_name, parameter_type, enabled, state);
}

88
/**
89 90
 * gtk_action_observer_action_enabled_changed:
 * @observer: a #GtkActionObserver
91 92 93 94 95 96 97 98 99
 * @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.
100
 */
101
void
102 103 104 105
gtk_action_observer_action_enabled_changed (GtkActionObserver   *observer,
                                            GtkActionObservable *observable,
                                            const gchar         *action_name,
                                            gboolean             enabled)
106
{
107
  g_return_if_fail (GTK_IS_ACTION_OBSERVER (observer));
108

109
  GTK_ACTION_OBSERVER_GET_IFACE (observer)
110 111 112
    ->action_enabled_changed (observer, observable, action_name, enabled);
}

113
/**
114 115
 * gtk_action_observer_action_state_changed:
 * @observer: a #GtkActionObserver
116 117 118 119 120
 * @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
121
 * registered to receive events for changes to its state.
122 123 124
 *
 * This function should only be called by objects with which the
 * observer has explicitly registered itself to receive events.
125
 */
126
void
127 128 129 130
gtk_action_observer_action_state_changed (GtkActionObserver   *observer,
                                          GtkActionObservable *observable,
                                          const gchar         *action_name,
                                          GVariant            *state)
131
{
132
  g_return_if_fail (GTK_IS_ACTION_OBSERVER (observer));
133

134
  GTK_ACTION_OBSERVER_GET_IFACE (observer)
135 136 137
    ->action_state_changed (observer, observable, action_name, state);
}

138
/**
139 140
 * gtk_action_observer_action_removed:
 * @observer: a #GtkActionObserver
141 142 143 144 145 146 147 148
 * @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.
149
 */
150
void
151 152 153
gtk_action_observer_action_removed (GtkActionObserver   *observer,
                                    GtkActionObservable *observable,
                                    const gchar         *action_name)
154
{
155
  g_return_if_fail (GTK_IS_ACTION_OBSERVER (observer));
156

157
  GTK_ACTION_OBSERVER_GET_IFACE (observer)
158 159
    ->action_removed (observer, observable, action_name);
}
160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189

/**
 * gtk_action_observer_primary_accel_changed:
 * @observer: a #GtkActionObserver
 * @observable: the source of the event
 * @action_name: the name of the action
 * @action_and_target: detailed action of the changed accel, in "action and target" format
 *
 * This function is called when an action that the observer is
 * registered to receive events for has one of its accelerators changed.
 *
 * Accelerator changes are reported for all targets associated with the
 * action.  The @action_and_target string should be used to check if the
 * reported target is the one that the observer is interested in.
 */
void
gtk_action_observer_primary_accel_changed (GtkActionObserver   *observer,
                                           GtkActionObservable *observable,
                                           const gchar         *action_name,
                                           const gchar         *action_and_target)
{
  GtkActionObserverInterface *iface;

  g_return_if_fail (GTK_IS_ACTION_OBSERVER (observer));

  iface = GTK_ACTION_OBSERVER_GET_IFACE (observer);

  if (iface->primary_accel_changed)
    iface->primary_accel_changed (observer, observable, action_name, action_and_target);
}