/*
* Copyright © 2010 Codethink Limited
*
* SPDX-License-Identifier: LGPL-2.1-or-later
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, 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 License along with this library; if not, see .
*
* Authors: Ryan Lortie
*/
#include "config.h"
#include "gsimpleaction.h"
#include "gactionmap.h"
#include "gaction.h"
/**
* GActionMap:
*
* `GActionMap` is an interface for action containers.
*
* The `GActionMap` interface is implemented by [iface@Gio.ActionGroup]
* implementations that operate by containing a number of named
* [iface@Gio.Action] instances, such as [class@Gio.SimpleActionGroup].
*
* One useful application of this interface is to map the
* names of actions from various action groups to unique,
* prefixed names (e.g. by prepending "app." or "win.").
* This is the motivation for the ‘Map’ part of the interface
* name.
*
* Since: 2.32
*/
/**
* GActionMapInterface:
* @lookup_action: the virtual function pointer for
* [method@Gio.ActionMap.lookup_action]
* @add_action: the virtual function pointer for
* [method@Gio.ActionMap.add_action]
* @remove_action: the virtual function pointer for
* [method@Gio.ActionMap.remove_action]
*
* The virtual function table for [iface@Gio.ActionMap].
*
* Since: 2.32
**/
G_DEFINE_INTERFACE (GActionMap, g_action_map, G_TYPE_OBJECT)
static void
g_action_map_default_init (GActionMapInterface *iface)
{
}
/**
* g_action_map_lookup_action:
* @action_map: an action map
* @action_name: the name of an action
*
* Looks up the action with the name @action_name in @action_map.
*
* If no such action exists, returns `NULL`.
*
* Returns: (nullable) (transfer none): a [iface@Gio.Action]
*
* Since: 2.32
*/
GAction *
g_action_map_lookup_action (GActionMap *action_map,
const gchar *action_name)
{
return G_ACTION_MAP_GET_IFACE (action_map)
->lookup_action (action_map, action_name);
}
/**
* g_action_map_add_action:
* @action_map: an action map
* @action: a [iface@Gio.Action]
*
* Adds an action to the @action_map.
*
* If the action map already contains an action with the same name
* as @action then the old action is dropped from the action map.
*
* The action map takes its own reference on @action.
*
* Since: 2.32
*/
void
g_action_map_add_action (GActionMap *action_map,
GAction *action)
{
G_ACTION_MAP_GET_IFACE (action_map)->add_action (action_map, action);
}
/**
* g_action_map_remove_action:
* @action_map: an action map
* @action_name: the name of the action
*
* Removes the named action from the action map.
*
* If no action of this name is in the map then nothing happens.
*
* Since: 2.32
*/
void
g_action_map_remove_action (GActionMap *action_map,
const gchar *action_name)
{
G_ACTION_MAP_GET_IFACE (action_map)->remove_action (action_map, action_name);
}
/**
* GActionEntry:
* @name: the name of the action
* @activate: the callback to connect to the "activate" signal of the action.
* Since GLib 2.40, this can be `NULL` for stateful actions, in which case
* the default handler is used. For boolean-stated actions with no
* parameter, this is a toggle. For other state types (and parameter type
* equal to the state type) this will be a function that just calls
* @change_state (which you should provide).
* @parameter_type: the type of the parameter that must be passed to the
* activate function for this action, given as a single GVariant type string
* (or `NULL` for no parameter)
* @state: the initial state for this action, given in
* [GVariant text format](gvariant-text-format.html). The state is parsed
* with no extra type information, so type tags must be added to the string
* if they are necessary. Stateless actions should give `NULL` here.
* @change_state: the callback to connect to the "change-state" signal of the
* action. All stateful actions should provide a handler here; stateless
* actions should not.
*
* This struct defines a single action. It is for use with
* [method@Gio.ActionMap.add_action_entries].
*
* The order of the items in the structure are intended to reflect
* frequency of use. It is permissible to use an incomplete initialiser
* in order to leave some of the later values as `NULL`. All values
* after @name are optional. Additional optional fields may be added in
* the future.
*
* See [method@Gio.ActionMap.add_action_entries] for an example.
**/
/**
* g_action_map_add_action_entries:
* @action_map: an action map
* @entries: (array length=n_entries) (element-type GActionEntry): a pointer to
* the first item in an array of [struct@Gio.ActionEntry] structs
* @n_entries: the length of @entries, or -1 if @entries is `NULL`-terminated
* @user_data: the user data for signal connections
*
* A convenience function for creating multiple [class@Gio.SimpleAction]
* instances and adding them to a [iface@Gio.ActionMap].
*
* Each action is constructed as per one [struct@Gio.ActionEntry].
*
* ```c
* static void
* activate_quit (GSimpleAction *simple,
* GVariant *parameter,
* gpointer user_data)
* {
* exit (0);
* }
*
* static void
* activate_print_string (GSimpleAction *simple,
* GVariant *parameter,
* gpointer user_data)
* {
* g_print ("%s\n", g_variant_get_string (parameter, NULL));
* }
*
* static GActionGroup *
* create_action_group (void)
* {
* const GActionEntry entries[] = {
* { "quit", activate_quit },
* { "print-string", activate_print_string, "s" }
* };
* GSimpleActionGroup *group;
*
* group = g_simple_action_group_new ();
* g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
*
* return G_ACTION_GROUP (group);
* }
* ```
*
* Since: 2.32
*/
void
g_action_map_add_action_entries (GActionMap *action_map,
const GActionEntry *entries,
gint n_entries,
gpointer user_data)
{
g_return_if_fail (G_IS_ACTION_MAP (action_map));
g_return_if_fail (entries != NULL || n_entries == 0);
for (int i = 0; n_entries < 0 ? entries[i].name != NULL : i < n_entries; i++)
{
const GActionEntry *entry = &entries[i];
const GVariantType *parameter_type;
GSimpleAction *action;
if (entry->parameter_type)
{
if (!g_variant_type_string_is_valid (entry->parameter_type))
{
g_critical ("g_action_map_add_entries: the type "
"string '%s' given as the parameter type for "
"action '%s' is not a valid GVariant type "
"string. This action will not be added.",
entry->parameter_type, entry->name);
return;
}
parameter_type = G_VARIANT_TYPE (entry->parameter_type);
}
else
parameter_type = NULL;
if (entry->state)
{
GError *error = NULL;
GVariant *state;
state = g_variant_parse (NULL, entry->state, NULL, NULL, &error);
if (state == NULL)
{
g_critical ("g_action_map_add_entries: GVariant could "
"not parse the state value given for action '%s' "
"('%s'): %s. This action will not be added.",
entry->name, entry->state, error->message);
g_error_free (error);
continue;
}
action = g_simple_action_new_stateful (entry->name,
parameter_type,
state);
g_variant_unref (state);
}
else
{
action = g_simple_action_new (entry->name,
parameter_type);
}
if (entry->activate != NULL)
g_signal_connect (action, "activate",
G_CALLBACK (entry->activate), user_data);
if (entry->change_state != NULL)
g_signal_connect (action, "change-state",
G_CALLBACK (entry->change_state), user_data);
g_action_map_add_action (action_map, G_ACTION (action));
g_object_unref (action);
}
}
/**
* g_action_map_remove_action_entries:
* @action_map: The [iface@Gio.ActionMap]
* @entries: (array length=n_entries) (element-type GActionEntry): a pointer to
* the first item in an array of [struct@Gio.ActionEntry] structs
* @n_entries: the length of @entries, or -1 if @entries is `NULL`-terminated
*
* Remove actions from a [iface@Gio.ActionMap]. This is meant as the reverse of
* [method@Gio.ActionMap.add_action_entries].
*
*
* ```c
* static const GActionEntry entries[] = {
* { "quit", activate_quit },
* { "print-string", activate_print_string, "s" }
* };
*
* void
* add_actions (GActionMap *map)
* {
* g_action_map_add_action_entries (map, entries, G_N_ELEMENTS (entries), NULL);
* }
*
* void
* remove_actions (GActionMap *map)
* {
* g_action_map_remove_action_entries (map, entries, G_N_ELEMENTS (entries));
* }
* ```
*
* Since: 2.78
*/
void
g_action_map_remove_action_entries (GActionMap *action_map,
const GActionEntry entries[],
gint n_entries)
{
g_return_if_fail (G_IS_ACTION_MAP (action_map));
g_return_if_fail (entries != NULL || n_entries == 0);
for (int i = 0; n_entries < 0 ? entries[i].name != NULL : i < n_entries; i++)
g_action_map_remove_action (action_map, entries[i].name);
}