* 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, write to the
- * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
*
* Authors: Ryan Lortie <desrt@desrt.ca>
*/
#include "config.h"
#include "gsimpleaction.h"
-#include "gactiongroup.h"
#include "gactionmap.h"
#include "gaction.h"
-G_DEFINE_INTERFACE (GActionMap, g_action_map, G_TYPE_ACTION_GROUP)
+/**
+ * SECTION:gactionmap
+ * @title: GActionMap
+ * @include: gio/gio.h
+ * @short_description: Interface for action containers
+ *
+ * The GActionMap interface is implemented by #GActionGroup
+ * implementations that operate by containing a number of
+ * named #GAction instances, such as #GSimpleActionGroup.
+ *
+ * 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 g_action_map_lookup_action()
+ * @add_action: the virtual function pointer for g_action_map_add_action()
+ * @remove_action: the virtual function pointer for g_action_map_remove_action()
+ *
+ * The virtual function table for #GActionMap.
+ *
+ * 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: a #GActionMap
+ * @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: (transfer none): a #GAction, or %NULL
+ *
+ * Since: 2.32
+ */
GAction *
g_action_map_lookup_action (GActionMap *action_map,
const gchar *action_name)
->lookup_action (action_map, action_name);
}
+/**
+ * g_action_map_add_action:
+ * @action_map: a #GActionMap
+ * @action: a #GAction
+ *
+ * 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_add_action (GActionMap *action_map,
+ GAction *action)
{
- return G_ACTION_MAP_GET_IFACE (action_map)
- ->add_action (action_map, action);
+ G_ACTION_MAP_GET_IFACE (action_map)->add_action (action_map, action);
}
+/**
+ * g_action_map_remove_action:
+ * @action_map: a #GActionMap
+ * @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)
{
- return G_ACTION_MAP_GET_IFACE (action_map)
- ->remove_action (action_map, 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
+ * 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. The state is parsed with no extra type information,
- * so type tags must be added to the string if they are
- * necessary.
+ * @state: the initial state for this action, given in
+ * [GVariant text format][gvariant-text]. 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
+ * 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
* g_action_map_add_action_entries().
/**
* g_action_map_add_action_entries:
- * @simple: a #GSimpleActionGroup
- * @entries: a pointer to the first item in an array of #GActionEntry
- * structs
- * @n_entries: the length of @entries, or -1
+ * @action_map: a #GActionMap
+ * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to
+ * the first item in an array of #GActionEntry 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 #GSimpleAction instances
*
* Each action is constructed as per one #GActionEntry.
*
- * <example>
- * <title>Using g_action_map_add_action_entries()</title>
- * <programlisting>
+ * |[<!-- language="C" -->
* static void
* activate_quit (GSimpleAction *simple,
* GVariant *parameter,
*
* return G_ACTION_GROUP (group);
* }
- * </programlisting>
- * </example>
+ * ]|
*
- * Since: 2.30
- **/
+ * Since: 2.32
+ */
void
g_action_map_add_action_entries (GActionMap *action_map,
const GActionEntry *entries,
{
if (!g_variant_type_string_is_valid (entry->parameter_type))
{
- g_critical ("g_simple_action_group_add_entries: the 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.",
state = g_variant_parse (NULL, entry->state, NULL, NULL, &error);
if (state == NULL)
{
- g_critical ("g_simple_action_group_add_entries: GVariant could "
+ 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);
projects / platform / upstream / glib.git / blobdiff