Interface Action

All Superinterfaces:

Proxy

All Known Implementing Classes:

Action.Action$Impl, PropertyAction, SimpleAction

@Generated("org.javagi.JavaGI")
public interface Action
extends Proxy

GAction represents a single named action.

The main interface to an action is that it can be activated with activate(Variant). This results in the 'activate' signal being emitted. An activation has a GVariant parameter (which may be NULL). The correct type for the parameter is determined by a static parameter type (which is given at construction time).

An action may optionally have a state, in which case the state may be set with changeState(Variant). This call takes a GLib.Variant. 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 merely the interface to the concept of an action, as described above. Various implementations of actions exist, including SimpleAction.

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 is responsible for filtering calls to activate(Variant) and changeState(Variant) 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 SimpleActionGroup.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	Action.Action$Impl	The Action$Impl type represents a native instance of the Action interface.
static class	Action.ActionInterface	The virtual function table for Gio.Action.
static interface	Action.Builder<B extends Builder<B>>

Method Summary

Modifier and Type	Method	Description
default void	activate(@Nullable Variant parameter)	Activates the action.
default void	changeState(Variant value)	Request for the state of this Action to be changed to value.
default boolean	getEnabled()	Checks if this Action is currently enabled.
default String	getName()	Queries the name of action.
default @Nullable VariantType	getParameterType()	Queries the type of the parameter that must be given when activating action.
default @Nullable Variant	getState()	Queries the current state of action.
default @Nullable Variant	getStateHint()	Requests a hint about the valid range of values for the state of action.
default @Nullable VariantType	getStateType()	Queries the type of the state of action.
static @Nullable Type	getType()	Get the GType of the Action class.
static boolean	nameIsValid(String actionName)	Checks if actionName is valid.
static boolean	parseDetailedName(String detailedName, @Nullable Out<String> actionName, @Nullable Out<Variant> targetValue)	Parses a detailed action name into its separate name and target components.
static String	printDetailedName(String actionName, @Nullable Variant targetValue)	Formats a detailed action name from actionName and targetValue.

Methods inherited from interface Proxy

handle

Method Details

getType

static @Nullable Type getType()

Get the GType of the Action class.

Returns:

the GType

nameIsValid

static boolean nameIsValid(String actionName)

Checks if actionName is valid.

actionName is valid if it consists only of alphanumeric characters, plus - and .. The empty string is not a valid action name.

It is an error to call this function with a non-UTF-8 actionName. actionName must not be NULL.

Parameters:

actionName - a potential action name

Returns:

TRUE if actionName is valid

Since:

2.38

parseDetailedName

static boolean parseDetailedName(String detailedName,
 @Nullable Out<String> actionName,
 @Nullable Out<Variant> targetValue)
                          throws GErrorException

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 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 actionName (if a pointer is passed in). A NULL value may still be returned in targetValue, as the detailedName may not contain a target.

If returned, the GLib.Variant in targetValue is guaranteed to not be floating.

Parameters:

detailedName - a detailed action name

actionName - the action name

targetValue - the target value, or NULL for no target

Returns:

TRUE if successful, else FALSE with error set

Throws:

GErrorException - see GError

Since:

2.38

printDetailedName

static String printDetailedName(String actionName,
 @Nullable Variant targetValue)

Formats a detailed action name from actionName and targetValue.

It is an error to call this function with an invalid action name.

This function is the opposite of parseDetailedName(String, Out, Out). It will produce a string that can be parsed back to the actionName and targetValue by that function.

See that function for the types of strings that will be printed by this function.

Parameters:

actionName - a valid action name

targetValue - a GLib.Variant target value, or NULL

Returns:

a detailed format string

Since:

2.38

activate

default void activate(@Nullable Variant parameter)

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.

If the parameter GLib.Variant is floating, it is consumed.

Parameters:

parameter - the parameter to the activation

Since:

2.28

changeState

default void changeState(Variant value)

Request for the state of this Action to be changed to value.

The action must be stateful and value must be of the correct type. See getStateType().

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

If the value GLib.Variant is floating, it is consumed.

Parameters:

value - the new state

Since:

2.30

getEnabled

default boolean getEnabled()

Checks if this Action is currently enabled.

An action must be enabled in order to be activated or in order to have its state changed from outside callers.

Returns:

whether the action is enabled

Since:

2.28

getName

default String getName()

Queries the name of action.

Returns:

the name of the action

Since:

2.28

getParameterType

default @Nullable VariantType getParameterType()

Queries the type of the parameter that must be given when activating action.

When activating the action using activate(Variant), the 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 GLib.Variant, but NULL instead.

Returns:

the parameter type

Since:

2.28

getState

default @Nullable Variant getState()

Queries the current state of action.

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

The return value (if non-NULL) should be freed with Variant#unref when it is no longer required.

Returns:

the current state of the action

Since:

2.28

getStateHint

default @Nullable Variant getStateHint()

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 or that there is no hint about the valid range of values for the state of the action.

If a GLib.Variant array is returned then each item in the array is a possible value for the state. If a GLib.Variant 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 Variant#unref when it is no longer required.

Returns:

the state range hint

Since:

2.28

getStateType

default @Nullable VariantType getStateType()

Queries the type of the state of action.

If the action is stateful (e.g. created with SimpleAction.stateful(String, VariantType, Variant)) then this function returns the GLib.VariantType of the state. This is the type of the initial value given as the state. All calls to changeState(Variant) must give a GLib.Variant of this type and getState() will return a GLib.Variant of the same type.

If the action is not stateful (e.g. created with SimpleAction()) then this function will return NULL. In that case, getState() will return NULL and you must not call changeState(Variant).

Returns:

the state type, if the action is stateful

Since:

2.28