Blame gio/gactiongroup.c

Packit ae235b
/*
Packit ae235b
 * Copyright © 2010 Codethink Limited
Packit ae235b
 *
Packit ae235b
 * This library is free software; you can redistribute it and/or
Packit ae235b
 * modify it under the terms of the GNU Lesser General Public
Packit ae235b
 * License as published by the Free Software Foundation; either
Packit ae235b
 * version 2.1 of the License, or (at your option) any later version.
Packit ae235b
 *
Packit ae235b
 * This library is distributed in the hope that it will be useful,
Packit ae235b
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
Packit ae235b
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Packit ae235b
 * Lesser General Public License for more details.
Packit ae235b
 *
Packit ae235b
 * You should have received a copy of the GNU Lesser General
Packit ae235b
 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
Packit ae235b
 *
Packit ae235b
 * Authors: Ryan Lortie <desrt@desrt.ca>
Packit ae235b
 */
Packit ae235b
Packit ae235b
#include "config.h"
Packit ae235b
#include "gactiongroup.h"
Packit ae235b
#include "gaction.h"
Packit ae235b
#include "glibintl.h"
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * SECTION:gactiongroup
Packit ae235b
 * @title: GActionGroup
Packit ae235b
 * @short_description: A group of actions
Packit ae235b
 * @include: gio/gio.h
Packit ae235b
 * @see_also: #GAction
Packit ae235b
 *
Packit ae235b
 * #GActionGroup represents a group of actions. Actions can be used to
Packit ae235b
 * expose functionality in a structured way, either from one part of a
Packit ae235b
 * program to another, or to the outside world. Action groups are often
Packit ae235b
 * used together with a #GMenuModel that provides additional
Packit ae235b
 * representation data for displaying the actions to the user, e.g. in
Packit ae235b
 * a menu.
Packit ae235b
 *
Packit ae235b
 * The main way to interact with the actions in a GActionGroup is to
Packit ae235b
 * activate them with g_action_group_activate_action(). Activating an
Packit ae235b
 * action may require a #GVariant parameter. The required type of the
Packit ae235b
 * parameter can be inquired with g_action_group_get_action_parameter_type().
Packit ae235b
 * Actions may be disabled, see g_action_group_get_action_enabled().
Packit ae235b
 * Activating a disabled action has no effect.
Packit ae235b
 *
Packit ae235b
 * Actions may optionally have a state in the form of a #GVariant. The
Packit ae235b
 * current state of an action can be inquired with
Packit ae235b
 * g_action_group_get_action_state(). Activating a stateful action may
Packit ae235b
 * change its state, but it is also possible to set the state by calling
Packit ae235b
 * g_action_group_change_action_state().
Packit ae235b
 *
Packit ae235b
 * As typical example, consider a text editing application which has an
Packit ae235b
 * option to change the current font to 'bold'. A good way to represent
Packit ae235b
 * this would be a stateful action, with a boolean state. Activating the
Packit ae235b
 * action would toggle the state.
Packit ae235b
 *
Packit ae235b
 * Each action in the group has a unique name (which is a string).  All
Packit ae235b
 * method calls, except g_action_group_list_actions() take the name of
Packit ae235b
 * an action as an argument.
Packit ae235b
 *
Packit ae235b
 * The #GActionGroup API is meant to be the 'public' API to the action
Packit ae235b
 * group.  The calls here are exactly the interaction that 'external
Packit ae235b
 * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
Packit ae235b
 * with actions.  'Internal' APIs (ie: ones meant only to be accessed by
Packit ae235b
 * the action group implementation) are found on subclasses.  This is
Packit ae235b
 * why you will find - for example - g_action_group_get_action_enabled()
Packit ae235b
 * but not an equivalent set() call.
Packit ae235b
 *
Packit ae235b
 * Signals are emitted on the action group in response to state changes
Packit ae235b
 * on individual actions.
Packit ae235b
 *
Packit ae235b
 * Implementations of #GActionGroup should provide implementations for
Packit ae235b
 * the virtual functions g_action_group_list_actions() and
Packit ae235b
 * g_action_group_query_action().  The other virtual functions should
Packit ae235b
 * not be implemented - their "wrappers" are actually implemented with
Packit ae235b
 * calls to g_action_group_query_action().
Packit ae235b
 */
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * GActionGroup:
Packit ae235b
 *
Packit ae235b
 * #GActionGroup is an opaque data structure and can only be accessed
Packit ae235b
 * using the following functions.
Packit ae235b
 **/
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * GActionGroupInterface:
Packit ae235b
 * @has_action: the virtual function pointer for g_action_group_has_action()
Packit ae235b
 * @list_actions: the virtual function pointer for g_action_group_list_actions()
