attached is patchfile updated copy of EventQueue.java with additional javadocs.
Same file is available on my website
http://pfarrell.com/java/EventQueue.java and
http://pfarrell.com/java/EventQueue.diffIndex: EventQueue.java
===================================================================
--- EventQueue.java (revision 236)
+++ EventQueue.java (working copy)
@@ -38,23 +38,56 @@
*****************************************************************************/
package net.java.games.input;
+ /**
+ * The <code>EventQueue</code> class implements a FIFO queue for Events.
+ * Typical usage pattern looks like:
+ * <pre>
+ for (Controller ctl : controllers) {
+ ctl.poll();
+ EventQueue localQueue = ctl.getEventQueue();
+ Event event = new Event();
+ while(localQueue.getNextEvent(event)) {
+ // do something cool here
+ }
+ try {
+ Thread.sleep(LOOP_TIME);
+ } catch (InterruptedException ex) {
+ // log exception
+ }
+ }
+ * </pre>
+ *
+ * @author Sun and open source contributors
+ */
public final class EventQueue {
private final Event[] queue;
private int head;
private int tail;
-
+ /**
+ * constructor, accepts argument with length of internal storage. Note, this constructor
+ * is not normally used by game developers, as they use the getEventQueue() function of
+ * Controller
+ * @param size capacity of the queue
+ */
public EventQueue(int size) {
queue = new Event[size + 1];
for (int i = 0; i < queue.length; i++)
queue
= new Event();
}
-
+ /**
+ * add one event to the queue. Note: package protected, not public.
+ * Question: does this fail or block if queue is full?
+ * @param event the Event to add
+ */
final synchronized void add(Event event) {
queue[tail].set(event);
tail = increase(tail);
}
-
+ /**
+ * test if queue is full. Note: package protected, not public
+ * @return true if the queue is full
+ */
final synchronized boolean isFull() {
return increase(tail) == head;
}
@@ -62,7 +95,15 @@
private final int increase(int x) {
return (x + 1)%queue.length;
}
-
+ /**
+ * The getNextEvent method returns true if the queue <i>had</i> an event in it,
+ * and it managed to populate the event object you passed in with the details.
+ * False if there was nothing in the queue to copy in to your event object.
+ * Populating an object you pass in is an efficiency saving designed to reduce
+ * the number of objects created, and thus the amount of garbage collection needed.
+ * @param event
+ * @return true if the queue <i>had</i> an event on it
+ */
public final synchronized boolean getNextEvent(Event event) {
if (head == tail)
return false;