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.AccelMap; 26 27 private import glib.ScannerG; 28 private import glib.Str; 29 private import gobject.ObjectG; 30 private import gobject.Signals; 31 private import gtkc.gtk; 32 public import gtkc.gtktypes; 33 private import std.algorithm; 34 35 36 /** 37 * Accelerator maps are used to define runtime configurable accelerators. 38 * Functions for manipulating them are are usually used by higher level 39 * convenience mechanisms like #GtkUIManager and are thus considered 40 * “low-level”. You’ll want to use them if you’re manually creating menus that 41 * should have user-configurable accelerators. 42 * 43 * An accelerator is uniquely defined by: 44 * - accelerator path 45 * - accelerator key 46 * - accelerator modifiers 47 * 48 * The accelerator path must consist of 49 * “<WINDOWTYPE>/Category1/Category2/.../Action”, where WINDOWTYPE 50 * should be a unique application-specific identifier that corresponds 51 * to the kind of window the accelerator is being used in, e.g. 52 * “Gimp-Image”, “Abiword-Document” or “Gnumeric-Settings”. 53 * The “Category1/.../Action” portion is most appropriately chosen by 54 * the action the accelerator triggers, i.e. for accelerators on menu 55 * items, choose the item’s menu path, e.g. “File/Save As”, 56 * “Image/View/Zoom” or “Edit/Select All”. So a full valid accelerator 57 * path may look like: “<Gimp-Toolbox>/File/Dialogs/Tool Options...”. 58 * 59 * All accelerators are stored inside one global #GtkAccelMap that can 60 * be obtained using gtk_accel_map_get(). See 61 * [Monitoring changes][monitoring-changes] for additional 62 * details. 63 * 64 * # Manipulating accelerators 65 * 66 * New accelerators can be added using gtk_accel_map_add_entry(). 67 * To search for specific accelerator, use gtk_accel_map_lookup_entry(). 68 * Modifications of existing accelerators should be done using 69 * gtk_accel_map_change_entry(). 70 * 71 * In order to avoid having some accelerators changed, they can be 72 * locked using gtk_accel_map_lock_path(). Unlocking is done using 73 * gtk_accel_map_unlock_path(). 74 * 75 * # Saving and loading accelerator maps 76 * 77 * Accelerator maps can be saved to and loaded from some external 78 * resource. For simple saving and loading from file, 79 * gtk_accel_map_save() and gtk_accel_map_load() are provided. 80 * Saving and loading can also be done by providing file descriptor 81 * to gtk_accel_map_save_fd() and gtk_accel_map_load_fd(). 82 * 83 * # Monitoring changes 84 * 85 * #GtkAccelMap object is only useful for monitoring changes of 86 * accelerators. By connecting to #GtkAccelMap::changed signal, one 87 * can monitor changes of all accelerators. It is also possible to 88 * monitor only single accelerator path by using it as a detail of 89 * the #GtkAccelMap::changed signal. 90 */ 91 public class AccelMap : ObjectG 92 { 93 /** the main Gtk struct */ 94 protected GtkAccelMap* gtkAccelMap; 95 96 /** Get the main Gtk struct */ 97 public GtkAccelMap* getAccelMapStruct(bool transferOwnership = false) 98 { 99 if (transferOwnership) 100 ownedRef = false; 101 return gtkAccelMap; 102 } 103 104 /** the main Gtk struct as a void* */ 105 protected override void* getStruct() 106 { 107 return cast(void*)gtkAccelMap; 108 } 109 110 protected override void setStruct(GObject* obj) 111 { 112 gtkAccelMap = cast(GtkAccelMap*)obj; 113 super.setStruct(obj); 114 } 115 116 /** 117 * Sets our main struct and passes it to the parent class. 118 */ 119 public this (GtkAccelMap* gtkAccelMap, bool ownedRef = false) 120 { 121 this.gtkAccelMap = gtkAccelMap; 122 super(cast(GObject*)gtkAccelMap, ownedRef); 123 } 124 125 126 /** */ 127 public static GType getType() 128 { 129 return gtk_accel_map_get_type(); 130 } 131 132 /** 133 * Registers a new accelerator with the global accelerator map. 134 * This function should only be called once per @accel_path 135 * with the canonical @accel_key and @accel_mods for this path. 136 * To change the accelerator during runtime programatically, use 137 * gtk_accel_map_change_entry(). 138 * 139 * Set @accel_key and @accel_mods to 0 to request a removal of 140 * the accelerator. 141 * 142 * Note that @accel_path string will be stored in a #GQuark. Therefore, if you 143 * pass a static string, you can save some memory by interning it first with 144 * g_intern_static_string(). 145 * 146 * Params: 147 * accelPath = valid accelerator path 148 * accelKey = the accelerator key 149 * accelMods = the accelerator modifiers 150 */ 151 public static void addEntry(string accelPath, uint accelKey, GdkModifierType accelMods) 152 { 153 gtk_accel_map_add_entry(Str.toStringz(accelPath), accelKey, accelMods); 154 } 155 156 /** 157 * Adds a filter to the global list of accel path filters. 158 * 159 * Accel map entries whose accel path matches one of the filters 160 * are skipped by gtk_accel_map_foreach(). 161 * 162 * This function is intended for GTK+ modules that create their own 163 * menus, but don’t want them to be saved into the applications accelerator 164 * map dump. 165 * 166 * Params: 167 * filterPattern = a pattern (see #GPatternSpec) 168 */ 169 public static void addFilter(string filterPattern) 170 { 171 gtk_accel_map_add_filter(Str.toStringz(filterPattern)); 172 } 173 174 /** 175 * Changes the @accel_key and @accel_mods currently associated with @accel_path. 176 * Due to conflicts with other accelerators, a change may not always be possible, 177 * @replace indicates whether other accelerators may be deleted to resolve such 178 * conflicts. A change will only occur if all conflicts could be resolved (which 179 * might not be the case if conflicting accelerators are locked). Successful 180 * changes are indicated by a %TRUE return value. 181 * 182 * Note that @accel_path string will be stored in a #GQuark. Therefore, if you 183 * pass a static string, you can save some memory by interning it first with 184 * g_intern_static_string(). 185 * 186 * Params: 187 * accelPath = a valid accelerator path 188 * accelKey = the new accelerator key 189 * accelMods = the new accelerator modifiers 190 * replace = %TRUE if other accelerators may be deleted upon conflicts 191 * 192 * Returns: %TRUE if the accelerator could be changed, %FALSE otherwise 193 */ 194 public static bool changeEntry(string accelPath, uint accelKey, GdkModifierType accelMods, bool replace) 195 { 196 return gtk_accel_map_change_entry(Str.toStringz(accelPath), accelKey, accelMods, replace) != 0; 197 } 198 199 /** 200 * Loops over the entries in the accelerator map whose accel path 201 * doesn’t match any of the filters added with gtk_accel_map_add_filter(), 202 * and execute @foreach_func on each. The signature of @foreach_func is 203 * that of #GtkAccelMapForeach, the @changed parameter indicates whether 204 * this accelerator was changed during runtime (thus, would need 205 * saving during an accelerator map dump). 206 * 207 * Params: 208 * data = data to be passed into @foreach_func 209 * foreachFunc = function to be executed for each accel 210 * map entry which is not filtered out 211 */ 212 public static void foreac(void* data, GtkAccelMapForeach foreachFunc) 213 { 214 gtk_accel_map_foreach(data, foreachFunc); 215 } 216 217 /** 218 * Loops over all entries in the accelerator map, and execute 219 * @foreach_func on each. The signature of @foreach_func is that of 220 * #GtkAccelMapForeach, the @changed parameter indicates whether 221 * this accelerator was changed during runtime (thus, would need 222 * saving during an accelerator map dump). 223 * 224 * Params: 225 * data = data to be passed into @foreach_func 226 * foreachFunc = function to be executed for each accel 227 * map entry 228 */ 229 public static void foreachUnfiltered(void* data, GtkAccelMapForeach foreachFunc) 230 { 231 gtk_accel_map_foreach_unfiltered(data, foreachFunc); 232 } 233 234 /** 235 * Gets the singleton global #GtkAccelMap object. This object 236 * is useful only for notification of changes to the accelerator 237 * map via the ::changed signal; it isn’t a parameter to the 238 * other accelerator map functions. 239 * 240 * Returns: the global #GtkAccelMap object 241 * 242 * Since: 2.4 243 */ 244 public static AccelMap get() 245 { 246 auto p = gtk_accel_map_get(); 247 248 if(p is null) 249 { 250 return null; 251 } 252 253 return ObjectG.getDObject!(AccelMap)(cast(GtkAccelMap*) p); 254 } 255 256 /** 257 * Parses a file previously saved with gtk_accel_map_save() for 258 * accelerator specifications, and propagates them accordingly. 259 * 260 * Params: 261 * fileName = a file containing accelerator specifications, 262 * in the GLib file name encoding 263 */ 264 public static void load(string fileName) 265 { 266 gtk_accel_map_load(Str.toStringz(fileName)); 267 } 268 269 /** 270 * Filedescriptor variant of gtk_accel_map_load(). 271 * 272 * Note that the file descriptor will not be closed by this function. 273 * 274 * Params: 275 * fd = a valid readable file descriptor 276 */ 277 public static void loadFd(int fd) 278 { 279 gtk_accel_map_load_fd(fd); 280 } 281 282 /** 283 * #GScanner variant of gtk_accel_map_load(). 284 * 285 * Params: 286 * scanner = a #GScanner which has already been provided with an input file 287 */ 288 public static void loadScanner(ScannerG scanner) 289 { 290 gtk_accel_map_load_scanner((scanner is null) ? null : scanner.getScannerGStruct()); 291 } 292 293 /** 294 * Locks the given accelerator path. If the accelerator map doesn’t yet contain 295 * an entry for @accel_path, a new one is created. 296 * 297 * Locking an accelerator path prevents its accelerator from being changed 298 * during runtime. A locked accelerator path can be unlocked by 299 * gtk_accel_map_unlock_path(). Refer to gtk_accel_map_change_entry() 300 * for information about runtime accelerator changes. 301 * 302 * If called more than once, @accel_path remains locked until 303 * gtk_accel_map_unlock_path() has been called an equivalent number 304 * of times. 305 * 306 * Note that locking of individual accelerator paths is independent from 307 * locking the #GtkAccelGroup containing them. For runtime accelerator 308 * changes to be possible, both the accelerator path and its #GtkAccelGroup 309 * have to be unlocked. 310 * 311 * Params: 312 * accelPath = a valid accelerator path 313 * 314 * Since: 2.4 315 */ 316 public static void lockPath(string accelPath) 317 { 318 gtk_accel_map_lock_path(Str.toStringz(accelPath)); 319 } 320 321 /** 322 * Looks up the accelerator entry for @accel_path and fills in @key. 323 * 324 * Params: 325 * accelPath = a valid accelerator path 326 * key = the accelerator key to be filled in (optional) 327 * 328 * Returns: %TRUE if @accel_path is known, %FALSE otherwise 329 */ 330 public static bool lookupEntry(string accelPath, out GtkAccelKey key) 331 { 332 return gtk_accel_map_lookup_entry(Str.toStringz(accelPath), &key) != 0; 333 } 334 335 /** 336 * Saves current accelerator specifications (accelerator path, key 337 * and modifiers) to @file_name. 338 * The file is written in a format suitable to be read back in by 339 * gtk_accel_map_load(). 340 * 341 * Params: 342 * fileName = the name of the file to contain 343 * accelerator specifications, in the GLib file name encoding 344 */ 345 public static void save(string fileName) 346 { 347 gtk_accel_map_save(Str.toStringz(fileName)); 348 } 349 350 /** 351 * Filedescriptor variant of gtk_accel_map_save(). 352 * 353 * Note that the file descriptor will not be closed by this function. 354 * 355 * Params: 356 * fd = a valid writable file descriptor 357 */ 358 public static void saveFd(int fd) 359 { 360 gtk_accel_map_save_fd(fd); 361 } 362 363 /** 364 * Undoes the last call to gtk_accel_map_lock_path() on this @accel_path. 365 * Refer to gtk_accel_map_lock_path() for information about accelerator path locking. 366 * 367 * Params: 368 * accelPath = a valid accelerator path 369 * 370 * Since: 2.4 371 */ 372 public static void unlockPath(string accelPath) 373 { 374 gtk_accel_map_unlock_path(Str.toStringz(accelPath)); 375 } 376 377 protected class OnChangedDelegateWrapper 378 { 379 static OnChangedDelegateWrapper[] listeners; 380 void delegate(string, uint, GdkModifierType, AccelMap) dlg; 381 gulong handlerId; 382 383 this(void delegate(string, uint, GdkModifierType, AccelMap) dlg) 384 { 385 this.dlg = dlg; 386 this.listeners ~= this; 387 } 388 389 void remove(OnChangedDelegateWrapper source) 390 { 391 foreach(index, wrapper; listeners) 392 { 393 if (wrapper.handlerId == source.handlerId) 394 { 395 listeners[index] = null; 396 listeners = std.algorithm.remove(listeners, index); 397 break; 398 } 399 } 400 } 401 } 402 403 /** 404 * Notifies of a change in the global accelerator map. 405 * The path is also used as the detail for the signal, 406 * so it is possible to connect to 407 * changed::`accel_path`. 408 * 409 * Params: 410 * accelPath = the path of the accelerator that changed 411 * accelKey = the key value for the new accelerator 412 * accelMods = the modifier mask for the new accelerator 413 * 414 * Since: 2.4 415 */ 416 gulong addOnChanged(void delegate(string, uint, GdkModifierType, AccelMap) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 417 { 418 auto wrapper = new OnChangedDelegateWrapper(dlg); 419 wrapper.handlerId = Signals.connectData( 420 this, 421 "changed", 422 cast(GCallback)&callBackChanged, 423 cast(void*)wrapper, 424 cast(GClosureNotify)&callBackChangedDestroy, 425 connectFlags); 426 return wrapper.handlerId; 427 } 428 429 extern(C) static void callBackChanged(GtkAccelMap* accelmapStruct, char* accelPath, uint accelKey, GdkModifierType accelMods, OnChangedDelegateWrapper wrapper) 430 { 431 wrapper.dlg(Str.toString(accelPath), accelKey, accelMods, wrapper.outer); 432 } 433 434 extern(C) static void callBackChangedDestroy(OnChangedDelegateWrapper wrapper, GClosure* closure) 435 { 436 wrapper.remove(wrapper); 437 } 438 }