Packit ae235b
 * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type()
Packit ae235b
 * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type()
Packit ae235b
 * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
Packit ae235b
 * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
Packit ae235b
 * @get_action_state: the virtual function pointer for g_action_group_get_action_state()
Packit ae235b
 * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
Packit ae235b
 * @query_action: the virtual function pointer for g_action_group_query_action()
Packit ae235b
 * @activate_action: the virtual function pointer for g_action_group_activate_action()
Packit ae235b
 * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
Packit ae235b
 * @action_added: the class closure for the #GActionGroup::action-added signal
Packit ae235b
 * @action_removed: the class closure for the #GActionGroup::action-removed signal
Packit ae235b
 * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
Packit ae235b
 * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal
Packit ae235b
 *
Packit ae235b
 * The virtual function table for #GActionGroup.
Packit ae235b
 *
Packit ae235b
 * Since: 2.28
Packit ae235b
 **/
Packit ae235b
Packit ae235b
G_DEFINE_INTERFACE (GActionGroup, g_action_group, G_TYPE_OBJECT)
Packit ae235b
Packit ae235b
enum
Packit ae235b
{
Packit ae235b
  SIGNAL_ACTION_ADDED,
Packit ae235b
  SIGNAL_ACTION_REMOVED,
Packit ae235b
  SIGNAL_ACTION_ENABLED_CHANGED,
Packit ae235b
  SIGNAL_ACTION_STATE_CHANGED,
Packit ae235b
  NR_SIGNALS
Packit ae235b
};
Packit ae235b
Packit ae235b
static guint g_action_group_signals[NR_SIGNALS];
Packit ae235b
Packit ae235b
static gboolean
Packit ae235b
g_action_group_real_has_action (GActionGroup *action_group,
Packit ae235b
                                const gchar  *action_name)
Packit ae235b
{
Packit ae235b
  return g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, NULL, NULL);
Packit ae235b
}
Packit ae235b
Packit ae235b
static gboolean
Packit ae235b
g_action_group_real_get_action_enabled (GActionGroup *action_group,
Packit ae235b
                                        const gchar  *action_name)
Packit ae235b
{
Packit ae235b
  gboolean enabled = FALSE;
Packit ae235b
Packit ae235b
  g_action_group_query_action (action_group, action_name, &enabled, NULL, NULL, NULL, NULL);
Packit ae235b
Packit ae235b
  return enabled;
Packit ae235b
}
Packit ae235b
Packit ae235b
static const GVariantType *
Packit ae235b
g_action_group_real_get_action_parameter_type (GActionGroup *action_group,
Packit ae235b
                                               const gchar  *action_name)
Packit ae235b
{
Packit ae235b
  const GVariantType *type = NULL;
Packit ae235b
Packit ae235b
  g_action_group_query_action (action_group, action_name, NULL, &type, NULL, NULL, NULL);
Packit ae235b
Packit ae235b
  return type;
Packit ae235b
}
Packit ae235b
Packit ae235b
static const GVariantType *
Packit ae235b
g_action_group_real_get_action_state_type (GActionGroup *action_group,
Packit ae235b
                                           const gchar  *action_name)
Packit ae235b
{
Packit ae235b
  const GVariantType *type = NULL;
Packit ae235b
Packit ae235b
  g_action_group_query_action (action_group, action_name, NULL, NULL, &type, NULL, NULL);
Packit ae235b
Packit ae235b
  return type;
Packit ae235b
}
Packit ae235b
Packit ae235b
static GVariant *
Packit ae235b
g_action_group_real_get_action_state_hint (GActionGroup *action_group,
Packit ae235b
                                           const gchar  *action_name)
Packit ae235b
{
Packit ae235b
  GVariant *hint = NULL;
Packit ae235b
Packit ae235b
  g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, &hint, NULL);
Packit ae235b
Packit ae235b
  return hint;
Packit ae235b
}
Packit ae235b
Packit ae235b
static GVariant *
Packit ae235b
g_action_group_real_get_action_state (GActionGroup *action_group,
Packit ae235b
                                      const gchar  *action_name)
Packit ae235b
{
Packit ae235b
  GVariant *state = NULL;
Packit ae235b
Packit ae235b
  g_action_group_query_action (action_group, action_name, NULL, NULL, NULL, NULL, &state);
Packit ae235b
Packit ae235b
  return state;
Packit ae235b
}
Packit ae235b
Packit ae235b
static gboolean
Packit ae235b
g_action_group_real_query_action (GActionGroup        *action_group,
Packit ae235b
                                  const gchar         *action_name,
Packit ae235b
                                  gboolean            *enabled,
Packit ae235b
                                  const GVariantType **parameter_type,
Packit ae235b
                                  const GVariantType **state_type,
Packit ae235b
                                  GVariant           **state_hint,
Packit ae235b
                                  GVariant           **state)
