gio/gactionmap.c

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