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 glib.ErrorG;
28 private import glib.GException;
29 private import glib.Str;
30 private import glib.Variant;
31 private import glib.VariantType;
32 private import gtkc.gio;
33 public  import gtkc.giotypes;
34 
35 
36 /**
37  * #GAction represents a single named action.
38  * 
39  * The main interface to an action is that it can be activated with
40  * g_action_activate().  This results in the 'activate' signal being
41  * emitted.  An activation has a #GVariant parameter (which may be
42  * %NULL).  The correct type for the parameter is determined by a static
43  * parameter type (which is given at construction time).
44  * 
45  * An action may optionally have a state, in which case the state may be
46  * set with g_action_change_state().  This call takes a #GVariant.  The
47  * correct type for the state is determined by a static state type
48  * (which is given at construction time).
49  * 
50  * The state may have a hint associated with it, specifying its valid
51  * range.
52  * 
53  * #GAction is merely the interface to the concept of an action, as
54  * described above.  Various implementations of actions exist, including
55  * #GSimpleAction.
56  * 
57  * In all cases, the implementing class is responsible for storing the
58  * name of the action, the parameter type, the enabled state, the
59  * optional state type and the state and emitting the appropriate
60  * signals when these change.  The implementor is responsible for filtering
61  * calls to g_action_activate() and g_action_change_state() for type
62  * safety and for the state being enabled.
63  * 
64  * Probably the only useful thing to do with a #GAction is to put it
65  * inside of a #GSimpleActionGroup.
66  */
67 public interface ActionIF{
68 	/** Get the main Gtk struct */
69 	public GAction* getActionStruct();
70 
71 	/** the main Gtk struct as a void* */
72 	protected void* getStruct();
73 
74 
75 	/**
76 	 * Checks if @action_name is valid.
77 	 *
78 	 * @action_name is valid if it consists only of alphanumeric characters,
79 	 * plus '-' and '.'.  The empty string is not a valid action name.
80 	 *
81 	 * It is an error to call this function with a non-utf8 @action_name.
82 	 * @action_name must not be %NULL.
83 	 *
84 	 * Params:
85 	 *     actionName = an potential action name
86 	 *
87 	 * Return: %TRUE if @action_name is valid
88 	 *
89 	 * Since: 2.38
90 	 */
91 	public static bool nameIsValid(string actionName);
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 	 * Return: %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 	/**
133 	 * Formats a detailed action name from @action_name and @target_value.
134 	 *
135 	 * It is an error to call this function with an invalid action name.
136 	 *
137 	 * This function is the opposite of g_action_parse_detailed_name().
138 	 * It will produce a string that can be parsed back to the @action_name
139 	 * and @target_value by that function.
140 	 *
141 	 * See that function for the types of strings that will be printed by
142 	 * this function.
143 	 *
144 	 * Params:
145 	 *     actionName = a valid action name
146 	 *     targetValue = a #GVariant target value, or %NULL
147 	 *
148 	 * Return: a detailed format string
149 	 *
150 	 * Since: 2.38
151 	 */
152 	public static string printDetailedName(string actionName, Variant targetValue);
153 
154 	/**
155 	 * Activates the action.
156 	 *
157 	 * @parameter must be the correct type of parameter for the action (ie:
158 	 * the parameter type given at construction time).  If the parameter
159 	 * type was %NULL then @parameter must also be %NULL.
160 	 *
161 	 * If the @parameter GVariant is floating, it is consumed.
162 	 *
163 	 * Params:
164 	 *     parameter = the parameter to the activation
165 	 *
166 	 * Since: 2.28
167 	 */
168 	public void activate(Variant parameter);
169 
170 	/**
171 	 * Request for the state of @action to be changed to @value.
172 	 *
173 	 * The action must be stateful and @value must be of the correct type.
174 	 * See g_action_get_state_type().
175 	 *
176 	 * This call merely requests a change.  The action may refuse to change
177 	 * its state or may change its state to something other than @value.
178 	 * See g_action_get_state_hint().
179 	 *
180 	 * If the @value GVariant is floating, it is consumed.
181 	 *
182 	 * Params:
183 	 *     value = the new state
184 	 *
185 	 * Since: 2.30
186 	 */
187 	public void changeState(Variant value);
188 
189 	/**
190 	 * Checks if @action is currently enabled.
191 	 *
192 	 * An action must be enabled in order to be activated or in order to
193 	 * have its state changed from outside callers.
194 	 *
195 	 * Return: whether the action is enabled
196 	 *
197 	 * Since: 2.28
198 	 */
199 	public bool getEnabled();
200 
201 	/**
202 	 * Queries the name of @action.
203 	 *
204 	 * Return: the name of the action
205 	 *
206 	 * Since: 2.28
207 	 */
208 	public string getName();
209 
210 	/**
211 	 * Queries the type of the parameter that must be given when activating
212 	 * @action.
213 	 *
214 	 * When activating the action using g_action_activate(), the #GVariant
215 	 * given to that function must be of the type returned by this function.
216 	 *
217 	 * In the case that this function returns %NULL, you must not give any
218 	 * #GVariant, but %NULL instead.
219 	 *
220 	 * Return: the parameter type
221 	 *
222 	 * Since: 2.28
223 	 */
224 	public VariantType getParameterType();
225 
226 	/**
227 	 * Queries the current state of @action.
228 	 *
229 	 * If the action is not stateful then %NULL will be returned.  If the
230 	 * action is stateful then the type of the return value is the type
231 	 * given by g_action_get_state_type().
232 	 *
233 	 * The return value (if non-%NULL) should be freed with
234 	 * g_variant_unref() when it is no longer required.
235 	 *
236 	 * Return: the current state of the action
237 	 *
238 	 * Since: 2.28
239 	 */
240 	public Variant getState();
241 
242 	/**
243 	 * Requests a hint about the valid range of values for the state of
244 	 * @action.
245 	 *
246 	 * If %NULL is returned it either means that the action is not stateful
247 	 * or that there is no hint about the valid range of values for the
248 	 * state of the action.
249 	 *
250 	 * If a #GVariant array is returned then each item in the array is a
251 	 * possible value for the state.  If a #GVariant pair (ie: two-tuple) is
252 	 * returned then the tuple specifies the inclusive lower and upper bound
253 	 * of valid values for the state.
254 	 *
255 	 * In any case, the information is merely a hint.  It may be possible to
256 	 * have a state value outside of the hinted range and setting a value
257 	 * within the range may fail.
258 	 *
259 	 * The return value (if non-%NULL) should be freed with
260 	 * g_variant_unref() when it is no longer required.
261 	 *
262 	 * Return: the state range hint
263 	 *
264 	 * Since: 2.28
265 	 */
266 	public Variant getStateHint();
267 
268 	/**
269 	 * Queries the type of the state of @action.
270 	 *
271 	 * If the action is stateful (e.g. created with
272 	 * g_simple_action_new_stateful()) then this function returns the
273 	 * #GVariantType of the state.  This is the type of the initial value
274 	 * given as the state. All calls to g_action_change_state() must give a
275 	 * #GVariant of this type and g_action_get_state() will return a
276 	 * #GVariant of the same type.
277 	 *
278 	 * If the action is not stateful (e.g. created with g_simple_action_new())
279 	 * then this function will return %NULL. In that case, g_action_get_state()
280 	 * will return %NULL and you must not call g_action_change_state().
281 	 *
282 	 * Return: the state type, if the action is stateful
283 	 *
284 	 * Since: 2.28
285 	 */
286 	public VariantType getStateType();
287 }