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 gtk.AccelGroup; 26 27 private import gdk.Display; 28 private import glib.ConstructionException; 29 private import glib.ListSG; 30 private import glib.Str; 31 private import gobject.Closure; 32 private import gobject.ObjectG; 33 private import gobject.Signals; 34 public import gtkc.gdktypes; 35 private import gtkc.gtk; 36 public import gtkc.gtktypes; 37 38 39 /** 40 * A #GtkAccelGroup represents a group of keyboard accelerators, 41 * typically attached to a toplevel #GtkWindow (with 42 * gtk_window_add_accel_group()). Usually you won’t need to create a 43 * #GtkAccelGroup directly; instead, when using #GtkUIManager, GTK+ 44 * automatically sets up the accelerators for your menus in the ui 45 * manager’s #GtkAccelGroup. 46 * 47 * Note that “accelerators” are different from 48 * “mnemonics”. Accelerators are shortcuts for 49 * activating a menu item; they appear alongside the menu item they’re a 50 * shortcut for. For example “Ctrl+Q” might appear alongside the “Quit” 51 * menu item. Mnemonics are shortcuts for GUI elements such as text 52 * entries or buttons; they appear as underlined characters. See 53 * gtk_label_new_with_mnemonic(). Menu items can have both accelerators 54 * and mnemonics, of course. 55 */ 56 public class AccelGroup : ObjectG 57 { 58 /** the main Gtk struct */ 59 protected GtkAccelGroup* gtkAccelGroup; 60 61 /** Get the main Gtk struct */ 62 public GtkAccelGroup* getAccelGroupStruct() 63 { 64 return gtkAccelGroup; 65 } 66 67 /** the main Gtk struct as a void* */ 68 protected override void* getStruct() 69 { 70 return cast(void*)gtkAccelGroup; 71 } 72 73 protected override void setStruct(GObject* obj) 74 { 75 gtkAccelGroup = cast(GtkAccelGroup*)obj; 76 super.setStruct(obj); 77 } 78 79 /** 80 * Sets our main struct and passes it to the parent class. 81 */ 82 public this (GtkAccelGroup* gtkAccelGroup, bool ownedRef = false) 83 { 84 this.gtkAccelGroup = gtkAccelGroup; 85 super(cast(GObject*)gtkAccelGroup, ownedRef); 86 } 87 88 /** 89 */ 90 91 public static GType getType() 92 { 93 return gtk_accel_group_get_type(); 94 } 95 96 /** 97 * Creates a new #GtkAccelGroup. 98 * 99 * Return: a new #GtkAccelGroup object 100 * 101 * Throws: ConstructionException GTK+ fails to create the object. 102 */ 103 public this() 104 { 105 auto p = gtk_accel_group_new(); 106 107 if(p is null) 108 { 109 throw new ConstructionException("null returned by new"); 110 } 111 112 this(cast(GtkAccelGroup*) p, true); 113 } 114 115 /** 116 * Finds the #GtkAccelGroup to which @closure is connected; 117 * see gtk_accel_group_connect(). 118 * 119 * Params: 120 * closure = a #GClosure 121 * 122 * Return: the #GtkAccelGroup to which @closure 123 * is connected, or %NULL 124 */ 125 public static AccelGroup fromAccelClosure(Closure closure) 126 { 127 auto p = gtk_accel_group_from_accel_closure((closure is null) ? null : closure.getClosureStruct()); 128 129 if(p is null) 130 { 131 return null; 132 } 133 134 return ObjectG.getDObject!(AccelGroup)(cast(GtkAccelGroup*) p); 135 } 136 137 /** 138 * Finds the first accelerator in @accel_group that matches 139 * @accel_key and @accel_mods, and activates it. 140 * 141 * Params: 142 * accelQuark = the quark for the accelerator name 143 * acceleratable = the #GObject, usually a #GtkWindow, on which 144 * to activate the accelerator 145 * accelKey = accelerator keyval from a key event 146 * accelMods = keyboard state mask from a key event 147 * 148 * Return: %TRUE if an accelerator was activated and handled 149 * this keypress 150 */ 151 public bool activate(GQuark accelQuark, ObjectG acceleratable, uint accelKey, GdkModifierType accelMods) 152 { 153 return gtk_accel_group_activate(gtkAccelGroup, accelQuark, (acceleratable is null) ? null : acceleratable.getObjectGStruct(), accelKey, accelMods) != 0; 154 } 155 156 /** 157 * Installs an accelerator in this group. When @accel_group is being 158 * activated in response to a call to gtk_accel_groups_activate(), 159 * @closure will be invoked if the @accel_key and @accel_mods from 160 * gtk_accel_groups_activate() match those of this connection. 161 * 162 * The signature used for the @closure is that of #GtkAccelGroupActivate. 163 * 164 * Note that, due to implementation details, a single closure can 165 * only be connected to one accelerator group. 166 * 167 * Params: 168 * accelKey = key value of the accelerator 169 * accelMods = modifier combination of the accelerator 170 * accelFlags = a flag mask to configure this accelerator 171 * closure = closure to be executed upon accelerator activation 172 */ 173 public void connect(uint accelKey, GdkModifierType accelMods, GtkAccelFlags accelFlags, Closure closure) 174 { 175 gtk_accel_group_connect(gtkAccelGroup, accelKey, accelMods, accelFlags, (closure is null) ? null : closure.getClosureStruct()); 176 } 177 178 /** 179 * Installs an accelerator in this group, using an accelerator path 180 * to look up the appropriate key and modifiers (see 181 * gtk_accel_map_add_entry()). When @accel_group is being activated 182 * in response to a call to gtk_accel_groups_activate(), @closure will 183 * be invoked if the @accel_key and @accel_mods from 184 * gtk_accel_groups_activate() match the key and modifiers for the path. 185 * 186 * The signature used for the @closure is that of #GtkAccelGroupActivate. 187 * 188 * Note that @accel_path string will be stored in a #GQuark. Therefore, 189 * if you pass a static string, you can save some memory by interning it 190 * first with g_intern_static_string(). 191 * 192 * Params: 193 * accelPath = path used for determining key and modifiers 194 * closure = closure to be executed upon accelerator activation 195 */ 196 public void connectByPath(string accelPath, Closure closure) 197 { 198 gtk_accel_group_connect_by_path(gtkAccelGroup, Str.toStringz(accelPath), (closure is null) ? null : closure.getClosureStruct()); 199 } 200 201 /** 202 * Removes an accelerator previously installed through 203 * gtk_accel_group_connect(). 204 * 205 * Since 2.20 @closure can be %NULL. 206 * 207 * Params: 208 * closure = the closure to remove from this accelerator 209 * group, or %NULL to remove all closures 210 * 211 * Return: %TRUE if the closure was found and got disconnected 212 */ 213 public bool disconnect(Closure closure) 214 { 215 return gtk_accel_group_disconnect(gtkAccelGroup, (closure is null) ? null : closure.getClosureStruct()) != 0; 216 } 217 218 /** 219 * Removes an accelerator previously installed through 220 * gtk_accel_group_connect(). 221 * 222 * Params: 223 * accelKey = key value of the accelerator 224 * accelMods = modifier combination of the accelerator 225 * 226 * Return: %TRUE if there was an accelerator which could be 227 * removed, %FALSE otherwise 228 */ 229 public bool disconnectKey(uint accelKey, GdkModifierType accelMods) 230 { 231 return gtk_accel_group_disconnect_key(gtkAccelGroup, accelKey, accelMods) != 0; 232 } 233 234 /** 235 * Finds the first entry in an accelerator group for which 236 * @find_func returns %TRUE and returns its #GtkAccelKey. 237 * 238 * Params: 239 * findFunc = a function to filter the entries 240 * of @accel_group with 241 * data = data to pass to @find_func 242 * 243 * Return: the key of the first entry passing 244 * @find_func. The key is owned by GTK+ and must not be freed. 245 */ 246 public GtkAccelKey* find(GtkAccelGroupFindFunc findFunc, void* data) 247 { 248 return gtk_accel_group_find(gtkAccelGroup, findFunc, data); 249 } 250 251 /** 252 * Locks are added and removed using gtk_accel_group_lock() and 253 * gtk_accel_group_unlock(). 254 * 255 * Return: %TRUE if there are 1 or more locks on the @accel_group, 256 * %FALSE otherwise. 257 * 258 * Since: 2.14 259 */ 260 public bool getIsLocked() 261 { 262 return gtk_accel_group_get_is_locked(gtkAccelGroup) != 0; 263 } 264 265 /** 266 * Gets a #GdkModifierType representing the mask for this 267 * @accel_group. For example, #GDK_CONTROL_MASK, #GDK_SHIFT_MASK, etc. 268 * 269 * Return: the modifier mask for this accel group. 270 * 271 * Since: 2.14 272 */ 273 public GdkModifierType getModifierMask() 274 { 275 return gtk_accel_group_get_modifier_mask(gtkAccelGroup); 276 } 277 278 /** 279 * Locks the given accelerator group. 280 * 281 * Locking an acelerator group prevents the accelerators contained 282 * within it to be changed during runtime. Refer to 283 * gtk_accel_map_change_entry() about runtime accelerator changes. 284 * 285 * If called more than once, @accel_group remains locked until 286 * gtk_accel_group_unlock() has been called an equivalent number 287 * of times. 288 */ 289 public void lock() 290 { 291 gtk_accel_group_lock(gtkAccelGroup); 292 } 293 294 /** 295 * Queries an accelerator group for all entries matching @accel_key 296 * and @accel_mods. 297 * 298 * Params: 299 * accelKey = key value of the accelerator 300 * accelMods = modifier combination of the accelerator 301 * 302 * Return: an array of 303 * @n_entries #GtkAccelGroupEntry elements, or %NULL. The array 304 * is owned by GTK+ and must not be freed. 305 */ 306 public GtkAccelGroupEntry[] query(uint accelKey, GdkModifierType accelMods) 307 { 308 uint nEntries; 309 310 auto p = gtk_accel_group_query(gtkAccelGroup, accelKey, accelMods, &nEntries); 311 312 return p[0 .. nEntries]; 313 } 314 315 /** 316 * Undoes the last call to gtk_accel_group_lock() on this @accel_group. 317 */ 318 public void unlock() 319 { 320 gtk_accel_group_unlock(gtkAccelGroup); 321 } 322 323 int[string] connectedSignals; 324 325 bool delegate(ObjectG, uint, GdkModifierType, AccelGroup)[] onAccelActivateListeners; 326 /** 327 * The accel-activate signal is an implementation detail of 328 * #GtkAccelGroup and not meant to be used by applications. 329 * 330 * Params: 331 * acceleratable = the object on which the accelerator was activated 332 * keyval = the accelerator keyval 333 * modifier = the modifier combination of the accelerator 334 * 335 * Return: %TRUE if the accelerator was activated 336 */ 337 void addOnAccelActivate(bool delegate(ObjectG, uint, GdkModifierType, AccelGroup) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 338 { 339 if ( "accel-activate" !in connectedSignals ) 340 { 341 Signals.connectData( 342 this, 343 "accel-activate", 344 cast(GCallback)&callBackAccelActivate, 345 cast(void*)this, 346 null, 347 connectFlags); 348 connectedSignals["accel-activate"] = 1; 349 } 350 onAccelActivateListeners ~= dlg; 351 } 352 extern(C) static int callBackAccelActivate(GtkAccelGroup* accelgroupStruct, GObject* acceleratable, uint keyval, GdkModifierType modifier, AccelGroup _accelgroup) 353 { 354 foreach ( bool delegate(ObjectG, uint, GdkModifierType, AccelGroup) dlg; _accelgroup.onAccelActivateListeners ) 355 { 356 if ( dlg(ObjectG.getDObject!(ObjectG)(acceleratable), keyval, modifier, _accelgroup) ) 357 { 358 return 1; 359 } 360 } 361 362 return 0; 363 } 364 365 void delegate(uint, GdkModifierType, Closure, AccelGroup)[] onAccelChangedListeners; 366 /** 367 * The accel-changed signal is emitted when an entry 368 * is added to or removed from the accel group. 369 * 370 * Widgets like #GtkAccelLabel which display an associated 371 * accelerator should connect to this signal, and rebuild 372 * their visual representation if the @accel_closure is theirs. 373 * 374 * Params: 375 * keyval = the accelerator keyval 376 * modifier = the modifier combination of the accelerator 377 * accelClosure = the #GClosure of the accelerator 378 */ 379 void addOnAccelChanged(void delegate(uint, GdkModifierType, Closure, AccelGroup) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 380 { 381 if ( "accel-changed" !in connectedSignals ) 382 { 383 Signals.connectData( 384 this, 385 "accel-changed", 386 cast(GCallback)&callBackAccelChanged, 387 cast(void*)this, 388 null, 389 connectFlags); 390 connectedSignals["accel-changed"] = 1; 391 } 392 onAccelChangedListeners ~= dlg; 393 } 394 extern(C) static void callBackAccelChanged(GtkAccelGroup* accelgroupStruct, uint keyval, GdkModifierType modifier, GClosure* accelClosure, AccelGroup _accelgroup) 395 { 396 foreach ( void delegate(uint, GdkModifierType, Closure, AccelGroup) dlg; _accelgroup.onAccelChangedListeners ) 397 { 398 dlg(keyval, modifier, ObjectG.getDObject!(Closure)(accelClosure), _accelgroup); 399 } 400 } 401 402 /** 403 * Finds the first accelerator in any #GtkAccelGroup attached 404 * to @object that matches @accel_key and @accel_mods, and 405 * activates that accelerator. 406 * 407 * Params: 408 * object = the #GObject, usually a #GtkWindow, on which 409 * to activate the accelerator 410 * accelKey = accelerator keyval from a key event 411 * accelMods = keyboard state mask from a key event 412 * 413 * Return: %TRUE if an accelerator was activated and handled 414 * this keypress 415 */ 416 public static bool accelGroupsActivate(ObjectG object, uint accelKey, GdkModifierType accelMods) 417 { 418 return gtk_accel_groups_activate((object is null) ? null : object.getObjectGStruct(), accelKey, accelMods) != 0; 419 } 420 421 /** 422 * Gets a list of all accel groups which are attached to @object. 423 * 424 * Params: 425 * object = a #GObject, usually a #GtkWindow 426 * 427 * Return: a list of 428 * all accel groups which are attached to @object 429 */ 430 public static ListSG accelGroupsFromObject(ObjectG object) 431 { 432 auto p = gtk_accel_groups_from_object((object is null) ? null : object.getObjectGStruct()); 433 434 if(p is null) 435 { 436 return null; 437 } 438 439 return new ListSG(cast(GSList*) p); 440 } 441 442 /** 443 * Gets the value set by gtk_accelerator_set_default_mod_mask(). 444 * 445 * Return: the default accelerator modifier mask 446 */ 447 public static GdkModifierType acceleratorGetDefaultModMask() 448 { 449 return gtk_accelerator_get_default_mod_mask(); 450 } 451 452 /** 453 * Converts an accelerator keyval and modifier mask into a string 454 * which can be used to represent the accelerator to the user. 455 * 456 * Params: 457 * acceleratorKey = accelerator keyval 458 * acceleratorMods = accelerator modifier mask 459 * 460 * Return: a newly-allocated string representing the accelerator. 461 * 462 * Since: 2.6 463 */ 464 public static string acceleratorGetLabel(uint acceleratorKey, GdkModifierType acceleratorMods) 465 { 466 return Str.toString(gtk_accelerator_get_label(acceleratorKey, acceleratorMods)); 467 } 468 469 /** 470 * Converts an accelerator keyval and modifier mask 471 * into a (possibly translated) string that can be displayed to 472 * a user, similarly to gtk_accelerator_get_label(), but handling 473 * keycodes. 474 * 475 * This is only useful for system-level components, applications 476 * should use gtk_accelerator_parse() instead. 477 * 478 * Params: 479 * display = a #GdkDisplay or %NULL to use the default display 480 * acceleratorKey = accelerator keyval 481 * keycode = accelerator keycode 482 * acceleratorMods = accelerator modifier mask 483 * 484 * Return: a newly-allocated string representing the accelerator. 485 * 486 * Since: 3.4 487 */ 488 public static string acceleratorGetLabelWithKeycode(Display display, uint acceleratorKey, uint keycode, GdkModifierType acceleratorMods) 489 { 490 return Str.toString(gtk_accelerator_get_label_with_keycode((display is null) ? null : display.getDisplayStruct(), acceleratorKey, keycode, acceleratorMods)); 491 } 492 493 /** 494 * Converts an accelerator keyval and modifier mask into a string 495 * parseable by gtk_accelerator_parse(). For example, if you pass in 496 * #GDK_KEY_q and #GDK_CONTROL_MASK, this function returns “<Control>q”. 497 * 498 * If you need to display accelerators in the user interface, 499 * see gtk_accelerator_get_label(). 500 * 501 * Params: 502 * acceleratorKey = accelerator keyval 503 * acceleratorMods = accelerator modifier mask 504 * 505 * Return: a newly-allocated accelerator name 506 */ 507 public static string acceleratorName(uint acceleratorKey, GdkModifierType acceleratorMods) 508 { 509 return Str.toString(gtk_accelerator_name(acceleratorKey, acceleratorMods)); 510 } 511 512 /** 513 * Converts an accelerator keyval and modifier mask 514 * into a string parseable by gtk_accelerator_parse_with_keycode(), 515 * similarly to gtk_accelerator_name() but handling keycodes. 516 * This is only useful for system-level components, applications 517 * should use gtk_accelerator_parse() instead. 518 * 519 * Params: 520 * display = a #GdkDisplay or %NULL to use the default display 521 * acceleratorKey = accelerator keyval 522 * keycode = accelerator keycode 523 * acceleratorMods = accelerator modifier mask 524 * 525 * Return: a newly allocated accelerator name. 526 * 527 * Since: 3.4 528 */ 529 public static string acceleratorNameWithKeycode(Display display, uint acceleratorKey, uint keycode, GdkModifierType acceleratorMods) 530 { 531 return Str.toString(gtk_accelerator_name_with_keycode((display is null) ? null : display.getDisplayStruct(), acceleratorKey, keycode, acceleratorMods)); 532 } 533 534 /** 535 * Parses a string representing an accelerator. The format looks like 536 * “<Control>a” or “<Shift><Alt>F1” or “<Release>z” (the last one is 537 * for key release). 538 * 539 * The parser is fairly liberal and allows lower or upper case, and also 540 * abbreviations such as “<Ctl>” and “<Ctrl>”. Key names are parsed using 541 * gdk_keyval_from_name(). For character keys the name is not the symbol, 542 * but the lowercase name, e.g. one would use “<Ctrl>minus” instead of 543 * “<Ctrl>-”. 544 * 545 * If the parse fails, @accelerator_key and @accelerator_mods will 546 * be set to 0 (zero). 547 * 548 * Params: 549 * accelerator = string representing an accelerator 550 * acceleratorKey = return location for accelerator 551 * keyval, or %NULL 552 * acceleratorMods = return location for accelerator 553 * modifier mask, %NULL 554 */ 555 public static void acceleratorParse(string accelerator, out uint acceleratorKey, out GdkModifierType acceleratorMods) 556 { 557 gtk_accelerator_parse(Str.toStringz(accelerator), &acceleratorKey, &acceleratorMods); 558 } 559 560 /** 561 * Parses a string representing an accelerator, similarly to 562 * gtk_accelerator_parse() but handles keycodes as well. This is only 563 * useful for system-level components, applications should use 564 * gtk_accelerator_parse() instead. 565 * 566 * If @accelerator_codes is given and the result stored in it is non-%NULL, 567 * the result must be freed with g_free(). 568 * 569 * If a keycode is present in the accelerator and no @accelerator_codes 570 * is given, the parse will fail. 571 * 572 * If the parse fails, @accelerator_key, @accelerator_mods and 573 * @accelerator_codes will be set to 0 (zero). 574 * 575 * Params: 576 * accelerator = string representing an accelerator 577 * acceleratorKey = return location for accelerator 578 * keyval, or %NULL 579 * acceleratorCodes = return location for accelerator keycodes, or %NULL 580 * acceleratorMods = return location for accelerator 581 * modifier mask, %NULL 582 * 583 * Since: 3.4 584 */ 585 public static void acceleratorParseWithKeycode(string accelerator, out uint acceleratorKey, out uint[] acceleratorCodes, out GdkModifierType acceleratorMods) 586 { 587 uint* outacceleratorCodes = null; 588 589 gtk_accelerator_parse_with_keycode(Str.toStringz(accelerator), &acceleratorKey, &outacceleratorCodes, &acceleratorMods); 590 591 acceleratorCodes = outacceleratorCodes[0 .. getArrayLength(outacceleratorCodes)]; 592 } 593 594 /** 595 * Sets the modifiers that will be considered significant for keyboard 596 * accelerators. The default mod mask is #GDK_CONTROL_MASK | 597 * #GDK_SHIFT_MASK | #GDK_MOD1_MASK | #GDK_SUPER_MASK | 598 * #GDK_HYPER_MASK | #GDK_META_MASK, that is, Control, Shift, Alt, 599 * Super, Hyper and Meta. Other modifiers will by default be ignored 600 * by #GtkAccelGroup. 601 * You must include at least the three modifiers Control, Shift 602 * and Alt in any value you pass to this function. 603 * 604 * The default mod mask should be changed on application startup, 605 * before using any accelerator groups. 606 * 607 * Params: 608 * defaultModMask = accelerator modifier mask 609 */ 610 public static void acceleratorSetDefaultModMask(GdkModifierType defaultModMask) 611 { 612 gtk_accelerator_set_default_mod_mask(defaultModMask); 613 } 614 615 /** 616 * Determines whether a given keyval and modifier mask constitute 617 * a valid keyboard accelerator. For example, the #GDK_KEY_a keyval 618 * plus #GDK_CONTROL_MASK is valid - this is a “Ctrl+a” accelerator. 619 * But, you can't, for instance, use the #GDK_KEY_Control_L keyval 620 * as an accelerator. 621 * 622 * Params: 623 * keyval = a GDK keyval 624 * modifiers = modifier mask 625 * 626 * Return: %TRUE if the accelerator is valid 627 */ 628 public static bool acceleratorValid(uint keyval, GdkModifierType modifiers) 629 { 630 return gtk_accelerator_valid(keyval, modifiers) != 0; 631 } 632 }