Commits

Anonymous committed 1b3338f

event.clear added

  • Participants
  • Parent commits 7f9b64f

Comments (0)

Files changed (7)

 # BREAK = change breaks existing code
 # BUG	= fixed a bug that was (or could have been) crashing
 
+October 6, 2002
+    	added event.clear() to efficiently clear the queue
+
 October 1, 2002
 	sprite.RenderGroups wasn't clearing killed sprites after draw()
 
 <a href=ref/pygame_draw.html#polygon>pygame.draw.polygon</a> - draws a polygon on a surface<br>
 <a href=ref/pygame_draw.html#rect>pygame.draw.rect</a> - draws a rectangle on a surface<br>
 <a href=ref/pygame_event.html#Event>pygame.event.Event</a> - create new event object<br>
+<a href=ref/pygame_event.html#clear>pygame.event.clear</a> - remove all of an event type from the queue<br>
 <a href=ref/pygame_event.html#event_name>pygame.event.event_name</a> - name for event type<br>
 <a href=ref/pygame_event.html#get>pygame.event.get</a> - get all of an event type from the queue<br>
 <a href=ref/pygame_event.html#get_blocked>pygame.event.get_blocked</a> - checks if an event is being blocked<br>

docs/ref/pygame_display.html

 pygame.display.list_modes([depth, [flags]]) -> [[x,y],...] | -1
 </tt></font><ul>
 This function returns a list of possible dimensions for a
-specified color depth. The return value will be an empty list of
+specified color depth. The return value will be an empty list if
 no display modes are available with the given arguments. A return
 value of -1 means that any requested resolution should work (this
 is likely the case for windowed modes). Mode sizes are sorted

docs/ref/pygame_event.html

 create new event object</td></tr>
 
 
+<tr><td><a href=#clear>clear</a></td><td> -
+remove all of an event type from the queue</td></tr>
+
+
 <tr><td><a href=#event_name>event_name</a></td><td> -
 name for event type</td></tr>
 
 the keys that will be members of the new event.
 <br>&nbsp;<br>
 Also, instead of passing a dictionary to create the event
-members, you also/or pass a list of keyword arguments that
-will become data members in the new event.
+members, you can pass keyword arguments that will become the
+attributes of the new event.
+</ul><br>&nbsp;<br>
+
+<a name=clear><font size=+2><b>clear
+</b></font><br><font size=+1><tt>
+pygame.event.clear([type]) -> None
+</tt></font><ul>
+Pass this a type of event to discard, and it will
+remove all matching event types from the queue. If no
+types are passed, this will remove all the events from the queue.
+You may also optionally pass a sequence of event types. For
+example, to remove all the mouse events from the queue, you
+would call,
+'<u>pygame.event.clear([MOUSEBUTTONUP,MOUSEBUTTONDOWN,MOUSEMOTION])</u>'.
 </ul><br>&nbsp;<br>
 
 <a name=event_name><font size=+2><b>event_name
 </b></font><br><font size=+1><tt>
 pygame.event.pump() -> None
 </tt></font><ul>
-Pumping the message queue is important if you are not getting
-events off the message queue. The pump will allow pygame to
-communicate with the window manager, which helps keep your
-application responsive, as well as updating the state for various
-input devices.
+For each frame of your game, you will need to make some sort
+of call to the event queue. This ensures your program can internally
+interact with the rest of the operating system. If you are not using
+other event functions in your game, you should call <u>pump()</u> to allow
+pygame to handle internal actions.
+<br>&nbsp;<br>
+There are important things that must be dealt with internally in the
+event queue. The main window may need to be repainted. Certain joysticks
+must be polled for their values. If you fail to make a call to the event
+queue for too long, the system may decide your program has locked up.
 </ul><br>&nbsp;<br>
 
 <a name=set_allowed><font size=+2><b>set_allowed
     /*DOC*/    "query all resolutions for requested mode\n"
     /*DOC*/    "\n"
     /*DOC*/    "This function returns a list of possible dimensions for a\n"
-    /*DOC*/    "specified color depth. The return value will be an empty list of\n"
+    /*DOC*/    "specified color depth. The return value will be an empty list if\n"
     /*DOC*/    "no display modes are available with the given arguments. A return\n"
     /*DOC*/    "value of -1 means that any requested resolution should work (this\n"
     /*DOC*/    "is likely the case for windowed modes). Mode sizes are sorted\n"
     /*DOC*/    "the keys that will be members of the new event.\n"
     /*DOC*/    "\n"
     /*DOC*/    "Also, instead of passing a dictionary to create the event\n"
-    /*DOC*/    "members, you also/or pass a list of keyword arguments that\n"
-    /*DOC*/    "will become data members in the new event.\n"
+    /*DOC*/    "members, you can pass keyword arguments that will become the\n"
+    /*DOC*/    "attributes of the new event.\n"
     /*DOC*/ ;
 
 static PyObject* Event(PyObject* self, PyObject* arg, PyObject* keywords)
     /*DOC*/    "pygame.event.pump() -> None\n"
     /*DOC*/    "update the internal messages\n"
     /*DOC*/    "\n"
