* 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>
*/
* SECTION:gactiongroup
* @title: GActionGroup
* @short_description: A group of actions
- *
- * #GActionGroup represents a group of actions.
+ * @include: gio/gio.h
+ * @see_also: #GAction
+ *
+ * #GActionGroup represents a group of actions. 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 groups are often
+ * used together with a #GMenuModel that provides additional
+ * 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
+ * activate them with g_action_group_activate_action(). Activating an
+ * action may require a #GVariant parameter. The required type of the
+ * parameter can be inquired with g_action_group_get_action_parameter_type().
+ * Actions may be disabled, see g_action_group_get_action_enabled().
+ * Activating a disabled action has no effect.
+ *
+ * Actions may optionally have a state in the form of a #GVariant. The
+ * current state of an action can be inquired with
+ * g_action_group_get_action_state(). Activating a stateful action may
+ * change its state, but it is also possible to set the state by calling
+ * g_action_group_change_action_state().
+ *
+ * As typical example, consider a text editing application which has an
+ * option to change the current font to 'bold'. A good way to represent
+ * this would be a stateful action, with a boolean state. Activating the
+ * action would toggle the state.
*
* Each action in the group has a unique name (which is a string). All
* method calls, except g_action_group_list_actions() take the name of
* an action as an argument.
*
- * Action groups are often used together with a #GMenuModel that provides
- * additional representation data for the actions.
- *
* The #GActionGroup API is meant to be the 'public' API to the action
* group. The calls here are exactly the interaction that 'external
* forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
* with actions. 'Internal' APIs (ie: ones meant only to be accessed by
* the action group implementation) are found on subclasses. This is
* why you will find - for example - g_action_group_get_action_enabled()
- * but not an equivalent <function>set()</function> call.
+ * but not an equivalent set() call.
*
* Signals are emitted on the action group in response to state changes
* on individual actions.
* g_action_group_query_action(). The other virtual functions should
* not be implemented - their "wrappers" are actually implemented with
* calls to g_action_group_query_action().
- **/
+ */
/**
* GActionGroupInterface:
* @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
* @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
* @get_action_state: the virtual function pointer for g_action_group_get_action_state()
- * @set_action_state: the virtual function pointer for g_action_group_set_action_state()
+ * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
* @query_action: the virtual function pointer for g_action_group_query_action()
* @activate_action: the virtual function pointer for g_action_group_activate_action()
* @change_action_state: the virtual function pointer for g_action_group_change_action_state()
* possible for an action to be removed and for a new action to be added
* with the same name but a different parameter type.
*
- * Return value: the parameter type
+ * Returns: (nullable): the parameter type
*
* Since: 2.28
**/
* possible for an action to be removed and for a new action to be added
* with the same name but a different state type.
*
- * Returns: (transfer full): the state type, if the action is stateful
+ * Returns: (nullable) (transfer full): the state type, if the action
+ * is stateful
*
* Since: 2.28
**/
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
- * Return value: (transfer full): the state range hint
+ * Returns: (nullable) (transfer full): the state range hint
*
* Since: 2.28
**/
* An action must be enabled in order to be activated or in order to
* have its state changed from outside callers.
*
- * Return value: whether or not the action is currently enabled
+ * Returns: whether or not the action is currently enabled
*
* Since: 2.28
**/
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
- * Return value: (allow-none): the current state of the action
+ * Returns: (nullable): the current state of the action
*
* Since: 2.28
**/
* @action_group: a #GActionGroup
* @action_name: the name of an action in the group
* @enabled: (out): if the action is presently enabled
- * @parameter_type: (out): the parameter type, or %NULL if none needed
- * @state_type: (out): the state type, or %NULL if stateless
- * @state_hint: (out): the state hint, or %NULL if none
- * @state: (out): the current state, or %NULL if stateless
+ * @parameter_type: (out) (allow-none): the parameter type, or %NULL if none needed
+ * @state_type: (out) (allow-none): the state type, or %NULL if stateless
+ * @state_hint: (out) (allow-none): the state hint, or %NULL if none
+ * @state: (out) (allow-none): the current state, or %NULL if stateless
*
* Queries all aspects of the named action within an @action_group.
*
* g_action_group_get_action_parameter_type(),
* g_action_group_get_action_state_type(),
* g_action_group_get_action_state_hint() and
- * g_action_group_get_state() with a single function call.
+ * g_action_group_get_action_state() with a single function call.
*
* This provides two main benefits.
*
projects / platform / upstream / glib.git / blobdiff