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.Main;
26 
27 private import gdk.Device;
28 private import gdk.Event;
29 private import gdk.Threads;
30 private import glib.ErrorG;
31 private import glib.GException;
32 private import glib.OptionGroup;
33 private import glib.Str;
34 private import gobject.ObjectG;
35 private import gtk.Widget;
36 private import gtkc.gtk;
37 public  import gtkc.gtktypes;
38 private import pango.PgLanguage;
39 
40 
41 public struct Main
42 {
43 	/**
44 	 * This initiates GtkD to supports multi threaded programs.
45 	 * read full documantation at http://gtk.org/faq/#AEN482
46 	 * from the FAQ:
47 	 * "There is a single global lock that you must acquire with
48 	 * gdk_threads_enter() before making any GDK calls,
49 	 * and release with gdk_threads_leave() afterwards throughout your code."
50 	 * This is to be used on any call to GDK not executed from the main thread.
51 	 */
52 	public static void initMultiThread(string[] args)
53 	{
54 		threadsInit();
55 		init(args);
56 	}
57 
58 	/**
59 	 */
60 
61 	/**
62 	 * Adds a GTK+ grab on @device, so all the events on @device and its
63 	 * associated pointer or keyboard (if any) are delivered to @widget.
64 	 * If the @block_others parameter is %TRUE, any other devices will be
65 	 * unable to interact with @widget during the grab.
66 	 *
67 	 * Params:
68 	 *     widget = a #GtkWidget
69 	 *     device = a #GdkDevice to grab on.
70 	 *     blockOthers = %TRUE to prevent other devices to interact with @widget.
71 	 *
72 	 * Since: 3.0
73 	 */
74 	public static void deviceGrabAdd(Widget widget, Device device, bool blockOthers)
75 	{
76 		gtk_device_grab_add((widget is null) ? null : widget.getWidgetStruct(), (device is null) ? null : device.getDeviceStruct(), blockOthers);
77 	}
78 
79 	/**
80 	 * Removes a device grab from the given widget.
81 	 *
82 	 * You have to pair calls to gtk_device_grab_add() and
83 	 * gtk_device_grab_remove().
84 	 *
85 	 * Params:
86 	 *     widget = a #GtkWidget
87 	 *     device = a #GdkDevice
88 	 *
89 	 * Since: 3.0
90 	 */
91 	public static void deviceGrabRemove(Widget widget, Device device)
92 	{
93 		gtk_device_grab_remove((widget is null) ? null : widget.getWidgetStruct(), (device is null) ? null : device.getDeviceStruct());
94 	}
95 
96 	/**
97 	 * Prevents gtk_init(), gtk_init_check(), gtk_init_with_args() and
98 	 * gtk_parse_args() from automatically
99 	 * calling `setlocale (LC_ALL, "")`. You would
100 	 * want to use this function if you wanted to set the locale for
101 	 * your program to something other than the user’s locale, or if
102 	 * you wanted to set different values for different locale categories.
103 	 *
104 	 * Most programs should not need to call this function.
105 	 */
106 	public static void disableSetlocale()
107 	{
108 		gtk_disable_setlocale();
109 	}
110 
111 	/**
112 	 * Checks if any events are pending.
113 	 *
114 	 * This can be used to update the UI and invoke timeouts etc.
115 	 * while doing some time intensive computation.
116 	 *
117 	 * ## Updating the UI during a long computation
118 	 *
119 	 * |[<!-- language="C" -->
120 	 * // computation going on...
121 	 *
122 	 * while (gtk_events_pending ())
123 	 * gtk_main_iteration ();
124 	 *
125 	 * // ...computation continued
126 	 * ]|
127 	 *
128 	 * Return: %TRUE if any events are pending, %FALSE otherwise
129 	 */
130 	public static bool eventsPending()
131 	{
132 		return gtk_events_pending() != 0;
133 	}
134 
135 	/**
136 	 * Obtains a copy of the event currently being processed by GTK+.
137 	 *
138 	 * For example, if you are handling a #GtkButton::clicked signal,
139 	 * the current event will be the #GdkEventButton that triggered
140 	 * the ::clicked signal.
141 	 *
142 	 * Return: a copy of the current event, or
143 	 *     %NULL if there is no current event. The returned event must be
144 	 *     freed with gdk_event_free().
145 	 */
146 	public static Event getCurrentEvent()
147 	{
148 		auto p = gtk_get_current_event();
149 		
150 		if(p is null)
151 		{
152 			return null;
153 		}
154 		
155 		return ObjectG.getDObject!(Event)(cast(GdkEvent*) p);
156 	}
157 
158 	/**
159 	 * If there is a current event and it has a device, return that
160 	 * device, otherwise return %NULL.
161 	 *
162 	 * Return: a #GdkDevice, or %NULL
163 	 */
164 	public static Device getCurrentEventDevice()
165 	{
166 		auto p = gtk_get_current_event_device();
167 		
168 		if(p is null)
169 		{
170 			return null;
171 		}
172 		
173 		return ObjectG.getDObject!(Device)(cast(GdkDevice*) p);
174 	}
175 
176 	/**
177 	 * If there is a current event and it has a state field, place
178 	 * that state field in @state and return %TRUE, otherwise return
179 	 * %FALSE.
180 	 *
181 	 * Params:
182 	 *     state = a location to store the state of the current event
183 	 *
184 	 * Return: %TRUE if there was a current event and it
185 	 *     had a state field
186 	 */
187 	public static bool getCurrentEventState(out GdkModifierType state)
188 	{
189 		return gtk_get_current_event_state(&state) != 0;
190 	}
191 
192 	/**
193 	 * If there is a current event and it has a timestamp,
194 	 * return that timestamp, otherwise return %GDK_CURRENT_TIME.
195 	 *
196 	 * Return: the timestamp from the current event,
197 	 *     or %GDK_CURRENT_TIME.
198 	 */
199 	public static uint getCurrentEventTime()
200 	{
201 		return gtk_get_current_event_time();
202 	}
203 
204 	/**
205 	 * Returns the GTK+ debug flags.
206 	 *
207 	 * This function is intended for GTK+ modules that want
208 	 * to adjust their debug output based on GTK+ debug flags.
209 	 *
210 	 * Return: the GTK+ debug flags.
211 	 */
212 	public static uint getDebugFlags()
213 	{
214 		return gtk_get_debug_flags();
215 	}
216 
217 	/**
218 	 * Returns the #PangoLanguage for the default language currently in
219 	 * effect. (Note that this can change over the life of an
220 	 * application.) The default language is derived from the current
221 	 * locale. It determines, for example, whether GTK+ uses the
222 	 * right-to-left or left-to-right text direction.
223 	 *
224 	 * This function is equivalent to pango_language_get_default().
225 	 * See that function for details.
226 	 *
227 	 * Return: the default language as a #PangoLanguage,
228 	 *     must not be freed
229 	 */
230 	public static PgLanguage getDefaultLanguage()
231 	{
232 		auto p = gtk_get_default_language();
233 		
234 		if(p is null)
235 		{
236 			return null;
237 		}
238 		
239 		return ObjectG.getDObject!(PgLanguage)(cast(PangoLanguage*) p);
240 	}
241 
242 	/**
243 	 * If @event is %NULL or the event was not associated with any widget,
244 	 * returns %NULL, otherwise returns the widget that received the event
245 	 * originally.
246 	 *
247 	 * Params:
248 	 *     event = a #GdkEvent
249 	 *
250 	 * Return: the widget that originally
251 	 *     received @event, or %NULL
252 	 */
253 	public static Widget getEventWidget(Event event)
254 	{
255 		auto p = gtk_get_event_widget((event is null) ? null : event.getEventStruct());
256 		
257 		if(p is null)
258 		{
259 			return null;
260 		}
261 		
262 		return ObjectG.getDObject!(Widget)(cast(GtkWidget*) p);
263 	}
264 
265 	/**
266 	 * Get the direction of the current locale. This is the expected
267 	 * reading direction for text and UI.
268 	 *
269 	 * This function depends on the current locale being set with
270 	 * setlocale() and will default to setting the %GTK_TEXT_DIR_LTR
271 	 * direction otherwise. %GTK_TEXT_DIR_NONE will never be returned.
272 	 *
273 	 * GTK+ sets the default text direction according to the locale
274 	 * during gtk_init(), and you should normally use
275 	 * gtk_widget_get_direction() or gtk_widget_get_default_direction()
276 	 * to obtain the current direcion.
277 	 *
278 	 * This function is only needed rare cases when the locale is
279 	 * changed after GTK+ has already been initialized. In this case,
280 	 * you can use it to update the default text direction as follows:
281 	 *
282 	 * |[<!-- language="C" -->
283 	 * setlocale (LC_ALL, new_locale);
284 	 * direction = gtk_get_locale_direction ();
285 	 * gtk_widget_set_default_direction (direction);
286 	 * ]|
287 	 *
288 	 * Return: the #GtkTextDirection of the current locale
289 	 *
290 	 * Since: 3.12
291 	 */
292 	public static GtkTextDirection getLocaleDirection()
293 	{
294 		return gtk_get_locale_direction();
295 	}
296 
297 	/**
298 	 * Returns a #GOptionGroup for the commandline arguments recognized
299 	 * by GTK+ and GDK.
300 	 *
301 	 * You should add this group to your #GOptionContext
302 	 * with g_option_context_add_group(), if you are using
303 	 * g_option_context_parse() to parse your commandline arguments.
304 	 *
305 	 * Params:
306 	 *     openDefaultDisplay = whether to open the default display
307 	 *         when parsing the commandline arguments
308 	 *
309 	 * Return: a #GOptionGroup for the commandline
310 	 *     arguments recognized by GTK+
311 	 *
312 	 * Since: 2.6
313 	 */
314 	public static OptionGroup getOptionGroup(bool openDefaultDisplay)
315 	{
316 		auto p = gtk_get_option_group(openDefaultDisplay);
317 		
318 		if(p is null)
319 		{
320 			return null;
321 		}
322 		
323 		return new OptionGroup(cast(GOptionGroup*) p);
324 	}
325 
326 	/**
327 	 * Queries the current grab of the default window group.
328 	 *
329 	 * Return: The widget which currently
330 	 *     has the grab or %NULL if no grab is active
331 	 */
332 	public static Widget grabGetCurrent()
333 	{
334 		auto p = gtk_grab_get_current();
335 		
336 		if(p is null)
337 		{
338 			return null;
339 		}
340 		
341 		return ObjectG.getDObject!(Widget)(cast(GtkWidget*) p);
342 	}
343 
344 	/**
345 	 * Call this function before using any other GTK+ functions in your GUI
346 	 * applications.  It will initialize everything needed to operate the
347 	 * toolkit and parses some standard command line options.
348 	 *
349 	 * Although you are expected to pass the @argc, @argv parameters from main() to
350 	 * this function, it is possible to pass %NULL if @argv is not available or
351 	 * commandline handling is not required.
352 	 *
353 	 * @argc and @argv are adjusted accordingly so your own code will
354 	 * never see those standard arguments.
355 	 *
356 	 * Note that there are some alternative ways to initialize GTK+:
357 	 * if you are calling gtk_parse_args(), gtk_init_check(),
358 	 * gtk_init_with_args() or g_option_context_parse() with
359 	 * the option group returned by gtk_get_option_group(),
360 	 * you don’t have to call gtk_init().
361 	 *
362 	 * And if you are using #GtkApplication, you don't have to call any of the
363 	 * initialization functions either; the #GtkApplication::startup handler
364 	 * does it for you.
365 	 *
366 	 * This function will terminate your program if it was unable to
367 	 * initialize the windowing system for some reason. If you want
368 	 * your program to fall back to a textual interface you want to
369 	 * call gtk_init_check() instead.
370 	 *
371 	 * Since 2.18, GTK+ calls `signal (SIGPIPE, SIG_IGN)`
372 	 * during initialization, to ignore SIGPIPE signals, since these are
373 	 * almost never wanted in graphical applications. If you do need to
374 	 * handle SIGPIPE for some reason, reset the handler after gtk_init(),
375 	 * but notice that other libraries (e.g. libdbus or gvfs) might do
376 	 * similar things.
377 	 *
378 	 * Params:
379 	 *     argc = Address of the `argc` parameter of
380 	 *         your main() function (or 0 if @argv is %NULL). This will be changed if
381 	 *         any arguments were handled.
382 	 *     argv = Address of the
383 	 *         `argv` parameter of main(), or %NULL. Any options
384 	 *         understood by GTK+ are stripped before return.
385 	 */
386 	public static void init(ref string[] argv)
387 	{
388 		int argc = cast(int)argv.length;
389 		char** outargv = Str.toStringzArray(argv);
390 		
391 		gtk_init(&argc, &outargv);
392 		
393 		argv = Str.toStringArray(outargv, argc);
394 	}
395 
396 	/**
397 	 * This function does the same work as gtk_init() with only a single
398 	 * change: It does not terminate the program if the windowing system
399 	 * can’t be initialized. Instead it returns %FALSE on failure.
400 	 *
401 	 * This way the application can fall back to some other means of
402 	 * communication with the user - for example a curses or command line
403 	 * interface.
404 	 *
405 	 * Params:
406 	 *     argc = Address of the `argc` parameter of
407 	 *         your main() function (or 0 if @argv is %NULL). This will be changed if
408 	 *         any arguments were handled.
409 	 *     argv = Address of the
410 	 *         `argv` parameter of main(), or %NULL. Any options
411 	 *         understood by GTK+ are stripped before return.
412 	 *
413 	 * Return: %TRUE if the windowing system has been successfully
414 	 *     initialized, %FALSE otherwise
415 	 */
416 	public static bool initCheck(ref string[] argv)
417 	{
418 		int argc = cast(int)argv.length;
419 		char** outargv = Str.toStringzArray(argv);
420 		
421 		auto p = gtk_init_check(&argc, &outargv) != 0;
422 		
423 		argv = Str.toStringArray(outargv, argc);
424 		
425 		return p;
426 	}
427 
428 	/**
429 	 * This function does the same work as gtk_init_check().
430 	 * Additionally, it allows you to add your own commandline options,
431 	 * and it automatically generates nicely formatted
432 	 * `--help` output. Note that your program will
433 	 * be terminated after writing out the help output.
434 	 *
435 	 * Params:
436 	 *     argc = Address of the `argc` parameter of
437 	 *         your main() function (or 0 if @argv is %NULL). This will be changed if
438 	 *         any arguments were handled.
439 	 *     argv = Address of the
440 	 *         `argv` parameter of main(), or %NULL. Any options
441 	 *         understood by GTK+ are stripped before return.
442 	 *     parameterString = a string which is displayed in
443 	 *         the first line of `--help` output, after
444 	 *         `programname [OPTION...]`
445 	 *     entries = a %NULL-terminated array
446 	 *         of #GOptionEntrys describing the options of your program
447 	 *     translationDomain = a translation domain to use for translating
448 	 *         the `--help` output for the options in @entries
449 	 *         and the @parameter_string with gettext(), or %NULL
450 	 *
451 	 * Return: %TRUE if the windowing system has been successfully
452 	 *     initialized, %FALSE otherwise
453 	 *
454 	 * Since: 2.6
455 	 *
456 	 * Throws: GException on failure.
457 	 */
458 	public static bool initWithArgs(ref string[] argv, string parameterString, GOptionEntry[] entries, string translationDomain)
459 	{
460 		int argc = cast(int)argv.length;
461 		char** outargv = Str.toStringzArray(argv);
462 		GError* err = null;
463 		
464 		auto p = gtk_init_with_args(&argc, &outargv, Str.toStringz(parameterString), entries.ptr, Str.toStringz(translationDomain), &err) != 0;
465 		
466 		if (err !is null)
467 		{
468 			throw new GException( new ErrorG(err) );
469 		}
470 		
471 		argv = Str.toStringArray(outargv, argc);
472 		
473 		return p;
474 	}
475 
476 	/**
477 	 * Installs a key snooper function, which will get called on all
478 	 * key events before delivering them normally.
479 	 *
480 	 * Deprecated: Key snooping should not be done. Events should
481 	 * be handled by widgets.
482 	 *
483 	 * Params:
484 	 *     snooper = a #GtkKeySnoopFunc
485 	 *     funcData = data to pass to @snooper
486 	 *
487 	 * Return: a unique id for this key snooper for use with
488 	 *     gtk_key_snooper_remove().
489 	 */
490 	public static uint keySnooperInstall(GtkKeySnoopFunc snooper, void* funcData)
491 	{
492 		return gtk_key_snooper_install(snooper, funcData);
493 	}
494 
495 	/**
496 	 * Removes the key snooper function with the given id.
497 	 *
498 	 * Deprecated: Key snooping should not be done. Events should
499 	 * be handled by widgets.
500 	 *
501 	 * Params:
502 	 *     snooperHandlerId = Identifies the key snooper to remove
503 	 */
504 	public static void keySnooperRemove(uint snooperHandlerId)
505 	{
506 		gtk_key_snooper_remove(snooperHandlerId);
507 	}
508 
509 	/**
510 	 * Runs the main loop until gtk_main_quit() is called.
511 	 *
512 	 * You can nest calls to gtk_main(). In that case gtk_main_quit()
513 	 * will make the innermost invocation of the main loop return.
514 	 */
515 	public static void run()
516 	{
517 		gtk_main();
518 	}
519 
520 	/**
521 	 * Processes a single GDK event.
522 	 *
523 	 * This is public only to allow filtering of events between GDK and GTK+.
524 	 * You will not usually need to call this function directly.
525 	 *
526 	 * While you should not call this function directly, you might want to
527 	 * know how exactly events are handled. So here is what this function
528 	 * does with the event:
529 	 *
530 	 * 1. Compress enter/leave notify events. If the event passed build an
531 	 * enter/leave pair together with the next event (peeked from GDK), both
532 	 * events are thrown away. This is to avoid a backlog of (de-)highlighting
533 	 * widgets crossed by the pointer.
534 	 *
535 	 * 2. Find the widget which got the event. If the widget can’t be determined
536 	 * the event is thrown away unless it belongs to a INCR transaction.
537 	 *
538 	 * 3. Then the event is pushed onto a stack so you can query the currently
539 	 * handled event with gtk_get_current_event().
540 	 *
541 	 * 4. The event is sent to a widget. If a grab is active all events for widgets
542 	 * that are not in the contained in the grab widget are sent to the latter
543 	 * with a few exceptions:
544 	 * - Deletion and destruction events are still sent to the event widget for
545 	 * obvious reasons.
546 	 * - Events which directly relate to the visual representation of the event
547 	 * widget.
548 	 * - Leave events are delivered to the event widget if there was an enter
549 	 * event delivered to it before without the paired leave event.
550 	 * - Drag events are not redirected because it is unclear what the semantics
551 	 * of that would be.
552 	 * Another point of interest might be that all key events are first passed
553 	 * through the key snooper functions if there are any. Read the description
554 	 * of gtk_key_snooper_install() if you need this feature.
555 	 *
556 	 * 5. After finishing the delivery the event is popped from the event stack.
557 	 *
558 	 * Params:
559 	 *     event = An event to process (normally passed by GDK)
560 	 */
561 	public static void doEvent(Event event)
562 	{
563 		gtk_main_do_event((event is null) ? null : event.getEventStruct());
564 	}
565 
566 	/**
567 	 * Runs a single iteration of the mainloop.
568 	 *
569 	 * If no events are waiting to be processed GTK+ will block
570 	 * until the next event is noticed. If you don’t want to block
571 	 * look at gtk_main_iteration_do() or check if any events are
572 	 * pending with gtk_events_pending() first.
573 	 *
574 	 * Return: %TRUE if gtk_main_quit() has been called for the
575 	 *     innermost mainloop
576 	 */
577 	public static bool iteration()
578 	{
579 		return gtk_main_iteration() != 0;
580 	}
581 
582 	/**
583 	 * Runs a single iteration of the mainloop.
584 	 * If no events are available either return or block depending on
585 	 * the value of @blocking.
586 	 *
587 	 * Params:
588 	 *     blocking = %TRUE if you want GTK+ to block if no events are pending
589 	 *
590 	 * Return: %TRUE if gtk_main_quit() has been called for the
591 	 *     innermost mainloop
592 	 */
593 	public static bool iterationDo(bool blocking)
594 	{
595 		return gtk_main_iteration_do(blocking) != 0;
596 	}
597 
598 	/**
599 	 * Asks for the current nesting level of the main loop.
600 	 *
601 	 * Return: the nesting level of the current invocation
602 	 *     of the main loop
603 	 */
604 	public static uint level()
605 	{
606 		return gtk_main_level();
607 	}
608 
609 	/**
610 	 * Makes the innermost invocation of the main loop return
611 	 * when it regains control.
612 	 */
613 	public static void quit()
614 	{
615 		gtk_main_quit();
616 	}
617 
618 	/**
619 	 * Parses command line arguments, and initializes global
620 	 * attributes of GTK+, but does not actually open a connection
621 	 * to a display. (See gdk_display_open(), gdk_get_display_arg_name())
622 	 *
623 	 * Any arguments used by GTK+ or GDK are removed from the array and
624 	 * @argc and @argv are updated accordingly.
625 	 *
626 	 * There is no need to call this function explicitly if you are using
627 	 * gtk_init(), or gtk_init_check().
628 	 *
629 	 * Params:
630 	 *     argc = a pointer to the number of command line arguments
631 	 *     argv = a pointer to the array of
632 	 *         command line arguments
633 	 *
634 	 * Return: %TRUE if initialization succeeded, otherwise %FALSE
635 	 */
636 	public static bool parseArgs(ref string[] argv)
637 	{
638 		int argc = cast(int)argv.length;
639 		char** outargv = Str.toStringzArray(argv);
640 		
641 		auto p = gtk_parse_args(&argc, &outargv) != 0;
642 		
643 		argv = Str.toStringArray(outargv, argc);
644 		
645 		return p;
646 	}
647 
648 	/**
649 	 * Sends an event to a widget, propagating the event to parent widgets
650 	 * if the event remains unhandled.
651 	 *
652 	 * Events received by GTK+ from GDK normally begin in gtk_main_do_event().
653 	 * Depending on the type of event, existence of modal dialogs, grabs, etc.,
654 	 * the event may be propagated; if so, this function is used.
655 	 *
656 	 * gtk_propagate_event() calls gtk_widget_event() on each widget it
657 	 * decides to send the event to. So gtk_widget_event() is the lowest-level
658 	 * function; it simply emits the #GtkWidget::event and possibly an
659 	 * event-specific signal on a widget. gtk_propagate_event() is a bit
660 	 * higher-level, and gtk_main_do_event() is the highest level.
661 	 *
662 	 * All that said, you most likely don’t want to use any of these
663 	 * functions; synthesizing events is rarely needed. There are almost
664 	 * certainly better ways to achieve your goals. For example, use
665 	 * gdk_window_invalidate_rect() or gtk_widget_queue_draw() instead
666 	 * of making up expose events.
667 	 *
668 	 * Params:
669 	 *     widget = a #GtkWidget
670 	 *     event = an event
671 	 */
672 	public static void propagateEvent(Widget widget, Event event)
673 	{
674 		gtk_propagate_event((widget is null) ? null : widget.getWidgetStruct(), (event is null) ? null : event.getEventStruct());
675 	}
676 
677 	/**
678 	 * Sets the GTK+ debug flags.
679 	 */
680 	public static void setDebugFlags(uint flags)
681 	{
682 		gtk_set_debug_flags(flags);
683 	}
684 }