luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-09 12:25:48 +01:00
Code Issues Packages Projects Releases Wiki Activity

Ports the documentation comments in gio/gactiongroup.c to GI-Docgen

Browse Source
This commit is contained in:
Sudhanshu Tiwari 2024-04-11 23:20:09 +05:30 committed by Philip Withnall
parent 204a76669b
commit a43ee8991e
1 changed files with 91 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

180
gio/gactiongroup.c
View File

@ -32,17 +32,17 @@
* *
* Actions can be used to expose functionality in a structured way, either * Actions can be used to expose functionality in a structured way, either
* from one part of a program to another, or to the outside world. Action * from one part of a program to another, or to the outside world. Action
* groups are often used together with a `GMenuModel` that provides additional * groups are often used together with a [type@Gio.MenuModel] that provides additional
* representation data for displaying the actions to the user, e.g. in a menu. * representation data for displaying the actions to the user, e.g. in a menu.
* *
* The main way to interact with the actions in a `GActionGroup` is to * The main way to interact with the actions in a `GActionGroup` is to
* activate them with [method@Gio.ActionGroup.activate_action]. Activating an * activate them with [method@Gio.ActionGroup.activate_action]. Activating an
* action may require a `GVariant` parameter. The required type of the * action may require a [type@GLib.Variant] parameter. The required type of the
* parameter can be inquired with [method@Gio.ActionGroup.get_action_parameter_type]. * parameter can be inquired with [method@Gio.ActionGroup.get_action_parameter_type].
* Actions may be disabled, see [method@Gio.ActionGroup.get_action_enabled]. * Actions may be disabled, see [method@Gio.ActionGroup.get_action_enabled].
* Activating a disabled action has no effect. * Activating a disabled action has no effect.
* *
* Actions may optionally have a state in the form of a #GVariant. The current * Actions may optionally have a state in the form of a [type@GLib.Variant]. The current
* state of an action can be inquired with [method@Gio.ActionGroup.get_action_state]. * state of an action can be inquired with [method@Gio.ActionGroup.get_action_state].
* Activating a stateful action may change its state, but it is also possible to * Activating a stateful action may change its state, but it is also possible to
* set the state by calling [method@Gio.ActionGroup.change_action_state]. * set the state by calling [method@Gio.ActionGroup.change_action_state].
@ -76,22 +76,22 @@
/** /**
* GActionGroupInterface: * GActionGroupInterface:
* @has_action: the virtual function pointer for g_action_group_has_action() * @has_action: the virtual function pointer for [method@Gio.ActionGroup.has_action]
* @list_actions: the virtual function pointer for g_action_group_list_actions() * @list_actions: the virtual function pointer for [method@Gio.ActionGroup.list_actions]
* @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type() * @get_action_parameter_type: the virtual function pointer for [method@Gio.ActionGroup.get_action_parameter_type]
* @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type() * @get_action_state_type: the virtual function pointer for [method@Gio.ActionGroup.get_action_state_type]
* @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint() * @get_action_state_hint: the virtual function pointer for [method@Gio.ActionGroup.get_action_state_hint]
* @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled() * @get_action_enabled: the virtual function pointer for [method@Gio.ActionGroup.get_action_enabled]
* @get_action_state: the virtual function pointer for g_action_group_get_action_state() * @get_action_state: the virtual function pointer for [method@Gio.ActionGroup.get_action_state]
* @change_action_state: the virtual function pointer for g_action_group_change_action_state() * @change_action_state: the virtual function pointer for [method@Gio.ActionGroup.change_action_state]
* @activate_action: the virtual function pointer for g_action_group_activate_action() * @activate_action: the virtual function pointer for [method@Gio.ActionGroup.activate_action]
* @action_added: the class closure for the #GActionGroup::action-added signal * @action_added: the class closure for the [signal@Gio.ActionGroup::action-added] signal
* @action_removed: the class closure for the #GActionGroup::action-removed signal * @action_removed: the class closure for the [signal@Gio.ActionGroup::action-removed] signal
* @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal * @action_enabled_changed: the class closure for the [signal@Gio.ActionGroup::action-enabled-changed] signal
* @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal * @action_state_changed: the class closure for the [signal@Gio.ActionGroup::action-enabled-changed] signal
* @query_action: the virtual function pointer for g_action_group_query_action() * @query_action: the virtual function pointer for [method@Gio.ActionGroup.query_action]
* *
* The virtual function table for #GActionGroup. * The virtual function table for [type@Gio.ActionGroup].
* *
* Since: 2.28 * Since: 2.28
**/ **/
@ -240,10 +240,11 @@ g_action_group_default_init (GActionGroupInterface *iface)
/** /**
* GActionGroup::action-added: * GActionGroup::action-added:
* @action_group: the #GActionGroup that changed * @action_group: the [type@Gio.ActionGroup] that changed
* @action_name: the name of the action in @action_group * @action_name: the name of the action in @action_group
* *
* Signals that a new action was just added to the group. * Signals that a new action was just added to the group.
*
* This signal is emitted after the action has been added * This signal is emitted after the action has been added
* and is now visible. * and is now visible.
* *
@ -261,10 +262,11 @@ g_action_group_default_init (GActionGroupInterface *iface)
/** /**
* GActionGroup::action-removed: * GActionGroup::action-removed:
* @action_group: the #GActionGroup that changed * @action_group: the [type@Gio.ActionGroup] that changed
* @action_name: the name of the action in @action_group * @action_name: the name of the action in @action_group
* *
* Signals that an action is just about to be removed from the group. * Signals that an action is just about to be removed from the group.
*
* This signal is emitted before the action is removed, so the action * This signal is emitted before the action is removed, so the action
* is still visible and can be queried from the signal handler. * is still visible and can be queried from the signal handler.
* *
@ -283,7 +285,7 @@ g_action_group_default_init (GActionGroupInterface *iface)
/** /**
* GActionGroup::action-enabled-changed: * GActionGroup::action-enabled-changed:
* @action_group: the #GActionGroup that changed * @action_group: the [type@Gio.ActionGroup] that changed
* @action_name: the name of the action in @action_group * @action_name: the name of the action in @action_group
* @enabled: whether the action is enabled or not * @enabled: whether the action is enabled or not
* *
@ -308,7 +310,7 @@ g_action_group_default_init (GActionGroupInterface *iface)
/** /**
* GActionGroup::action-state-changed: * GActionGroup::action-state-changed:
* @action_group: the #GActionGroup that changed * @action_group: the [type@Gio.ActionGroup] that changed
* @action_name: the name of the action in @action_group * @action_name: the name of the action in @action_group
* @value: the new value of the state * @value: the new value of the state
* *
@ -336,14 +338,14 @@ g_action_group_default_init (GActionGroupInterface *iface)
/** /**
* g_action_group_list_actions: * g_action_group_list_actions:
* @action_group: a #GActionGroup * @action_group: a [type@Gio.ActionGroup]
* *
* Lists the actions contained within @action_group. * Lists the actions contained within @action_group.
* *
* The caller is responsible for freeing the list with g_strfreev() when * The caller is responsible for freeing the list with [func@GLib.strfreev] when
* it is no longer required. * it is no longer required.
* *
* Returns: (transfer full): a %NULL-terminated array of the names of the * Returns: (transfer full): a `NULL`-terminated array of the names of the
* actions in the group * actions in the group
* *
* Since: 2.28 * Since: 2.28
@ -359,7 +361,7 @@ g_action_group_list_actions (GActionGroup *action_group)
/** /**
* g_action_group_has_action: * g_action_group_has_action:
* @action_group: a #GActionGroup * @action_group: a [type@Gio.ActionGroup]
* @action_name: the name of the action to check for * @action_name: the name of the action to check for
* *
* Checks if the named action exists within @action_group. * Checks if the named action exists within @action_group.
@ -380,18 +382,18 @@ g_action_group_has_action (GActionGroup *action_group,
/** /**
* g_action_group_get_action_parameter_type: * g_action_group_get_action_parameter_type:
* @action_group: a #GActionGroup * @action_group: a [type@Gio.ActionGroup]
* @action_name: the name of the action to query * @action_name: the name of the action to query
* *
* Queries the type of the parameter that must be given when activating * Queries the type of the parameter that must be given when activating
* the named action within @action_group. * the named action within @action_group.
* *
* When activating the action using g_action_group_activate_action(), * When activating the action using [method@Gio.ActionGroup.activate_action],
* the #GVariant given to that function must be of the type returned * the [type@GLib.Variant] given to that function must be of the type returned
* by this function. * by this function.
* *
* In the case that this function returns %NULL, you must not give any * In the case that this function returns `NULL`, you must not give any
* #GVariant, but %NULL instead. * [type@GLib.Variant], but `NULL` instead.
* *
* The parameter type of a particular action will never change but it is * The parameter type of a particular action will never change but it is
* possible for an action to be removed and for a new action to be added * possible for an action to be removed and for a new action to be added
@ -413,21 +415,21 @@ g_action_group_get_action_parameter_type (GActionGroup *action_group,
/** /**
* g_action_group_get_action_state_type: * g_action_group_get_action_state_type:
* @action_group: a #GActionGroup * @action_group: a [type@Gio.ActionGroup]
* @action_name: the name of the action to query * @action_name: the name of the action to query
* *
* Queries the type of the state of the named action within * Queries the type of the state of the named action within
* @action_group. * @action_group.
* *
* If the action is stateful then this function returns the * If the action is stateful then this function returns the
* #GVariantType of the state. All calls to * [type@GLib.VariantType] of the state. All calls to
* g_action_group_change_action_state() must give a #GVariant of this * [method@Gio.ActionGroup.change_action_state] must give a [type@GLib.Variant] of this
* type and g_action_group_get_action_state() will return a #GVariant * type and [method@Gio.ActionGroup.get_action_state] will return a [type@GLib.Variant]
* of the same type. * of the same type.
* *
* If the action is not stateful then this function will return %NULL. * If the action is not stateful then this function will return `NULL`.
* In that case, g_action_group_get_action_state() will return %NULL * In that case, [method@Gio.ActionGroup.get_action_state] will return `NULL`
* and you must not call g_action_group_change_action_state(). * and you must not call [method@Gio.ActionGroup.change_action_state].
* *
* The state type of a particular action will never change but it is * The state type of a particular action will never change but it is
* possible for an action to be removed and for a new action to be added * possible for an action to be removed and for a new action to be added
@ -449,18 +451,18 @@ g_action_group_get_action_state_type (GActionGroup *action_group,
/** /**
* g_action_group_get_action_state_hint: * g_action_group_get_action_state_hint:
* @action_group: a #GActionGroup * @action_group: a [type@Gio.ActionGroup]
* @action_name: the name of the action to query * @action_name: the name of the action to query
* *
* Requests a hint about the valid range of values for the state of the * Requests a hint about the valid range of values for the state of the
* named action within @action_group. * named action within @action_group.
* *
* 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 * or that there is no hint about the valid range of values for the
* state of the action. * state of the action.
* *
* If a #GVariant array is returned then each item in the array is a * If a [type@GLib.Variant] array is returned then each item in the array is a
* possible value for the state. If a #GVariant pair (ie: two-tuple) is * 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 * returned then the tuple specifies the inclusive lower and upper bound
* of valid values for the state. * of valid values for the state.
* *
@ -468,8 +470,8 @@ g_action_group_get_action_state_type (GActionGroup *action_group,
* have a state value outside of the hinted range and setting a value * have a state value outside of the hinted range and setting a value
* within the range may fail. * within the range may fail.
* *
* The return value (if non-%NULL) should be freed with * The return value (if non-`NULL`) should be freed with
* g_variant_unref() when it is no longer required. * [method@GLib.Variant.unref] when it is no longer required.
* *
* Returns: (nullable) (transfer full): the state range hint * Returns: (nullable) (transfer full): the state range hint
* *
@ -487,7 +489,7 @@ g_action_group_get_action_state_hint (GActionGroup *action_group,
/** /**
* g_action_group_get_action_enabled: * g_action_group_get_action_enabled:
* @action_group: a #GActionGroup * @action_group: a [type@Gio.ActionGroup]
* @action_name: the name of the action to query * @action_name: the name of the action to query
* *
* Checks if the named action within @action_group is currently enabled. * Checks if the named action within @action_group is currently enabled.
@ -511,17 +513,17 @@ g_action_group_get_action_enabled (GActionGroup *action_group,
/** /**
* g_action_group_get_action_state: * g_action_group_get_action_state:
* @action_group: a #GActionGroup * @action_group: a [type@Gio.ActionGroup]
* @action_name: the name of the action to query * @action_name: the name of the action to query
* *
* Queries the current state of the named action within @action_group. * Queries the current state of the named action within @action_group.
* *
* 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 * action is stateful then the type of the return value is the type
* given by g_action_group_get_action_state_type(). * given by [method@Gio.ActionGroup.get_action_state_type].
* *
* The return value (if non-%NULL) should be freed with * The return value (if non-`NULL`) should be freed with
* g_variant_unref() when it is no longer required. * [method@GLib.Variant.unref] when it is no longer required.
* *
* Returns: (nullable) (transfer full): the current state of the action * Returns: (nullable) (transfer full): the current state of the action
* *
@ -539,7 +541,7 @@ g_action_group_get_action_state (GActionGroup *action_group,
/** /**
* g_action_group_change_action_state: * g_action_group_change_action_state:
* @action_group: a #GActionGroup * @action_group: a [type@Gio.ActionGroup]
* @action_name: the name of the action to request the change on * @action_name: the name of the action to request the change on
* @value: the new state * @value: the new state
* *
@ -547,11 +549,11 @@ g_action_group_get_action_state (GActionGroup *action_group,
* changed to @value. * changed to @value.
* *
* The action must be stateful and @value must be of the correct type. * The action must be stateful and @value must be of the correct type.
* See g_action_group_get_action_state_type(). * See [method@Gio.ActionGroup.get_action_state_type].
* *
* This call merely requests a change. The action may refuse to change * This call merely requests a change. The action may refuse to change
* its state or may change its state to something other than @value. * its state or may change its state to something other than @value.
* See g_action_group_get_action_state_hint(). * See [method@Gio.ActionGroup.get_action_state_hint].
* *
* If the @value GVariant is floating, it is consumed. * If the @value GVariant is floating, it is consumed.
* *
@ -572,7 +574,7 @@ g_action_group_change_action_state (GActionGroup *action_group,
/** /**
* g_action_group_activate_action: * g_action_group_activate_action:
* @action_group: a #GActionGroup * @action_group: a [type@Gio.ActionGroup]
* @action_name: the name of the action to activate * @action_name: the name of the action to activate
* @parameter: (nullable): parameters to the activation * @parameter: (nullable): parameters to the activation
* *
@ -580,25 +582,25 @@ g_action_group_change_action_state (GActionGroup *action_group,
* *
* If the action is expecting a parameter, then the correct type of * If the action is expecting a parameter, then the correct type of
* parameter must be given as @parameter. If the action is expecting no * parameter must be given as @parameter. If the action is expecting no
* parameters then @parameter must be %NULL. See * parameters then @parameter must be `NULL`. See
* g_action_group_get_action_parameter_type(). * [method@Gio.ActionGroup.get_action_parameter_type].
* *
* If the #GActionGroup implementation supports asynchronous remote * If the [type@Gio.ActionGroup] implementation supports asynchronous remote
* activation over D-Bus, this call may return before the relevant * activation over D-Bus, this call may return before the relevant
* D-Bus traffic has been sent, or any replies have been received. In * D-Bus traffic has been sent, or any replies have been received. In
* order to block on such asynchronous activation calls, * order to block on such asynchronous activation calls,
* g_dbus_connection_flush() should be called prior to the code, which * [method@Gio.DBusConnection.flush] should be called prior to the code, which
* depends on the result of the action activation. Without flushing * depends on the result of the action activation. Without flushing
* the D-Bus connection, there is no guarantee that the action would * the D-Bus connection, there is no guarantee that the action would
* have been activated. * have been activated.
* *
* The following code which runs in a remote app instance, shows an * The following code which runs in a remote app instance, shows an
* example of a "quit" action being activated on the primary app * example of a "quit" action being activated on the primary app
* instance over D-Bus. Here g_dbus_connection_flush() is called * instance over D-Bus. Here [method@Gio.DBusConnection.flush] is called
* before `exit()`. Without g_dbus_connection_flush(), the "quit" action * before `exit()`. Without `g_dbus_connection_flush()`, the "quit" action
* may fail to be activated on the primary instance. * may fail to be activated on the primary instance.
* *
* |[<!-- language="C" --> * ```c
* // call "quit" action on primary instance * // call "quit" action on primary instance
* g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL); * g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);
* *
@ -608,7 +610,7 @@ g_action_group_change_action_state (GActionGroup *action_group,
* g_debug ("application has been terminated. exiting."); * g_debug ("application has been terminated. exiting.");
* *
* exit (0); * exit (0);
* ]| * ```
* *
* Since: 2.28 * Since: 2.28
**/ **/
@ -626,12 +628,12 @@ g_action_group_activate_action (GActionGroup *action_group,
/** /**
* g_action_group_action_added: * g_action_group_action_added:
* @action_group: a #GActionGroup * @action_group: a [type@Gio.ActionGroup]
* @action_name: the name of an action in the group * @action_name: the name of an action in the group
* *
* Emits the #GActionGroup::action-added signal on @action_group. * Emits the [signal@Gio.ActionGroup::action-added] signal on @action_group.
* *
* This function should only be called by #GActionGroup implementations. * This function should only be called by [type@Gio.ActionGroup] implementations.
* *
* Since: 2.28 * Since: 2.28
**/ **/
@ -650,12 +652,12 @@ g_action_group_action_added (GActionGroup *action_group,
/** /**
* g_action_group_action_removed: * g_action_group_action_removed:
* @action_group: a #GActionGroup * @action_group: a [type@Gio.ActionGroup]
* @action_name: the name of an action in the group * @action_name: the name of an action in the group
* *
* Emits the #GActionGroup::action-removed signal on @action_group. * Emits the [signal@Gio.ActionGroup::action-removed] signal on @action_group.
* *
* This function should only be called by #GActionGroup implementations. * This function should only be called by [type@Gio.ActionGroup] implementations.
* *
* Since: 2.28 * Since: 2.28
**/ **/
@ -674,13 +676,13 @@ g_action_group_action_removed (GActionGroup *action_group,
/** /**
* g_action_group_action_enabled_changed: * g_action_group_action_enabled_changed:
* @action_group: a #GActionGroup * @action_group: a [type@Gio.ActionGroup]
* @action_name: the name of an action in the group * @action_name: the name of an action in the group
* @enabled: whether or not the action is now enabled * @enabled: whether or not the action is now enabled
* *
* Emits the #GActionGroup::action-enabled-changed signal on @action_group. * Emits the [signal@Gio.ActionGroup::action-enabled-changed] signal on @action_group.
* *
* This function should only be called by #GActionGroup implementations. * This function should only be called by [type@Gio.ActionGroup] implementations.
* *
* Since: 2.28 * Since: 2.28
**/ **/
@ -703,13 +705,13 @@ g_action_group_action_enabled_changed (GActionGroup *action_group,
/** /**
* g_action_group_action_state_changed: * g_action_group_action_state_changed:
* @action_group: a #GActionGroup * @action_group: a [type@Gio.ActionGroup]
* @action_name: the name of an action in the group * @action_name: the name of an action in the group
* @state: the new state of the named action * @state: the new state of the named action
* *
* Emits the #GActionGroup::action-state-changed signal on @action_group. * Emits the [signal@Gio.ActionGroup::action-state-changed] signal on @action_group.
* *
* This function should only be called by #GActionGroup implementations. * This function should only be called by [type@Gio.ActionGroup] implementations.
* *
* Since: 2.28 * Since: 2.28
**/ **/
@ -730,29 +732,29 @@ g_action_group_action_state_changed (GActionGroup *action_group,
/** /**
* g_action_group_query_action: * g_action_group_query_action:
* @action_group: a #GActionGroup * @action_group: a [type@Gio.ActionGroup]
* @action_name: the name of an action in the group * @action_name: the name of an action in the group
* @enabled: (out): if the action is presently enabled * @enabled: (out): if the action is presently enabled
* @parameter_type: (out) (transfer none) (optional): the parameter type, or %NULL if none needed * @parameter_type: (out) (transfer none) (optional): the parameter type, or `NULL` if none needed
* @state_type: (out) (transfer none) (optional): the state type, or %NULL if stateless * @state_type: (out) (transfer none) (optional): the state type, or `NULL` if stateless
* @state_hint: (out) (optional): the state hint, or %NULL if none * @state_hint: (out) (optional): the state hint, or `NULL` if none
* @state: (out) (optional): the current state, or %NULL if stateless * @state: (out) (optional): the current state, or `NULL` if stateless
* *
* Queries all aspects of the named action within an @action_group. * Queries all aspects of the named action within an @action_group.
* *
* This function acquires the information available from * This function acquires the information available from
* g_action_group_has_action(), g_action_group_get_action_enabled(), * [method@Gio.ActionGroup.has_action], [method@Gio.ActionGroup.get_action_enabled],
* g_action_group_get_action_parameter_type(), * [method@Gio.ActionGroup.get_action_parameter_type],
* g_action_group_get_action_state_type(), * [method@Gio.ActionGroup.get_action_state_type],
* g_action_group_get_action_state_hint() and * [method@Gio.ActionGroup.get_action_state_hint] and
* g_action_group_get_action_state() with a single function call. * [method@Gio.ActionGroup.get_action_state] with a single function call.
* *
* This provides two main benefits. * This provides two main benefits.
* *
* The first is the improvement in efficiency that comes with not having * The first is the improvement in efficiency that comes with not having
* to perform repeated lookups of the action in order to discover * to perform repeated lookups of the action in order to discover
* different things about it. The second is that implementing * different things about it. The second is that implementing
* #GActionGroup can now be done by only overriding this one virtual * [type@Gio.ActionGroup] can now be done by only overriding this one virtual
* function. * function.
* *
* The interface provides a default implementation of this function that * The interface provides a default implementation of this function that
@ -761,12 +763,12 @@ g_action_group_action_state_changed (GActionGroup *action_group,
* those functions that call this function. All implementations, * those functions that call this function. All implementations,
* therefore, must override either this function or all of the others. * therefore, must override either this function or all of the others.
* *
* If the action exists, %TRUE is returned and any of the requested * If the action exists, `TRUE` is returned and any of the requested
* fields (as indicated by having a non-%NULL reference passed in) are * fields (as indicated by having a non-`NULL` reference passed in) are
* filled. If the action doesn't exist, %FALSE is returned and the * filled. If the action doesn't exist, `FALSE` is returned and the
* fields may or may not have been modified. * fields may or may not have been modified.
* *
* Returns: %TRUE if the action exists, else %FALSE * Returns: `TRUE` if the action exists, else `FALSE`
* *
* Since: 2.32 * Since: 2.32
**/ **/