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 /** 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 /** 140 * Formats a detailed action name from @action_name and @target_value. 141 * 142 * It is an error to call this function with an invalid action name. 143 * 144 * This function is the opposite of g_action_parse_detailed_name(). 145 * It will produce a string that can be parsed back to the @action_name 146 * and @target_value by that function. 147 * 148 * See that function for the types of strings that will be printed by 149 * this function. 150 * 151 * Params: 152 * actionName = a valid action name 153 * targetValue = a #GVariant target value, or %NULL 154 * 155 * Returns: a detailed format string 156 * 157 * Since: 2.38 158 */ 159 public static string printDetailedName(string actionName, Variant targetValue); 160 161 /** 162 * Activates the action. 163 * 164 * @parameter must be the correct type of parameter for the action (ie: 165 * the parameter type given at construction time). If the parameter 166 * type was %NULL then @parameter must also be %NULL. 167 * 168 * If the @parameter GVariant is floating, it is consumed. 169 * 170 * Params: 171 * parameter = the parameter to the activation 172 * 173 * Since: 2.28 174 */ 175 public void activate(Variant parameter); 176 177 /** 178 * Request for the state of @action to be changed to @value. 179 * 180 * The action must be stateful and @value must be of the correct type. 181 * See g_action_get_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_get_state_hint(). 186 * 187 * If the @value GVariant is floating, it is consumed. 188 * 189 * Params: 190 * value = the new state 191 * 192 * Since: 2.30 193 */ 194 public void changeState(Variant value); 195 196 /** 197 * Checks if @action is currently enabled. 198 * 199 * An action must be enabled in order to be activated or in order to 200 * have its state changed from outside callers. 201 * 202 * Returns: whether the action is enabled 203 * 204 * Since: 2.28 205 */ 206 public bool getEnabled(); 207 208 /** 209 * Queries the name of @action. 210 * 211 * Returns: the name of the action 212 * 213 * Since: 2.28 214 */ 215 public string getName(); 216 217 /** 218 * Queries the type of the parameter that must be given when activating 219 * @action. 220 * 221 * When activating the action using g_action_activate(), the #GVariant 222 * given to that function must be of the type returned by this function. 223 * 224 * In the case that this function returns %NULL, you must not give any 225 * #GVariant, but %NULL instead. 226 * 227 * Returns: the parameter type 228 * 229 * Since: 2.28 230 */ 231 public VariantType getParameterType(); 232 233 /** 234 * Queries the current state of @action. 235 * 236 * If the action is not stateful then %NULL will be returned. If the 237 * action is stateful then the type of the return value is the type 238 * given by g_action_get_state_type(). 239 * 240 * The return value (if non-%NULL) should be freed with 241 * g_variant_unref() when it is no longer required. 242 * 243 * Returns: the current state of the action 244 * 245 * Since: 2.28 246 */ 247 public Variant getState(); 248 249 /** 250 * Requests a hint about the valid range of values for the state of 251 * @action. 252 * 253 * If %NULL is returned it either means that the action is not stateful 254 * or that there is no hint about the valid range of values for the 255 * state of the action. 256 * 257 * If a #GVariant array is returned then each item in the array is a 258 * possible value for the state. If a #GVariant pair (ie: two-tuple) is 259 * returned then the tuple specifies the inclusive lower and upper bound 260 * of valid values for the state. 261 * 262 * In any case, the information is merely a hint. It may be possible to 263 * have a state value outside of the hinted range and setting a value 264 * within the range may fail. 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 state range hint 270 * 271 * Since: 2.28 272 */ 273 public Variant getStateHint(); 274 275 /** 276 * Queries the type of the state of @action. 277 * 278 * If the action is stateful (e.g. created with 279 * g_simple_action_new_stateful()) then this function returns the 280 * #GVariantType of the state. This is the type of the initial value 281 * given as the state. All calls to g_action_change_state() must give a 282 * #GVariant of this type and g_action_get_state() will return a 283 * #GVariant of the same type. 284 * 285 * If the action is not stateful (e.g. created with g_simple_action_new()) 286 * then this function will return %NULL. In that case, g_action_get_state() 287 * will return %NULL and you must not call g_action_change_state(). 288 * 289 * Returns: the state type, if the action is stateful 290 * 291 * Since: 2.28 292 */ 293 public VariantType getStateType(); 294 }