mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-24 14:36:13 +01:00
Ported the remaining documentation comments in gio/gaction.c to GI-Docgen
This commit is contained in:
Sudhanshu Tiwari
Philip Withnall
parent
ad903074a4
commit
57d6b945f1
@ -39,7 +39,7 @@ G_DEFINE_INTERFACE (GAction, g_action, G_TYPE_OBJECT)
|
||||
* parameter type (which is given at construction time).
|
||||
*
|
||||
* An action may optionally have a state, in which case the state may be
|
||||
* set with [method@Gio.Action.change_state]. This call takes a #GVariant. The
|
||||
* set with [method@Gio.Action.change_state]. This call takes a [type@GLib.Variant]. The
|
||||
* correct type for the state is determined by a static state type
|
||||
* (which is given at construction time).
|
||||
*
|
||||
@ -143,7 +143,7 @@ g_action_default_init (GActionInterface *iface)
|
||||
/**
|
||||
* GAction:state:
|
||||
*
|
||||
* The state of the action, or %NULL if the action is stateless.
|
||||
* The state of the action, or `NULL` if the action is stateless.
|
||||
*
|
||||
* Since: 2.28
|
||||
**/
|
||||
@ -157,19 +157,19 @@ g_action_default_init (GActionInterface *iface)
|
||||
|
||||
/**
|
||||
* g_action_change_state:
|
||||
* @action: a #GAction
|
||||
* @action: a [type@Gio.Action]
|
||||
* @value: the new state
|
||||
*
|
||||
* Request for the state of @action to be changed to @value.
|
||||
*
|
||||
* The action must be stateful and @value must be of the correct type.
|
||||
* See g_action_get_state_type().
|
||||
* See [method@Gio.Action.get_state_type].
|
||||
*
|
||||
* This call merely requests a change. The action may refuse to change
|
||||
* its state or may change its state to something other than @value.
|
||||
* See g_action_get_state_hint().
|
||||
* See [method@Gio.Action.get_state_hint].
|
||||
*
|
||||
* If the @value GVariant is floating, it is consumed.
|
||||
* If the @value [type@GLib.Variant] is floating, it is consumed.
|
||||
*
|
||||
* Since: 2.30
|
||||
**/
|
||||
@ -195,16 +195,16 @@ g_action_change_state (GAction *action,
|
||||
|
||||
/**
|
||||
* g_action_get_state:
|
||||
* @action: a #GAction
|
||||
* @action: a [type@Gio.Action]
|
||||
*
|
||||
* Queries the current state of @action.
|
||||
*
|
||||
* If the action is not stateful then %NULL will be returned. If the
|
||||
* If the action is not stateful then `NULL` will be returned. If the
|
||||
* action is stateful then the type of the return value is the type
|
||||
* given by g_action_get_state_type().
|
||||
* given by [method@Gio.Action.get_state_type].
|
||||
*
|
||||
* The return value (if non-%NULL) should be freed with
|
||||
* g_variant_unref() when it is no longer required.
|
||||
* The return value (if non-`NULL`) should be freed with
|
||||
* [method@GLib.Variant.unref] when it is no longer required.
|
||||
*
|
||||
* Returns: (nullable) (transfer full): the current state of the action
|
||||
*
|
||||
@ -221,7 +221,7 @@ g_action_get_state (GAction *action)
|
||||
|
||||
/**
|
||||
* g_action_get_name:
|
||||
* @action: a #GAction
|
||||
* @action: a [type@Gio.Action]
|
||||
*
|
||||
* Queries the name of @action.
|
||||
*
|
||||
@ -240,16 +240,17 @@ g_action_get_name (GAction *action)
|
||||
|
||||
/**
|
||||
* g_action_get_parameter_type:
|
||||
* @action: a #GAction
|
||||
* @action: a [type@Gio.Action]
|
||||
*
|
||||
* Queries the type of the parameter that must be given when activating
|
||||
* @action.
|
||||
*
|
||||
* When activating the action using g_action_activate(), the #GVariant
|
||||
* given to that function must be of the type returned by this function.
|
||||
* When activating the action using [method@Gio.Action.activate], the
|
||||
* [type@GLib.Variant] given to that function must be of the type returned by
|
||||
* this function.
|
||||
*
|
||||
* In the case that this function returns %NULL, you must not give any
|
||||
* #GVariant, but %NULL instead.
|
||||
* In the case that this function returns `NULL`, you must not give any
|
||||
* [type@GLib.Variant], but `NULL` instead.
|
||||
*
|
||||
* Returns: (nullable): the parameter type
|
||||
*
|
||||
@ -266,20 +267,20 @@ g_action_get_parameter_type (GAction *action)
|
||||
|
||||
/**
|
||||
* g_action_get_state_type:
|
||||
* @action: a #GAction
|
||||
* @action: a [type@Gio.Action]
|
||||
*
|
||||
* Queries the type of the state of @action.
|
||||
*
|
||||
* 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.
|
||||
* [ctor@Gio.SimpleAction.new_stateful]) then this function returns the
|
||||
* [type@GLib.VariantType] of the state. This is the type of the initial value
|
||||
* given as the state. All calls to [method@Gio.Action.change_state] must give a
|
||||
* [type@GLib.Variant] of this type and [method@Gio.Action.get_state] will return a
|
||||
* [type@GLib.Variant] of the same type.
|
||||
*
|
||||
* 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().
|
||||
* If the action is not stateful (e.g. created with [ctor@Gio.SimpleAction.new])
|
||||
* then this function will return `NULL`. In that case, [method@Gio.Action.get_state]
|
||||
* will return `NULL` and you must not call [method@Gio.Action.change_state].
|
||||
*
|
||||
* Returns: (nullable): the state type, if the action is stateful
|
||||
*
|
||||
@ -296,17 +297,17 @@ g_action_get_state_type (GAction *action)
|
||||
|
||||
/**
|
||||
* g_action_get_state_hint:
|
||||
* @action: a #GAction
|
||||
* @action: a [type@Gio.Action]
|
||||
*
|
||||
* Requests a hint about the valid range of values for the state of
|
||||
* @action.
|
||||
*
|
||||
* If %NULL is returned it either means that the action is not stateful
|
||||
* If `NULL` is returned it either means that the action is not stateful
|
||||
* or that there is no hint about the valid range of values for the
|
||||
* state of the action.
|
||||
*
|
||||
* If a #GVariant array is returned then each item in the array is a
|
||||
* possible value for the state. If a #GVariant pair (ie: two-tuple) is
|
||||
* If a [type@GLib.Variant] array is returned then each item in the array is a
|
||||
* possible value for the state. If a [type@GLib.Variant] pair (ie: two-tuple) is
|
||||
* returned then the tuple specifies the inclusive lower and upper bound
|
||||
* of valid values for the state.
|
||||
*
|
||||
@ -314,8 +315,8 @@ g_action_get_state_type (GAction *action)
|
||||
* have a state value outside of the hinted range and setting a value
|
||||
* within the range may fail.
|
||||
*
|
||||
* The return value (if non-%NULL) should be freed with
|
||||
* g_variant_unref() when it is no longer required.
|
||||
* The return value (if non-`NULL`) should be freed with
|
||||
* [method@GLib.Variant.unref] when it is no longer required.
|
||||
*
|
||||
* Returns: (nullable) (transfer full): the state range hint
|
||||
*
|
||||
@ -332,7 +333,7 @@ g_action_get_state_hint (GAction *action)
|
||||
|
||||
/**
|
||||
* g_action_get_enabled:
|
||||
* @action: a #GAction
|
||||
* @action: a [type@Gio.Action]
|
||||
*
|
||||
* Checks if @action is currently enabled.
|
||||
*
|
||||
@ -354,16 +355,16 @@ g_action_get_enabled (GAction *action)
|
||||
|
||||
/**
|
||||
* g_action_activate:
|
||||
* @action: a #GAction
|
||||
* @action: a [type@Gio.Action]
|
||||
* @parameter: (nullable): the parameter to the activation
|
||||
*
|
||||
* Activates the action.
|
||||
*
|
||||
* @parameter must be the correct type of parameter for the action (ie:
|
||||
* the parameter type given at construction time). If the parameter
|
||||
* type was %NULL then @parameter must also be %NULL.
|
||||
* type was `NULL` then @parameter must also be `NULL`.
|
||||
*
|
||||
* If the @parameter GVariant is floating, it is consumed.
|
||||
* If the @parameter [type@GLib.Variant] is floating, it is consumed.
|
||||
*
|
||||
* Since: 2.28
|
||||
**/
|
||||
@ -390,12 +391,12 @@ g_action_activate (GAction *action,
|
||||
* Checks if @action_name is valid.
|
||||
*
|
||||
* @action_name is valid if it consists only of alphanumeric characters,
|
||||
* plus '-' and '.'. The empty string is not a valid action name.
|
||||
* plus `-` and `.`. The empty string is not a valid action name.
|
||||
*
|
||||
* It is an error to call this function with a non-utf8 @action_name.
|
||||
* @action_name must not be %NULL.
|
||||
* It is an error to call this function with a non-UTF-8 @action_name.
|
||||
* @action_name must not be `NULL`.
|
||||
*
|
||||
* Returns: %TRUE if @action_name is valid
|
||||
* Returns: `TRUE` if @action_name is valid
|
||||
*
|
||||
* Since: 2.38
|
||||
**/
|
||||
@ -419,8 +420,8 @@ g_action_name_is_valid (const gchar *action_name)
|
||||
* @detailed_name: a detailed action name
|
||||
* @action_name: (out) (optional) (not nullable) (transfer full): the action name
|
||||
* @target_value: (out) (optional) (nullable) (transfer full): the target value,
|
||||
* or %NULL for no target
|
||||
* @error: a pointer to a %NULL #GError, or %NULL
|
||||
* or `NULL` for no target
|
||||
* @error: a pointer to a `NULL` [type@GLib.Error], or `NULL`
|
||||
*
|
||||
* Parses a detailed action name into its separate name and target
|
||||
* components.
|
||||
@ -440,20 +441,20 @@ g_action_name_is_valid (const gchar *action_name)
|
||||
* 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
|
||||
* target value is parsed using [func@GLib.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 `.`.
|
||||
*
|
||||
* If this function returns %TRUE, a non-%NULL value is guaranteed to be returned
|
||||
* in @action_name (if a pointer is passed in). A %NULL value may still be
|
||||
* If this function returns `TRUE`, a non-`NULL` value is guaranteed to be returned
|
||||
* in @action_name (if a pointer is passed in). A `NULL` value may still be
|
||||
* returned in @target_value, as the @detailed_name may not contain a target.
|
||||
*
|
||||
* If returned, the #GVariant in @target_value is guaranteed to not be floating.
|
||||
* If returned, the [type@GLib.Variant] in @target_value is guaranteed to not be floating.
|
||||
*
|
||||
* Returns: %TRUE if successful, else %FALSE with @error set
|
||||
* Returns: `TRUE` if successful, else `FALSE` with @error set
|
||||
*
|
||||
* Since: 2.38
|
||||
**/
|
||||
@ -531,13 +532,13 @@ bad_fmt:
|
||||
/**
|
||||
* g_action_print_detailed_name:
|
||||
* @action_name: a valid action name
|
||||
* @target_value: (nullable): a #GVariant target value, or %NULL
|
||||
* @target_value: (nullable): a [type@GLib.Variant] target value, or `NULL`
|
||||
*
|
||||
* Formats a detailed action name from @action_name and @target_value.
|
||||
*
|
||||
* It is an error to call this function with an invalid action name.
|
||||
*
|
||||
* This function is the opposite of g_action_parse_detailed_name().
|
||||
* This function is the opposite of [func@Gio.Action.parse_detailed_name].
|
||||
* It will produce a string that can be parsed back to the @action_name
|
||||
* and @target_value by that function.
|
||||
*
|
||||
|
||||
Loading…
Reference in New Issue
Block a user