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