From: Arjan Molenaar Date: Tue, 17 Jan 2023 15:24:47 +0000 (+0100) Subject: macos: Update event source doc X-Git-Tag: archive/raspbian/4.12.3+ds-1+rpi1~1^2^2^2~22^2~8^2~50^2~2 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=136c1ccd2c4646f401e356f80ee88b2762767259;p=gtk4.git macos: Update event source doc Update the documentation with the interaction pattern we need to support DnD. --- diff --git a/gdk/macos/gdkmacoseventsource.c b/gdk/macos/gdkmacoseventsource.c index c0311fc745..6c4a962ae0 100644 --- a/gdk/macos/gdkmacoseventsource.c +++ b/gdk/macos/gdkmacoseventsource.c @@ -37,11 +37,15 @@ /* * This file implementations integration between the GLib main loop and * the native system of the Core Foundation run loop and Cocoa event - * handling. There are basically two different cases that we need to - * handle: either the GLib main loop is in control (the application - * has called gtk_main(), or is otherwise iterating the main loop), or - * CFRunLoop is in control (we are in a modal operation such as window - * resizing or drag-and-drop.) + * handling. There are basically three different cases that we need to + * handle: + * + * - the GLib main loop is in control. The application has called + * gtk_main(), or is otherwise iterating the main loop. + * - CFRunLoop is in control. We are in a modal operation such as window + * resizing. + * - CFRunLoop is running a nested loop. This happens when a drag-and-drop + * operation has been initiated. * * When the GLib main loop is in control we integrate in native event * handling in two ways: first we add a GSource that handles checking @@ -57,14 +61,23 @@ * stages of the GLib main loop (prepare, check, dispatch), and make the * appropriate calls into GLib. * - * Both cases share a single problem: the OS X API’s don’t allow us to + * When initiating a drag operation, a nested CFRunLoop is executed. + * The nested run loop is started when fetching a native event in our GLib + * main loop. The application does not receive any events until the nested loop + * is finished. We work around this by forwarding the + * events that trigger the callbacks of the NSDraggingSource protocol. + * The "run loop observer" is executing the GLib main loop stages as long as we're + * in the nested run loop, as if CFRunLoop were in control. + * See also GdkMacosWindow. + * + * All cases share a single problem: the macOS API’s don’t allow us to * wait simultaneously for file descriptors and for events. So when we * need to do a blocking wait that includes file descriptor activity, we * push the actual work of calling select() to a helper thread (the * "select thread") and wait for native events in the main thread. * * The main known limitation of this code is that if a callback is triggered - * via the OS X run loop while we are "polling" (in either case described + * via the macOS run loop while we are "polling" (in either case described * above), iteration of the GLib main loop is not possible from within * that callback. If the programmer tries to do so explicitly, then they * will get a warning from GLib "main loop already active in another thread".