AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

docs: Remove a reference to gtk_main_do_event

Browse Source 
It is not great to put a function in the public api and
document it as "do not call this" only so we can refer
to its docs in other places. Therefore, fold the docs
directly into the input handling overview chapter.
This commit is contained in:
Matthias Clasen 2020-02-09 10:38:01 -05:00
parent ba825dce29
commit 8f0fc24516
1 changed files with 43 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/reference/gtk/input-handling.xml
View File

@ -92,12 +92,50 @@
<para>
The function which initially receives input events on the GTK
side is gtk_main_do_event(). See its documentation
for details of what it does: compression of enter/leave events,
identification of the widget receiving the event, pushing the event onto a
stack for gtk_get_current_event(), and propagating the event to the
widget.
side is responsible for a number of tasks.
</para>
<orderedlist>
<listitem><para>
Compress enter/leave notify events. If the event passed build an
enter/leave pair together with the next event (peeked from GDK), both
events are thrown away. This is to avoid a backlog of (de-)highlighting
widgets crossed by the pointer.
</para></listitem>
<listitem><para>
Find the widget which got the event. If the widget can’t be determined
the event is thrown away unless it belongs to a INCR transaction.
</para></listitem>
<listitem><para>
Then the event is pushed onto a stack so you can query the currently
handled event with gtk_get_current_event().
</para></listitem>
<listitem><para>
The event is sent to a widget. If a grab is active all events for widgets
that are not in the contained in the grab widget are sent to the latter
with a few exceptions:
<itemizedlist>
<listitem><para>
Deletion and destruction events are still sent to the event widget for
obvious reasons.
</para></listitem>
<listitem><para>
Events which directly relate to the visual representation of the event
widget.
</para></listitem>
<listitem><para>
Leave events are delivered to the event widget if there was an enter
event delivered to it before without the paired leave event.
</para></listitem>
<listitem><para>
Drag events are not redirected because it is unclear what the semantics
of that would be.
</para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para>
After finishing the delivery the event is popped from the event stack.
</para></listitem>
</orderedlist>
<para>
When a GDK backend produces an input event, it is tied to a #GdkDevice and