* 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 "gaction.h"
+#include "glibintl.h"
-G_DEFINE_TYPE (GAction, g_action, G_TYPE_OBJECT)
+#include <string.h>
+
+G_DEFINE_INTERFACE (GAction, g_action, G_TYPE_OBJECT)
/**
* SECTION:gaction
* @title: GAction
- * @short_description: an action
+ * @short_description: An action interface
+ * @include: gio/gio.h
*
* #GAction represents a single named action.
*
* parameter type (which is given at construction time).
*
* An action may optionally have a state, in which case the state may be
- * set with g_action_set_state(). This call takes a #GVariant. The
+ * set with g_action_change_state(). This call takes a #GVariant. The
* correct type for the state is determined by a static state type
* (which is given at construction time).
*
* The state may have a hint associated with it, specifying its valid
* range.
*
- * #GAction is intended to be used both as a simple action class and as
- * a base class for more complicated action types. The base class
- * itself supports activation and state. Not supported are state hints
- * and filtering requests to set the state based on the requested value.
- * You should subclass if you require either of these abilities.
+ * #GAction is merely the interface to the concept of an action, as
+ * described above. Various implementations of actions exist, including
+ * #GSimpleAction.
*
- * In all cases, the base class is responsible for storing the name of
- * the action, the parameter type, the enabled state, the optional state
- * type and the state and emitting the appropriate signals when these
- * change. The base class is also responsbile for filtering calls to
- * g_action_activate() and g_action_set_state() for type safety and for
- * the state being enabled.
+ * In all cases, the implementing class is responsible for storing the
+ * name of the action, the parameter type, the enabled state, the
+ * optional state type and the state and emitting the appropriate
+ * signals when these change. The implementor responsible for filtering
+ * calls to g_action_activate() and g_action_change_state() for type
+ * safety and for the state being enabled.
*
* Probably the only useful thing to do with a #GAction is to put it
* inside of a #GSimpleActionGroup.
**/
-struct _GActionPrivate
-{
- gchar *name;
- GVariantType *parameter_type;
- gboolean enabled;
-
- GVariantType *state_type;
- GVariant *state;
-};
-
-enum
-{
- PROP_NONE,
- PROP_NAME,
- PROP_PARAMETER_TYPE,
- PROP_ENABLED,
- PROP_STATE_TYPE,
- PROP_STATE
-};
-
-enum
-{
- SIGNAL_ACTIVATE,
- NR_SIGNALS
-};
-
-static guint g_action_signals[NR_SIGNALS];
-
-static void
-g_action_real_set_state (GAction *action,
- GVariant *value)
-{
- if (action->priv->state == value)
- return;
-
- if (!action->priv->state || !g_variant_equal (action->priv->state, value))
- {
- if (action->priv->state)
- g_variant_unref (action->priv->state);
-
- action->priv->state = g_variant_ref (value);
-
- g_object_notify (G_OBJECT (action), "state");
- }
-}
-
-static GVariant *
-g_action_real_get_state_hint (GAction *action)
-{
- return NULL;
-}
-
-static void
-g_action_set_property (GObject *object, guint prop_id,
- const GValue *value, GParamSpec *pspec)
-{
- GAction *action = G_ACTION (object);
-
- switch (prop_id)
- {
- case PROP_NAME:
- g_assert (action->priv->name == NULL);
- action->priv->name = g_value_dup_string (value);
- break;
-
- case PROP_PARAMETER_TYPE:
- g_assert (action->priv->parameter_type == NULL);
- action->priv->parameter_type = g_value_dup_boxed (value);
- break;
-
- case PROP_ENABLED:
- g_action_set_enabled (action, g_value_get_boolean (value));
- break;
-
- case PROP_STATE_TYPE:
- g_assert (action->priv->state_type == NULL);
- action->priv->state_type = g_value_dup_boxed (value);
- break;
-
- case PROP_STATE:
- g_action_set_state (action, g_value_get_variant (value));
- break;
-
- default:
- g_assert_not_reached ();
- }
-}
-
-static void
-g_action_get_property (GObject *object, guint prop_id,
- GValue *value, GParamSpec *pspec)
-{
- GAction *action = G_ACTION (object);
-
- switch (prop_id)
- {
- case PROP_NAME:
- g_value_set_string (value, g_action_get_name (action));
- break;
-
- case PROP_PARAMETER_TYPE:
- g_value_set_boxed (value, g_action_get_parameter_type (action));
- break;
-
- case PROP_ENABLED:
- g_value_set_boolean (value, g_action_get_enabled (action));
- break;
-
- case PROP_STATE_TYPE:
- g_value_set_boxed (value, g_action_get_state_type (action));
- break;
-
- case PROP_STATE:
- g_value_set_variant (value, g_action_get_state (action));
- break;
-
- default:
- g_assert_not_reached ();
- }
-}
-
-static void
-g_action_finalize (GObject *object)
-{
- GAction *action = G_ACTION (object);
-
- g_free (action->priv->name);
- if (action->priv->parameter_type)
- g_variant_type_free (action->priv->parameter_type);
- if (action->priv->state_type)
- g_variant_type_free (action->priv->state_type);
- if (action->priv->state)
- g_variant_unref (action->priv->state);
-
- G_OBJECT_CLASS (g_action_parent_class)
- ->finalize (object);
-}
-
-void
-g_action_init (GAction *action)
-{
- action->priv = G_TYPE_INSTANCE_GET_PRIVATE (action,
- G_TYPE_ACTION,
- GActionPrivate);
-}
+/**
+ * GActionInterface:
+ * @get_name: the virtual function pointer for g_action_get_name()
+ * @get_parameter_type: the virtual function pointer for g_action_get_parameter_type()
+ * @get_state_type: the virtual function pointer for g_action_get_state_type()
+ * @get_state_hint: the virtual function pointer for g_action_get_state_hint()
+ * @get_enabled: the virtual function pointer for g_action_get_enabled()
+ * @get_state: the virtual function pointer for g_action_get_state()
+ * @change_state: the virtual function pointer for g_action_change_state()
+ * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an
+ * 'activate' signal but that implementations of it may have one.
+ *
+ * The virtual function table for #GAction.
+ *
+ * Since: 2.28
+ */
void
-g_action_class_init (GActionClass *class)
+g_action_default_init (GActionInterface *iface)
{
- GObjectClass *object_class = G_OBJECT_CLASS (class);
-
- class->get_state_hint = g_action_real_get_state_hint;
- class->set_state = g_action_real_set_state;
-
- object_class->get_property = g_action_get_property;
- object_class->set_property = g_action_set_property;
- object_class->finalize = g_action_finalize;
-
- /**
- * GAction::activate:
- * @action: the #GAction
- * @parameter: (allow-none): the parameter to the activation
- *
- * Indicates that the action was just activated.
- *
- * @parameter will always be of the expected type. In the event that
- * an incorrect type was given, no signal will be emitted.
- **/
- g_action_signals[SIGNAL_ACTIVATE] =
- g_signal_new ("activate", G_TYPE_ACTION, G_SIGNAL_RUN_LAST,
- G_STRUCT_OFFSET (GActionClass, activate),
- NULL, NULL, g_cclosure_marshal_VOID__VARIANT,
- G_TYPE_NONE, 1, G_TYPE_VARIANT);
-
/**
* GAction:name:
*
* The name of the action. This is mostly meaningful for identifying
- * the action once it has been added to a #GActionGroup.
+ * the action once it has been added to a #GActionGroup. It is immutable.
+ *
+ * Since: 2.28
**/
- g_object_class_install_property (object_class, PROP_NAME,
- g_param_spec_string ("name", "action name",
- "the name used to invoke the action",
- NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
- G_PARAM_STATIC_STRINGS));
+ g_object_interface_install_property (iface,
+ g_param_spec_string ("name",
+ P_("Action Name"),
+ P_("The name used to invoke the action"),
+ NULL,
+ G_PARAM_READABLE |
+ G_PARAM_STATIC_STRINGS));
/**
* GAction:parameter-type:
*
* The type of the parameter that must be given when activating the
- * action.
+ * action. This is immutable, and may be %NULL if no parameter is needed when
+ * activating the action.
+ *
+ * Since: 2.28
**/
- g_object_class_install_property (object_class, PROP_PARAMETER_TYPE,
- g_param_spec_boxed ("parameter-type", "parameter type",
- "the type of GVariant passed to activate()",
- G_TYPE_VARIANT_TYPE, G_PARAM_READWRITE |
- G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
+ g_object_interface_install_property (iface,
+ g_param_spec_boxed ("parameter-type",
+ P_("Parameter Type"),
+ P_("The type of GVariant passed to activate()"),
+ G_TYPE_VARIANT_TYPE,
+ G_PARAM_READABLE |
+ G_PARAM_STATIC_STRINGS));
/**
* GAction:enabled:
* If @action is currently enabled.
*
* If the action is disabled then calls to g_action_activate() and
- * g_action_set_state() have no effect.
+ * g_action_change_state() have no effect.
+ *
+ * Since: 2.28
**/
- g_object_class_install_property (object_class, PROP_ENABLED,
- g_param_spec_boolean ("enabled", "enabled",
- "if the action can be activated", TRUE,
- G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+ g_object_interface_install_property (iface,
+ g_param_spec_boolean ("enabled",
+ P_("Enabled"),
+ P_("If the action can be activated"),
+ TRUE,
+ G_PARAM_READABLE |
+ G_PARAM_STATIC_STRINGS));
/**
* GAction:state-type:
*
* The #GVariantType of the state that the action has, or %NULL if the
- * action is stateless.
+ * action is stateless. This is immutable.
+ *
+ * Since: 2.28
**/
- g_object_class_install_property (object_class, PROP_STATE_TYPE,
- g_param_spec_boxed ("state-type", "state type",
- "the type of the state kept by the action",
- G_TYPE_VARIANT_TYPE, G_PARAM_READWRITE |
- G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
+ g_object_interface_install_property (iface,
+ g_param_spec_boxed ("state-type",
+ P_("State Type"),
+ P_("The type of the state kept by the action"),
+ G_TYPE_VARIANT_TYPE,
+ G_PARAM_READABLE |
+ G_PARAM_STATIC_STRINGS));
/**
* GAction:state:
*
* The state of the action, or %NULL if the action is stateless.
+ *
+ * Since: 2.28
**/
- g_object_class_install_property (object_class, PROP_STATE,
- g_param_spec_variant ("state", "state", "the state the action is in",
- G_VARIANT_TYPE_ANY, NULL,
- G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
-
- g_type_class_add_private (class, sizeof (GActionPrivate));
+ g_object_interface_install_property (iface,
+ g_param_spec_variant ("state",
+ P_("State"),
+ P_("The state the action is in"),
+ G_VARIANT_TYPE_ANY,
+ NULL,
+ G_PARAM_READABLE |
+ G_PARAM_STATIC_STRINGS));
}
/**
- * g_action_set_state:
+ * g_action_change_state:
* @action: a #GAction
* @value: the new state
*
* its state or may change its state to something other than @value.
* See g_action_get_state_hint().
*
- * Since: 2.26
+ * If the @value GVariant is floating, it is consumed.
+ *
+ * Since: 2.30
**/
void
-g_action_set_state (GAction *action,
- GVariant *value)
+g_action_change_state (GAction *action,
+ GVariant *value)
{
+ const GVariantType *state_type;
+
g_return_if_fail (G_IS_ACTION (action));
- g_return_if_fail ((action->priv->state_type == NULL && value == NULL) ||
- g_variant_is_of_type (value, action->priv->state_type));
+ g_return_if_fail (value != NULL);
+ state_type = g_action_get_state_type (action);
+ g_return_if_fail (state_type != NULL);
+ g_return_if_fail (g_variant_is_of_type (value, state_type));
g_variant_ref_sink (value);
- if (action->priv->enabled)
- G_ACTION_GET_CLASS (action)
- ->set_state (action, value);
+ G_ACTION_GET_IFACE (action)
+ ->change_state (action, value);
g_variant_unref (value);
}
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
- * Returns: (allow-none): the current state of the action
+ * Returns: (transfer full): the current state of the action
*
- * Since: 2.26
+ * Since: 2.28
**/
GVariant *
g_action_get_state (GAction *action)
{
g_return_val_if_fail (G_IS_ACTION (action), NULL);
- return action->priv->state;
+ return G_ACTION_GET_IFACE (action)
+ ->get_state (action);
}
/**
*
* Returns: the name of the action
*
- * Since: 2.26
+ * Since: 2.28
**/
const gchar *
g_action_get_name (GAction *action)
{
g_return_val_if_fail (G_IS_ACTION (action), NULL);
- return action->priv->name;
+ return G_ACTION_GET_IFACE (action)
+ ->get_name (action);
}
/**
*
* Returns: (allow-none): the parameter type
*
- * Since: 2.26
+ * Since: 2.28
**/
const GVariantType *
g_action_get_parameter_type (GAction *action)
{
g_return_val_if_fail (G_IS_ACTION (action), NULL);
- return action->priv->parameter_type;
+ return G_ACTION_GET_IFACE (action)
+ ->get_parameter_type (action);
}
/**
*
* Queries the type of the state of @action.
*
- * If the action is stateful (ie: was created with
- * g_action_new_stateful()) then this function returns the #GVariantType
- * of the state. This is the type of the initial value given as the
- * state. All calls to g_action_set_state() must give a #GVariant of
- * this type and g_action_get_state() will return a #GVariant of the
- * same type.
+ * If the action is stateful (e.g. created with
+ * g_simple_action_new_stateful()) then this function returns the
+ * #GVariantType of the state. This is the type of the initial value
+ * given as the state. All calls to g_action_change_state() must give a
+ * #GVariant of this type and g_action_get_state() will return a
+ * #GVariant of the same type.
*
- * If the action is not stateful (ie: created with g_action_new()) then
- * this function will return %NULL. In that case, g_action_get_state()
- * will return %NULL and you must not call g_action_set_state().
+ * If the action is not stateful (e.g. created with g_simple_action_new())
+ * then this function will return %NULL. In that case, g_action_get_state()
+ * will return %NULL and you must not call g_action_change_state().
*
* Returns: (allow-none): the state type, if the action is stateful
*
- * Since: 2.26
+ * Since: 2.28
**/
const GVariantType *
g_action_get_state_type (GAction *action)
{
g_return_val_if_fail (G_IS_ACTION (action), NULL);
- return action->priv->state_type;
+ return G_ACTION_GET_IFACE (action)
+ ->get_state_type (action);
}
/**
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
- * Returns: (allow-none): the state range hint
+ * Returns: (nullable) (transfer full): the state range hint
*
- * Since: 2.26
+ * Since: 2.28
**/
GVariant *
g_action_get_state_hint (GAction *action)
{
g_return_val_if_fail (G_IS_ACTION (action), NULL);
- return G_ACTION_GET_CLASS (action)
+ return G_ACTION_GET_IFACE (action)
->get_state_hint (action);
}
*
* Returns: whether the action is enabled
*
- * Since: 2.26
+ * Since: 2.28
**/
gboolean
g_action_get_enabled (GAction *action)
{
g_return_val_if_fail (G_IS_ACTION (action), FALSE);
- return action->priv->enabled;
-}
-
-/**
- * g_action_set_enabled:
- * @action: a #GAction
- * @enabled: whether the action is enabled
- *
- * Sets the action as enabled or not.
- *
- * An action must be enabled in order to be activated or in order to
- * have its state changed from outside callers.
- *
- * Since: 2.26
- **/
-void
-g_action_set_enabled (GAction *action,
- gboolean enabled)
-{
- g_return_if_fail (G_IS_ACTION (action));
-
- enabled = !!enabled;
-
- if (action->priv->enabled != enabled)
- {
- action->priv->enabled = enabled;
- g_object_notify (G_OBJECT (action), "enabled");
- }
+ return G_ACTION_GET_IFACE (action)
+ ->get_enabled (action);
}
/**
* g_action_activate:
* @action: a #GAction
- * @parameter: the parameter to the activation
+ * @parameter: (allow-none): the parameter to the activation
*
* Activates the action.
*
* the parameter type given at construction time). If the parameter
* type was %NULL then @parameter must also be %NULL.
*
- * Since: 2.26
+ * If the @parameter GVariant is floating, it is consumed.
+ *
+ * Since: 2.28
**/
void
g_action_activate (GAction *action,
{
g_return_if_fail (G_IS_ACTION (action));
- g_return_if_fail (action->priv->parameter_type == NULL ?
- parameter == NULL :
- (parameter != NULL &&
- g_variant_is_of_type (parameter,
- action->priv->parameter_type)));
-
- if (parameter)
+ if (parameter != NULL)
g_variant_ref_sink (parameter);
- if (action->priv->enabled)
- g_signal_emit (action, g_action_signals[SIGNAL_ACTIVATE], 0, parameter);
+ G_ACTION_GET_IFACE (action)
+ ->activate (action, parameter);
- if (parameter)
+ if (parameter != NULL)
g_variant_unref (parameter);
}
/**
- * g_action_new:
- * @name: the name of the action
- * @parameter_type: the type of parameter to the activate function
+ * g_action_name_is_valid:
+ * @action_name: an potential action name
*
- * Creates a new action.
+ * Checks if @action_name is valid.
*
- * The created action is stateless. See g_action_new_stateful().
+ * @action_name is valid if it consists only of alphanumeric characters,
+ * plus '-' and '.'. The empty string is not a valid action name.
*
- * Returns: a new #GAction
+ * It is an error to call this function with a non-utf8 @action_name.
+ * @action_name must not be %NULL.
*
- * Since: 2.26
+ * Returns: %TRUE if @action_name is valid
+ *
+ * Since: 2.38
**/
-GAction *
-g_action_new (const gchar *name,
- const GVariantType *parameter_type)
+gboolean
+g_action_name_is_valid (const gchar *action_name)
{
- return g_object_new (G_TYPE_ACTION,
- "name", name,
- "parameter-type", parameter_type,
- NULL);
+ gchar c;
+ gint i;
+
+ g_return_val_if_fail (action_name != NULL, FALSE);
+
+ for (i = 0; (c = action_name[i]); i++)
+ if (!g_ascii_isalnum (c) && c != '.' && c != '-')
+ return FALSE;
+
+ return i > 0;
}
/**
- * g_action_new_stateful:
- * @name: the name of the action
- * @parameter_type: the type of the parameter to the activate function
- * @state: the initial state of the action
+ * g_action_parse_detailed_name:
+ * @detailed_name: a detailed action name
+ * @action_name: (out): the action name
+ * @target_value: (out): the target value, or %NULL for no target
+ * @error: a pointer to a %NULL #GError, or %NULL
+ *
+ * Parses a detailed action name into its separate name and target
+ * components.
+ *
+ * Detailed action names can have three formats.
+ *
+ * The first format is used to represent an action name with no target
+ * value and consists of just an action name containing no whitespace
+ * nor the characters ':', '(' or ')'. For example: "app.action".
+ *
+ * The second format is used to represent an action with a target value
+ * that is a non-empty string consisting only of alphanumerics, plus '-'
+ * and '.'. In that case, the action name and target value are
+ * separated by a double colon ("::"). For example:
+ * "app.action::target".
+ *
+ * The third format is used to represent an action with any type of
+ * target value, including strings. The target value follows the action
+ * name, surrounded in parens. For example: "app.action(42)". The
+ * target value is parsed using g_variant_parse(). If a tuple-typed
+ * value is desired, it must be specified in the same way, resulting in
+ * two sets of parens, for example: "app.action((1,2,3))". A string
+ * target can be specified this way as well: "app.action('target')".
+ * For strings, this third format must be used if * target value is
+ * empty or contains characters other than alphanumerics, '-' and '.'.
+ *
+ * Returns: %TRUE if successful, else %FALSE with @error set
+ *
+ * Since: 2.38
+ **/
+gboolean
+g_action_parse_detailed_name (const gchar *detailed_name,
+ gchar **action_name,
+ GVariant **target_value,
+ GError **error)
+{
+ const gchar *target;
+ gsize target_len;
+ gsize base_len;
+
+ /* For historical (compatibility) reasons, this function accepts some
+ * cases of invalid action names as long as they don't interfere with
+ * the separation of the action from the target value.
+ *
+ * We decide which format we have based on which we see first between
+ * '::' '(' and '\0'.
+ */
+
+ if (*detailed_name == '\0' || *detailed_name == ' ')
+ goto bad_fmt;
+
+ base_len = strcspn (detailed_name, ": ()");
+ target = detailed_name + base_len;
+ target_len = strlen (target);
+
+ switch (target[0])
+ {
+ case ' ':
+ case ')':
+ goto bad_fmt;
+
+ case ':':
+ if (target[1] != ':')
+ goto bad_fmt;
+
+ *target_value = g_variant_ref_sink (g_variant_new_string (target + 2));
+ break;
+
+ case '(':
+ {
+ if (target[target_len - 1] != ')')
+ goto bad_fmt;
+
+ *target_value = g_variant_parse (NULL, target + 1, target + target_len - 1, NULL, error);
+ if (*target_value == NULL)
+ goto bad_fmt;
+ }
+ break;
+
+ case '\0':
+ *target_value = NULL;
+ break;
+ }
+
+ *action_name = g_strndup (detailed_name, base_len);
+
+ return TRUE;
+
+bad_fmt:
+ if (error)
+ {
+ if (*error == NULL)
+ g_set_error (error, G_VARIANT_PARSE_ERROR, G_VARIANT_PARSE_ERROR_FAILED,
+ "Detailed action name '%s' has invalid format", detailed_name);
+ else
+ g_prefix_error (error, "Detailed action name '%s' has invalid format: ", detailed_name);
+ }
+
+ return FALSE;
+}
+
+/**
+ * g_action_print_detailed_name:
+ * @action_name: a valid action name
+ * @target_value: (allow-none): a #GVariant target value, or %NULL
+ *
+ * Formats a detailed action name from @action_name and @target_value.
*
- * Creates a new stateful action.
+ * It is an error to call this function with an invalid action name.
*
- * @state is the initial state of the action. All future state values
- * must have the same #GVariantType as the initial state.
+ * This function is the opposite of
+ * g_action_parse_detailed_action_name(). It will produce a string that
+ * can be parsed back to the @action_name and @target_value by that
+ * function.
*
- * Returns: a new #GAction
+ * See that function for the types of strings that will be printed by
+ * this function.
*
- * Since: 2.26
+ * Returns: a detailed format string
+ *
+ * Since: 2.38
**/
-GAction *
-g_action_new_stateful (const gchar *name,
- const GVariantType *parameter_type,
- GVariant *state)
+gchar *
+g_action_print_detailed_name (const gchar *action_name,
+ GVariant *target_value)
{
- return g_object_new (G_TYPE_ACTION,
- "name", name,
- "parameter-type", parameter_type,
- "state", state,
- NULL);
+ g_return_val_if_fail (g_action_name_is_valid (action_name), NULL);
+
+ if (target_value == NULL)
+ return g_strdup (action_name);
+
+ if (g_variant_is_of_type (target_value, G_VARIANT_TYPE_STRING))
+ {
+ const gchar *str = g_variant_get_string (target_value, NULL);
+
+ if (g_action_name_is_valid (str))
+ return g_strconcat (action_name, "::", str, NULL);
+ }
+
+ {
+ GString *result = g_string_new (action_name);
+ g_string_append_c (result, '(');
+ g_variant_print_string (target_value, result, TRUE);
+ g_string_append_c (result, ')');
+
+ return g_string_free (result, FALSE);
+ }
}
projects / platform / upstream / glib.git / blobdiff