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

   1 /*
   2  * Copyright © 2011 Canonical Limited
   3  *
   4  * This program 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, write to the Free Software
  16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
  17  * USA.
  18  *
  19  * Authors: Ryan Lortie <desrt@desrt.ca>
  20  */
  21
  22 #include "config.h"
  23
  24 #include "gactionobserver.h"
  25
  26 G_DEFINE_INTERFACE (GActionObserver, g_action_observer, G_TYPE_OBJECT)
  27
  28 /**
  29  * SECTION:gactionobserver
  30  * @short_description: an interface implemented by objects that are
  31  *                     interested in monitoring actions for changes
  32  *
  33  * GActionObserver is a simple interface allowing objects that wish to
  34  * be notified of changes to actions to be notified of those changes.
  35  *
  36  * It is also possible to monitor changes to action groups using
  37  * #GObject signals, but there are a number of reasons that this
  38  * approach could become problematic:
  39  *
  40  *  - there are four separate signals that must be manually connected
  41  *    and disconnected
  42  *
  43  *  - when a large number of different observers wish to monitor a
  44  *    (usually disjoint) set of actions within the same action group,
  45  *    there is only one way to avoid having all notifications delivered
  46  *    to all observers: signal detail.  In order to use signal detail,
  47  *    each action name must be quarked, which is not always practical.
  48  *
  49  *  - even if quarking is acceptable, #GObject signal details are
  50  *    implemented by scanning a linked list, so there is no real
  51  *    decrease in complexity
  52  */
  53
  54 void
  55 g_action_observer_default_init (GActionObserverInterface *class)
  56 {
  57 }
  58
  59 /*
  60  * g_action_observer_action_added:
  61  * @observer: a #GActionObserver
  62  * @observable: the source of the event
  63  * @action_name: the name of the action
  64  * @enabled: %TRUE if the action is now enabled
  65  * @parameter_type: the parameter type for action invocations, or %NULL
  66  *                  if no parameter is required
  67  * @state: the current state of the action, or %NULL if the action is
  68  *         stateless
  69  *
  70  * This function is called when an action that the observer is
  71  * registered to receive events for is added.
  72  *
  73  * This function should only be called by objects with which the
  74  * observer has explicitly registered itself to receive events.
  75  */
  76 void
  77 g_action_observer_action_added (GActionObserver    *observer,
  78                                 GActionObservable  *observable,
  79                                 const gchar        *action_name,
  80                                 const GVariantType *parameter_type,
  81                                 gboolean            enabled,
  82                                 GVariant           *state)
  83 {
  84   g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
  85
  86   G_ACTION_OBSERVER_GET_IFACE (observer)
  87     ->action_added (observer, observable, action_name, parameter_type, enabled, state);
  88 }
  89
  90 /*
  91  * g_action_observer_action_enabled_changed:
  92  * @observer: a #GActionObserver
  93  * @observable: the source of the event
  94  * @action_name: the name of the action
  95  * @enabled: %TRUE if the action is now enabled
  96  *
  97  * This function is called when an action that the observer is
  98  * registered to receive events for becomes enabled or disabled.
  99  *
 100  * This function should only be called by objects with which the
 101  * observer has explicitly registered itself to receive events.
 102  */
 103 void
 104 g_action_observer_action_enabled_changed (GActionObserver   *observer,
 105                                           GActionObservable *observable,
 106                                           const gchar       *action_name,
 107                                           gboolean           enabled)
 108 {
 109   g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
 110
 111   G_ACTION_OBSERVER_GET_IFACE (observer)
 112     ->action_enabled_changed (observer, observable, action_name, enabled);
 113 }
 114
 115 /*
 116  * g_action_observer_action_state_changed:
 117  * @observer: a #GActionObserver
 118  * @observable: the source of the event
 119  * @action_name: the name of the action
 120  * @state: the new state of the action
 121  *
 122  * This function is called when an action that the observer is
 123  * registered to receive events for changes its state.
 124  *
 125  * This function should only be called by objects with which the
 126  * observer has explicitly registered itself to receive events.
 127  */
 128 void
 129 g_action_observer_action_state_changed (GActionObserver   *observer,
 130                                         GActionObservable *observable,
 131                                         const gchar       *action_name,
 132                                         GVariant          *state)
 133 {
 134   g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
 135
 136   G_ACTION_OBSERVER_GET_IFACE (observer)
 137     ->action_state_changed (observer, observable, action_name, state);
 138 }
 139
 140 /*
 141  * g_action_observer_action_removed:
 142  * @observer: a #GActionObserver
 143  * @observable: the source of the event
 144  * @action_name: the name of the action
 145  *
 146  * This function is called when an action that the observer is
 147  * registered to receive events for is removed.
 148  *
 149  * This function should only be called by objects with which the
 150  * observer has explicitly registered itself to receive events.
 151  */
 152 void
 153 g_action_observer_action_removed (GActionObserver   *observer,
 154                                   GActionObservable *observable,
 155                                   const gchar       *action_name)
 156 {
 157   g_return_if_fail (G_IS_ACTION_OBSERVER (observer));
 158
 159   G_ACTION_OBSERVER_GET_IFACE (observer)
 160     ->action_removed (observer, observable, action_name);
 161 }