xcb: document QXcbEventQueue::PeekOption enum

And renamed PeekRemove* to PeekConsumed to document
better that nodes are not removed when peeking.

Change-Id: I7349f57fcfc3287d1a1309a31ee7f481f8d18755
Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>

2 files changed, 23 insertions, 8 deletions

diff --git a/src/plugins/platforms/xcb/qxcbeventqueue.h b/src/plugins/platforms/xcb/qxcbeventqueue.h
index 67a1825ead..10b6810014 100644
--- a/src/plugins/platforms/xcb/qxcbeventqueue.h
+++ b/src/plugins/platforms/xcb/qxcbeventqueue.h
@@ -75,11 +75,24 @@ public:
     enum { PoolSize = 100 }; // 2.4 kB with 100 nodes
 
     enum PeekOption {
-        PeekDefault = 0, // see qx11info_x11.h for docs
+        // See qx11info_x11.cpp in X11 Extras module.
+        PeekDefault = 0,
+        // See qx11info_x11.cpp in X11 Extras module.
         PeekFromCachedIndex = 1,
+        // Used by the event compression algorithms to determine if
+        // the currently processed event (which has been already dequeued)
+        // can be compressed. Returns from the QXcbEventQueue::peek()
+        // on the first match.
         PeekRetainMatch = 2,
-        PeekRemoveMatch = 3,
-        PeekRemoveMatchContinue = 4
+        // Marks the event in the node as "nullptr". The actual
+        // node remains in the queue. The nodes are unlinked only
+        // by dequeueNode(). Returns from the QXcbEventQueue::peek()
+        // on the first match.
+        PeekConsumeMatch = 3,
+        // Same as above, but continues to the next node in the
+        // queue. Repeats this until the flushed tailed node has
+        // been reached.
+        PeekConsumeMatchAndContinue = 4
     };
     Q_DECLARE_FLAGS(PeekOptions, PeekOption)
 
@@ -92,10 +105,11 @@ public:
     void wakeUpDispatcher();
 
     // ### peek() and peekEventQueue() could be unified. Note that peekEventQueue()
-    // is public API exposed via QX11Extras/QX11Info.
+    // is public API exposed via QX11Extras/QX11Info. PeekOption could be reworked to
+    // have values that can be OR-ed together.
     template<typename Peeker>
     xcb_generic_event_t *peek(Peeker &&peeker) {
-        return peek(PeekRemoveMatch, std::forward<Peeker>(peeker));
+        return peek(PeekConsumeMatch, std::forward<Peeker>(peeker));
     }
     template<typename Peeker>
     inline xcb_generic_event_t *peek(PeekOption config, Peeker &&peeker);
@@ -154,9 +168,10 @@ xcb_generic_event_t *QXcbEventQueue::peek(PeekOption option, Peeker &&peeker)
     do {
         xcb_generic_event_t *event = node->event;
         if (event && peeker(event, event->response_type & ~0x80)) {
-            if (option == PeekRemoveMatch || option == PeekRemoveMatchContinue)
+            if (option == PeekConsumeMatch || option == PeekConsumeMatchAndContinue)
                 node->event = nullptr;
-            if (option != PeekRemoveMatchContinue)
+
+            if (option != PeekConsumeMatchAndContinue)
                 return event;
         }
         if (node == m_flushedTail)
diff --git a/src/plugins/platforms/xcb/qxcbwindow.cpp b/src/plugins/platforms/xcb/qxcbwindow.cpp
index 359ee14488..66f0558a55 100644
--- a/src/plugins/platforms/xcb/qxcbwindow.cpp
+++ b/src/plugins/platforms/xcb/qxcbwindow.cpp
@@ -1618,7 +1618,7 @@ void QXcbWindow::handleExposeEvent(const xcb_expose_event_t *event)
 
     bool pending = true;
 
-    connection()->eventQueue()->peek(QXcbEventQueue::PeekRemoveMatchContinue,
+    connection()->eventQueue()->peek(QXcbEventQueue::PeekConsumeMatchAndContinue,
                                      [this, &pending](xcb_generic_event_t *event, int type) {
         if (type != XCB_EXPOSE)
             return false;