Packit ae235b
{
Packit ae235b
  GActionGroupInterface *iface = G_ACTION_GROUP_GET_IFACE (action_group);
Packit ae235b
Packit ae235b
  /* we expect implementations to override this method, but we also
Packit ae235b
   * allow for implementations that existed before this method was
Packit ae235b
   * introduced to override the individual accessors instead.
Packit ae235b
   *
Packit ae235b
   * detect the case that neither has happened and report it.
Packit ae235b
   */
Packit ae235b
  if G_UNLIKELY (iface->has_action == g_action_group_real_has_action ||
Packit ae235b
                 iface->get_action_enabled == g_action_group_real_get_action_enabled ||
Packit ae235b
                 iface->get_action_parameter_type == g_action_group_real_get_action_parameter_type ||
Packit ae235b
                 iface->get_action_state_type == g_action_group_real_get_action_state_type ||
Packit ae235b
                 iface->get_action_state_hint == g_action_group_real_get_action_state_hint ||
Packit ae235b
                 iface->get_action_state == g_action_group_real_get_action_state)
Packit ae235b
    {
Packit ae235b
      g_critical ("Class '%s' implements GActionGroup interface without overriding "
Packit ae235b
                  "query_action() method -- bailing out to avoid infinite recursion.",
Packit ae235b
                  G_OBJECT_TYPE_NAME (action_group));
Packit ae235b
      return FALSE;
Packit ae235b
    }
Packit ae235b
Packit ae235b
  if (!(* iface->has_action) (action_group, action_name))
Packit ae235b
    return FALSE;
Packit ae235b
Packit ae235b
  if (enabled != NULL)
Packit ae235b
    *enabled = (* iface->get_action_enabled) (action_group, action_name);
Packit ae235b
Packit ae235b
  if (parameter_type != NULL)
Packit ae235b
    *parameter_type = (* iface->get_action_parameter_type) (action_group, action_name);
Packit ae235b
Packit ae235b
  if (state_type != NULL)
Packit ae235b
    *state_type = (* iface->get_action_state_type) (action_group, action_name);
Packit ae235b
Packit ae235b
  if (state_hint != NULL)
Packit ae235b
    *state_hint = (* iface->get_action_state_hint) (action_group, action_name);
Packit ae235b
Packit ae235b
  if (state != NULL)
Packit ae235b
    *state = (* iface->get_action_state) (action_group, action_name);
Packit ae235b
Packit ae235b
  return TRUE;
Packit ae235b
}
Packit ae235b
Packit ae235b
static void
Packit ae235b
g_action_group_default_init (GActionGroupInterface *iface)
Packit ae235b
{
Packit ae235b
  iface->has_action = g_action_group_real_has_action;
Packit ae235b
  iface->get_action_enabled = g_action_group_real_get_action_enabled;
Packit ae235b
  iface->get_action_parameter_type = g_action_group_real_get_action_parameter_type;
Packit ae235b
  iface->get_action_state_type = g_action_group_real_get_action_state_type;
Packit ae235b
  iface->get_action_state_hint = g_action_group_real_get_action_state_hint;
Packit ae235b
  iface->get_action_state = g_action_group_real_get_action_state;
Packit ae235b
  iface->query_action = g_action_group_real_query_action;
Packit ae235b
Packit ae235b
  /**
Packit ae235b
   * GActionGroup::action-added:
Packit ae235b
   * @action_group: the #GActionGroup that changed
Packit ae235b
   * @action_name: the name of the action in @action_group
Packit ae235b
   *
Packit ae235b
   * Signals that a new action was just added to the group.
Packit ae235b
   * This signal is emitted after the action has been added
Packit ae235b
   * and is now visible.
Packit ae235b
   *
Packit ae235b
   * Since: 2.28
Packit ae235b
   **/
Packit ae235b
  g_action_group_signals[SIGNAL_ACTION_ADDED] =
Packit ae235b
    g_signal_new (I_("action-added"),
Packit ae235b
                  G_TYPE_ACTION_GROUP,
Packit ae235b
                  G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
Packit ae235b
                  G_STRUCT_OFFSET (GActionGroupInterface, action_added),
Packit ae235b
                  NULL, NULL,
Packit ae235b
                  g_cclosure_marshal_VOID__STRING,
Packit ae235b
                  G_TYPE_NONE, 1,
Packit ae235b
                  G_TYPE_STRING);
Packit ae235b
Packit ae235b
  /**
Packit ae235b
   * GActionGroup::action-removed:
Packit ae235b
   * @action_group: the #GActionGroup that changed
Packit ae235b
   * @action_name: the name of the action in @action_group
Packit ae235b
   *
Packit ae235b
   * Signals that an action is just about to be removed from the group.
Packit ae235b
   * This signal is emitted before the action is removed, so the action
Packit ae235b
   * is still visible and can be queried from the signal handler.
Packit ae235b
   *
Packit ae235b
   * Since: 2.28
Packit ae235b
   **/
Packit ae235b
  g_action_group_signals[SIGNAL_ACTION_REMOVED] =
Packit ae235b
    g_signal_new (I_("action-removed"),
Packit ae235b
                  G_TYPE_ACTION_GROUP,
Packit ae235b
                  G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
Packit ae235b
                  G_STRUCT_OFFSET (GActionGroupInterface, action_removed),
Packit ae235b
                  NULL, NULL,
Packit ae235b
                  g_cclosure_marshal_VOID__STRING,
Packit ae235b
                  G_TYPE_NONE, 1,
Packit ae235b
                  G_TYPE_STRING);
Packit ae235b
Packit ae235b
Packit ae235b
  /**
Packit ae235b
   * GActionGroup::action-enabled-changed:
Packit ae235b
   * @action_group: the #GActionGroup that changed
Packit ae235b
   * @action_name: the name of the action in @action_group
Packit ae235b
   * @enabled: whether the action is enabled or not
Packit ae235b
   *
Packit ae235b
   * Signals that the enabled status of the named action has changed.
Packit ae235b
   *
Packit ae235b
   * Since: 2.28
Packit ae235b
   **/
Packit ae235b
  g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED] =
