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