Class MultiClick

source code

The MultiClick Plan class is an event processing aid for using events that
come in <something>UP and <something>DOWN pairs. <something> can currently
be KEY, MOUSEBUTTON or JOYBUTTON.

Because UP and DOWN events happen for individual keys, it is cumbersome to
write interfaces that use key combinations, or use multi-button game 
controller combinations as commands. MultiClick exists to address this
difficultly.

MultiClick takes in UP and DOWN events and processes them into two kinds
of events: Click and MultiClick. Click events occur when an UP event is
received that quickly followed the corresponding DOWN event, indicating a
short "click". If the DOWN event is quickly followed by more DOWN events,
these are combined until no additional events are received for a while.
At that point, a "MultiClick" event is generated. Similarly, UP events are
combined if they are received close to each other. If a "Click" occurs while
another "MultiClick" is happening, the MultiClick is re-generated after the
"Click".

Example
------- 

To illustrate these ideas, assume three buttons 1 2 and 3 and take a '-' 
to indicate a long delay. The following timeline demonstrates these ideas:
DOWN 1 
UP 1  --> click 1
DOWN 1
DOWN 2
-     --> MultiClick [1,2]
UP 1
-     --> MultiClick [2]
DOWN 3
UP 3  --> Click 3, MultiClick [2]
-
UP 2
-     --> (optional) MultiClick []

Usage
-----
For convenience, the default behavior for MultiClick is to call event 
handler methods of the JoyApp that owns it. This means that for typical use
cases the MultiClick Plan can be used as is, without subclassing.

MultiClick will call self.app.onClick( self,evt ) for click events, where evt
is the UP event that generated the click.

MultiClick will call self.app.onMultiClick( self, evts ) for multi-click
events, where evts is a dictionary whose values are the DOWN events that
combined into this multi-click combination.

The MultiClick object is passed to these event handlers to allow events
from multiple MultiClick Plans to be distinguished by the event handler.

Alternatively, MultiClick can be subclassed. Subclasses may override the
.onClick(evt) and .onMultiClick(evts) methods to process the events.

NOTE: the MultiClick .onEvent returns False unless the onClick or
  onMultiClick handlers return boolean True. Thus the .behavior never gets to
  run -- but a subclass may override the .behavior and use a True return
  value from the JoyApp to control its execution.

Initialize a MultiClick Plan
INPUTS:
  app -- JoyApp -- application running this Plan
  allowEmpty -- boolean -- should MultiClick events indicating no keys are
     currently pressed (empty set payload) be emitted. Default is False
  delay -- float -- delay used for merging multiple events

NOTE:
  MultiClick can only combine the events you .push() to it. For example,
  a MultiClick that only gets JOYBUTTONDOWN and JOYBUTTONUP from one
  joystick will only generate Click and MultiClick events from that
  joystick's buttons -- no keyboard, no mouse, no other joysticks.

(default)
Punts to self.app.OnClick(self,evt)

Override in subclass to process "Click" events -- i.e. events
that represent short (less than self.delay) keypresses / clicks

INPUT:
    evt -- pygame event

(default)
Punts to self.app.onMultiClick(self,evts)

Override in subclass to process "MultiClick" events -- i.e. 
events that represent one or more keys held together for long
(i.e. more than self.delay). 

A key can be clicked while other keys are MultiClicked. This
will generate a new multi-click after the short click is over.

When all keys are up, a multi-click can be generated with an
empty evts dictionary. This feature is controlled by
self.allowEmptyEvents, which is set by the allowEmpty 
parameter to the contstructor.

INPUT:
    evts -- dictionary -- event category --> pygame event