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