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 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 77 /** 78 * Checks if @action_name is valid. 79 * 80 * @action_name is valid if it consists only of alphanumeric characters, 81 * plus '-' and '.'. The empty string is not a valid action name. 82 * 83 * It is an error to call this function with a non-utf8 @action_name. 84 * @action_name must not be %NULL. 85 * 86 * Params: 87 * actionName = an potential action name 88 * 89 * Return: %TRUE if @action_name is valid 90 * 91 * Since: 2.38 92 */ 93 public static bool nameIsValid(string actionName); 94 95 /** 96 * Parses a detailed action name into its separate name and target 97 * components. 98 * 99 * Detailed action names can have three formats. 100 * 101 * The first format is used to represent an action name with no target 102 * value and consists of just an action name containing no whitespace 103 * nor the characters ':', '(' or ')'. For example: "app.action". 104 * 105 * The second format is used to represent an action with a target value 106 * that is a non-empty string consisting only of alphanumerics, plus '-' 107 * and '.'. In that case, the action name and target value are 108 * separated by a double colon ("::"). For example: 109 * "app.action::target". 110 * 111 * The third format is used to represent an action with any type of 112 * target value, including strings. The target value follows the action 113 * name, surrounded in parens. For example: "app.action(42)". The 114 * target value is parsed using g_variant_parse(). If a tuple-typed 115 * value is desired, it must be specified in the same way, resulting in 116 * two sets of parens, for example: "app.action((1,2,3))". A string 117 * target can be specified this way as well: "app.action('target')". 118 * For strings, this third format must be used if * target value is 119 * empty or contains characters other than alphanumerics, '-' and '.'. 120 * 121 * Params: 122 * detailedName = a detailed action name 123 * actionName = the action name 124 * targetValue = the target value, or %NULL for no target 125 * 126 * Return: %TRUE if successful, else %FALSE with @error set 127 * 128 * Since: 2.38 129 * 130 * Throws: GException on failure. 131 */ 132 public static bool parseDetailedName(string detailedName, out string actionName, out Variant targetValue); 133 134 /** 135 * Formats a detailed action name from @action_name and @target_value. 136 * 137 * It is an error to call this function with an invalid action name. 138 * 139 * This function is the opposite of 140 * g_action_parse_detailed_action_name(). It will produce a string that 141 * can be parsed back to the @action_name and @target_value by that 142 * function. 143 * 144 * See that function for the types of strings that will be printed by 145 * this function. 146 * 147 * Params: 148 * actionName = a valid action name 149 * targetValue = a #GVariant target value, or %NULL 150 * 151 * Return: a detailed format string 152 * 153 * Since: 2.38 154 */ 155 public static string printDetailedName(string actionName, Variant targetValue); 156 157 /** 158 * Activates the action. 159 * 160 * @parameter must be the correct type of parameter for the action (ie: 161 * the parameter type given at construction time). If the parameter 162 * type was %NULL then @parameter must also be %NULL. 163 * 164 * If the @parameter GVariant is floating, it is consumed. 165 * 166 * Params: 167 * parameter = the parameter to the activation 168 * 169 * Since: 2.28 170 */ 171 public void activate(Variant parameter); 172 173 /** 174 * Request for the state of @action to be changed to @value. 175 * 176 * The action must be stateful and @value must be of the correct type. 177 * See g_action_get_state_type(). 178 * 179 * This call merely requests a change. The action may refuse to change 180 * its state or may change its state to something other than @value. 181 * See g_action_get_state_hint(). 182 * 183 * If the @value GVariant is floating, it is consumed. 184 * 185 * Params: 186 * value = the new state 187 * 188 * Since: 2.30 189 */ 190 public void changeState(Variant value); 191 192 /** 193 * Checks if @action is currently enabled. 194 * 195 * An action must be enabled in order to be activated or in order to 196 * have its state changed from outside callers. 197 * 198 * Return: whether the action is enabled 199 * 200 * Since: 2.28 201 */ 202 public bool getEnabled(); 203 204 /** 205 * Queries the name of @action. 206 * 207 * Return: the name of the action 208 * 209 * Since: 2.28 210 */ 211 public string getName(); 212 213 /** 214 * Queries the type of the parameter that must be given when activating 215 * @action. 216 * 217 * When activating the action using g_action_activate(), the #GVariant 218 * given to that function must be of the type returned by this function. 219 * 220 * In the case that this function returns %NULL, you must not give any 221 * #GVariant, but %NULL instead. 222 * 223 * Return: the parameter type 224 * 225 * Since: 2.28 226 */ 227 public VariantType getParameterType(); 228 229 /** 230 * Queries the current state of @action. 231 * 232 * If the action is not stateful then %NULL will be returned. If the 233 * action is stateful then the type of the return value is the type 234 * given by g_action_get_state_type(). 235 * 236 * The return value (if non-%NULL) should be freed with 237 * g_variant_unref() when it is no longer required. 238 * 239 * Return: the current state of the action 240 * 241 * Since: 2.28 242 */ 243 public Variant getState(); 244 245 /** 246 * Requests a hint about the valid range of values for the state of 247 * @action. 248 * 249 * If %NULL is returned it either means that the action is not stateful 250 * or that there is no hint about the valid range of values for the 251 * state of the action. 252 * 253 * If a #GVariant array is returned then each item in the array is a 254 * possible value for the state. If a #GVariant pair (ie: two-tuple) is 255 * returned then the tuple specifies the inclusive lower and upper bound 256 * of valid values for the state. 257 * 258 * In any case, the information is merely a hint. It may be possible to 259 * have a state value outside of the hinted range and setting a value 260 * within the range may fail. 261 * 262 * The return value (if non-%NULL) should be freed with 263 * g_variant_unref() when it is no longer required. 264 * 265 * Return: the state range hint 266 * 267 * Since: 2.28 268 */ 269 public Variant getStateHint(); 270 271 /** 272 * Queries the type of the state of @action. 273 * 274 * If the action is stateful (e.g. created with 275 * g_simple_action_new_stateful()) then this function returns the 276 * #GVariantType of the state. This is the type of the initial value 277 * given as the state. All calls to g_action_change_state() must give a 278 * #GVariant of this type and g_action_get_state() will return a 279 * #GVariant of the same type. 280 * 281 * If the action is not stateful (e.g. created with g_simple_action_new()) 282 * then this function will return %NULL. In that case, g_action_get_state() 283 * will return %NULL and you must not call g_action_change_state(). 284 * 285 * Return: the state type, if the action is stateful 286 * 287 * Since: 2.28 288 */ 289 public VariantType getStateType(); 290 }