Packit ae235b
    g_signal_new (I_("action-enabled-changed"),
Packit ae235b
                  G_TYPE_ACTION_GROUP,
Packit ae235b
                  G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
Packit ae235b
                  G_STRUCT_OFFSET (GActionGroupInterface,
Packit ae235b
                                   action_enabled_changed),
Packit ae235b
                  NULL, NULL,
Packit ae235b
                  NULL,
Packit ae235b
                  G_TYPE_NONE, 2,
Packit ae235b
                  G_TYPE_STRING,
Packit ae235b
                  G_TYPE_BOOLEAN);
Packit ae235b
Packit ae235b
  /**
Packit ae235b
   * GActionGroup::action-state-changed:
Packit ae235b
   * @action_group: the #GActionGroup that changed
Packit ae235b
   * @action_name: the name of the action in @action_group
Packit ae235b
   * @value: the new value of the state
Packit ae235b
   *
Packit ae235b
   * Signals that the state of the named action has changed.
Packit ae235b
   *
Packit ae235b
   * Since: 2.28
Packit ae235b
   **/
Packit ae235b
  g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED] =
Packit ae235b
    g_signal_new (I_("action-state-changed"),
Packit ae235b
                  G_TYPE_ACTION_GROUP,
Packit ae235b
                  G_SIGNAL_RUN_LAST |
Packit ae235b
                  G_SIGNAL_DETAILED |
Packit ae235b
                  G_SIGNAL_MUST_COLLECT,
Packit ae235b
                  G_STRUCT_OFFSET (GActionGroupInterface,
Packit ae235b
                                   action_state_changed),
Packit ae235b
                  NULL, NULL,
Packit ae235b
                  NULL,
Packit ae235b
                  G_TYPE_NONE, 2,
Packit ae235b
                  G_TYPE_STRING,
Packit ae235b
                  G_TYPE_VARIANT);
Packit ae235b
}
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * g_action_group_list_actions:
Packit ae235b
 * @action_group: a #GActionGroup
Packit ae235b
 *
Packit ae235b
 * Lists the actions contained within @action_group.
Packit ae235b
 *
Packit ae235b
 * The caller is responsible for freeing the list with g_strfreev() when
Packit ae235b
 * it is no longer required.
Packit ae235b
 *
Packit ae235b
 * Returns: (transfer full): a %NULL-terminated array of the names of the
Packit ae235b
 * actions in the group
Packit ae235b
 *
Packit ae235b
 * Since: 2.28
Packit ae235b
 **/
Packit ae235b
gchar **
Packit ae235b
g_action_group_list_actions (GActionGroup *action_group)
Packit ae235b
{
Packit ae235b
  g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
Packit ae235b
Packit ae235b
  return G_ACTION_GROUP_GET_IFACE (action_group)
Packit ae235b
    ->list_actions (action_group);
Packit ae235b
}
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * g_action_group_has_action:
Packit ae235b
 * @action_group: a #GActionGroup
Packit ae235b
 * @action_name: the name of the action to check for
Packit ae235b
 *
Packit ae235b
 * Checks if the named action exists within @action_group.
Packit ae235b
 *
Packit ae235b
 * Returns: whether the named action exists