-    /*DOC*/    "Pumping the message queue is important if you are not getting\n"
-    /*DOC*/    "events off the message queue. The pump will allow pygame to\n"
-    /*DOC*/    "communicate with the window manager, which helps keep your\n"
-    /*DOC*/    "application responsive, as well as updating the state for various\n"
-    /*DOC*/    "input devices.\n"
+    /*DOC*/    "For each frame of your game, you will need to make some sort\n"
+    /*DOC*/    "of call to the event queue. This ensures your program can internally\n"
+    /*DOC*/    "interact with the rest of the operating system. If you are not using\n"
+    /*DOC*/    "other event functions in your game, you should call pump() to allow\n"
+    /*DOC*/    "pygame to handle internal actions.\n"
+    /*DOC*/    "\n"
+    /*DOC*/    "There are important things that must be dealt with internally in the\n"
+    /*DOC*/    "event queue. The main window may need to be repainted. Certain joysticks\n"
+    /*DOC*/    "must be polled for their values. If you fail to make a call to the event\n"
+    /*DOC*/    "queue for too long, the system may decide your program has locked up.\n"
     /*DOC*/ ;
 
 static PyObject* pump(PyObject* self, PyObject* args)
 }
 
 
-    /*DOC*/ static char doc_get[] =
+    /*DOC*/ static char doc_event_clear[] =
+    /*DOC*/    "pygame.event.clear([type]) -> None\n"
+    /*DOC*/    "remove all of an event type from the queue\n"
+    /*DOC*/    "\n"
+    /*DOC*/    "Pass this a type of event to discard, and it will\n"
+    /*DOC*/    "remove all matching event types from the queue. If no\n"
+    /*DOC*/    "types are passed, this will remove all the events from the queue.\n"
+    /*DOC*/    "You may also optionally pass a sequence of event types. For\n"
+    /*DOC*/    "example, to remove all the mouse events from the queue, you\n"
+    /*DOC*/    "would call,\n"
+    /*DOC*/    "'pygame.event.clear([MOUSEBUTTONUP,MOUSEBUTTONDOWN,MOUSEMOTION])'.\n"
+    /*DOC*/ ;
+
+static PyObject* event_clear(PyObject* self, PyObject* args)
+{
+	SDL_Event event;
+	int mask = 0;
+	int loop, num;
+	PyObject* type,  *e;
+	short val;
+
+	if(PyTuple_Size(args) != 0 && PyTuple_Size(args) != 1)
+		return RAISE(PyExc_ValueError, "get requires 0 or 1 argument");
+
+	VIDEO_INIT_CHECK();
+
+	if(PyTuple_Size(args) == 0)
+		mask = SDL_ALLEVENTS;
+	else
+	{
+		type = PyTuple_GET_ITEM(args, 0);
+		if(PySequence_Check(type))
+		{
+			num = PySequence_Size(type);
+			for(loop=0; loop<num; ++loop)
+			{
+				if(!ShortFromObjIndex(type, loop, &val))
+					return RAISE(PyExc_TypeError, "type sequence must contain valid event types");
+				mask |= SDL_EVENTMASK(val);
+			}
+		}
+		else if(ShortFromObj(type, &val))
+			mask = SDL_EVENTMASK(val);
+		else
+			return RAISE(PyExc_TypeError, "get type must be numeric or a sequence");
+	}
+
+	SDL_PumpEvents();
+
+	while(SDL_PeepEvents(&event, 1, SDL_GETEVENT, mask) == 1)
+	{}
+
+	RETURN_NONE;
+}
+
+
+    /*DOC*/ static char doc_event_get[] =
     /*DOC*/    "pygame.event.get([type]) -> list of Events\n"
     /*DOC*/    "get all of an event type from the queue\n"
     /*DOC*/    "\n"
     /*DOC*/    "would call, 'pygame.event.get([KEYDOWN,KEYUP])'.\n"
     /*DOC*/ ;
 
-static PyObject* get(PyObject* self, PyObject* args)
+static PyObject* event_get(PyObject* self, PyObject* args)
 {
 	SDL_Event event;
 	int mask = 0;
 	{ "pump", pump, 1, doc_pump },
 	{ "wait", pygame_wait, 1, doc_wait },
 	{ "poll", poll, 1, doc_poll },
-	{ "get", get, 1, doc_get },
+	{ "clear", event_clear, 1, doc_event_clear },
+	{ "get", event_get, 1, doc_event_get },
 	{ "peek", event_peek, 1, doc_peek },
 	{ "post", event_post, 1, doc_post },
 
 
     /*DOC*/ static char doc_save[] =
     /*DOC*/    "pygame.image.save(Surface, file) -> None\n"
-    /*DOC*/    "save surface as BMP data\n"
+    /*DOC*/    "save surface data\n"
     /*DOC*/    "\n"
-    /*DOC*/    "This will save your surface in the BMP format. The given file\n"
-    /*DOC*/    "argument can be either a filename or a python file-like object\n"
-    /*DOC*/    "to save the BMP image to. This will also work for an opengl\n"
-    /*DOC*/    "display surface.\n"
+    /*DOC*/    "This will save your surface as a BMP or TGA image. The given\n"
+    /*DOC*/    "file argument can be either a filename or a python file-like\n"
+    /*DOC*/    "object. This will also work under OPENGL display modes.\n"
+    /*DOC*/    "\n"
+    /*DOC*/    "The image will default to save with the TGA format. If the\n"
+    /*DOC*/    "filename has the BMP extension, it will use the BMP format.\n"
     /*DOC*/ ;
 
 PyObject* image_save(PyObject* self, PyObject* arg)