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 * nEntries = location to return the number 302 * of entries found, or %NULL 303 * 304 * Return: an array of 305 * @n_entries #GtkAccelGroupEntry elements, or %NULL. The array 306 * is owned by GTK+ and must not be freed. 307 */ 308 public GtkAccelGroupEntry[] query(uint accelKey, GdkModifierType accelMods) 309 { 310 uint nEntries; 311 312 auto p = gtk_accel_group_query(gtkAccelGroup, accelKey, accelMods, &nEntries); 313 314 return p[0 .. nEntries]; 315 } 316 317 /** 318 * Undoes the last call to gtk_accel_group_lock() on this @accel_group. 319 */ 320 public void unlock() 321 { 322 gtk_accel_group_unlock(gtkAccelGroup); 323 } 324 325 int[string] connectedSignals; 326 327 bool delegate(ObjectG, uint, GdkModifierType, AccelGroup)[] onAccelActivateListeners; 328 /** 329 * The accel-activate signal is an implementation detail of 330 * #GtkAccelGroup and not meant to be used by applications. 331 * 332 * Params: 333 * acceleratable = the object on which the accelerator was activated 334 * keyval = the accelerator keyval 335 * modifier = the modifier combination of the accelerator 336 * 337 * Return: %TRUE if the accelerator was activated 338 */ 339 void addOnAccelActivate(bool delegate(ObjectG, uint, GdkModifierType, AccelGroup) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 340 { 341 if ( "accel-activate" !in connectedSignals ) 342 { 343 Signals.connectData( 344 this, 345 "accel-activate", 346 cast(GCallback)&callBackAccelActivate, 347 cast(void*)this, 348 null, 349 connectFlags); 350 connectedSignals["accel-activate"] = 1; 351 } 352 onAccelActivateListeners ~= dlg; 353 } 354 extern(C) static int callBackAccelActivate(GtkAccelGroup* accelgroupStruct, GObject* acceleratable, uint keyval, GdkModifierType modifier, AccelGroup _accelgroup) 355 { 356 foreach ( bool delegate(ObjectG, uint, GdkModifierType, AccelGroup) dlg; _accelgroup.onAccelActivateListeners ) 357 { 358 if ( dlg(ObjectG.getDObject!(ObjectG)(acceleratable), keyval, modifier, _accelgroup) ) 359 { 360 return 1; 361 } 362 } 363 364 return 0; 365 } 366 367 void delegate(uint, GdkModifierType, Closure, AccelGroup)[] onAccelChangedListeners; 368 /** 369 * The accel-changed signal is emitted when an entry 370 * is added to or removed from the accel group. 371 * 372 * Widgets like #GtkAccelLabel which display an associated 373 * accelerator should connect to this signal, and rebuild 374 * their visual representation if the @accel_closure is theirs. 375 * 376 * Params: 377 * keyval = the accelerator keyval 378 * modifier = the modifier combination of the accelerator 379 * accelClosure = the #GClosure of the accelerator 380 */ 381 void addOnAccelChanged(void delegate(uint, GdkModifierType, Closure, AccelGroup) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 382 { 383 if ( "accel-changed" !in connectedSignals ) 384 { 385 Signals.connectData( 386 this, 387 "accel-changed", 388 cast(GCallback)&callBackAccelChanged, 389 cast(void*)this, 390 null, 391 connectFlags); 392 connectedSignals["accel-changed"] = 1; 393 } 394 onAccelChangedListeners ~= dlg; 395 } 396 extern(C) static void callBackAccelChanged(GtkAccelGroup* accelgroupStruct, uint keyval, GdkModifierType modifier, GClosure* accelClosure, AccelGroup _accelgroup) 397 { 398 foreach ( void delegate(uint, GdkModifierType, Closure, AccelGroup) dlg; _accelgroup.onAccelChangedListeners ) 399 { 400 dlg(keyval, modifier, ObjectG.getDObject!(Closure)(accelClosure), _accelgroup); 401 } 402 } 403 404 /** 405 * Finds the first accelerator in any #GtkAccelGroup attached 406 * to @object that matches @accel_key and @accel_mods, and 407 * activates that accelerator. 408 * 409 * Params: 410 * object = the #GObject, usually a #GtkWindow, on which 411 * to activate the accelerator 412 * accelKey = accelerator keyval from a key event 413 * accelMods = keyboard state mask from a key event 414 * 415 * Return: %TRUE if an accelerator was activated and handled 416 * this keypress 417 */ 418 public static bool accelGroupsActivate(ObjectG object, uint accelKey, GdkModifierType accelMods) 419 { 420 return gtk_accel_groups_activate((object is null) ? null : object.getObjectGStruct(), accelKey, accelMods) != 0; 421 } 422 423 /** 424 * Gets a list of all accel groups which are attached to @object. 425 * 426 * Params: 427 * object = a #GObject, usually a #GtkWindow 428 * 429 * Return: a list of 430 * all accel groups which are attached to @object 431 */ 432 public static ListSG accelGroupsFromObject(ObjectG object) 433 { 434 auto p = gtk_accel_groups_from_object((object is null) ? null : object.getObjectGStruct()); 435 436 if(p is null) 437 { 438 return null; 439 } 440 441 return new ListSG(cast(GSList*) p); 442 } 443 444 /** 445 * Gets the value set by gtk_accelerator_set_default_mod_mask(). 446 * 447 * Return: the default accelerator modifier mask 448 */ 449 public static GdkModifierType acceleratorGetDefaultModMask() 450 { 451 return gtk_accelerator_get_default_mod_mask(); 452 } 453 454 /** 455 * Converts an accelerator keyval and modifier mask into a string 456 * which can be used to represent the accelerator to the user. 457 * 458 * Params: 459 * acceleratorKey = accelerator keyval 460 * acceleratorMods = accelerator modifier mask 461 * 462 * Return: a newly-allocated string representing the accelerator. 463 * 464 * Since: 2.6 465 */ 466 public static string acceleratorGetLabel(uint acceleratorKey, GdkModifierType acceleratorMods) 467 { 468 return Str.toString(gtk_accelerator_get_label(acceleratorKey, acceleratorMods)); 469 } 470 471 /** 472 * Converts an accelerator keyval and modifier mask 473 * into a (possibly translated) string that can be displayed to 474 * a user, similarly to gtk_accelerator_get_label(), but handling 475 * keycodes. 476 * 477 * This is only useful for system-level components, applications 478 * should use gtk_accelerator_parse() instead. 479 * 480 * Params: 481 * display = a #GdkDisplay or %NULL to use the default display 482 * acceleratorKey = accelerator keyval 483 * keycode = accelerator keycode 484 * acceleratorMods = accelerator modifier mask 485 * 486 * Return: a newly-allocated string representing the accelerator. 487 * 488 * Since: 3.4 489 */ 490 public static string acceleratorGetLabelWithKeycode(Display display, uint acceleratorKey, uint keycode, GdkModifierType acceleratorMods) 491 { 492 return Str.toString(gtk_accelerator_get_label_with_keycode((display is null) ? null : display.getDisplayStruct(), acceleratorKey, keycode, acceleratorMods)); 493 } 494 495 /** 496 * Converts an accelerator keyval and modifier mask into a string 497 * parseable by gtk_accelerator_parse(). For example, if you pass in 498 * #GDK_KEY_q and #GDK_CONTROL_MASK, this function returns “<Control>q”. 499 * 500 * If you need to display accelerators in the user interface, 501 * see gtk_accelerator_get_label(). 502 * 503 * Params: 504 * acceleratorKey = accelerator keyval 505 * acceleratorMods = accelerator modifier mask 506 * 507 * Return: a newly-allocated accelerator name 508 */ 509 public static string acceleratorName(uint acceleratorKey, GdkModifierType acceleratorMods) 510 { 511 return Str.toString(gtk_accelerator_name(acceleratorKey, acceleratorMods)); 512 } 513 514 /** 515 * Converts an accelerator keyval and modifier mask 516 * into a string parseable by gtk_accelerator_parse_with_keycode(), 517 * similarly to gtk_accelerator_name() but handling keycodes. 518 * This is only useful for system-level components, applications 519 * should use gtk_accelerator_parse() instead. 520 * 521 * Params: 522 * display = a #GdkDisplay or %NULL to use the default display 523 * acceleratorKey = accelerator keyval 524 * keycode = accelerator keycode 525 * acceleratorMods = accelerator modifier mask 526 * 527 * Return: a newly allocated accelerator name. 528 * 529 * Since: 3.4 530 */ 531 public static string acceleratorNameWithKeycode(Display display, uint acceleratorKey, uint keycode, GdkModifierType acceleratorMods) 532 { 533 return Str.toString(gtk_accelerator_name_with_keycode((display is null) ? null : display.getDisplayStruct(), acceleratorKey, keycode, acceleratorMods)); 534 } 535 536 /** 537 * Parses a string representing an accelerator. The format looks like 538 * “<Control>a” or “<Shift><Alt>F1” or “<Release>z” (the last one is 539 * for key release). 540 * 541 * The parser is fairly liberal and allows lower or upper case, and also 542 * abbreviations such as “<Ctl>” and “<Ctrl>”. Key names are parsed using 543 * gdk_keyval_from_name(). For character keys the name is not the symbol, 544 * but the lowercase name, e.g. one would use “<Ctrl>minus” instead of 545 * “<Ctrl>-”. 546 * 547 * If the parse fails, @accelerator_key and @accelerator_mods will 548 * be set to 0 (zero). 549 * 550 * Params: 551 * accelerator = string representing an accelerator 552 * acceleratorKey = return location for accelerator 553 * keyval, or %NULL 554 * acceleratorMods = return location for accelerator 555 * modifier mask, %NULL 556 */ 557 public static void acceleratorParse(string accelerator, out uint acceleratorKey, out GdkModifierType acceleratorMods) 558 { 559 gtk_accelerator_parse(Str.toStringz(accelerator), &acceleratorKey, &acceleratorMods); 560 } 561 562 /** 563 * Parses a string representing an accelerator, similarly to 564 * gtk_accelerator_parse() but handles keycodes as well. This is only 565 * useful for system-level components, applications should use 566 * gtk_accelerator_parse() instead. 567 * 568 * If @accelerator_codes is given and the result stored in it is non-%NULL, 569 * the result must be freed with g_free(). 570 * 571 * If a keycode is present in the accelerator and no @accelerator_codes 572 * is given, the parse will fail. 573 * 574 * If the parse fails, @accelerator_key, @accelerator_mods and 575 * @accelerator_codes will be set to 0 (zero). 576 * 577 * Params: 578 * accelerator = string representing an accelerator 579 * acceleratorKey = return location for accelerator 580 * keyval, or %NULL 581 * acceleratorCodes = return location for accelerator keycodes, or %NULL 582 * acceleratorMods = return location for accelerator 583 * modifier mask, %NULL 584 * 585 * Since: 3.4 586 */ 587 public static void acceleratorParseWithKeycode(string accelerator, out uint acceleratorKey, out uint[] acceleratorCodes, out GdkModifierType acceleratorMods) 588 { 589 uint* outacceleratorCodes = null; 590 591 gtk_accelerator_parse_with_keycode(Str.toStringz(accelerator), &acceleratorKey, &outacceleratorCodes, &acceleratorMods); 592 593 acceleratorCodes = outacceleratorCodes[0 .. getArrayLength(outacceleratorCodes)]; 594 } 595 596 /** 597 * Sets the modifiers that will be considered significant for keyboard 598 * accelerators. The default mod mask is #GDK_CONTROL_MASK | 599 * #GDK_SHIFT_MASK | #GDK_MOD1_MASK | #GDK_SUPER_MASK | 600 * #GDK_HYPER_MASK | #GDK_META_MASK, that is, Control, Shift, Alt, 601 * Super, Hyper and Meta. Other modifiers will by default be ignored 602 * by #GtkAccelGroup. 603 * You must include at least the three modifiers Control, Shift 604 * and Alt in any value you pass to this function. 605 * 606 * The default mod mask should be changed on application startup, 607 * before using any accelerator groups. 608 * 609 * Params: 610 * defaultModMask = accelerator modifier mask 611 */ 612 public static void acceleratorSetDefaultModMask(GdkModifierType defaultModMask) 613 { 614 gtk_accelerator_set_default_mod_mask(defaultModMask); 615 } 616 617 /** 618 * Determines whether a given keyval and modifier mask constitute 619 * a valid keyboard accelerator. For example, the #GDK_KEY_a keyval 620 * plus #GDK_CONTROL_MASK is valid - this is a “Ctrl+a” accelerator. 621 * But, you can't, for instance, use the #GDK_KEY_Control_L keyval 622 * as an accelerator. 623 * 624 * Params: 625 * keyval = a GDK keyval 626 * modifiers = modifier mask 627 * 628 * Return: %TRUE if the accelerator is valid 629 */ 630 public static bool acceleratorValid(uint keyval, GdkModifierType modifiers) 631 { 632 return gtk_accelerator_valid(keyval, modifiers) != 0; 633 } 634 }