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