====== Mozaic: Include Snippet - Pad & Shift Manager ======
{{tag>Mozaic midi_scripting}}

The Pad & Shift Manager (Include) is a code snippet that allows to detect single-/double-/triple-tap & hold interactions for all pads and the shift button of Mozaic. You just need to add 1 event calls and define 2 events for callbacks.

==== Problem Solved by the Snippet ====
Mozaic offers event functions for pad down, pad up, shift down and shift up. Sometimes more interactions are needed for the pads and shift button, this can either be scripted by yourself, or you just include this snippet.

==== Scripts using the Pad & Shift Manager Snippet ==== 
  * The [[https://patchstorage.com/pad-manager-include/|Pad & Shift Manager (Include) Demo]]

\\ 
===== Adding the 'Pad & Shift Manager' to own scripts =====

You can either grab the snippet from the example scripts where you find the to-be-included snippet below the line
  // =========================================
  //    PAD & SHIFT Manager 
  // ============== V 3.1 ====================
at the end of the example - check that you found the current v3.1 snippet code.

Or you copy the code from the large code block at the end of this page to the end of your own script.

  * In the @OnLoad configure the Pad & Shift Manager variables and call @PadAndShiftManagerInit
  
  * When using an own script timer, add a call to @PadAndShiftManagerUpdate in the timer
  
  * Add an @OnPad callback event function to receive pad state changes
  
  * Add an @OnShift callback event function to receive shift button state changes
  
  
==== @OnLoad ====
Before initializing the Pad and Shift Manager, you can set the following variables
otherwise defaults will be used. In the most basic case you don't need to setup 
any of the variables.

<code>
  pmAnalyseTime = 200
</code>
Length of double tap / tap-and-hold time window in msec. With 200ms one
is able to catch dbl-tap, with 250msec some triple-taps with hold and
300msec seem to catch triple-tap without and with hold.

<code>
  pmManageTimer = YES
</code>
Set to NO if your script wants to controll the timer. Your timer needs to run 
continously and with an update interval faster than 50, otherwise the pad manager 
won't work. Also set pmTickInterval accordingly.

<code>
  pmTickInterval = 50
</code>
Update interval for the timer in msec.

<code>
  pmExcludePads = [7,15]
  pmExcludeCnt  = 2
</code>
List of pad ids and length of list to be excluded from
analysis. For these pads OnPad will be called immediately 
without the analysis delay.

After the optional setup of variables
<code>
  Call @PadAndShiftManagerInit
</code>

==== @Timer ====
When using an own timer, you need to call @PadAndShiftManagerUpdate 
from within the timer event.

The timer needs to run continously with an update tick faster than 50ms. 
Please set pmManageTimer = NO and  pmTickInterval with your interval before 
calling @PadAndShiftManagerInit

<code>
@SetupMyTimer
  SetTimerInterval 42
  pmTickInterval = 42
  pmManageTimer = NO
  StartTimer
@End

@OnTimer
  Call @PadAndShiftManagerUpdate
  // Do whatever you intended to do with your timer
@End 
</code>

==== @OnPad ====
This callback event function is called with the following parameter variables set:

  * pPad - contains the id pad pressed
  * pDown - TRUE if the pad is still pressed
  * pNumTaps - number of taps on that pad

This allows to detect various interaction pattern, like single tap, single tap and 
hold, double tap, double-tap and hold, tripple taps etc.

The more taps you want to detect, the longer analysis time is needed and the longer
single tap reaction will be delayed.

==== @OnShift ====
This callback event function is called with the following parameter variable set:

  * pNumTaps - number of taps on that pad

The shift-button down state can be retrieved using the ShiftPressed Moazic function

==== Overriding Pad or Shift Detection ====
If you only want to use the shift detection, simply define an own @OnPadDown event
above the include snippet. Since Moazic always calls the first definition of
an event, the Pad and Shift Managers pad detection will no longer be called.

If you only want to use the pad detection, simply define an own @OnShiftDown event
above the incude snippet.


\\ 
\\ 
===== Pad & Shift Manager Include Snippet =====

<code>
// =========================================
//          PAD & SHIFT Manager 
// ============== V 3.1 ====================
// -ki
//
// V3.1    13.07.2020  Simplified handling to two user callbacks
// V3.0.1  19.01.2020  Changed formatting
// V3.0    09.01.2020  Added SHIFT button and better instructions
// V2.0.   01.06.2019  Release on PatchStorage

@PadAndShiftManagerInit

  // Apply defaults, if the vars are not yet defined

  if Unassigned pmAnalyseTime
    pmAnalyseTime = 200 
  endif
  if Unassigned pmManageTimer
    pmManageTimer = YES
  endif
  if Unassigned pmTickInterval
    pmTickInterval = 50
  endif
  if Unassigned pmExcludePads
    pmExcludePads = []
  endif
  if Unassigned pmExcludeCnt
    pmExcludeCnt  = 0
  endif
  
  FillArray pmPadActive,  NO,16
  FillArray pmPadTicks,   0, 16
  FillArray pmPadTaps,    0, 16
  FillArray pmPadExclude, NO,16
  FillArray pmPadDown,    NO,16
  pmPadsActiveCnt = 0  
  pmShiftActive  = NO
  pmShiftTicks   = 0
  pmShiftTaps    = 0
    
  if pmExcludeCnt>0
    for _pad = 0 to pmExcludeCnt-1
      pmPadExclude[ pmExcludePads[_pad] ] = YES
    endfor
  endif

  pmAnalyseTicks = pmAnalyseTime / pmTickInterval

  pmTimerRunning = NO
  if pmManageTimer
    SetTimerInterval pmTickInterval
  endif
  
  Log {Pad & Shift Manager v3.1 started (},pmExcludeCnt,{ excluded pads, timer=}, pmTickInterval,{msec)}
@End

@PMCheckStopTimer
  if pmManageTimer and pmTimerRunning and pmPadsActiveCnt=0 and not pmShiftActive
    pmTimerRunning = NO
    StopTimer 
  endif
@End

@PMCheckStartTimer
  if pmManageTimer and not pmTimerRunning
    pmTimerRunning = YES
    StartTimer 
  endif
@End

@OnPadDown 
  pmPadDown[LastPad] = YES      
  if pmPadExclude[LastPad]
    pPad = LastPad 
    pNumTaps = 1
    pDown = YES
    Call @OnPad
    
  else
    Call @PMCheckStartTimer    
    if not pmPadActive[LastPad]
      Inc pmPadsActiveCnt
      pmPadActive[LastPad] = YES
    endif
    inc pmPadTaps[LastPad]
  endif
@End 

@OnPadUp 
  pmPadDown[LastPad] = NO  
@End 

@OnShiftDown
  pmShiftActive = YES
  inc pmShiftTaps
  Call @PMCheckStartTimer
@End

@OnTimer 
  if pmManageTimer
    Call @PadAndShiftManagerUpdate
  endif
@End 

@PadAndShiftManagerUpdate
  if not Unassigned pmShiftActive  
    for pPad = 0 to 15
      if pmPadActive[pPad]
        Inc pmPadTicks[pPad]

        if pmPadTicks[pPad] > pmAnalyseTicks
          pDown    = pmPadDown[pPad]
          pNumTaps = pmPadTaps[pPad]
          Call @OnPad
          
          // Reset pad
          pmPadActive[pPad] = NO
          pmPadTicks[pPad]  = 0
          pmPadTaps[pPad]   = 0
          pmPadExclude[pPad]= NO
          pmPadDown[pPad]   = NO

          Dec pmPadsActiveCnt
          Call @PMCheckStopTimer          
        endif
      endif
    endfor
  
    if pmShiftActive 
      Inc pmShiftTicks
      if pmShiftTicks > pmAnalyseTicks      
        pNumTaps = pmShiftTaps
        Call @OnShift       
        
        // Reset shift handling
        pmShiftActive = NO
        pmShiftTicks  = 0
        pmShiftTaps   = 0
  
        Call @PMCheckStopTimer
      endif
    endif
  endif
@End

// ================ END ====================
//    PAD & SHIFT Manager 
// =========================================
</code>