source: appstream-generator/build/girepo/gio/ActionIF.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

File size: 9.2 KB
Line 
1/*
2 * Licensed under the GNU Lesser General Public License Version 3
3 *
4 * This library is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation, either version 3 of the license, or
7 * (at your option) any later version.
8 *
9 * This software is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
16 */
17
18// generated automatically - do not change
19
20
21module gio.ActionIF;
22
23private import gi.gio;
24public  import gi.giotypes;
25private import glib.ErrorG;
26private import glib.GException;
27private import glib.Str;
28private import glib.Variant;
29private import glib.VariantType;
30
31
32/**
33 * #GAction represents a single named action.
34 *
35 * The main interface to an action is that it can be activated with
36 * g_action_activate().  This results in the 'activate' signal being
37 * emitted.  An activation has a #GVariant parameter (which may be
38 * %NULL).  The correct type for the parameter is determined by a static
39 * parameter type (which is given at construction time).
40 *
41 * An action may optionally have a state, in which case the state may be
42 * set with g_action_change_state().  This call takes a #GVariant.  The
43 * correct type for the state is determined by a static state type
44 * (which is given at construction time).
45 *
46 * The state may have a hint associated with it, specifying its valid
47 * range.
48 *
49 * #GAction is merely the interface to the concept of an action, as
50 * described above.  Various implementations of actions exist, including
51 * #GSimpleAction.
52 *
53 * In all cases, the implementing class is responsible for storing the
54 * name of the action, the parameter type, the enabled state, the
55 * optional state type and the state and emitting the appropriate
56 * signals when these change.  The implementor responsible for filtering
57 * calls to g_action_activate() and g_action_change_state() for type
58 * safety and for the state being enabled.
59 *
60 * Probably the only useful thing to do with a #GAction is to put it
61 * inside of a #GSimpleActionGroup.
62 */
63public interface ActionIF{
64        /** Get the main Gtk struct */
65        public GAction* getActionStruct();
66
67        /** the main Gtk struct as a void* */
68        protected void* getStruct();
69
70
71        /**
72         * Checks if @action_name is valid.
73         *
74         * @action_name is valid if it consists only of alphanumeric characters,
75         * plus '-' and '.'.  The empty string is not a valid action name.
76         *
77         * It is an error to call this function with a non-utf8 @action_name.
78         * @action_name must not be %NULL.
79         *
80         * Params:
81         *     actionName = an potential action name
82         *
83         * Returns: %TRUE if @action_name is valid
84         *
85         * Since: 2.38
86         */
87        public static bool nameIsValid(string actionName);
88
89        /**
90         * Parses a detailed action name into its separate name and target
91         * components.
92         *
93         * Detailed action names can have three formats.
94         *
95         * The first format is used to represent an action name with no target
96         * value and consists of just an action name containing no whitespace
97         * nor the characters ':', '(' or ')'.  For example: "app.action".
98         *
99         * The second format is used to represent an action with a target value
100         * that is a non-empty string consisting only of alphanumerics, plus '-'
101         * and '.'.  In that case, the action name and target value are
102         * separated by a double colon ("::").  For example:
103         * "app.action::target".
104         *
105         * The third format is used to represent an action with any type of
106         * target value, including strings.  The target value follows the action
107         * name, surrounded in parens.  For example: "app.action(42)".  The
108         * target value is parsed using g_variant_parse().  If a tuple-typed
109         * value is desired, it must be specified in the same way, resulting in
110         * two sets of parens, for example: "app.action((1,2,3))".  A string
111         * target can be specified this way as well: "app.action('target')".
112         * For strings, this third format must be used if * target value is
113         * empty or contains characters other than alphanumerics, '-' and '.'.
114         *
115         * Params:
116         *     detailedName = a detailed action name
117         *     actionName = the action name
118         *     targetValue = the target value, or %NULL for no target
119         *
120         * Returns: %TRUE if successful, else %FALSE with @error set
121         *
122         * Since: 2.38
123         *
124         * Throws: GException on failure.
125         */
126        public static bool parseDetailedName(string detailedName, out string actionName, out Variant targetValue);
127
128        /**
129         * Formats a detailed action name from @action_name and @target_value.
130         *
131         * It is an error to call this function with an invalid action name.
132         *
133         * This function is the opposite of
134         * g_action_parse_detailed_action_name().  It will produce a string that
135         * can be parsed back to the @action_name and @target_value by that
136         * function.
137         *
138         * See that function for the types of strings that will be printed by
139         * this function.
140         *
141         * Params:
142         *     actionName = a valid action name
143         *     targetValue = a #GVariant target value, or %NULL
144         *
145         * Returns: a detailed format string
146         *
147         * Since: 2.38
148         */
149        public static string printDetailedName(string actionName, Variant targetValue);
150
151        /**
152         * Activates the action.
153         *
154         * @parameter must be the correct type of parameter for the action (ie:
155         * the parameter type given at construction time).  If the parameter
156         * type was %NULL then @parameter must also be %NULL.
157         *
158         * If the @parameter GVariant is floating, it is consumed.
159         *
160         * Params:
161         *     parameter = the parameter to the activation
162         *
163         * Since: 2.28
164         */
165        public void activate(Variant parameter);
166
167        /**
168         * Request for the state of @action to be changed to @value.
169         *
170         * The action must be stateful and @value must be of the correct type.
171         * See g_action_get_state_type().
172         *
173         * This call merely requests a change.  The action may refuse to change
174         * its state or may change its state to something other than @value.
175         * See g_action_get_state_hint().
176         *
177         * If the @value GVariant is floating, it is consumed.
178         *
179         * Params:
180         *     value = the new state
181         *
182         * Since: 2.30
183         */
184        public void changeState(Variant value);
185
186        /**
187         * Checks if @action is currently enabled.
188         *
189         * An action must be enabled in order to be activated or in order to
190         * have its state changed from outside callers.
191         *
192         * Returns: whether the action is enabled
193         *
194         * Since: 2.28
195         */
196        public bool getEnabled();
197
198        /**
199         * Queries the name of @action.
200         *
201         * Returns: the name of the action
202         *
203         * Since: 2.28
204         */
205        public string getName();
206
207        /**
208         * Queries the type of the parameter that must be given when activating
209         * @action.
210         *
211         * When activating the action using g_action_activate(), the #GVariant
212         * given to that function must be of the type returned by this function.
213         *
214         * In the case that this function returns %NULL, you must not give any
215         * #GVariant, but %NULL instead.
216         *
217         * Returns: the parameter type
218         *
219         * Since: 2.28
220         */
221        public VariantType getParameterType();
222
223        /**
224         * Queries the current state of @action.
225         *
226         * If the action is not stateful then %NULL will be returned.  If the
227         * action is stateful then the type of the return value is the type
228         * given by g_action_get_state_type().
229         *
230         * The return value (if non-%NULL) should be freed with
231         * g_variant_unref() when it is no longer required.
232         *
233         * Returns: the current state of the action
234         *
235         * Since: 2.28
236         */
237        public Variant getState();
238
239        /**
240         * Requests a hint about the valid range of values for the state of
241         * @action.
242         *
243         * If %NULL is returned it either means that the action is not stateful
244         * or that there is no hint about the valid range of values for the
245         * state of the action.
246         *
247         * If a #GVariant array is returned then each item in the array is a
248         * possible value for the state.  If a #GVariant pair (ie: two-tuple) is
249         * returned then the tuple specifies the inclusive lower and upper bound
250         * of valid values for the state.
251         *
252         * In any case, the information is merely a hint.  It may be possible to
253         * have a state value outside of the hinted range and setting a value
254         * within the range may fail.
255         *
256         * The return value (if non-%NULL) should be freed with
257         * g_variant_unref() when it is no longer required.
258         *
259         * Returns: the state range hint
260         *
261         * Since: 2.28
262         */
263        public Variant getStateHint();
264
265        /**
266         * Queries the type of the state of @action.
267         *
268         * If the action is stateful (e.g. created with
269         * g_simple_action_new_stateful()) then this function returns the
270         * #GVariantType of the state.  This is the type of the initial value
271         * given as the state. All calls to g_action_change_state() must give a
272         * #GVariant of this type and g_action_get_state() will return a
273         * #GVariant of the same type.
274         *
275         * If the action is not stateful (e.g. created with g_simple_action_new())
276         * then this function will return %NULL. In that case, g_action_get_state()
277         * will return %NULL and you must not call g_action_change_state().
278         *
279         * Returns: the state type, if the action is stateful
280         *
281         * Since: 2.28
282         */
283        public VariantType getStateType();
284}
Note: See TracBrowser for help on using the repository browser.