Pileus Git - ~andy/gtk/blob - gtk/gactionobserver.c

   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 "gactionobserver.h"
  23
  24 G_DEFINE_INTERFACE (GActionObserver, g_action_observer, G_TYPE_OBJECT)
  25
  26 /**
  27  * SECTION:gactionobserver
  28  * @short_description: an interface implemented by objects that are
  29  *                     interested in monitoring actions for changes
  30  *
  31  * GActionObserver is a simple interface allowing objects that wish to
  32  * be notified of changes to actions to be notified of those changes.
  33  *
  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:
  37  *
  38  *  - there are four separate signals that must be manually connected
  39  *    and disconnected
  40  *
  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.
  46  *
  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
  50  */
  51
  52 void
  53 g_action_observer_default_init (GActionObserverInterface *class)
  54 {
  55 }
  56
  57 /*
  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
  66  *         stateless
  67  *
  68  * This function is called when an action that the observer is
  69  * registered to receive events for is added.
  70  *
  71  * This function should only be called by objects with which the
  72  * observer has explicitly registered itself to receive events.
  73  */
  74 void
  75 g_action_observer_action_added (GActionObserver    *observer,
  76                                 GActionObservable  *observable,
  77                                 const gchar        *action_name,
  78                                 const GVariantType *parameter_type,
  79                                 gboolean            enabled,
  80                                 GVariant           *state)
  81 {
  82   g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
  83
  84   G_ACTION_OBSERVER_GET_IFACE (observer)
  85     ->action_added (observer, observable, action_name, parameter_type, enabled, state);
  86 }
  87
  88 /*
  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
  94  *
  95  * This function is called when an action that the observer is
  96  * registered to receive events for becomes enabled or disabled.
  97  *
  98  * This function should only be called by objects with which the
  99  * observer has explicitly registered itself to receive events.
 100  */
 101 void
 102 g_action_observer_action_enabled_changed (GActionObserver   *observer,
 103                                           GActionObservable *observable,
 104                                           const gchar       *action_name,
 105                                           gboolean           enabled)
 106 {
 107   g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
 108
 109   G_ACTION_OBSERVER_GET_IFACE (observer)
 110     ->action_enabled_changed (observer, observable, action_name, enabled);
 111 }
 112
 113 /*
 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
 119  *
 120  * This function is called when an action that the observer is
 121  * registered to receive events for changes to its state.
 122  *
 123  * This function should only be called by objects with which the
 124  * observer has explicitly registered itself to receive events.
 125  */
 126 void
 127 g_action_observer_action_state_changed (GActionObserver   *observer,
 128                                         GActionObservable *observable,
 129                                         const gchar       *action_name,
 130                                         GVariant          *state)
 131 {
 132   g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
 133
 134   G_ACTION_OBSERVER_GET_IFACE (observer)
 135     ->action_state_changed (observer, observable, action_name, state);
 136 }
 137
 138 /*
 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
 143  *
 144  * This function is called when an action that the observer is
 145  * registered to receive events for is removed.
 146  *
 147  * This function should only be called by objects with which the
 148  * observer has explicitly registered itself to receive events.
 149  */
 150 void
 151 g_action_observer_action_removed (GActionObserver   *observer,
 152                                   GActionObservable *observable,
 153                                   const gchar       *action_name)
 154 {
 155   g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
 156
 157   G_ACTION_OBSERVER_GET_IFACE (observer)
 158     ->action_removed (observer, observable, action_name);
 159 }