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