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 glib.Source; 26 27 private import glib.ConstructionException; 28 private import glib.MainContext; 29 private import glib.Str; 30 private import glib.TimeVal; 31 private import glib.c.functions; 32 public import glib.c.types; 33 public import gtkc.glibtypes; 34 private import gtkd.Loader; 35 36 37 /** 38 * The `GSource` struct is an opaque data type 39 * representing an event source. 40 */ 41 public class Source 42 { 43 /** the main Gtk struct */ 44 protected GSource* gSource; 45 protected bool ownedRef; 46 47 /** Get the main Gtk struct */ 48 public GSource* getSourceStruct(bool transferOwnership = false) 49 { 50 if (transferOwnership) 51 ownedRef = false; 52 return gSource; 53 } 54 55 /** the main Gtk struct as a void* */ 56 protected void* getStruct() 57 { 58 return cast(void*)gSource; 59 } 60 61 /** 62 * Sets our main struct and passes it to the parent class. 63 */ 64 public this (GSource* gSource, bool ownedRef = false) 65 { 66 this.gSource = gSource; 67 this.ownedRef = ownedRef; 68 } 69 70 ~this () 71 { 72 if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef ) 73 g_source_unref(gSource); 74 } 75 76 77 /** 78 * Creates a new #GSource structure. The size is specified to 79 * allow creating structures derived from #GSource that contain 80 * additional data. The size passed in must be at least 81 * `sizeof (GSource)`. 82 * 83 * The source will not initially be associated with any #GMainContext 84 * and must be added to one with g_source_attach() before it will be 85 * executed. 86 * 87 * Params: 88 * sourceFuncs = structure containing functions that implement 89 * the sources behavior. 90 * structSize = size of the #GSource structure to create. 91 * 92 * Returns: the newly-created #GSource. 93 * 94 * Throws: ConstructionException GTK+ fails to create the object. 95 */ 96 public this(GSourceFuncs* sourceFuncs, uint structSize) 97 { 98 auto p = g_source_new(sourceFuncs, structSize); 99 100 if(p is null) 101 { 102 throw new ConstructionException("null returned by new"); 103 } 104 105 this(cast(GSource*) p); 106 } 107 108 /** 109 * Adds @child_source to @source as a "polled" source; when @source is 110 * added to a #GMainContext, @child_source will be automatically added 111 * with the same priority, when @child_source is triggered, it will 112 * cause @source to dispatch (in addition to calling its own 113 * callback), and when @source is destroyed, it will destroy 114 * @child_source as well. (@source will also still be dispatched if 115 * its own prepare/check functions indicate that it is ready.) 116 * 117 * If you don't need @child_source to do anything on its own when it 118 * triggers, you can call g_source_set_dummy_callback() on it to set a 119 * callback that does nothing (except return %TRUE if appropriate). 120 * 121 * @source will hold a reference on @child_source while @child_source 122 * is attached to it. 123 * 124 * This API is only intended to be used by implementations of #GSource. 125 * Do not call this API on a #GSource that you did not create. 126 * 127 * Params: 128 * childSource = a second #GSource that @source should "poll" 129 * 130 * Since: 2.28 131 */ 132 public void addChildSource(Source childSource) 133 { 134 g_source_add_child_source(gSource, (childSource is null) ? null : childSource.getSourceStruct()); 135 } 136 137 /** 138 * Adds a file descriptor to the set of file descriptors polled for 139 * this source. This is usually combined with g_source_new() to add an 140 * event source. The event source's check function will typically test 141 * the @revents field in the #GPollFD struct and return %TRUE if events need 142 * to be processed. 143 * 144 * This API is only intended to be used by implementations of #GSource. 145 * Do not call this API on a #GSource that you did not create. 146 * 147 * Using this API forces the linear scanning of event sources on each 148 * main loop iteration. Newly-written event sources should try to use 149 * g_source_add_unix_fd() instead of this API. 150 * 151 * Params: 152 * fd = a #GPollFD structure holding information about a file 153 * descriptor to watch. 154 */ 155 public void addPoll(GPollFD* fd) 156 { 157 g_source_add_poll(gSource, fd); 158 } 159 160 /** 161 * Monitors @fd for the IO events in @events. 162 * 163 * The tag returned by this function can be used to remove or modify the 164 * monitoring of the fd using g_source_remove_unix_fd() or 165 * g_source_modify_unix_fd(). 166 * 167 * It is not necessary to remove the fd before destroying the source; it 168 * will be cleaned up automatically. 169 * 170 * This API is only intended to be used by implementations of #GSource. 171 * Do not call this API on a #GSource that you did not create. 172 * 173 * As the name suggests, this function is not available on Windows. 174 * 175 * Params: 176 * fd = the fd to monitor 177 * events = an event mask 178 * 179 * Returns: an opaque tag 180 * 181 * Since: 2.36 182 */ 183 public void* addUnixFd(int fd, GIOCondition events) 184 { 185 return g_source_add_unix_fd(gSource, fd, events); 186 } 187 188 /** 189 * Adds a #GSource to a @context so that it will be executed within 190 * that context. Remove it by calling g_source_destroy(). 191 * 192 * Params: 193 * context = a #GMainContext (if %NULL, the default context will be used) 194 * 195 * Returns: the ID (greater than 0) for the source within the 196 * #GMainContext. 197 */ 198 public uint attach(MainContext context) 199 { 200 return g_source_attach(gSource, (context is null) ? null : context.getMainContextStruct()); 201 } 202 203 /** 204 * Removes a source from its #GMainContext, if any, and mark it as 205 * destroyed. The source cannot be subsequently added to another 206 * context. It is safe to call this on sources which have already been 207 * removed from their context. 208 */ 209 public void destroy() 210 { 211 g_source_destroy(gSource); 212 } 213 214 /** 215 * Checks whether a source is allowed to be called recursively. 216 * see g_source_set_can_recurse(). 217 * 218 * Returns: whether recursion is allowed. 219 */ 220 public bool getCanRecurse() 221 { 222 return g_source_get_can_recurse(gSource) != 0; 223 } 224 225 /** 226 * Gets the #GMainContext with which the source is associated. 227 * 228 * You can call this on a source that has been destroyed, provided 229 * that the #GMainContext it was attached to still exists (in which 230 * case it will return that #GMainContext). In particular, you can 231 * always call this function on the source returned from 232 * g_main_current_source(). But calling this function on a source 233 * whose #GMainContext has been destroyed is an error. 234 * 235 * Returns: the #GMainContext with which the 236 * source is associated, or %NULL if the context has not 237 * yet been added to a source. 238 */ 239 public MainContext getContext() 240 { 241 auto p = g_source_get_context(gSource); 242 243 if(p is null) 244 { 245 return null; 246 } 247 248 return new MainContext(cast(GMainContext*) p); 249 } 250 251 /** 252 * This function ignores @source and is otherwise the same as 253 * g_get_current_time(). 254 * 255 * Deprecated: use g_source_get_time() instead 256 * 257 * Params: 258 * timeval = #GTimeVal structure in which to store current time. 259 */ 260 public void getCurrentTime(TimeVal timeval) 261 { 262 g_source_get_current_time(gSource, (timeval is null) ? null : timeval.getTimeValStruct()); 263 } 264 265 /** 266 * Returns the numeric ID for a particular source. The ID of a source 267 * is a positive integer which is unique within a particular main loop 268 * context. The reverse 269 * mapping from ID to source is done by g_main_context_find_source_by_id(). 270 * 271 * Returns: the ID (greater than 0) for the source 272 */ 273 public uint getId() 274 { 275 return g_source_get_id(gSource); 276 } 277 278 /** 279 * Gets a name for the source, used in debugging and profiling. The 280 * name may be #NULL if it has never been set with g_source_set_name(). 281 * 282 * Returns: the name of the source 283 * 284 * Since: 2.26 285 */ 286 public string getName() 287 { 288 return Str.toString(g_source_get_name(gSource)); 289 } 290 291 /** 292 * Gets the priority of a source. 293 * 294 * Returns: the priority of the source 295 */ 296 public int getPriority() 297 { 298 return g_source_get_priority(gSource); 299 } 300 301 /** 302 * Gets the "ready time" of @source, as set by 303 * g_source_set_ready_time(). 304 * 305 * Any time before the current monotonic time (including 0) is an 306 * indication that the source will fire immediately. 307 * 308 * Returns: the monotonic ready time, -1 for "never" 309 */ 310 public long getReadyTime() 311 { 312 return g_source_get_ready_time(gSource); 313 } 314 315 /** 316 * Gets the time to be used when checking this source. The advantage of 317 * calling this function over calling g_get_monotonic_time() directly is 318 * that when checking multiple sources, GLib can cache a single value 319 * instead of having to repeatedly get the system monotonic time. 320 * 321 * The time here is the system monotonic time, if available, or some 322 * other reasonable alternative otherwise. See g_get_monotonic_time(). 323 * 324 * Returns: the monotonic time in microseconds 325 * 326 * Since: 2.28 327 */ 328 public long getTime() 329 { 330 return g_source_get_time(gSource); 331 } 332 333 /** 334 * Returns whether @source has been destroyed. 335 * 336 * This is important when you operate upon your objects 337 * from within idle handlers, but may have freed the object 338 * before the dispatch of your idle handler. 339 * 340 * |[<!-- language="C" --> 341 * static gboolean 342 * idle_callback (gpointer data) 343 * { 344 * SomeWidget *self = data; 345 * 346 * GDK_THREADS_ENTER (); 347 * // do stuff with self 348 * self->idle_id = 0; 349 * GDK_THREADS_LEAVE (); 350 * 351 * return G_SOURCE_REMOVE; 352 * } 353 * 354 * static void 355 * some_widget_do_stuff_later (SomeWidget *self) 356 * { 357 * self->idle_id = g_idle_add (idle_callback, self); 358 * } 359 * 360 * static void 361 * some_widget_finalize (GObject *object) 362 * { 363 * SomeWidget *self = SOME_WIDGET (object); 364 * 365 * if (self->idle_id) 366 * g_source_remove (self->idle_id); 367 * 368 * G_OBJECT_CLASS (parent_class)->finalize (object); 369 * } 370 * ]| 371 * 372 * This will fail in a multi-threaded application if the 373 * widget is destroyed before the idle handler fires due 374 * to the use after free in the callback. A solution, to 375 * this particular problem, is to check to if the source 376 * has already been destroy within the callback. 377 * 378 * |[<!-- language="C" --> 379 * static gboolean 380 * idle_callback (gpointer data) 381 * { 382 * SomeWidget *self = data; 383 * 384 * GDK_THREADS_ENTER (); 385 * if (!g_source_is_destroyed (g_main_current_source ())) 386 * { 387 * // do stuff with self 388 * } 389 * GDK_THREADS_LEAVE (); 390 * 391 * return FALSE; 392 * } 393 * ]| 394 * 395 * Calls to this function from a thread other than the one acquired by the 396 * #GMainContext the #GSource is attached to are typically redundant, as the 397 * source could be destroyed immediately after this function returns. However, 398 * once a source is destroyed it cannot be un-destroyed, so this function can be 399 * used for opportunistic checks from any thread. 400 * 401 * Returns: %TRUE if the source has been destroyed 402 * 403 * Since: 2.12 404 */ 405 public bool isDestroyed() 406 { 407 return g_source_is_destroyed(gSource) != 0; 408 } 409 410 /** 411 * Updates the event mask to watch for the fd identified by @tag. 412 * 413 * @tag is the tag returned from g_source_add_unix_fd(). 414 * 415 * If you want to remove a fd, don't set its event mask to zero. 416 * Instead, call g_source_remove_unix_fd(). 417 * 418 * This API is only intended to be used by implementations of #GSource. 419 * Do not call this API on a #GSource that you did not create. 420 * 421 * As the name suggests, this function is not available on Windows. 422 * 423 * Params: 424 * tag = the tag from g_source_add_unix_fd() 425 * newEvents = the new event mask to watch 426 * 427 * Since: 2.36 428 */ 429 public void modifyUnixFd(void* tag, GIOCondition newEvents) 430 { 431 g_source_modify_unix_fd(gSource, tag, newEvents); 432 } 433 434 /** 435 * Queries the events reported for the fd corresponding to @tag on 436 * @source during the last poll. 437 * 438 * The return value of this function is only defined when the function 439 * is called from the check or dispatch functions for @source. 440 * 441 * This API is only intended to be used by implementations of #GSource. 442 * Do not call this API on a #GSource that you did not create. 443 * 444 * As the name suggests, this function is not available on Windows. 445 * 446 * Params: 447 * tag = the tag from g_source_add_unix_fd() 448 * 449 * Returns: the conditions reported on the fd 450 * 451 * Since: 2.36 452 */ 453 public GIOCondition queryUnixFd(void* tag) 454 { 455 return g_source_query_unix_fd(gSource, tag); 456 } 457 458 /** 459 * Increases the reference count on a source by one. 460 * 461 * Returns: @source 462 */ 463 public Source doref() 464 { 465 auto p = g_source_ref(gSource); 466 467 if(p is null) 468 { 469 return null; 470 } 471 472 return new Source(cast(GSource*) p, true); 473 } 474 475 /** 476 * Detaches @child_source from @source and destroys it. 477 * 478 * This API is only intended to be used by implementations of #GSource. 479 * Do not call this API on a #GSource that you did not create. 480 * 481 * Params: 482 * childSource = a #GSource previously passed to 483 * g_source_add_child_source(). 484 * 485 * Since: 2.28 486 */ 487 public void removeChildSource(Source childSource) 488 { 489 g_source_remove_child_source(gSource, (childSource is null) ? null : childSource.getSourceStruct()); 490 } 491 492 /** 493 * Removes a file descriptor from the set of file descriptors polled for 494 * this source. 495 * 496 * This API is only intended to be used by implementations of #GSource. 497 * Do not call this API on a #GSource that you did not create. 498 * 499 * Params: 500 * fd = a #GPollFD structure previously passed to g_source_add_poll(). 501 */ 502 public void removePoll(GPollFD* fd) 503 { 504 g_source_remove_poll(gSource, fd); 505 } 506 507 /** 508 * Reverses the effect of a previous call to g_source_add_unix_fd(). 509 * 510 * You only need to call this if you want to remove an fd from being 511 * watched while keeping the same source around. In the normal case you 512 * will just want to destroy the source. 513 * 514 * This API is only intended to be used by implementations of #GSource. 515 * Do not call this API on a #GSource that you did not create. 516 * 517 * As the name suggests, this function is not available on Windows. 518 * 519 * Params: 520 * tag = the tag from g_source_add_unix_fd() 521 * 522 * Since: 2.36 523 */ 524 public void removeUnixFd(void* tag) 525 { 526 g_source_remove_unix_fd(gSource, tag); 527 } 528 529 /** 530 * Sets the callback function for a source. The callback for a source is 531 * called from the source's dispatch function. 532 * 533 * The exact type of @func depends on the type of source; ie. you 534 * should not count on @func being called with @data as its first 535 * parameter. 536 * 537 * See [memory management of sources][mainloop-memory-management] for details 538 * on how to handle memory management of @data. 539 * 540 * Typically, you won't use this function. Instead use functions specific 541 * to the type of source you are using. 542 * 543 * Params: 544 * func = a callback function 545 * data = the data to pass to callback function 546 * notify = a function to call when @data is no longer in use, or %NULL. 547 */ 548 public void setCallback(GSourceFunc func, void* data, GDestroyNotify notify) 549 { 550 g_source_set_callback(gSource, func, data, notify); 551 } 552 553 /** 554 * Sets the callback function storing the data as a refcounted callback 555 * "object". This is used internally. Note that calling 556 * g_source_set_callback_indirect() assumes 557 * an initial reference count on @callback_data, and thus 558 * @callback_funcs->unref will eventually be called once more 559 * than @callback_funcs->ref. 560 * 561 * Params: 562 * callbackData = pointer to callback data "object" 563 * callbackFuncs = functions for reference counting @callback_data 564 * and getting the callback and data 565 */ 566 public void setCallbackIndirect(void* callbackData, GSourceCallbackFuncs* callbackFuncs) 567 { 568 g_source_set_callback_indirect(gSource, callbackData, callbackFuncs); 569 } 570 571 /** 572 * Sets whether a source can be called recursively. If @can_recurse is 573 * %TRUE, then while the source is being dispatched then this source 574 * will be processed normally. Otherwise, all processing of this 575 * source is blocked until the dispatch function returns. 576 * 577 * Params: 578 * canRecurse = whether recursion is allowed for this source 579 */ 580 public void setCanRecurse(bool canRecurse) 581 { 582 g_source_set_can_recurse(gSource, canRecurse); 583 } 584 585 /** 586 * Sets the source functions (can be used to override 587 * default implementations) of an unattached source. 588 * 589 * Params: 590 * funcs = the new #GSourceFuncs 591 * 592 * Since: 2.12 593 */ 594 public void setFuncs(GSourceFuncs* funcs) 595 { 596 g_source_set_funcs(gSource, funcs); 597 } 598 599 /** 600 * Sets a name for the source, used in debugging and profiling. 601 * The name defaults to #NULL. 602 * 603 * The source name should describe in a human-readable way 604 * what the source does. For example, "X11 event queue" 605 * or "GTK+ repaint idle handler" or whatever it is. 606 * 607 * It is permitted to call this function multiple times, but is not 608 * recommended due to the potential performance impact. For example, 609 * one could change the name in the "check" function of a #GSourceFuncs 610 * to include details like the event type in the source name. 611 * 612 * Use caution if changing the name while another thread may be 613 * accessing it with g_source_get_name(); that function does not copy 614 * the value, and changing the value will free it while the other thread 615 * may be attempting to use it. 616 * 617 * Params: 618 * name = debug name for the source 619 * 620 * Since: 2.26 621 */ 622 public void setName(string name) 623 { 624 g_source_set_name(gSource, Str.toStringz(name)); 625 } 626 627 /** 628 * Sets the priority of a source. While the main loop is being run, a 629 * source will be dispatched if it is ready to be dispatched and no 630 * sources at a higher (numerically smaller) priority are ready to be 631 * dispatched. 632 * 633 * A child source always has the same priority as its parent. It is not 634 * permitted to change the priority of a source once it has been added 635 * as a child of another source. 636 * 637 * Params: 638 * priority = the new priority. 639 */ 640 public void setPriority(int priority) 641 { 642 g_source_set_priority(gSource, priority); 643 } 644 645 /** 646 * Sets a #GSource to be dispatched when the given monotonic time is 647 * reached (or passed). If the monotonic time is in the past (as it 648 * always will be if @ready_time is 0) then the source will be 649 * dispatched immediately. 650 * 651 * If @ready_time is -1 then the source is never woken up on the basis 652 * of the passage of time. 653 * 654 * Dispatching the source does not reset the ready time. You should do 655 * so yourself, from the source dispatch function. 656 * 657 * Note that if you have a pair of sources where the ready time of one 658 * suggests that it will be delivered first but the priority for the 659 * other suggests that it would be delivered first, and the ready time 660 * for both sources is reached during the same main context iteration 661 * then the order of dispatch is undefined. 662 * 663 * It is a no-op to call this function on a #GSource which has already been 664 * destroyed with g_source_destroy(). 665 * 666 * This API is only intended to be used by implementations of #GSource. 667 * Do not call this API on a #GSource that you did not create. 668 * 669 * Params: 670 * readyTime = the monotonic time at which the source will be ready, 671 * 0 for "immediately", -1 for "never" 672 * 673 * Since: 2.36 674 */ 675 public void setReadyTime(long readyTime) 676 { 677 g_source_set_ready_time(gSource, readyTime); 678 } 679 680 /** 681 * Decreases the reference count of a source by one. If the 682 * resulting reference count is zero the source and associated 683 * memory will be destroyed. 684 */ 685 public void unref() 686 { 687 g_source_unref(gSource); 688 } 689 690 /** 691 * Removes the source with the given id from the default main context. 692 * 693 * The id of a #GSource is given by g_source_get_id(), or will be 694 * returned by the functions g_source_attach(), g_idle_add(), 695 * g_idle_add_full(), g_timeout_add(), g_timeout_add_full(), 696 * g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and 697 * g_io_add_watch_full(). 698 * 699 * See also g_source_destroy(). You must use g_source_destroy() for sources 700 * added to a non-default main context. 701 * 702 * It is a programmer error to attempt to remove a non-existent source. 703 * 704 * More specifically: source IDs can be reissued after a source has been 705 * destroyed and therefore it is never valid to use this function with a 706 * source ID which may have already been removed. An example is when 707 * scheduling an idle to run in another thread with g_idle_add(): the 708 * idle may already have run and been removed by the time this function 709 * is called on its (now invalid) source ID. This source ID may have 710 * been reissued, leading to the operation being performed against the 711 * wrong source. 712 * 713 * Params: 714 * tag = the ID of the source to remove. 715 * 716 * Returns: For historical reasons, this function always returns %TRUE 717 */ 718 public static bool remove(uint tag) 719 { 720 return g_source_remove(tag) != 0; 721 } 722 723 /** 724 * Removes a source from the default main loop context given the 725 * source functions and user data. If multiple sources exist with the 726 * same source functions and user data, only one will be destroyed. 727 * 728 * Params: 729 * funcs = The @source_funcs passed to g_source_new() 730 * userData = the user data for the callback 731 * 732 * Returns: %TRUE if a source was found and removed. 733 */ 734 public static bool removeByFuncsUserData(GSourceFuncs* funcs, void* userData) 735 { 736 return g_source_remove_by_funcs_user_data(funcs, userData) != 0; 737 } 738 739 /** 740 * Removes a source from the default main loop context given the user 741 * data for the callback. If multiple sources exist with the same user 742 * data, only one will be destroyed. 743 * 744 * Params: 745 * userData = the user_data for the callback. 746 * 747 * Returns: %TRUE if a source was found and removed. 748 */ 749 public static bool removeByUserData(void* userData) 750 { 751 return g_source_remove_by_user_data(userData) != 0; 752 } 753 754 /** 755 * Sets the name of a source using its ID. 756 * 757 * This is a convenience utility to set source names from the return 758 * value of g_idle_add(), g_timeout_add(), etc. 759 * 760 * It is a programmer error to attempt to set the name of a non-existent 761 * source. 762 * 763 * More specifically: source IDs can be reissued after a source has been 764 * destroyed and therefore it is never valid to use this function with a 765 * source ID which may have already been removed. An example is when 766 * scheduling an idle to run in another thread with g_idle_add(): the 767 * idle may already have run and been removed by the time this function 768 * is called on its (now invalid) source ID. This source ID may have 769 * been reissued, leading to the operation being performed against the 770 * wrong source. 771 * 772 * Params: 773 * tag = a #GSource ID 774 * name = debug name for the source 775 * 776 * Since: 2.26 777 */ 778 public static void setNameById(uint tag, string name) 779 { 780 g_source_set_name_by_id(tag, Str.toStringz(name)); 781 } 782 }