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 }