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

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

Initial release

File size: 10.7 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.ActionT;
22
23public  import gi.gio;
24public  import gi.giotypes;
25public  import glib.ErrorG;
26public  import glib.GException;
27public  import glib.Str;
28public  import glib.Variant;
29public  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 template ActionT(TStruct)
64{
65        /** Get the main Gtk struct */
66        public GAction* getActionStruct()
67        {
68                return cast(GAction*)getStruct();
69        }
70
71
72        /**
73         * Checks if @action_name is valid.
74         *
75         * @action_name is valid if it consists only of alphanumeric characters,
76         * plus '-' and '.'.  The empty string is not a valid action name.
77         *
78         * It is an error to call this function with a non-utf8 @action_name.
79         * @action_name must not be %NULL.
80         *
81         * Params:
82         *     actionName = an potential action name
83         *
84         * Returns: %TRUE if @action_name is valid
85         *
86         * Since: 2.38
87         */
88        public static bool nameIsValid(string actionName)
89        {
90                return g_action_name_is_valid(Str.toStringz(actionName)) != 0;
91        }
92
93        /**
94         * Parses a detailed action name into its separate name and target
95         * components.
96         *
97         * Detailed action names can have three formats.
98         *
99         * The first format is used to represent an action name with no target
100         * value and consists of just an action name containing no whitespace
101         * nor the characters ':', '(' or ')'.  For example: "app.action".
102         *
103         * The second format is used to represent an action with a target value
104         * that is a non-empty string consisting only of alphanumerics, plus '-'
105         * and '.'.  In that case, the action name and target value are
106         * separated by a double colon ("::").  For example:
107         * "app.action::target".
108         *
109         * The third format is used to represent an action with any type of
110         * target value, including strings.  The target value follows the action
111         * name, surrounded in parens.  For example: "app.action(42)".  The
112         * target value is parsed using g_variant_parse().  If a tuple-typed
113         * value is desired, it must be specified in the same way, resulting in
114         * two sets of parens, for example: "app.action((1,2,3))".  A string
115         * target can be specified this way as well: "app.action('target')".
116         * For strings, this third format must be used if * target value is
117         * empty or contains characters other than alphanumerics, '-' and '.'.
118         *
119         * Params:
120         *     detailedName = a detailed action name
121         *     actionName = the action name
122         *     targetValue = the target value, or %NULL for no target
123         *
124         * Returns: %TRUE if successful, else %FALSE with @error set
125         *
126         * Since: 2.38
127         *
128         * Throws: GException on failure.
129         */
130        public static bool parseDetailedName(string detailedName, out string actionName, out Variant targetValue)
131        {
132                char* outactionName = null;
133                GVariant* outtargetValue = null;
134                GError* err = null;
135               
136                auto p = g_action_parse_detailed_name(Str.toStringz(detailedName), &outactionName, &outtargetValue, &err) != 0;
137               
138                if (err !is null)
139                {
140                        throw new GException( new ErrorG(err) );
141                }
142               
143                actionName = Str.toString(outactionName);
144                targetValue = new Variant(outtargetValue);
145               
146                return p;
147        }
148
149        /**
150         * Formats a detailed action name from @action_name and @target_value.
151         *
152         * It is an error to call this function with an invalid action name.
153         *
154         * This function is the opposite of
155         * g_action_parse_detailed_action_name().  It will produce a string that
156         * can be parsed back to the @action_name and @target_value by that
157         * function.
158         *
159         * See that function for the types of strings that will be printed by
160         * this function.
161         *
162         * Params:
163         *     actionName = a valid action name
164         *     targetValue = a #GVariant target value, or %NULL
165         *
166         * Returns: a detailed format string
167         *
168         * Since: 2.38
169         */
170        public static string printDetailedName(string actionName, Variant targetValue)
171        {
172                auto retStr = g_action_print_detailed_name(Str.toStringz(actionName), (targetValue is null) ? null : targetValue.getVariantStruct());
173               
174                scope(exit) Str.freeString(retStr);
175                return Str.toString(retStr);
176        }
177
178        /**
179         * Activates the action.
180         *
181         * @parameter must be the correct type of parameter for the action (ie:
182         * the parameter type given at construction time).  If the parameter
183         * type was %NULL then @parameter must also be %NULL.
184         *
185         * If the @parameter GVariant is floating, it is consumed.
186         *
187         * Params:
188         *     parameter = the parameter to the activation
189         *
190         * Since: 2.28
191         */
192        public void activate(Variant parameter)
193        {
194                g_action_activate(getActionStruct(), (parameter is null) ? null : parameter.getVariantStruct());
195        }
196
197        /**
198         * Request for the state of @action to be changed to @value.
199         *
200         * The action must be stateful and @value must be of the correct type.
201         * See g_action_get_state_type().
202         *
203         * This call merely requests a change.  The action may refuse to change
204         * its state or may change its state to something other than @value.
205         * See g_action_get_state_hint().
206         *
207         * If the @value GVariant is floating, it is consumed.
208         *
209         * Params:
210         *     value = the new state
211         *
212         * Since: 2.30
213         */
214        public void changeState(Variant value)
215        {
216                g_action_change_state(getActionStruct(), (value is null) ? null : value.getVariantStruct());
217        }
218
219        /**
220         * Checks if @action is currently enabled.
221         *
222         * An action must be enabled in order to be activated or in order to
223         * have its state changed from outside callers.
224         *
225         * Returns: whether the action is enabled
226         *
227         * Since: 2.28
228         */
229        public bool getEnabled()
230        {
231                return g_action_get_enabled(getActionStruct()) != 0;
232        }
233
234        /**
235         * Queries the name of @action.
236         *
237         * Returns: the name of the action
238         *
239         * Since: 2.28
240         */
241        public string getName()
242        {
243                return Str.toString(g_action_get_name(getActionStruct()));
244        }
245
246        /**
247         * Queries the type of the parameter that must be given when activating
248         * @action.
249         *
250         * When activating the action using g_action_activate(), the #GVariant
251         * given to that function must be of the type returned by this function.
252         *
253         * In the case that this function returns %NULL, you must not give any
254         * #GVariant, but %NULL instead.
255         *
256         * Returns: the parameter type
257         *
258         * Since: 2.28
259         */
260        public VariantType getParameterType()
261        {
262                auto p = g_action_get_parameter_type(getActionStruct());
263               
264                if(p is null)
265                {
266                        return null;
267                }
268               
269                return new VariantType(cast(GVariantType*) p);
270        }
271
272        /**
273         * Queries the current state of @action.
274         *
275         * If the action is not stateful then %NULL will be returned.  If the
276         * action is stateful then the type of the return value is the type
277         * given by g_action_get_state_type().
278         *
279         * The return value (if non-%NULL) should be freed with
280         * g_variant_unref() when it is no longer required.
281         *
282         * Returns: the current state of the action
283         *
284         * Since: 2.28
285         */
286        public Variant getState()
287        {
288                auto p = g_action_get_state(getActionStruct());
289               
290                if(p is null)
291                {
292                        return null;
293                }
294               
295                return new Variant(cast(GVariant*) p, true);
296        }
297
298        /**
299         * Requests a hint about the valid range of values for the state of
300         * @action.
301         *
302         * If %NULL is returned it either means that the action is not stateful
303         * or that there is no hint about the valid range of values for the
304         * state of the action.
305         *
306         * If a #GVariant array is returned then each item in the array is a
307         * possible value for the state.  If a #GVariant pair (ie: two-tuple) is
308         * returned then the tuple specifies the inclusive lower and upper bound
309         * of valid values for the state.
310         *
311         * In any case, the information is merely a hint.  It may be possible to
312         * have a state value outside of the hinted range and setting a value
313         * within the range may fail.
314         *
315         * The return value (if non-%NULL) should be freed with
316         * g_variant_unref() when it is no longer required.
317         *
318         * Returns: the state range hint
319         *
320         * Since: 2.28
321         */
322        public Variant getStateHint()
323        {
324                auto p = g_action_get_state_hint(getActionStruct());
325               
326                if(p is null)
327                {
328                        return null;
329                }
330               
331                return new Variant(cast(GVariant*) p, true);
332        }
333
334        /**
335         * Queries the type of the state of @action.
336         *
337         * If the action is stateful (e.g. created with
338         * g_simple_action_new_stateful()) then this function returns the
339         * #GVariantType of the state.  This is the type of the initial value
340         * given as the state. All calls to g_action_change_state() must give a
341         * #GVariant of this type and g_action_get_state() will return a
342         * #GVariant of the same type.
343         *
344         * If the action is not stateful (e.g. created with g_simple_action_new())
345         * then this function will return %NULL. In that case, g_action_get_state()
346         * will return %NULL and you must not call g_action_change_state().
347         *
348         * Returns: the state type, if the action is stateful
349         *
350         * Since: 2.28
351         */
352        public VariantType getStateType()
353        {
354                auto p = g_action_get_state_type(getActionStruct());
355               
356                if(p is null)
357                {
358                        return null;
359                }
360               
361                return new VariantType(cast(GVariantType*) p);
362        }
363}
Note: See TracBrowser for help on using the repository browser.