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.ActionGroupT;
26 
27 public  import gio.c.functions;
28 public  import gio.c.types;
29 public  import glib.Str;
30 public  import glib.Variant;
31 public  import glib.VariantType;
32 public  import gobject.Signals;
33 public  import gtkc.giotypes;
34 public  import std.algorithm;
35 
36 
37 /**
38  * #GActionGroup represents a group of actions. Actions can be used to
39  * expose functionality in a structured way, either from one part of a
40  * program to another, or to the outside world. Action groups are often
41  * used together with a #GMenuModel that provides additional
42  * representation data for displaying the actions to the user, e.g. in
43  * a menu.
44  * 
45  * The main way to interact with the actions in a GActionGroup is to
46  * activate them with g_action_group_activate_action(). Activating an
47  * action may require a #GVariant parameter. The required type of the
48  * parameter can be inquired with g_action_group_get_action_parameter_type().
49  * Actions may be disabled, see g_action_group_get_action_enabled().
50  * Activating a disabled action has no effect.
51  * 
52  * Actions may optionally have a state in the form of a #GVariant. The
53  * current state of an action can be inquired with
54  * g_action_group_get_action_state(). Activating a stateful action may
55  * change its state, but it is also possible to set the state by calling
56  * g_action_group_change_action_state().
57  * 
58  * As typical example, consider a text editing application which has an
59  * option to change the current font to 'bold'. A good way to represent
60  * this would be a stateful action, with a boolean state. Activating the
61  * action would toggle the state.
62  * 
63  * Each action in the group has a unique name (which is a string).  All
64  * method calls, except g_action_group_list_actions() take the name of
65  * an action as an argument.
66  * 
67  * The #GActionGroup API is meant to be the 'public' API to the action
68  * group.  The calls here are exactly the interaction that 'external
69  * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
70  * with actions.  'Internal' APIs (ie: ones meant only to be accessed by
71  * the action group implementation) are found on subclasses.  This is
72  * why you will find - for example - g_action_group_get_action_enabled()
73  * but not an equivalent set() call.
74  * 
75  * Signals are emitted on the action group in response to state changes
76  * on individual actions.
77  * 
78  * Implementations of #GActionGroup should provide implementations for
79  * the virtual functions g_action_group_list_actions() and
80  * g_action_group_query_action().  The other virtual functions should
81  * not be implemented - their "wrappers" are actually implemented with
82  * calls to g_action_group_query_action().
83  */
84 public template ActionGroupT(TStruct)
85 {
86 	/** Get the main Gtk struct */
87 	public GActionGroup* getActionGroupStruct(bool transferOwnership = false)
88 	{
89 		if (transferOwnership)
90 			ownedRef = false;
91 		return cast(GActionGroup*)getStruct();
92 	}
93 
94 
95 	/**
96 	 * Emits the #GActionGroup::action-added signal on @action_group.
97 	 *
98 	 * This function should only be called by #GActionGroup implementations.
99 	 *
100 	 * Params:
101 	 *     actionName = the name of an action in the group
102 	 *
103 	 * Since: 2.28
104 	 */
105 	public void actionAdded(string actionName)
106 	{
107 		g_action_group_action_added(getActionGroupStruct(), Str.toStringz(actionName));
108 	}
109 
110 	/**
111 	 * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
112 	 *
113 	 * This function should only be called by #GActionGroup implementations.
114 	 *
115 	 * Params:
116 	 *     actionName = the name of an action in the group
117 	 *     enabled = whether or not the action is now enabled
118 	 *
119 	 * Since: 2.28
120 	 */
121 	public void actionEnabledChanged(string actionName, bool enabled)
122 	{
123 		g_action_group_action_enabled_changed(getActionGroupStruct(), Str.toStringz(actionName), enabled);
124 	}
125 
126 	/**
127 	 * Emits the #GActionGroup::action-removed signal on @action_group.
128 	 *
129 	 * This function should only be called by #GActionGroup implementations.
130 	 *
131 	 * Params:
132 	 *     actionName = the name of an action in the group
133 	 *
134 	 * Since: 2.28
135 	 */
136 	public void actionRemoved(string actionName)
137 	{
138 		g_action_group_action_removed(getActionGroupStruct(), Str.toStringz(actionName));
139 	}
140 
141 	/**
142 	 * Emits the #GActionGroup::action-state-changed signal on @action_group.
143 	 *
144 	 * This function should only be called by #GActionGroup implementations.
145 	 *
146 	 * Params:
147 	 *     actionName = the name of an action in the group
148 	 *     state = the new state of the named action
149 	 *
150 	 * Since: 2.28
151 	 */
152 	public void actionStateChanged(string actionName, Variant state)
153 	{
154 		g_action_group_action_state_changed(getActionGroupStruct(), Str.toStringz(actionName), (state is null) ? null : state.getVariantStruct());
155 	}
156 
157 	/**
158 	 * Activate the named action within @action_group.
159 	 *
160 	 * If the action is expecting a parameter, then the correct type of
161 	 * parameter must be given as @parameter.  If the action is expecting no
162 	 * parameters then @parameter must be %NULL.  See
163 	 * g_action_group_get_action_parameter_type().
164 	 *
165 	 * Params:
166 	 *     actionName = the name of the action to activate
167 	 *     parameter = parameters to the activation
168 	 *
169 	 * Since: 2.28
170 	 */
171 	public void activateAction(string actionName, Variant parameter)
172 	{
173 		g_action_group_activate_action(getActionGroupStruct(), Str.toStringz(actionName), (parameter is null) ? null : parameter.getVariantStruct());
174 	}
175 
176 	/**
177 	 * Request for the state of the named action within @action_group to be
178 	 * changed to @value.
179 	 *
180 	 * The action must be stateful and @value must be of the correct type.
181 	 * See g_action_group_get_action_state_type().
182 	 *
183 	 * This call merely requests a change.  The action may refuse to change
184 	 * its state or may change its state to something other than @value.
185 	 * See g_action_group_get_action_state_hint().
186 	 *
187 	 * If the @value GVariant is floating, it is consumed.
188 	 *
189 	 * Params:
190 	 *     actionName = the name of the action to request the change on
191 	 *     value = the new state
192 	 *
193 	 * Since: 2.28
194 	 */
195 	public void changeActionState(string actionName, Variant value)
196 	{
197 		g_action_group_change_action_state(getActionGroupStruct(), Str.toStringz(actionName), (value is null) ? null : value.getVariantStruct());
198 	}
199 
200 	/**
201 	 * Checks if the named action within @action_group is currently enabled.
202 	 *
203 	 * An action must be enabled in order to be activated or in order to
204 	 * have its state changed from outside callers.
205 	 *
206 	 * Params:
207 	 *     actionName = the name of the action to query
208 	 *
209 	 * Returns: whether or not the action is currently enabled
210 	 *
211 	 * Since: 2.28
212 	 */
213 	public bool getActionEnabled(string actionName)
214 	{
215 		return g_action_group_get_action_enabled(getActionGroupStruct(), Str.toStringz(actionName)) != 0;
216 	}
217 
218 	/**
219 	 * Queries the type of the parameter that must be given when activating
220 	 * the named action within @action_group.
221 	 *
222 	 * When activating the action using g_action_group_activate_action(),
223 	 * the #GVariant given to that function must be of the type returned
224 	 * by this function.
225 	 *
226 	 * In the case that this function returns %NULL, you must not give any
227 	 * #GVariant, but %NULL instead.
228 	 *
229 	 * The parameter type of a particular action will never change but it is
230 	 * possible for an action to be removed and for a new action to be added
231 	 * with the same name but a different parameter type.
232 	 *
233 	 * Params:
234 	 *     actionName = the name of the action to query
235 	 *
236 	 * Returns: the parameter type
237 	 *
238 	 * Since: 2.28
239 	 */
240 	public VariantType getActionParameterType(string actionName)
241 	{
242 		auto p = g_action_group_get_action_parameter_type(getActionGroupStruct(), Str.toStringz(actionName));
243 
244 		if(p is null)
245 		{
246 			return null;
247 		}
248 
249 		return new VariantType(cast(GVariantType*) p);
250 	}
251 
252 	/**
253 	 * Queries the current state of the named action within @action_group.
254 	 *
255 	 * If the action is not stateful then %NULL will be returned.  If the
256 	 * action is stateful then the type of the return value is the type
257 	 * given by g_action_group_get_action_state_type().
258 	 *
259 	 * The return value (if non-%NULL) should be freed with
260 	 * g_variant_unref() when it is no longer required.
261 	 *
262 	 * Params:
263 	 *     actionName = the name of the action to query
264 	 *
265 	 * Returns: the current state of the action
266 	 *
267 	 * Since: 2.28
268 	 */
269 	public Variant getActionState(string actionName)
270 	{
271 		auto p = g_action_group_get_action_state(getActionGroupStruct(), Str.toStringz(actionName));
272 
273 		if(p is null)
274 		{
275 			return null;
276 		}
277 
278 		return new Variant(cast(GVariant*) p, true);
279 	}
280 
281 	/**
282 	 * Requests a hint about the valid range of values for the state of the
283 	 * named action within @action_group.
284 	 *
285 	 * If %NULL is returned it either means that the action is not stateful
286 	 * or that there is no hint about the valid range of values for the
287 	 * state of the action.
288 	 *
289 	 * If a #GVariant array is returned then each item in the array is a
290 	 * possible value for the state.  If a #GVariant pair (ie: two-tuple) is
291 	 * returned then the tuple specifies the inclusive lower and upper bound
292 	 * of valid values for the state.
293 	 *
294 	 * In any case, the information is merely a hint.  It may be possible to
295 	 * have a state value outside of the hinted range and setting a value
296 	 * within the range may fail.
297 	 *
298 	 * The return value (if non-%NULL) should be freed with
299 	 * g_variant_unref() when it is no longer required.
300 	 *
301 	 * Params:
302 	 *     actionName = the name of the action to query
303 	 *
304 	 * Returns: the state range hint
305 	 *
306 	 * Since: 2.28
307 	 */
308 	public Variant getActionStateHint(string actionName)
309 	{
310 		auto p = g_action_group_get_action_state_hint(getActionGroupStruct(), Str.toStringz(actionName));
311 
312 		if(p is null)
313 		{
314 			return null;
315 		}
316 
317 		return new Variant(cast(GVariant*) p, true);
318 	}
319 
320 	/**
321 	 * Queries the type of the state of the named action within
322 	 * @action_group.
323 	 *
324 	 * If the action is stateful then this function returns the
325 	 * #GVariantType of the state.  All calls to
326 	 * g_action_group_change_action_state() must give a #GVariant of this
327 	 * type and g_action_group_get_action_state() will return a #GVariant
328 	 * of the same type.
329 	 *
330 	 * If the action is not stateful then this function will return %NULL.
331 	 * In that case, g_action_group_get_action_state() will return %NULL
332 	 * and you must not call g_action_group_change_action_state().
333 	 *
334 	 * The state type of a particular action will never change but it is
335 	 * possible for an action to be removed and for a new action to be added
336 	 * with the same name but a different state type.
337 	 *
338 	 * Params:
339 	 *     actionName = the name of the action to query
340 	 *
341 	 * Returns: the state type, if the action is stateful
342 	 *
343 	 * Since: 2.28
344 	 */
345 	public VariantType getActionStateType(string actionName)
346 	{
347 		auto p = g_action_group_get_action_state_type(getActionGroupStruct(), Str.toStringz(actionName));
348 
349 		if(p is null)
350 		{
351 			return null;
352 		}
353 
354 		return new VariantType(cast(GVariantType*) p);
355 	}
356 
357 	/**
358 	 * Checks if the named action exists within @action_group.
359 	 *
360 	 * Params:
361 	 *     actionName = the name of the action to check for
362 	 *
363 	 * Returns: whether the named action exists
364 	 *
365 	 * Since: 2.28
366 	 */
367 	public bool hasAction(string actionName)
368 	{
369 		return g_action_group_has_action(getActionGroupStruct(), Str.toStringz(actionName)) != 0;
370 	}
371 
372 	/**
373 	 * Lists the actions contained within @action_group.
374 	 *
375 	 * The caller is responsible for freeing the list with g_strfreev() when
376 	 * it is no longer required.
377 	 *
378 	 * Returns: a %NULL-terminated array of the names of the
379 	 *     actions in the group
380 	 *
381 	 * Since: 2.28
382 	 */
383 	public string[] listActions()
384 	{
385 		auto retStr = g_action_group_list_actions(getActionGroupStruct());
386 
387 		scope(exit) Str.freeStringArray(retStr);
388 		return Str.toStringArray(retStr);
389 	}
390 
391 	/**
392 	 * Queries all aspects of the named action within an @action_group.
393 	 *
394 	 * This function acquires the information available from
395 	 * g_action_group_has_action(), g_action_group_get_action_enabled(),
396 	 * g_action_group_get_action_parameter_type(),
397 	 * g_action_group_get_action_state_type(),
398 	 * g_action_group_get_action_state_hint() and
399 	 * g_action_group_get_action_state() with a single function call.
400 	 *
401 	 * This provides two main benefits.
402 	 *
403 	 * The first is the improvement in efficiency that comes with not having
404 	 * to perform repeated lookups of the action in order to discover
405 	 * different things about it.  The second is that implementing
406 	 * #GActionGroup can now be done by only overriding this one virtual
407 	 * function.
408 	 *
409 	 * The interface provides a default implementation of this function that
410 	 * calls the individual functions, as required, to fetch the
411 	 * information.  The interface also provides default implementations of
412 	 * those functions that call this function.  All implementations,
413 	 * therefore, must override either this function or all of the others.
414 	 *
415 	 * If the action exists, %TRUE is returned and any of the requested
416 	 * fields (as indicated by having a non-%NULL reference passed in) are
417 	 * filled.  If the action doesn't exist, %FALSE is returned and the
418 	 * fields may or may not have been modified.
419 	 *
420 	 * Params:
421 	 *     actionName = the name of an action in the group
422 	 *     enabled = if the action is presently enabled
423 	 *     parameterType = the parameter type, or %NULL if none needed
424 	 *     stateType = the state type, or %NULL if stateless
425 	 *     stateHint = the state hint, or %NULL if none
426 	 *     state = the current state, or %NULL if stateless
427 	 *
428 	 * Returns: %TRUE if the action exists, else %FALSE
429 	 *
430 	 * Since: 2.32
431 	 */
432 	public bool queryAction(string actionName, out bool enabled, out VariantType parameterType, out VariantType stateType, out Variant stateHint, out Variant state)
433 	{
434 		int outenabled;
435 		GVariantType* outparameterType = null;
436 		GVariantType* outstateType = null;
437 		GVariant* outstateHint = null;
438 		GVariant* outstate = null;
439 
440 		auto p = g_action_group_query_action(getActionGroupStruct(), Str.toStringz(actionName), &outenabled, &outparameterType, &outstateType, &outstateHint, &outstate) != 0;
441 
442 		enabled = (outenabled == 1);
443 		parameterType = new VariantType(outparameterType);
444 		stateType = new VariantType(outstateType);
445 		stateHint = new Variant(outstateHint);
446 		state = new Variant(outstate);
447 
448 		return p;
449 	}
450 
451 	/**
452 	 * Signals that a new action was just added to the group.
453 	 * This signal is emitted after the action has been added
454 	 * and is now visible.
455 	 *
456 	 * Params:
457 	 *     actionName = the name of the action in @action_group
458 	 *
459 	 * Since: 2.28
460 	 */
461 	gulong addOnActionAdded(void delegate(string, ActionGroupIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
462 	{
463 		return Signals.connect(this, "action-added", dlg, connectFlags ^ ConnectFlags.SWAPPED);
464 	}
465 
466 	/**
467 	 * Signals that the enabled status of the named action has changed.
468 	 *
469 	 * Params:
470 	 *     actionName = the name of the action in @action_group
471 	 *     enabled = whether the action is enabled or not
472 	 *
473 	 * Since: 2.28
474 	 */
475 	gulong addOnActionEnabledChanged(void delegate(string, bool, ActionGroupIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
476 	{
477 		return Signals.connect(this, "action-enabled-changed", dlg, connectFlags ^ ConnectFlags.SWAPPED);
478 	}
479 
480 	/**
481 	 * Signals that an action is just about to be removed from the group.
482 	 * This signal is emitted before the action is removed, so the action
483 	 * is still visible and can be queried from the signal handler.
484 	 *
485 	 * Params:
486 	 *     actionName = the name of the action in @action_group
487 	 *
488 	 * Since: 2.28
489 	 */
490 	gulong addOnActionRemoved(void delegate(string, ActionGroupIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
491 	{
492 		return Signals.connect(this, "action-removed", dlg, connectFlags ^ ConnectFlags.SWAPPED);
493 	}
494 
495 	/**
496 	 * Signals that the state of the named action has changed.
497 	 *
498 	 * Params:
499 	 *     actionName = the name of the action in @action_group
500 	 *     value = the new value of the state
501 	 *
502 	 * Since: 2.28
503 	 */
504 	gulong addOnActionStateChanged(void delegate(string, Variant, ActionGroupIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
505 	{
506 		return Signals.connect(this, "action-state-changed", dlg, connectFlags ^ ConnectFlags.SWAPPED);
507 	}
508 }