Packit ae235b
 *
Packit ae235b
 * Since: 2.28
Packit ae235b
 **/
Packit ae235b
gboolean
Packit ae235b
g_action_group_has_action (GActionGroup *action_group,
Packit ae235b
                           const gchar  *action_name)
Packit ae235b
{
Packit ae235b
  g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
Packit ae235b
Packit ae235b
  return G_ACTION_GROUP_GET_IFACE (action_group)
Packit ae235b
    ->has_action (action_group, action_name);
Packit ae235b
}
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * g_action_group_get_action_parameter_type:
Packit ae235b
 * @action_group: a #GActionGroup
Packit ae235b
 * @action_name: the name of the action to query
Packit ae235b
 *
Packit ae235b
 * Queries the type of the parameter that must be given when activating
Packit ae235b
 * the named action within @action_group.
Packit ae235b
 *
Packit ae235b
 * When activating the action using g_action_group_activate_action(),
Packit ae235b
 * the #GVariant given to that function must be of the type returned
Packit ae235b
 * by this function.
Packit ae235b
 *
Packit ae235b
 * In the case that this function returns %NULL, you must not give any
Packit ae235b
 * #GVariant, but %NULL instead.
Packit ae235b
 *
Packit ae235b
 * The parameter type of a particular action will never change but it is
Packit ae235b
 * possible for an action to be removed and for a new action to be added
Packit ae235b
 * with the same name but a different parameter type.
Packit ae235b
 *
Packit ae235b
 * Returns: (nullable): the parameter type
Packit ae235b
 *
Packit ae235b
 * Since: 2.28
Packit ae235b
 **/
Packit ae235b
const GVariantType *
Packit ae235b
g_action_group_get_action_parameter_type (GActionGroup *action_group,
Packit ae235b
                                          const gchar  *action_name)
Packit ae235b
{
Packit ae235b
  g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
Packit ae235b
Packit ae235b
  return G_ACTION_GROUP_GET_IFACE (action_group)
Packit ae235b
    ->get_action_parameter_type (action_group, action_name);
Packit ae235b
}
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * g_action_group_get_action_state_type:
Packit ae235b
 * @action_group: a #GActionGroup
Packit ae235b
 * @action_name: the name of the action to query
Packit ae235b
 *
Packit ae235b
 * Queries the type of the state of the named action within
Packit ae235b
 * @action_group.
Packit ae235b
 *
Packit ae235b
 * If the action is stateful then this function returns the
Packit ae235b
 * #GVariantType of the state.  All calls to
Packit ae235b
 * g_action_group_change_action_state() must give a #GVariant of this
Packit ae235b
 * type and g_action_group_get_action_state() will return a #GVariant
Packit ae235b
 * of the same type.
Packit ae235b
 *
Packit ae235b
 * If the action is not stateful then this function will return %NULL.
Packit ae235b
 * In that case, g_action_group_get_action_state() will return %NULL
Packit ae235b
 * and you must not call g_action_group_change_action_state().
Packit ae235b
 *
Packit ae235b
 * The state type of a particular action will never change but it is
Packit ae235b
 * possible for an action to be removed and for a new action to be added
Packit ae235b
 * with the same name but a different state type.
Packit ae235b
 *
Packit ae235b
 * Returns: (nullable): the state type, if the action is stateful
Packit ae235b
 *
Packit ae235b
 * Since: 2.28
Packit ae235b
 **/
Packit ae235b
const GVariantType *
Packit ae235b
g_action_group_get_action_state_type (GActionGroup *action_group,
Packit ae235b
                                      const gchar  *action_name)
Packit ae235b
{
Packit ae235b
  g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
Packit ae235b
Packit ae235b
  return G_ACTION_GROUP_GET_IFACE (action_group)
Packit ae235b
    ->get_action_state_type (action_group, action_name);
Packit ae235b
}
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * g_action_group_get_action_state_hint:
Packit ae235b
 * @action_group: a #GActionGroup
Packit ae235b
 * @action_name: the name of the action to query
Packit ae235b
 *
Packit ae235b
 * Requests a hint about the valid range of values for the state of the
Packit ae235b
 * named action within @action_group.
Packit ae235b
 *
Packit ae235b
 * If %NULL is returned it either means that the action is not stateful
Packit ae235b
 * or that there is no hint about the valid range of values for the
Packit ae235b
 * state of the action.
Packit ae235b
 *
Packit ae235b
 * If a #GVariant array is returned then each item in the array is a
Packit ae235b
 * possible value for the state.  If a #GVariant pair (ie: two-tuple) is
Packit ae235b
 * returned then the tuple specifies the inclusive lower and upper bound
Packit ae235b
 * of valid values for the state.
Packit ae235b
 *
