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