Merge pull request #805 from pygame/event-pump

Add pump parameter and keyword arguments to some event functions

docs/reST/ref/event.rst

@@ -135,14 +135,16 @@ attributes.
    you fail to make a call to the event queue for too long, the system may
    decide your program has locked up.
 
+   .. caution::
+      This function should only be called in the thread that initialized :mod:`pygame.display`.
+
    .. ## pygame.event.pump ##
 
 .. function:: get
 
    | :sl:`get events from the queue`
-   | :sg:`get() -> Eventlist`
-   | :sg:`get(type) -> Eventlist`
-   | :sg:`get(typelist) -> Eventlist`
+   | :sg:`get(eventtype=None) -> Eventlist`
+   | :sg:`get(eventtype=None, pump=True) -> Eventlist`
 
    This will get all the messages and remove them from the queue. If a type or
    sequence of types is given only those messages will be removed from the
@@ -151,6 +153,10 @@ attributes.
    If you are only taking specific events from the queue, be aware that the
    queue could eventually fill up with the events you are not interested.
 
+   If ``pump`` is ``True`` (the default), then :func:`pygame.event.pump()` will be called.
+
+   .. versionadded:: 1.9.5 ``pump``
+
    .. ## pygame.event.get ##
 
 .. function:: poll
@@ -162,6 +168,9 @@ attributes.
    of type ``pygame.NOEVENT`` will be returned immediately. The returned event
    is removed from the queue.
 
+   .. caution::
+      This function should only be called in the thread that initialized :mod:`pygame.display`.
+
    .. ## pygame.event.poll ##
 
 .. function:: wait
@@ -175,30 +184,40 @@ attributes.
    state. This is important for programs that want to share the system with
    other applications.
 
+   .. caution::
+      This function should only be called in the thread that initialized :mod:`pygame.display`.
+
    .. ## pygame.event.wait ##
 
 .. function:: peek
 
    | :sl:`test if event types are waiting on the queue`
-   | :sg:`peek(type) -> bool`
-   | :sg:`peek(typelist) -> bool`
+   | :sg:`peek(eventtype=None) -> bool`
+   | :sg:`peek(eventtype=None, pump=True) -> bool`
 
    Returns ``True`` if there are any events of the given type waiting on the
    queue. If a sequence of event types is passed, this will return ``True`` if
    any of those events are on the queue.
 
+   If ``pump`` is ``True`` (the default), then :func:`pygame.event.pump()` will be called.
+
+   .. versionadded:: 1.9.5 ``pump``
+
    .. ## pygame.event.peek ##
 
 .. function:: clear
 
    | :sl:`remove all events from the queue`
-   | :sg:`clear() -> None`
-   | :sg:`clear(type) -> None`
-   | :sg:`clear(typelist) -> None`
+   | :sg:`clear(eventtype=None) -> None`
+   | :sg:`clear(eventtype=None, pump=True) -> None`
+
+   Removes all events from the queue. If ``eventtype`` is given, removes the given event
+   or sequence of events. This has the same effect as :func:`pygame.event.get()` except ``None``
+   is returned. It can be slightly more efficient when clearing a full event queue.
+
+   If ``pump`` is ``True`` (the default), then :func:`pygame.event.pump()` will be called.
 
-   Remove all events or events of a specific type from the queue. This has the
-   same effect as :func:`pygame.event.get()` except ``None`` is returned. This
-   can be slightly more efficient when clearing a full event queue.
+   .. versionadded:: 1.9.5 ``pump``
 
    .. ## pygame.event.clear ##
 

docs/reST/themes/classic/static/pygame.css_t

@@ -569,6 +569,11 @@ div.topic {
     background-color: #eee;
 }
 
+div.caution {
+    background-color: #eeffcc;
+    border: 1px solid #aabb88;
+}
+
 div.warning {
     background-color: #ffe4e4;
     border: 1px solid #f66;

src_c/doc/event_doc.h

@@ -3,15 +3,15 @@
 
 #define DOC_PYGAMEEVENTPUMP "pump() -> None\ninternally process pygame event handlers"
 
-#define DOC_PYGAMEEVENTGET "get() -> Eventlist\nget(type) -> Eventlist\nget(typelist) -> Eventlist\nget events from the queue"
+#define DOC_PYGAMEEVENTGET "get(eventtype=None) -> Eventlist\nget(eventtype=None, pump=True) -> Eventlist\nget events from the queue"
 
 #define DOC_PYGAMEEVENTPOLL "poll() -> EventType instance\nget a single event from the queue"
 
 #define DOC_PYGAMEEVENTWAIT "wait() -> EventType instance\nwait for a single event from the queue"
 
-#define DOC_PYGAMEEVENTPEEK "peek(type) -> bool\npeek(typelist) -> bool\ntest if event types are waiting on the queue"
+#define DOC_PYGAMEEVENTPEEK "peek(eventtype=None) -> bool\npeek(eventtype=None, pump=True) -> bool\ntest if event types are waiting on the queue"
 
-#define DOC_PYGAMEEVENTCLEAR "clear() -> None\nclear(type) -> None\nclear(typelist) -> None\nremove all events from the queue"
+#define DOC_PYGAMEEVENTCLEAR "clear(eventtype=None) -> None\nclear(eventtype=None, pump=True) -> None\nremove all events from the queue"
 
 #define DOC_PYGAMEEVENTEVENTNAME "event_name(type) -> string\nget the string name from an event id"
 
@@ -49,9 +49,8 @@ pygame.event.pump
 internally process pygame event handlers
 
 pygame.event.get
- get() -> Eventlist
- get(type) -> Eventlist
- get(typelist) -> Eventlist
+ get(eventtype=None) -> Eventlist
+ get(eventtype=None, pump=True) -> Eventlist
 get events from the queue
 
 pygame.event.poll
@@ -63,14 +62,13 @@ pygame.event.wait
 wait for a single event from the queue
 
 pygame.event.peek
- peek(type) -> bool
- peek(typelist) -> bool
+ peek(eventtype=None) -> bool
+ peek(eventtype=None, pump=True) -> bool
 test if event types are waiting on the queue
 
 pygame.event.clear
- clear() -> None
- clear(type) -> None
- clear(typelist) -> None
+ clear(eventtype=None) -> None
+ clear(eventtype=None, pump=True) -> None
 remove all events from the queue
 
 pygame.event.event_name