Packit ae235b
 * In any case, the information is merely a hint.  It may be possible to
Packit ae235b
 * have a state value outside of the hinted range and setting a value
Packit ae235b
 * within the range may fail.
Packit ae235b
 *
Packit ae235b
 * The return value (if non-%NULL) should be freed with
Packit ae235b
 * g_variant_unref() when it is no longer required.
Packit ae235b
 *
Packit ae235b
 * Returns: (nullable) (transfer full): the state range hint
Packit ae235b
 *
Packit ae235b
 * Since: 2.28
Packit ae235b
 **/
Packit ae235b
GVariant *
Packit ae235b
g_action_group_get_action_state_hint (GActionGroup *action_group,
Packit ae235b
                                      const gchar  *action_name)
Packit ae235b
{
Packit ae235b
  g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
Packit ae235b
Packit ae235b
  return G_ACTION_GROUP_GET_IFACE (action_group)
Packit ae235b
    ->get_action_state_hint (action_group, action_name);
Packit ae235b
}
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * g_action_group_get_action_enabled:
Packit ae235b
 * @action_group: a #GActionGroup
Packit ae235b
 * @action_name: the name of the action to query
Packit ae235b
 *
Packit ae235b
 * Checks if the named action within @action_group is currently enabled.
Packit ae235b
 *
Packit ae235b
 * An action must be enabled in order to be activated or in order to
Packit ae235b
 * have its state changed from outside callers.
Packit ae235b
 *
Packit ae235b
 * Returns: whether or not the action is currently enabled
Packit ae235b
 *
Packit ae235b
 * Since: 2.28
Packit ae235b
 **/
Packit ae235b
gboolean
Packit ae235b
g_action_group_get_action_enabled (GActionGroup *action_group,
Packit ae235b
                                   const gchar  *action_name)
Packit ae235b
{
Packit ae235b
  g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
Packit ae235b
Packit ae235b
  return G_ACTION_GROUP_GET_IFACE (action_group)
Packit ae235b
    ->get_action_enabled (action_group, action_name);
Packit ae235b
}
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * g_action_group_get_action_state:
Packit ae235b
 * @action_group: a #GActionGroup
Packit ae235b
 * @action_name: the name of the action to query
Packit ae235b
 *
Packit ae235b
 * Queries the current state of the named action within @action_group.
Packit ae235b
 *
Packit ae235b
 * If the action is not stateful then %NULL will be returned.  If the
Packit ae235b
 * action is stateful then the type of the return value is the type
Packit ae235b
 * given by g_action_group_get_action_state_type().
Packit ae235b
 *
Packit ae235b
 * The return value (if non-%NULL) should be freed with
Packit ae235b
 * g_variant_unref() when it is no longer required.
Packit ae235b
 *
Packit ae235b
 * Returns: (nullable): the current state of the action
Packit ae235b
 *
Packit ae235b
 * Since: 2.28
Packit ae235b
 **/
Packit ae235b
GVariant *
Packit ae235b
g_action_group_get_action_state (GActionGroup *action_group,
Packit ae235b
                                 const gchar  *action_name)
Packit ae235b
{
Packit ae235b
  g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
Packit ae235b
Packit ae235b
  return G_ACTION_GROUP_GET_IFACE (action_group)
Packit ae235b
    ->get_action_state (action_group, action_name);
Packit ae235b
}
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * g_action_group_change_action_state:
Packit ae235b
 * @action_group: a #GActionGroup
Packit ae235b
 * @action_name: the name of the action to request the change on
Packit ae235b
 * @value: the new state
Packit ae235b
 *
Packit ae235b
 * Request for the state of the named action within @action_group to be
Packit ae235b
 * changed to @value.
Packit ae235b
 *
Packit ae235b
 * The action must be stateful and @value must be of the correct type.
Packit ae235b
 * See g_action_group_get_action_state_type().
Packit ae235b
 *
Packit ae235b
 * This call merely requests a change.  The action may refuse to change
Packit ae235b
 * its state or may change its state to something other than @value.
Packit ae235b
 * See g_action_group_get_action_state_hint().
Packit ae235b
 *
Packit ae235b
 * If the @value GVariant is floating, it is consumed.
Packit ae235b
 *
Packit ae235b
 * Since: 2.28
Packit ae235b
 **/
Packit ae235b
void
Packit ae235b
g_action_group_change_action_state (GActionGroup *action_group,
Packit ae235b
                                    const gchar  *action_name,
Packit ae235b
                                    GVariant     *value)
