EventEngine.java

package edu.stanford.hci.r3.events;

import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import edu.stanford.hci.r3.events.PenEvent.PenEventModifier;
import edu.stanford.hci.r3.events.replay.EventReplayManager;
import edu.stanford.hci.r3.paper.Region;
import edu.stanford.hci.r3.paper.Sheet;
import edu.stanford.hci.r3.pattern.coordinates.PatternLocationToSheetLocationMapping;
import edu.stanford.hci.r3.pattern.coordinates.conversion.PatternCoordinateConverter;
import edu.stanford.hci.r3.pen.PenInput;
import edu.stanford.hci.r3.pen.PenSample;
import edu.stanford.hci.r3.pen.streaming.listeners.PenListener;
import edu.stanford.hci.r3.units.coordinates.PercentageCoordinates;
import edu.stanford.hci.r3.util.DebugUtils;

public class EventEngine {

        private List<EventHandler> catchAllHandlers = new ArrayList<EventHandler>();

        private PercentageCoordinates lastKnownLocation;

        private List<EventHandler> mostRecentEventHandlers = new ArrayList<EventHandler>();

        private int numTrashedPenEvents = 0;

        private List<PatternLocationToSheetLocationMapping> patternToSheetMaps = Collections
                        .synchronizedList(new ArrayList<PatternLocationToSheetLocationMapping>());

        private Map<PenInput, Integer> penRegistrationCount = new HashMap<PenInput, Integer>();

        private List<PenInput> pensCurrentlyMonitoring = new ArrayList<PenInput>();

        private Map<PenInput, PenListener> penToListener = new HashMap<PenInput, PenListener>();

        private EventReplayManager replayManager;

        public EventEngine() {
                replayManager = new EventReplayManager(this);
        }

        public void addEventHandlerForUnmappedEvents(EventHandler handler) {
                catchAllHandlers.add(handler);
        }

        private void addPenToInternalLists(PenInput pen, PenListener listener) {
                penToListener.put(pen, listener);
                pen.addLivePenListener(listener);
        }

        private PenEvent createPenEvent(String penName, int penID, PenSample sample) {
                // make an event object so that someone can send it to the right event handler
                final PenEvent event = new PenEvent(penID, penName, System.currentTimeMillis(), sample);
                return event;
        }

        private int decrementPenRegistrationCount(PenInput pen) {
                Integer count = penRegistrationCount.get(pen);
                if (count == null) {
                        // huh? We don't have a record for this pen...
                        DebugUtils.println("We do not have a record for this pen, and "
                                        + "cannot decrement the registration count.");
                        return 0;
                } else if (count == 1) {
                        penRegistrationCount.remove(pen); // decrement from one to zero
                        return 0;
                } else {
                        penRegistrationCount.put(pen, count - 1);
                        return count - 1;
                }
        }

        public EventReplayManager getEventReplayManager() {
                return replayManager;
        }

        private PenListener getNewPenListener(final PenInput penInputDevice) {
                pensCurrentlyMonitoring.add(penInputDevice);

                // properties of the pen
                final int penID = pensCurrentlyMonitoring.indexOf(penInputDevice);
                final String penName = penInputDevice.getName();

                return new PenListener() {

                        public void penDown(PenSample sample) {
                                final PenEvent event = createPenEvent(penName, penID, sample);
                                event.setModifier(PenEventModifier.DOWN);

                                // a pendown generated through a real pen listener should be saved
                                // so that future sessions can replay the stream of events
                                replayManager.saveEvent(event);
                                handlePenEvent(event);
                        }

                        public void penUp(PenSample sample) {
                                final PenEvent event = createPenEvent(penName, penID, sample);
                                event.setModifier(PenEventModifier.UP);

                                // save the pen up also!
                                // do this before setting the location
                                // the location will be determined later, when the event is resent
                                replayManager.saveEvent(event);
                                handlePenUpEvent(event);
                        }

                        public void sample(PenSample sample) {
                                final PenEvent event = createPenEvent(penName, penID, sample);
                                replayManager.saveEvent(event);
                                handlePenEvent(event);
                        }
                };
        }

