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 public  import gtkc.gdktypes;
32 private import gtkc.gtk;
33 public  import gtkc.gtktypes;
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()
98 	{
99 		return gtkAccelMap;
100 	}
101 
102 	/** the main Gtk struct as a void* */
103 	protected override void* getStruct()
104 	{
105 		return cast(void*)gtkAccelMap;
106 	}
107 
108 	protected override void setStruct(GObject* obj)
109 	{
110 		gtkAccelMap = cast(GtkAccelMap*)obj;
111 		super.setStruct(obj);
112 	}
113 
114 	/**
115 	 * Sets our main struct and passes it to the parent class.
116 	 */
117 	public this (GtkAccelMap* gtkAccelMap, bool ownedRef = false)
118 	{
119 		this.gtkAccelMap = gtkAccelMap;
120 		super(cast(GObject*)gtkAccelMap, ownedRef);
121 	}
122 
123 
124 	/** */
125 	public static GType getType()
126 	{
127 		return gtk_accel_map_get_type();
128 	}
129 
130 	/**
131 	 * Registers a new accelerator with the global accelerator map.
132 	 * This function should only be called once per @accel_path
133 	 * with the canonical @accel_key and @accel_mods for this path.
134 	 * To change the accelerator during runtime programatically, use
135 	 * gtk_accel_map_change_entry().
136 	 *
137 	 * Set @accel_key and @accel_mods to 0 to request a removal of
138 	 * the accelerator.
139 	 *
140 	 * Note that @accel_path string will be stored in a #GQuark. Therefore, if you
141 	 * pass a static string, you can save some memory by interning it first with
142 	 * g_intern_static_string().
143 	 *
144 	 * Params:
145 	 *     accelPath = valid accelerator path
146 	 *     accelKey = the accelerator key
147 	 *     accelMods = the accelerator modifiers
148 	 */
149 	public static void addEntry(string accelPath, uint accelKey, GdkModifierType accelMods)
150 	{
151 		gtk_accel_map_add_entry(Str.toStringz(accelPath), accelKey, accelMods);
152 	}
153 
154 	/**
155 	 * Adds a filter to the global list of accel path filters.
156 	 *
157 	 * Accel map entries whose accel path matches one of the filters
158 	 * are skipped by gtk_accel_map_foreach().
159 	 *
160 	 * This function is intended for GTK+ modules that create their own
161 	 * menus, but don’t want them to be saved into the applications accelerator
162 	 * map dump.
163 	 *
164 	 * Params:
165 	 *     filterPattern = a pattern (see #GPatternSpec)
166 	 */
167 	public static void addFilter(string filterPattern)
168 	{
169 		gtk_accel_map_add_filter(Str.toStringz(filterPattern));
170 	}
171 
172 	/**
173 	 * Changes the @accel_key and @accel_mods currently associated with @accel_path.
174 	 * Due to conflicts with other accelerators, a change may not always be possible,
175 	 * @replace indicates whether other accelerators may be deleted to resolve such
176 	 * conflicts. A change will only occur if all conflicts could be resolved (which
177 	 * might not be the case if conflicting accelerators are locked). Successful
178 	 * changes are indicated by a %TRUE return value.
179 	 *
180 	 * Note that @accel_path string will be stored in a #GQuark. Therefore, if you
181 	 * pass a static string, you can save some memory by interning it first with
182 	 * g_intern_static_string().
183 	 *
184 	 * Params:
185 	 *     accelPath = a valid accelerator path
186 	 *     accelKey = the new accelerator key
187 	 *     accelMods = the new accelerator modifiers
188 	 *     replace = %TRUE if other accelerators may be deleted upon conflicts
189 	 *
190 	 * Return: %TRUE if the accelerator could be changed, %FALSE otherwise
191 	 */
192 	public static bool changeEntry(string accelPath, uint accelKey, GdkModifierType accelMods, bool replace)
193 	{
194 		return gtk_accel_map_change_entry(Str.toStringz(accelPath), accelKey, accelMods, replace) != 0;
195 	}
196 
197 	/**
198 	 * Loops over the entries in the accelerator map whose accel path
199 	 * doesn’t match any of the filters added with gtk_accel_map_add_filter(),
200 	 * and execute @foreach_func on each. The signature of @foreach_func is
201 	 * that of #GtkAccelMapForeach, the @changed parameter indicates whether
202 	 * this accelerator was changed during runtime (thus, would need
203 	 * saving during an accelerator map dump).
204 	 *
205 	 * Params:
206 	 *     data = data to be passed into @foreach_func
207 	 *     foreachFunc = function to be executed for each accel
208 	 *         map entry which is not filtered out
209 	 */
210 	public static void foreac(void* data, GtkAccelMapForeach foreachFunc)
211 	{
212 		gtk_accel_map_foreach(data, foreachFunc);
213 	}
214 
215 	/**
216 	 * Loops over all entries in the accelerator map, and execute
217 	 * @foreach_func on each. The signature of @foreach_func is that of
218 	 * #GtkAccelMapForeach, the @changed parameter indicates whether
219 	 * this accelerator was changed during runtime (thus, would need
220 	 * saving during an accelerator map dump).
221 	 *
222 	 * Params:
223 	 *     data = data to be passed into @foreach_func
224 	 *     foreachFunc = function to be executed for each accel
225 	 *         map entry
226 	 */
227 	public static void foreachUnfiltered(void* data, GtkAccelMapForeach foreachFunc)
228 	{
229 		gtk_accel_map_foreach_unfiltered(data, foreachFunc);
230 	}
231 
232 	/**
233 	 * Gets the singleton global #GtkAccelMap object. This object
234 	 * is useful only for notification of changes to the accelerator
235 	 * map via the ::changed signal; it isn’t a parameter to the
236 	 * other accelerator map functions.
237 	 *
238 	 * Return: the global #GtkAccelMap object
239 	 *
240 	 * Since: 2.4
241 	 */
242 	public static AccelMap get()
243 	{
244 		auto p = gtk_accel_map_get();
245 		
246 		if(p is null)
247 		{
248 			return null;
249 		}
250 		
251 		return ObjectG.getDObject!(AccelMap)(cast(GtkAccelMap*) p);
252 	}
253 
254 	/**
255 	 * Parses a file previously saved with gtk_accel_map_save() for
256 	 * accelerator specifications, and propagates them accordingly.
257 	 *
258 	 * Params:
259 	 *     fileName = a file containing accelerator specifications,
260 	 *         in the GLib file name encoding
261 	 */
262 	public static void load(string fileName)
263 	{
264 		gtk_accel_map_load(Str.toStringz(fileName));
265 	}
266 
267 	/**
268 	 * Filedescriptor variant of gtk_accel_map_load().
269 	 *
270 	 * Note that the file descriptor will not be closed by this function.
271 	 *
272 	 * Params:
273 	 *     fd = a valid readable file descriptor
274 	 */
275 	public static void loadFd(int fd)
276 	{
277 		gtk_accel_map_load_fd(fd);
278 	}
279 
280 	/**
281 	 * #GScanner variant of gtk_accel_map_load().
282 	 *
283 	 * Params:
284 	 *     scanner = a #GScanner which has already been provided with an input file
285 	 */
286 	public static void loadScanner(ScannerG scanner)
287 	{
288 		gtk_accel_map_load_scanner((scanner is null) ? null : scanner.getScannerGStruct());
289 	}
290 
291 	/**
292 	 * Locks the given accelerator path. If the accelerator map doesn’t yet contain
293 	 * an entry for @accel_path, a new one is created.
294 	 *
295 	 * Locking an accelerator path prevents its accelerator from being changed
296 	 * during runtime. A locked accelerator path can be unlocked by
297 	 * gtk_accel_map_unlock_path(). Refer to gtk_accel_map_change_entry()
298 	 * for information about runtime accelerator changes.
299 	 *
300 	 * If called more than once, @accel_path remains locked until
301 	 * gtk_accel_map_unlock_path() has been called an equivalent number
302 	 * of times.
303 	 *
304 	 * Note that locking of individual accelerator paths is independent from
305 	 * locking the #GtkAccelGroup containing them. For runtime accelerator
306 	 * changes to be possible, both the accelerator path and its #GtkAccelGroup
307 	 * have to be unlocked.
308 	 *
309 	 * Params:
310 	 *     accelPath = a valid accelerator path
311 	 *
312 	 * Since: 2.4
313 	 */
314 	public static void lockPath(string accelPath)
315 	{
316 		gtk_accel_map_lock_path(Str.toStringz(accelPath));
317 	}
318 
319 	/**
320 	 * Looks up the accelerator entry for @accel_path and fills in @key.
321 	 *
322 	 * Params:
323 	 *     accelPath = a valid accelerator path
324 	 *     key = the accelerator key to be filled in (optional)
325 	 *
326 	 * Return: %TRUE if @accel_path is known, %FALSE otherwise
327 	 */
328 	public static bool lookupEntry(string accelPath, out GtkAccelKey key)
329 	{
330 		return gtk_accel_map_lookup_entry(Str.toStringz(accelPath), &key) != 0;
331 	}
332 
333 	/**
334 	 * Saves current accelerator specifications (accelerator path, key
335 	 * and modifiers) to @file_name.
336 	 * The file is written in a format suitable to be read back in by
337 	 * gtk_accel_map_load().
338 	 *
339 	 * Params:
340 	 *     fileName = the name of the file to contain
341 	 *         accelerator specifications, in the GLib file name encoding
342 	 */
343 	public static void save(string fileName)
344 	{
345 		gtk_accel_map_save(Str.toStringz(fileName));
346 	}
347 
348 	/**
349 	 * Filedescriptor variant of gtk_accel_map_save().
350 	 *
351 	 * Note that the file descriptor will not be closed by this function.
352 	 *
353 	 * Params:
354 	 *     fd = a valid writable file descriptor
355 	 */
356 	public static void saveFd(int fd)
357 	{
358 		gtk_accel_map_save_fd(fd);
359 	}
360 
361 	/**
362 	 * Undoes the last call to gtk_accel_map_lock_path() on this @accel_path.
363 	 * Refer to gtk_accel_map_lock_path() for information about accelerator path locking.
364 	 *
365 	 * Params:
366 	 *     accelPath = a valid accelerator path
367 	 *
368 	 * Since: 2.4
369 	 */
370 	public static void unlockPath(string accelPath)
371 	{
372 		gtk_accel_map_unlock_path(Str.toStringz(accelPath));
373 	}
374 
375 	int[string] connectedSignals;
376 
377 	void delegate(string, uint, GdkModifierType, AccelMap)[] onChangedListeners;
378 	/**
379 	 * Notifies of a change in the global accelerator map.
380 	 * The path is also used as the detail for the signal,
381 	 * so it is possible to connect to
382 	 * changed::`accel_path`.
383 	 *
384 	 * Params:
385 	 *     accelPath = the path of the accelerator that changed
386 	 *     accelKey = the key value for the new accelerator
387 	 *     accelMods = the modifier mask for the new accelerator
388 	 *
389 	 * Since: 2.4
390 	 */
391 	void addOnChanged(void delegate(string, uint, GdkModifierType, AccelMap) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
392 	{
393 		if ( "changed" !in connectedSignals )
394 		{
395 			Signals.connectData(
396 				this,
397 				"changed",
398 				cast(GCallback)&callBackChanged,
399 				cast(void*)this,
400 				null,
401 				connectFlags);
402 			connectedSignals["changed"] = 1;
403 		}
404 		onChangedListeners ~= dlg;
405 	}
406 	extern(C) static void callBackChanged(GtkAccelMap* accelmapStruct, char* accelPath, uint accelKey, GdkModifierType accelMods, AccelMap _accelmap)
407 	{
408 		foreach ( void delegate(string, uint, GdkModifierType, AccelMap) dlg; _accelmap.onChangedListeners )
409 		{
410 			dlg(Str.toString(accelPath), accelKey, accelMods, _accelmap);
411 		}
412 	}
413 }