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 modifier mask. 444 * 445 * The modifier mask determines which modifiers are considered significant 446 * for keyboard accelerators. See gtk_accelerator_set_default_mod_mask(). 447 * 448 * Return: the default accelerator modifier mask 449 */ 450 public static GdkModifierType acceleratorGetDefaultModMask() 451 { 452 return gtk_accelerator_get_default_mod_mask(); 453 } 454 455 /** 456 * Converts an accelerator keyval and modifier mask into a string 457 * which can be used to represent the accelerator to the user. 458 * 459 * Params: 460 * acceleratorKey = accelerator keyval 461 * acceleratorMods = accelerator modifier mask 462 * 463 * Return: a newly-allocated string representing the accelerator. 464 * 465 * Since: 2.6 466 */ 467 public static string acceleratorGetLabel(uint acceleratorKey, GdkModifierType acceleratorMods) 468 { 469 return Str.toString(gtk_accelerator_get_label(acceleratorKey, acceleratorMods)); 470 } 471 472 /** 473 * Converts an accelerator keyval and modifier mask 474 * into a (possibly translated) string that can be displayed to 475 * a user, similarly to gtk_accelerator_get_label(), but handling 476 * keycodes. 477 * 478 * This is only useful for system-level components, applications 479 * should use gtk_accelerator_parse() instead. 480 * 481 * Params: 482 * display = a #GdkDisplay or %NULL to use the default display 483 * acceleratorKey = accelerator keyval 484 * keycode = accelerator keycode 485 * acceleratorMods = accelerator modifier mask 486 * 487 * Return: a newly-allocated string representing the accelerator. 488 * 489 * Since: 3.4 490 */ 491 public static string acceleratorGetLabelWithKeycode(Display display, uint acceleratorKey, uint keycode, GdkModifierType acceleratorMods) 492 { 493 return Str.toString(gtk_accelerator_get_label_with_keycode((display is null) ? null : display.getDisplayStruct(), acceleratorKey, keycode, acceleratorMods)); 494 } 495 496 /** 497 * Converts an accelerator keyval and modifier mask into a string 498 * parseable by gtk_accelerator_parse(). For example, if you pass in 499 * #GDK_KEY_q and #GDK_CONTROL_MASK, this function returns “<Control>q”. 500 * 501 * If you need to display accelerators in the user interface, 502 * see gtk_accelerator_get_label(). 503 * 504 * Params: 505 * acceleratorKey = accelerator keyval 506 * acceleratorMods = accelerator modifier mask 507 * 508 * Return: a newly-allocated accelerator name 509 */ 510 public static string acceleratorName(uint acceleratorKey, GdkModifierType acceleratorMods) 511 { 512 return Str.toString(gtk_accelerator_name(acceleratorKey, acceleratorMods)); 513 } 514 515 /** 516 * Converts an accelerator keyval and modifier mask 517 * into a string parseable by gtk_accelerator_parse_with_keycode(), 518 * similarly to gtk_accelerator_name() but handling keycodes. 519 * This is only useful for system-level components, applications 520 * should use gtk_accelerator_parse() instead. 521 * 522 * Params: 523 * display = a #GdkDisplay or %NULL to use the default display 524 * acceleratorKey = accelerator keyval 525 * keycode = accelerator keycode 526 * acceleratorMods = accelerator modifier mask 527 * 528 * Return: a newly allocated accelerator name. 529 * 530 * Since: 3.4 531 */ 532 public static string acceleratorNameWithKeycode(Display display, uint acceleratorKey, uint keycode, GdkModifierType acceleratorMods) 533 { 534 return Str.toString(gtk_accelerator_name_with_keycode((display is null) ? null : display.getDisplayStruct(), acceleratorKey, keycode, acceleratorMods)); 535 } 536 537 /** 538 * Parses a string representing an accelerator. The format looks like 539 * “<Control>a” or “<Shift><Alt>F1” or “<Release>z” (the last one is 540 * for key release). 541 * 542 * The parser is fairly liberal and allows lower or upper case, and also 543 * abbreviations such as “<Ctl>” and “<Ctrl>”. Key names are parsed using 544 * gdk_keyval_from_name(). For character keys the name is not the symbol, 545 * but the lowercase name, e.g. one would use “<Ctrl>minus” instead of 546 * “<Ctrl>-”. 547 * 548 * If the parse fails, @accelerator_key and @accelerator_mods will 549 * be set to 0 (zero). 550 * 551 * Params: 552 * accelerator = string representing an accelerator 553 * acceleratorKey = return location for accelerator 554 * keyval, or %NULL 555 * acceleratorMods = return location for accelerator 556 * modifier mask, %NULL 557 */ 558 public static void acceleratorParse(string accelerator, out uint acceleratorKey, out GdkModifierType acceleratorMods) 559 { 560 gtk_accelerator_parse(Str.toStringz(accelerator), &acceleratorKey, &acceleratorMods); 561 } 562 563 /** 564 * Parses a string representing an accelerator, similarly to 565 * gtk_accelerator_parse() but handles keycodes as well. This is only 566 * useful for system-level components, applications should use 567 * gtk_accelerator_parse() instead. 568 * 569 * If @accelerator_codes is given and the result stored in it is non-%NULL, 570 * the result must be freed with g_free(). 571 * 572 * If a keycode is present in the accelerator and no @accelerator_codes 573 * is given, the parse will fail. 574 * 575 * If the parse fails, @accelerator_key, @accelerator_mods and 576 * @accelerator_codes will be set to 0 (zero). 577 * 578 * Params: 579 * accelerator = string representing an accelerator 580 * acceleratorKey = return location for accelerator 581 * keyval, or %NULL 582 * acceleratorCodes = return location for accelerator keycodes, or %NULL 583 * acceleratorMods = return location for accelerator 584 * modifier mask, %NULL 585 * 586 * Since: 3.4 587 */ 588 public static void acceleratorParseWithKeycode(string accelerator, out uint acceleratorKey, out uint[] acceleratorCodes, out GdkModifierType acceleratorMods) 589 { 590 uint* outacceleratorCodes = null; 591 592 gtk_accelerator_parse_with_keycode(Str.toStringz(accelerator), &acceleratorKey, &outacceleratorCodes, &acceleratorMods); 593 594 acceleratorCodes = outacceleratorCodes[0 .. getArrayLength(outacceleratorCodes)]; 595 } 596 597 /** 598 * Sets the modifiers that will be considered significant for keyboard 599 * accelerators. The default mod mask depends on the GDK backend in use, 600 * but will typically include #GDK_CONTROL_MASK | #GDK_SHIFT_MASK | 601 * #GDK_MOD1_MASK | #GDK_SUPER_MASK | #GDK_HYPER_MASK | #GDK_META_MASK. 602 * In other words, Control, Shift, Alt, Super, Hyper and Meta. Other 603 * modifiers will by default be ignored by #GtkAccelGroup. 604 * 605 * You must include at least the three modifiers Control, Shift 606 * and Alt in any value you pass to this function. 607 * 608 * The default mod mask should be changed on application startup, 609 * before using any accelerator groups. 610 * 611 * Params: 612 * defaultModMask = accelerator modifier mask 613 */ 614 public static void acceleratorSetDefaultModMask(GdkModifierType defaultModMask) 615 { 616 gtk_accelerator_set_default_mod_mask(defaultModMask); 617 } 618 619 /** 620 * Determines whether a given keyval and modifier mask constitute 621 * a valid keyboard accelerator. For example, the #GDK_KEY_a keyval 622 * plus #GDK_CONTROL_MASK is valid - this is a “Ctrl+a” accelerator. 623 * But, you can't, for instance, use the #GDK_KEY_Control_L keyval 624 * as an accelerator. 625 * 626 * Params: 627 * keyval = a GDK keyval 628 * modifiers = modifier mask 629 * 630 * Return: %TRUE if the accelerator is valid 631 */ 632 public static bool acceleratorValid(uint keyval, GdkModifierType modifiers) 633 { 634 return gtk_accelerator_valid(keyval, modifiers) != 0; 635 } 636 }