        public void handlePenEvent(PenEvent penEvent) {
                // System.out.println("Dispatching Event for pen #" + penID + " " + sample);
                mostRecentEventHandlers.clear();

                synchronized (patternToSheetMaps) {

                        boolean eventHandledAtLeastOnce = false;

                        // for each sample, we first have to convert it to a location on the sheet.
                        // THEN, we will be able to make more interesting events...
                        for (final PatternLocationToSheetLocationMapping pmap : patternToSheetMaps) {

                                // this is a key step!
                                // the event engine figures out which pattern region contains
                                // this sample. This determines the set of event handlers the event
                                // should be sent to
                                final PatternCoordinateConverter coordinateConverter = pmap
                                                .getCoordinateConverterForSample(penEvent.getOriginalSample());

                                // this map doesn't know about this sample; next!
                                if (coordinateConverter == null) {
                                        continue;
                                }

                                // which sheet are we on?
                                final Sheet sheet = pmap.getSheet();

                                // which region are we on?
                                final String regionName = coordinateConverter.getRegionName();
                                final Region region = sheet.getRegion(regionName);

                                // where are we on this region?
                                final PercentageCoordinates relativeLocation = coordinateConverter
                                                .getRelativeLocation(penEvent.getStreamedPatternCoordinate());
                                penEvent.setPercentageLocation(relativeLocation);

                                lastKnownLocation = relativeLocation;

                                // does this region have any event handler?
                                // if not, just go onto the next region
                                final List<EventHandler> eventHandlers = region.getEventHandlers();
                                // send the event to every event handler!
                                // so long as the event is not consumed
                                for (EventHandler eh : eventHandlers) {
                                        eh.handleEvent(penEvent);
                                        eventHandledAtLeastOnce = true;
                                        mostRecentEventHandlers.add(eh);
                                        if (penEvent.isConsumed()) {
                                                // we are done handling this event
                                                // look at no more event handlers
                                                // look at no more pattern maps
                                                // DebugUtils.println("Event Consumed");
                                                return;
                                        }
                                } // check the next event handler

                        } // check the next pattern map

                        if (!eventHandledAtLeastOnce) {

                                // send the event to our "catch-all" event handlers...
                                for (EventHandler eh : catchAllHandlers) {
                                        eventHandledAtLeastOnce = true;
                                        eh.handleEvent(penEvent);
                                        mostRecentEventHandlers.add(eh);
                                } // check the next event handler

                                if (!eventHandledAtLeastOnce) {
                                        // if still, no one has had a chance to deal with this event
                                        // it becomes TRASH!

                                        // there is no pattern map that matches the incoming pen event!
                                        // we dump it in a trash bin, and notify the user of this situation
                                        // perhaps the developer would like to register a mapping at run time?
                                        if (numTrashedPenEvents % 29 == 0) {
                                                // print out this warning once in a while...
                                                System.err
                                                                .println("The event engine cannot map these pen events to any active region. "
                                                                                + "We'll trash these events for now, but perhaps you should investigate "
                                                                                + "attaching a pattern mapping (even at runtime) to your regions.");
                                        }
                                        numTrashedPenEvents++;
                                        DebugUtils.println("Cannot Map " + penEvent);
                                }
                        }
                }
        }

        public void handlePenUpEvent(PenEvent event) {
                event.setPercentageLocation(lastKnownLocation);
                for (EventHandler h : mostRecentEventHandlers) {
                        h.handleEvent(event);
                }
        }

        private void incrementPenRegistrationCount(PenInput pen) {
                Integer count = penRegistrationCount.get(pen);
                if (count == null) {
                        penRegistrationCount.put(pen, 1); // incremented from zero to one
                } else {
                        penRegistrationCount.put(pen, count + 1);
                }
                DebugUtils.println("We have registered " + penRegistrationCount.get(pen) + " pens in total.");
        }

        public void register(PenInput pen) {
                // get the old listener, if it exists
                PenListener listener = penToListener.get(pen);
                if (listener != null) {
                        removePenFromInternalLists(pen, listener);
                }
                // this pen has never been registered, or
                // we just removed the old listener...

                // add a new listener
                listener = getNewPenListener(pen);
                addPenToInternalLists(pen, listener);
                incrementPenRegistrationCount(pen);
        }

        public void registerPatternMapForEventHandling(PatternLocationToSheetLocationMapping mapping) {
                DebugUtils.println("Registering A Pattern Location to Sheet Location Map");
                if (patternToSheetMaps.contains(mapping)) {
                        DebugUtils.println("EventEngine is already aware of this pattern map.");
                }
                patternToSheetMaps.add(mapping);
        }

        public void registerPatternMapsForEventHandling(
                        Collection<PatternLocationToSheetLocationMapping> patternMaps) {
                DebugUtils
                                .println("Registering the (Pattern Location --> Sheet Location) Maps [" + patternMaps + "]");
                patternToSheetMaps.addAll(patternMaps);
                DebugUtils.println("Registered " + patternMaps.size() + " New Maps");
        }

        public void removeEventHandlerForUnmappedEvents(EventHandler handler) {
                catchAllHandlers.remove(handler);
        }

        private void removePenFromInternalLists(PenInput pen, PenListener listener) {
                penToListener.remove(pen);
                pen.removeLivePenListener(listener);
                pensCurrentlyMonitoring.remove(pen);
        }

        public void unregisterAllPatternMaps() {
                patternToSheetMaps.clear();
        }

        public void unregisterPatternMapForEventHandling(PatternLocationToSheetLocationMapping patternMap) {
                patternToSheetMaps.remove(patternMap);
        }

        public void unregisterPatternMapsForEventHandling(
                        Collection<PatternLocationToSheetLocationMapping> patternMaps) {
                patternToSheetMaps.removeAll(patternMaps);
        }

        public void unregisterPen(PenInput pen) {
                int newCount = decrementPenRegistrationCount(pen);
                if (newCount == 0) {
                        DebugUtils.println("Count is at Zero. Let's remove the pen and its listener...");
                        PenListener listener = penToListener.get(pen);
                        removePenFromInternalLists(pen, listener);
                }
        }
}

---