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