gio/gactionmap.c

   1 /*
   2  * Copyright © 2010 Codethink 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 published
   6  * by the Free Software Foundation; either version 2 of the licence or (at
   7  * your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but 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
  15  * Public 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 "gsimpleaction.h"
  23 #include "gactionmap.h"
  24 #include "gaction.h"
  25
  26 /**
  27  * SECTION:gactionmap
  28  * @title: GActionMap
  29  * @include: gio/gio.h
  30  * @short_description: Interface for action containers
  31  *
  32  * The GActionMap interface is implemented by #GActionGroup
  33  * implementations that operate by containing a number of
  34  * named #GAction instances, such as #GSimpleActionGroup.
  35  *
  36  * One useful application of this interface is to map the
  37  * names of actions from various action groups to unique,
  38  * prefixed names (e.g. by prepending "app." or "win.").
  39  * This is the motivation for the 'Map' part of the interface
  40  * name.
  41  *
  42  * Since: 2.32
  43  **/
  44
  45 /**
  46  * GActionMapInterface:
  47  * @lookup_action: the virtual function pointer for g_action_map_lookup_action()
  48  * @add_action: the virtual function pointer for g_action_map_add_action()
  49  * @remove_action: the virtual function pointer for g_action_map_remove_action()
  50  *
  51  * The virtual function table for #GActionMap.
  52  *
  53  * Since: 2.32
  54  **/
  55
  56 G_DEFINE_INTERFACE (GActionMap, g_action_map, G_TYPE_OBJECT)
  57
  58 static void
  59 g_action_map_default_init (GActionMapInterface *iface)
  60 {
  61 }
  62
  63 /**
  64  * g_action_map_lookup_action:
  65  * @action_map: a #GActionMap
  66  * @action_name: the name of an action
  67  *
  68  * Looks up the action with the name @action_name in @action_map.
  69  *
  70  * If no such action exists, returns %NULL.
  71  *
  72  * Returns: (transfer none): a #GAction, or %NULL
  73  *
  74  * Since: 2.32
  75  */
  76 GAction *
  77 g_action_map_lookup_action (GActionMap  *action_map,
  78                             const gchar *action_name)
  79 {
  80   return G_ACTION_MAP_GET_IFACE (action_map)
  81     ->lookup_action (action_map, action_name);
  82 }
  83
  84 /**
  85  * g_action_map_add_action:
  86  * @action_map: a #GActionMap
  87  * @action: a #GAction
  88  *
  89  * Adds an action to the @action_map.
  90  *
  91  * If the action map already contains an action with the same name
  92  * as @action then the old action is dropped from the action map.
  93  *
  94  * The action map takes its own reference on @action.
  95  *
  96  * Since: 2.32
  97  */
  98 void
  99 g_action_map_add_action (GActionMap *action_map,
 100                          GAction    *action)
 101 {
 102   G_ACTION_MAP_GET_IFACE (action_map)->add_action (action_map, action);
 103 }
 104
 105 /**
 106  * g_action_map_remove_action:
 107  * @action_map: a #GActionMap
 108  * @action_name: the name of the action
 109  *
 110  * Removes the named action from the action map.
 111  *
 112  * If no action of this name is in the map then nothing happens.
 113  *
 114  * Since: 2.32
 115  */
 116 void
 117 g_action_map_remove_action (GActionMap  *action_map,
 118                             const gchar *action_name)
 119 {
 120   G_ACTION_MAP_GET_IFACE (action_map)->remove_action (action_map, action_name);
 121 }
 122
 123 /**
 124  * GActionEntry:
 125  * @name: the name of the action
 126  * @activate: the callback to connect to the "activate" signal of the
 127  *            action.  Since GLib 2.40, this can be %NULL for stateful
 128  *            actions, in which case the default handler is used.  For
 129  *            boolean-stated actions with no parameter, this is a
 130  *            toggle.  For other state types (and parameter type equal
 131  *            to the state type) this will be a function that
 132  *            just calls @change_state (which you should provide).
 133  * @parameter_type: the type of the parameter that must be passed to the
 134  *                  activate function for this action, given as a single
 135  *                  GVariant type string (or %NULL for no parameter)
 136  * @state: the initial state for this action, given in
 137  *         [GVariant text format][gvariant-text].  The state is parsed
 138  *         with no extra type information, so type tags must be added to
 139  *         the string if they are necessary.  Stateless actions should
 140  *         give %NULL here.
 141  * @change_state: the callback to connect to the "change-state" signal
 142  *                of the action.  All stateful actions should provide a
 143  *                handler here; stateless actions should not.
 144  *
 145  * This struct defines a single action.  It is for use with
 146  * g_action_map_add_action_entries().
 147  *
 148  * The order of the items in the structure are intended to reflect
 149  * frequency of use.  It is permissible to use an incomplete initialiser
 150  * in order to leave some of the later values as %NULL.  All values
 151  * after @name are optional.  Additional optional fields may be added in
 152  * the future.
 153  *
 154  * See g_action_map_add_action_entries() for an example.
 155  **/
 156
 157 /**
 158  * g_action_map_add_action_entries:
 159  * @action_map: a #GActionMap
 160  * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to
 161  *           the first item in an array of #GActionEntry structs
 162  * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated
 163  * @user_data: the user data for signal connections
 164  *
 165  * A convenience function for creating multiple #GSimpleAction instances
 166  * and adding them to a #GActionMap.
 167  *
 168  * Each action is constructed as per one #GActionEntry.
 169  *
 170  * |[<!-- language="C" -->
 171  * static void
 172  * activate_quit (GSimpleAction *simple,
 173  *                GVariant      *parameter,
 174  *                gpointer       user_data)
 175  * {
 176  *   exit (0);
 177  * }
 178  *
 179  * static void
 180  * activate_print_string (GSimpleAction *simple,
 181  *                        GVariant      *parameter,
 182  *                        gpointer       user_data)
 183  * {
 184  *   g_print ("%s\n", g_variant_get_string (parameter, NULL));
 185  * }
 186  *
 187  * static GActionGroup *
 188  * create_action_group (void)
 189  * {
 190  *   const GActionEntry entries[] = {
 191  *     { "quit",         activate_quit              },
 192  *     { "print-string", activate_print_string, "s" }
 193  *   };
 194  *   GSimpleActionGroup *group;
 195  *
 196  *   group = g_simple_action_group_new ();
 197  *   g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
 198  *
 199  *   return G_ACTION_GROUP (group);
 200  * }
 201  * ]|
 202  *
 203  * Since: 2.32
 204  */
 205 void
 206 g_action_map_add_action_entries (GActionMap         *action_map,
 207                                  const GActionEntry *entries,
 208                                  gint                n_entries,
 209                                  gpointer            user_data)
 210 {
 211   gint i;
 212
 213   g_return_if_fail (G_IS_ACTION_MAP (action_map));
 214   g_return_if_fail (entries != NULL || n_entries == 0);
 215
 216   for (i = 0; n_entries == -1 ? entries[i].name != NULL : i < n_entries; i++)
 217     {
 218       const GActionEntry *entry = &entries[i];
 219       const GVariantType *parameter_type;
 220       GSimpleAction *action;
 221
 222       if (entry->parameter_type)
 223         {
 224           if (!g_variant_type_string_is_valid (entry->parameter_type))
 225             {
 226               g_critical ("g_action_map_add_entries: the type "
 227                           "string '%s' given as the parameter type for "
 228                           "action '%s' is not a valid GVariant type "
 229                           "string.  This action will not be added.",
 230                           entry->parameter_type, entry->name);
 231               return;
 232             }
 233
 234           parameter_type = G_VARIANT_TYPE (entry->parameter_type);
 235         }
 236       else
 237         parameter_type = NULL;
 238
 239       if (entry->state)
 240         {
 241           GError *error = NULL;
 242           GVariant *state;
 243
 244           state = g_variant_parse (NULL, entry->state, NULL, NULL, &error);
 245           if (state == NULL)
 246             {
 247               g_critical ("g_action_map_add_entries: GVariant could "
 248                           "not parse the state value given for action '%s' "
 249                           "('%s'): %s.  This action will not be added.",
 250                           entry->name, entry->state, error->message);
 251               g_error_free (error);
 252               continue;
 253             }
 254
 255           action = g_simple_action_new_stateful (entry->name,
 256                                                  parameter_type,
 257                                                  state);
 258
 259           g_variant_unref (state);
 260         }
 261       else
 262         {
 263           action = g_simple_action_new (entry->name,
 264                                         parameter_type);
 265         }
 266
 267       if (entry->activate != NULL)
 268         g_signal_connect (action, "activate",
 269                           G_CALLBACK (entry->activate), user_data);
 270
 271       if (entry->change_state != NULL)
 272         g_signal_connect (action, "change-state",
 273                           G_CALLBACK (entry->change_state), user_data);
 274
 275       g_action_map_add_action (action_map, G_ACTION (action));
 276       g_object_unref (action);
 277     }
 278 }