Package ch.bailu.gtk.gio

Class ActionGroup

java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.gobject.Object
ch.bailu.gtk.type.Interface
ch.bailu.gtk.gio.ActionGroup
All Implemented Interfaces:
PointerInterface
public class ActionGroup extends Interface
#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.

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 set() call.

Signals are emitted on the action group in response to state changes
on individual actions.

Implementations of #GActionGroup should provide implementations for
the virtual functions g_action_group_list_actions() and
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().

https://docs.gtk.org/gio/iface.ActionGroup.html

  • Field Details

  • Constructor Details

  • Method Details

    • getClassHandler

      public static ClassHandler getClassHandler()

    • actionAdded

      public void actionAdded(@Nonnull Str action_name)
      Emits the #GActionGroup::action-added signal on @action_group.

      This function should only be called by #GActionGroup implementations.
      Parameters:
      action_name - the name of an action in the group

    • actionAdded

      public void actionAdded(String action_name)
      Emits the #GActionGroup::action-added signal on @action_group.

      This function should only be called by #GActionGroup implementations.
      Parameters:
      action_name - the name of an action in the group

    • actionEnabledChanged

      public void actionEnabledChanged(@Nonnull Str action_name, boolean enabled)
      Emits the #GActionGroup::action-enabled-changed signal on @action_group.

      This function should only be called by #GActionGroup implementations.
      Parameters:
      action_name - the name of an action in the group
      enabled - whether or not the action is now enabled

    • actionEnabledChanged

      public void actionEnabledChanged(String action_name, boolean enabled)
      Emits the #GActionGroup::action-enabled-changed signal on @action_group.

      This function should only be called by #GActionGroup implementations.
      Parameters:
      action_name - the name of an action in the group
      enabled - whether or not the action is now enabled

    • actionRemoved

      public void actionRemoved(@Nonnull Str action_name)
      Emits the #GActionGroup::action-removed signal on @action_group.

      This function should only be called by #GActionGroup implementations.
      Parameters:
      action_name - the name of an action in the group

    • actionRemoved

      public void actionRemoved(String action_name)
      Emits the #GActionGroup::action-removed signal on @action_group.

      This function should only be called by #GActionGroup implementations.
      Parameters:
      action_name - the name of an action in the group

    • actionStateChanged

      public void actionStateChanged(@Nonnull Str action_name, @Nonnull Variant state)
      Emits the #GActionGroup::action-state-changed signal on @action_group.

      This function should only be called by #GActionGroup implementations.
      Parameters:
      action_name - the name of an action in the group
      state - the new state of the named action

    • actionStateChanged

      public void actionStateChanged(String action_name, @Nonnull Variant state)
      Emits the #GActionGroup::action-state-changed signal on @action_group.

      This function should only be called by #GActionGroup implementations.
      Parameters:
      action_name - the name of an action in the group
      state - the new state of the named action

    • activateAction

      public void activateAction(@Nonnull Str action_name, @Nullable Variant parameter)
      Activate the named action within @action_group.

      If the action is expecting a parameter, then the correct type of
      parameter must be given as @parameter. If the action is expecting no
      parameters then @parameter must be %NULL. See
      g_action_group_get_action_parameter_type().

      If the #GActionGroup implementation supports asynchronous remote
      activation over D-Bus, this call may return before the relevant
      D-Bus traffic has been sent, or any replies have been received. In
      order to block on such asynchronous activation calls,
      g_dbus_connection_flush() should be called prior to the code, which
      depends on the result of the action activation. Without flushing
      the D-Bus connection, there is no guarantee that the action would
      have been activated.

      The following code which runs in a remote app instance, shows an
      example of a "quit" action being activated on the primary app
      instance over D-Bus. Here g_dbus_connection_flush() is called
      before `exit()`. Without g_dbus_connection_flush(), the "quit" action
      may fail to be activated on the primary instance. 
      <!-- language="C" -->
 // call "quit" action on primary instance
 g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);
 
 // make sure the action is activated now
 g_dbus_connection_flush (...);
 
 g_debug ("application has been terminated. exiting.");
 
 exit (0);
      Parameters:
      action_name - the name of the action to activate
      parameter - parameters to the activation

    • activateAction

      public void activateAction(String action_name, @Nullable Variant parameter)
      Activate the named action within @action_group.

      If the action is expecting a parameter, then the correct type of
      parameter must be given as @parameter. If the action is expecting no
      parameters then @parameter must be %NULL. See
      g_action_group_get_action_parameter_type().

      If the #GActionGroup implementation supports asynchronous remote
      activation over D-Bus, this call may return before the relevant
      D-Bus traffic has been sent, or any replies have been received. In
      order to block on such asynchronous activation calls,
      g_dbus_connection_flush() should be called prior to the code, which
      depends on the result of the action activation. Without flushing
      the D-Bus connection, there is no guarantee that the action would
      have been activated.

      The following code which runs in a remote app instance, shows an
      example of a "quit" action being activated on the primary app
      instance over D-Bus. Here g_dbus_connection_flush() is called
      before `exit()`. Without g_dbus_connection_flush(), the "quit" action
      may fail to be activated on the primary instance. 
      <!-- language="C" -->
 // call "quit" action on primary instance
 g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);
 
 // make sure the action is activated now
 g_dbus_connection_flush (...);
 
 g_debug ("application has been terminated. exiting.");
 
 exit (0);
      Parameters:
      action_name - the name of the action to activate
      parameter - parameters to the activation

    • changeActionState

      public void changeActionState(@Nonnull Str action_name, @Nonnull Variant value)
      Request for the state of the named action within @action_group to be
      changed to @value.

      The action must be stateful and @value must be of the correct type.
      See g_action_group_get_action_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_group_get_action_state_hint().

      If the @value GVariant is floating, it is consumed.
      Parameters:
      action_name - the name of the action to request the change on
      value - the new state

    • changeActionState

      public void changeActionState(String action_name, @Nonnull Variant value)
      Request for the state of the named action within @action_group to be
      changed to @value.

      The action must be stateful and @value must be of the correct type.
      See g_action_group_get_action_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_group_get_action_state_hint().

      If the @value GVariant is floating, it is consumed.
      Parameters:
      action_name - the name of the action to request the change on
      value - the new state

    • getActionEnabled

      public boolean getActionEnabled(@Nonnull Str action_name)
      Checks if the named action within @action_group is currently enabled.

      An action must be enabled in order to be activated or in order to
      have its state changed from outside callers.
      Parameters:
      action_name - the name of the action to query
      Returns:
      whether or not the action is currently enabled

    • getActionEnabled

      public boolean getActionEnabled(String action_name)
      Checks if the named action within @action_group is currently enabled.

      An action must be enabled in order to be activated or in order to
      have its state changed from outside callers.
      Parameters:
      action_name - the name of the action to query
      Returns:
      whether or not the action is currently enabled

    • getActionParameterType

      public VariantType getActionParameterType(@Nonnull Str action_name)
      Queries the type of the parameter that must be given when activating
      the named action within @action_group.

      When activating the action using g_action_group_activate_action(),
      the #GVariant 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.

      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
      with the same name but a different parameter type.
      Parameters:
      action_name - the name of the action to query
      Returns:
      the parameter type

    • getActionParameterType

      public VariantType getActionParameterType(String action_name)
      Queries the type of the parameter that must be given when activating
      the named action within @action_group.

      When activating the action using g_action_group_activate_action(),
      the #GVariant 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.

      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
      with the same name but a different parameter type.
      Parameters:
      action_name - the name of the action to query
      Returns:
      the parameter type

    • getActionState

      public Variant getActionState(@Nonnull Str action_name)
      Queries the current state of the named action within @action_group.

      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_group_get_action_state_type().

      The return value (if non-%NULL) should be freed with
      g_variant_unref() when it is no longer required.
      Parameters:
      action_name - the name of the action to query
      Returns:
      the current state of the action

    • getActionState

      public Variant getActionState(String action_name)
      Queries the current state of the named action within @action_group.

      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_group_get_action_state_type().

      The return value (if non-%NULL) should be freed with
      g_variant_unref() when it is no longer required.
      Parameters:
      action_name - the name of the action to query
      Returns:
      the current state of the action

    • getActionStateHint

      public Variant getActionStateHint(@Nonnull Str action_name)
      Requests a hint about the valid range of values for the state of the
      named action within @action_group.

      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
      returned then the tuple specifies the inclusive lower and upper bound
      of valid values for the state.

      In any case, the information is merely a hint. It may be possible to
      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.
      Parameters:
      action_name - the name of the action to query
      Returns:
      the state range hint

    • getActionStateHint

      public Variant getActionStateHint(String action_name)
      Requests a hint about the valid range of values for the state of the
      named action within @action_group.

      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
      returned then the tuple specifies the inclusive lower and upper bound
      of valid values for the state.

      In any case, the information is merely a hint. It may be possible to
      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.
      Parameters:
      action_name - the name of the action to query
      Returns:
      the state range hint

    • getActionStateType

      public VariantType getActionStateType(@Nonnull Str action_name)
      Queries the type of the state of the named action within
      @action_group.

      If the action is stateful then this function returns the
      #GVariantType of the state. All calls to
      g_action_group_change_action_state() must give a #GVariant of this
      type and g_action_group_get_action_state() will return a #GVariant
      of the same type.

      If the action is not stateful then this function will return %NULL.
      In that case, g_action_group_get_action_state() will return %NULL
      and you must not call g_action_group_change_action_state().

      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
      with the same name but a different state type.
      Parameters:
      action_name - the name of the action to query
      Returns:
      the state type, if the action is stateful

    • getActionStateType

      public VariantType getActionStateType(String action_name)
      Queries the type of the state of the named action within
      @action_group.

      If the action is stateful then this function returns the
      #GVariantType of the state. All calls to
      g_action_group_change_action_state() must give a #GVariant of this
      type and g_action_group_get_action_state() will return a #GVariant
      of the same type.

      If the action is not stateful then this function will return %NULL.
      In that case, g_action_group_get_action_state() will return %NULL
      and you must not call g_action_group_change_action_state().

      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
      with the same name but a different state type.
      Parameters:
      action_name - the name of the action to query
      Returns:
      the state type, if the action is stateful

    • hasAction

      public boolean hasAction(@Nonnull Str action_name)
      Checks if the named action exists within @action_group.
      Parameters:
      action_name - the name of the action to check for
      Returns:
      whether the named action exists

    • hasAction

      public boolean hasAction(String action_name)
      Checks if the named action exists within @action_group.
      Parameters:
      action_name - the name of the action to check for
      Returns:
      whether the named action exists

    • onActionAdded

      public SignalHandler onActionAdded(ActionGroup.OnActionAdded signal)
      Connect to signal "action-added".
      See ActionGroup.OnActionAdded.onActionAdded(ch.bailu.gtk.type.Str) for signal description.
      Field SIGNAL_ON_ACTION_ADDED contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onActionEnabledChanged

      public SignalHandler onActionEnabledChanged(ActionGroup.OnActionEnabledChanged signal)
      Connect to signal "action-enabled-changed".
      See ActionGroup.OnActionEnabledChanged.onActionEnabledChanged(ch.bailu.gtk.type.Str, boolean) for signal description.
      Field SIGNAL_ON_ACTION_ENABLED_CHANGED contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onActionRemoved

      public SignalHandler onActionRemoved(ActionGroup.OnActionRemoved signal)
      Connect to signal "action-removed".
      See ActionGroup.OnActionRemoved.onActionRemoved(ch.bailu.gtk.type.Str) for signal description.
      Field SIGNAL_ON_ACTION_REMOVED contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onActionStateChanged

      public SignalHandler onActionStateChanged(ActionGroup.OnActionStateChanged signal)
      Connect to signal "action-state-changed".
      See ActionGroup.OnActionStateChanged.onActionStateChanged(ch.bailu.gtk.type.Str, ch.bailu.gtk.glib.Variant) for signal description.
      Field SIGNAL_ON_ACTION_STATE_CHANGED contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • getTypeID

      public static long getTypeID()

    • getParentTypeID

      public static long getParentTypeID()

    • getTypeSize

      public static TypeSystem.TypeSize getTypeSize()

    • getParentTypeSize

      public static TypeSystem.TypeSize getParentTypeSize()

    • getInstanceSize

      public static int getInstanceSize()