/** Handling GWT events.
  *
  * <h3 id='CAES'>Using a collection as an event source (CAES)</h3>
  *
  * <p>When a HashMap or AbstractList itself is the event source, then events are not
  * dispatched (GWT 2.4 devmode, production mode not tested).  Traced (at least in the
  * case of the HashMap) to SimpleEventBus getHandlerList(), where sourceMap.get(source)
  * returns a null list of handlers.  This is strange because sourceMap.toString shows the
  * list is there (first entry in sourceMap) and the equivalent line in
  * ensureHandlerList() returns a non-null list earlier when handlers are registered.
  * Maybe a collection works as a key when it's the only key, but fails later when other
  * keys are added?</p>
  *
  * <p>The <a
  * href='https://developers.google.com/web-toolkit/doc/latest/DevGuideUiBinder#HTML_entities'
  * target='_top'>user manual says</a> adding a <code>DOCTYPE</code> will enable named
  * entities, but do not add it.  Firefox and Chrome will still complain that the template
  * is unreadable owing to undefined entities (not sure why).  Instead use numeric
  * entities.</p>
  *
  * <h3>Event class hierarchy</h3>
  *
  * <p>Here is an outline of the most important classes:</p><pre
  *
  *>    * {@linkplain com.google.web.bindery.event.shared.Event Event}
  *         * {@linkplain com.google.gwt.event.shared.GWTEvent GWTEvent}
  *             - these (excepting DomEvent) are synthetic ("logical")
  *               and have no native counterparts
  *             * {@linkplain com.google.gwt.event.dom.client.DomEvent DomEvent}
  *                 - wraps a NativeEvent
  *     * {@linkplain com.google.gwt.dom.client.NativeEvent NativeEvent}
  *         * {@linkplain com.google.gwt.user.client.Event Event}</pre>
  *
  * <h3 id='schedulingOrder'>Scheduler execution order</h3>
  *
  * {@linkplain votorola.g.web.gwt.event.CoalescingScheduler.Tester Testing indicates}
  * that (A) Scheduler executes commands in two groups based on scheduling mode: 1)
  * "finally" commands and then 2) "deferred" and "entry" commands.  Further (B) the
  * commands within each of the two groups are executed in the order requested.  The
  * grouping together of "deferred" and "entry" (A2), and the ordering behaviour within
  * groups (B) are undocumented in the API.  Consider using this warning wherever your
  * code depends on them:<pre
  *
 *>    "scheduling order assumption" (quoted, without a line break)</pre>
  *
  *     @see <a href='http://stackoverflow.com/questions/5131086' target='_top'
  *       >Using the GWT scheduler</a>
  */
package votorola.g.web.gwt.event;

  // Note: it now appears that (B) may be an artifact of the testing procedure.  The
  // "entry" commands, unlike the "deferred" commands, are witheld until a native browser
  // event fires.  If there is no input from the user for instance, then execution may be
  // delayed indefinitely (2.4).
  //// not sure, but witholding may have been artifact of coalescer bug fixed here:
  //// http://reluk.ca/var/db/repo/votorola/rev/00156ed947fc