Packit ae235b
{
Packit ae235b
  g_return_if_fail (G_IS_ACTION_GROUP (action_group));
Packit ae235b
  g_return_if_fail (action_name != NULL);
Packit ae235b
  g_return_if_fail (value != NULL);
Packit ae235b
Packit ae235b
  G_ACTION_GROUP_GET_IFACE (action_group)
Packit ae235b
    ->change_action_state (action_group, action_name, value);
Packit ae235b
}
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * g_action_group_activate_action:
Packit ae235b
 * @action_group: a #GActionGroup
Packit ae235b
 * @action_name: the name of the action to activate
Packit ae235b
 * @parameter: (nullable): parameters to the activation
Packit ae235b
 *
Packit ae235b
 * Activate the named action within @action_group.
Packit ae235b
 *
Packit ae235b
 * If the action is expecting a parameter, then the correct type of
Packit ae235b
 * parameter must be given as @parameter.  If the action is expecting no
Packit ae235b
 * parameters then @parameter must be %NULL.  See
Packit ae235b
 * g_action_group_get_action_parameter_type().
Packit ae235b
 *
Packit ae235b
 * Since: 2.28
Packit ae235b
 **/
Packit ae235b
void
Packit ae235b
g_action_group_activate_action (GActionGroup *action_group,
Packit ae235b
                                const gchar  *action_name,
Packit ae235b
                                GVariant     *parameter)
Packit ae235b
{
Packit ae235b
  g_return_if_fail (G_IS_ACTION_GROUP (action_group));
Packit ae235b
  g_return_if_fail (action_name != NULL);
Packit ae235b
Packit ae235b
  G_ACTION_GROUP_GET_IFACE (action_group)
Packit ae235b
    ->activate_action (action_group, action_name, parameter);
Packit ae235b
}
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * g_action_group_action_added:
Packit ae235b
 * @action_group: a #GActionGroup
Packit ae235b
 * @action_name: the name of an action in the group
Packit ae235b
 *
Packit ae235b
 * Emits the #GActionGroup::action-added signal on @action_group.
Packit ae235b
 *
Packit ae235b
 * This function should only be called by #GActionGroup implementations.
Packit ae235b
 *
Packit ae235b
 * Since: 2.28
Packit ae235b
 **/
Packit ae235b
void
Packit ae235b
g_action_group_action_added (GActionGroup *action_group,
Packit ae235b
                             const gchar  *action_name)
Packit ae235b
{
Packit ae235b
  g_return_if_fail (G_IS_ACTION_GROUP (action_group));
Packit ae235b
  g_return_if_fail (action_name != NULL);
Packit ae235b
Packit ae235b
  g_signal_emit (action_group,
Packit ae235b
                 g_action_group_signals[SIGNAL_ACTION_ADDED],
Packit ae235b
                 g_quark_try_string (action_name),
Packit ae235b
                 action_name);
Packit ae235b
}
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * g_action_group_action_removed:
Packit ae235b
 * @action_group: a #GActionGroup
Packit ae235b
 * @action_name: the name of an action in the group
Packit ae235b
 *
Packit ae235b
 * Emits the #GActionGroup::action-removed signal on @action_group.
Packit ae235b
 *
Packit ae235b
 * This function should only be called by #GActionGroup implementations.
Packit ae235b
 *
Packit ae235b
 * Since: 2.28
Packit ae235b
 **/
Packit ae235b
void
Packit ae235b
g_action_group_action_removed (GActionGroup *action_group,
Packit ae235b
                               const gchar  *action_name)
Packit ae235b
{
Packit ae235b
  g_return_if_fail (G_IS_ACTION_GROUP (action_group));
Packit ae235b
  g_return_if_fail (action_name != NULL);
Packit ae235b
Packit ae235b
  g_signal_emit (action_group,
Packit ae235b
                 g_action_group_signals[SIGNAL_ACTION_REMOVED],
Packit ae235b
                 g_quark_try_string (action_name),
Packit ae235b
                 action_name);
Packit ae235b
}
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * g_action_group_action_enabled_changed:
Packit ae235b
 * @action_group: a #GActionGroup
Packit ae235b
 * @action_name: the name of an action in the group
Packit ae235b
 * @enabled: whether or not the action is now enabled
Packit ae235b
 *
Packit ae235b
 * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
Packit ae235b
 *
Packit ae235b
 * This function should only be called by #GActionGroup implementations.
Packit ae235b
 *
Packit ae235b
 * Since: 2.28
Packit ae235b
 **/
Packit ae235b
void
Packit ae235b
g_action_group_action_enabled_changed (GActionGroup *action_group,
Packit ae235b
                                       const gchar  *action_name,
Packit ae235b
                                       gboolean      enabled)
Packit ae235b
{
Packit ae235b
  g_return_if_fail (G_IS_ACTION_GROUP (action_group));
Packit ae235b
  g_return_if_fail (action_name != NULL);
Packit ae235b
Packit ae235b
  enabled = !!enabled;
Packit ae235b
Packit ae235b
  g_signal_emit (action_group,
Packit ae235b
                 g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED],
Packit ae235b
                 g_quark_try_string (action_name),
Packit ae235b
                 action_name,
Packit ae235b
                 enabled);
Packit ae235b
}
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * g_action_group_action_state_changed:
Packit ae235b
 * @action_group: a #GActionGroup
Packit ae235b
 * @action_name: the name of an action in the group
Packit ae235b
 * @state: the new state of the named action
Packit ae235b
 *
Packit ae235b
 * Emits the #GActionGroup::action-state-changed signal on @action_group.
Packit ae235b
 *
Packit ae235b
 * This function should only be called by #GActionGroup implementations.
Packit ae235b
 *
Packit ae235b
 * Since: 2.28
Packit ae235b
 **/
Packit ae235b
void
Packit ae235b
g_action_group_action_state_changed (GActionGroup *action_group,
Packit ae235b
                                     const gchar  *action_name,
Packit ae235b
                                     GVariant     *state)
Packit ae235b
{
Packit ae235b
  g_return_if_fail (G_IS_ACTION_GROUP (action_group));
Packit ae235b
  g_return_if_fail (action_name != NULL);
Packit ae235b
Packit ae235b
  g_signal_emit (action_group,
Packit ae235b
                 g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED],
Packit ae235b
                 g_quark_try_string (action_name),
Packit ae235b
                 action_name,
Packit ae235b
                 state);
Packit ae235b
}
Packit ae235b
Packit ae235b
/**
Packit ae235b
 * g_action_group_query_action:
Packit ae235b
 * @action_group: a #GActionGroup
Packit ae235b
 * @action_name: the name of an action in the group
Packit ae235b
 * @enabled: (out): if the action is presently enabled
Packit ae235b
 * @parameter_type: (out) (optional): the parameter type, or %NULL if none needed
Packit ae235b
 * @state_type: (out) (optional): the state type, or %NULL if stateless
Packit ae235b
 * @state_hint: (out) (optional): the state hint, or %NULL if none
Packit ae235b
 * @state: (out) (optional): the current state, or %NULL if stateless
Packit ae235b
 *
Packit ae235b
 * Queries all aspects of the named action within an @action_group.
Packit ae235b
 *
Packit ae235b
 * This function acquires the information available from
Packit ae235b
 * g_action_group_has_action(), g_action_group_get_action_enabled(),
Packit ae235b
 * g_action_group_get_action_parameter_type(),
Packit ae235b
 * g_action_group_get_action_state_type(),
Packit ae235b
 * g_action_group_get_action_state_hint() and
Packit ae235b
 * g_action_group_get_action_state() with a single function call.
Packit ae235b
 *
Packit ae235b
 * This provides two main benefits.
Packit ae235b
 *
Packit ae235b
 * The first is the improvement in efficiency that comes with not having
Packit ae235b
 * to perform repeated lookups of the action in order to discover
Packit ae235b
 * different things about it.  The second is that implementing
Packit ae235b
 * #GActionGroup can now be done by only overriding this one virtual
Packit ae235b
 * function.
Packit ae235b
 *
Packit ae235b
 * The interface provides a default implementation of this function that
Packit ae235b
 * calls the individual functions, as required, to fetch the
Packit ae235b
 * information.  The interface also provides default implementations of
Packit ae235b
 * those functions that call this function.  All implementations,
Packit ae235b
 * therefore, must override either this function or all of the others.
Packit ae235b
 *
Packit ae235b
 * If the action exists, %TRUE is returned and any of the requested
Packit ae235b
 * fields (as indicated by having a non-%NULL reference passed in) are
Packit ae235b
 * filled.  If the action doesn't exist, %FALSE is returned and the
Packit ae235b
 * fields may or may not have been modified.
Packit ae235b
 *
Packit ae235b
 * Returns: %TRUE if the action exists, else %FALSE
Packit ae235b
 *
Packit ae235b
 * Since: 2.32
Packit ae235b
 **/
Packit ae235b
gboolean
Packit ae235b
g_action_group_query_action (GActionGroup        *action_group,
Packit ae235b
                             const gchar         *action_name,
Packit ae235b
                             gboolean            *enabled,
Packit ae235b
                             const GVariantType **parameter_type,
Packit ae235b
                             const GVariantType **state_type,
Packit ae235b
                             GVariant           **state_hint,
Packit ae235b
                             GVariant           **state)
Packit ae235b
{
Packit ae235b
  return G_ACTION_GROUP_GET_IFACE (action_group)
Packit ae235b
    ->query_action (action_group, action_name, enabled, parameter_type, state_type, state_hint, state);
Packit ae235b
}