Modular and extensible UI framework and ui elements.

----- keyboard/keypad - 3 x 10 Btns ------------------------- 20190927

*** uiKbd3x10B - ui keyboard module w/ 3 rows x 10 columns of uiBtn ui elements.

Note: uiKbd3x10B IS NOT part of the ui singleton. It is a standalone
input ui element similar to the touch modules: connected to ui and ui
elements, but not mixed into the ui element and managed by the ui (yet
or ever).

--- Key assugnments and mappings

For Keyboards with buttons, key ids are the button ids, and button ids are
SINGLE character ids (thus reserved for the ui modules and not available
to application ui elements). The id of a key is the 1st char on the key
(btn), for examples:

 - "a" for key (btn) "a@"  , returning the values "a"    , "A", and "@".
 - "<" for key (btn) "<' \", returning the values "cr/lf", "'", and "\".
 - "." for key (btn) "

Keyboard key handler calls cb callback w/ values v, k, u, e, and t parameters:

  v - key value - single character representing the printable key; special
      values: "sh0".."sh3" for shift key, "bs" for BacksSpace, "cr/lf" for
      CR/LF 
  k - keyboard object (this)
  u - ui core singleton
  e - event source (key btn)
  t - touch object

e is the key board button that has just been untouched (k: keyboard, u: ui
core and t: touch event object).

Key value depends on short TAP / LONG TOUCH and shift key mode.

The ^-shift key cycles w/ short taps through ^ m=0, ^^ m=1, ^^^ m=2,
^# m=3 its displays and modes; long touch always goes directly to
^# m=3 shift mode (number and special characters - NUM-LOCK).

For REGULAR keys, shift key modes and returned chars with regular - SHORT
TAP - are:

shift   shift
key     mode
display    impact (and for mode 1 only also state change)
  ^     0: lowercase   - key id/1st char in lowercase
  ^^    1: 1 uppercase - key id/1st char in uppercase, falls back to mode 0.
  ^^^   2: all uppercase, key id/1st char in uppercase (SHIFT LOCK)
  ^#    3: all number and special chars - 2nd char on key (NUM LOCK)

LONG TOUCH return number for key with numbers - top row - and for other
keys with three (3) characters this third character (except cr/lf key),
otherwise none (cr/lf key is double special: special 'special key').

The ^-shift key itself returns key values: "sh"+mode: "sh0", "sh1", "sh2"
and "sh3".

Special keys with shift mode 0..3 returns (listed by key, mode and short
tap or long touch):

special key w/ [chars on key] - location on keyboard
1st
chr
on  shift shft
key displ mod returns  (comment)
--- ----- --- -------- ----------------------------------------­-----------
^ (shift)[^],[^^],[^^^],[#^] - 1st key in bottom row
  ... w/ short tap:
    ^     0:  sh1     (when sh0 / ^ no-shift,     cycles to sh1, single shot)
    ^^    1:  sh2     (when sh1 / ^^ single shot  cycles to sh2)
    ^^^   2:  sh3     (when sh2 / ^^^ shift lock, cycles to sh3)
    #^    3:  sh0     (when sh3 / #^ NumLock,     cycles back to sh0)
  ... w/ long touch:
    N/C   *:  sh3     (ALWAYS jumps to mode 3 / "sh3" string for NumLock)

< (=cr/lf) [<'\] - last key in 2nd to bottom row:
  ... w/ short tap:
    ^     0:  cr/lf   ("cr/lf" string)
    ^^    1:  '       (single quote) and back to shift mode 0
    ^^^   2:  \       (back slash)
    #^    3:  cr/lf   ("cr/lf" string)
  ... w/ long touch:

. (dot) [.?..] - second to last key in bottom row:
  ... w/ short tap:
    ^     0:  .       (dot)
    ^^    1:  ?       (question mark) and back to shift mode 0
    ^^^   2:  .       (dot) 
    #^    3:  .       (dot)
  ... w/ long touch:
    ^     0:  .       (dot)
    ^^    1:  ?       (question mark) and back to shift mode 0
    ^^^   2:  .       (dot)
    #^    3:  .       (dot)

b/blank [ "_] - last key in bottom row:
  ... w/ short tap:
    ^     0:  b/blank (space 'bar')
    ^^    1:  "       (double quotes) and back to shift mode 0
    ^^^   2:  _       (underscore)
    #^    3:  b/blank (space 'bar')
  ... w/ long touch:
    N/A   *:  bs      (ALWAYS "bs" string for BackSpace)

In other words - basically:

• When no-shift (^): first char on key prints.
  
• Tap shift once (^^) prints next char in uppercase or 2nd special key on special key.
  
• Tap shift twice goes into SHIFT-LOCK (^^^) and twice again goes back to no-shift.
  
• When in SHIFT-LOCK (^^^): char key prints uppercase and special key 3rd char.
  
• Touch shift long goes always into NUM-LOCK.
  
• When in NUM-LOCK (#^): key with number prints number, special key.
  
• Touch long key with number or 3rd, special char prints number and special char, resp.
  
• Tapping shift cycles from no-shift to single-shot shift, SHIFT-LOCK,
  NUM-LOCK and back to no-shift.
  
  
  

--- Usage example

get the keyboard and 'connect' it to entry field "i1" - as part of UI definition:

Note: this keyboard modules requires ui base and uiBtn modules to be
loaded. It creates for each key a button with the id being the first char
displayed on the key, for example, a,b,c,..., ^ for shift, < for enter /
return, blank (" ") for blank/backspace,... Therefore, (practically) all
single letter ui element id's are taken and therefore 'reserved'.

var ui = require("ui")     // load ui base module
    .add(require("uiBtn")) // add module into base and remove from cache
    ;
var kbd = require("uiKbd3x10B")
                  .connect(ui,0,215,24,24, 7, 7,-2, 1, 1,10 ,0, 2, 4,
//                         ui,x,  y, w, h,bc,fc,sc,mx,my,fs,tc,tx,ty,cb
  function(v) {
    var s = ui.g("i1"); // is uiInp(ut field) ui element 
    if (v.length === 1) {  'normal' key - append
      ui.s("i1",s + "" + v);
    } else if (v === "bs") { BS/BackSpace key - remove last char
      if (s.length > 0) { ui.s("i1",s.substr(0,s.length - 1)); } 
    }
  } );

--- Module .connect(arguments)

 0  ui  ui core
 1  x   top of bounding box border
 2  y   left of bounding box border
 3  w   width of bounding box
 4  h   height of bounding box
 5  bc  key border color
 6  fc  key fill color for regular keys
 7  sc  key fill color for special keys (shift, return, special chars,...
 8  mx  x margin of key bounding box            ...only, blank, backspace)
 9  my  y margin of key bounding box
10  fv  key fontVector (size)
11  tc  key text color 
12  tx  key text x offset (within key/btn bounding box)
13  ty  key text y offset (within key/btn bounding box)
14  cb  callback function to accept following parameters:
   0  v   key: a single printable char, string for non-printables:
          "bs" for backspace, "cr/lf", "sh0".."sh4" for shift key
   1  k   keyboard (this sigleton)
   1  u   ui core singleton (see ui module)
   2  e   key btn that was just released (see uiBtn module)
   3  t   touch object (see ui module)

--- uiKbd3x10B - soft keyboard properties - variables and methods - mixed into ui base:

exports =  // uiKbd3x10B
{ mn: "uiKbd3x10B"
, kc: 30   // key count
, fi: -1   // idx 1st key in ui.es ui elts; adjust when insert/remove before
, fk: null // first key ("q")
, lt: 0.14 // short touch maximum / medium ('long') touch min time in seconds
, tt: 0    // touch time in secs
, sm: 0    // shift mode (0="^", 1="^^", 2="^#", 3="^^^")
, sk: null // shift key
, cb: null // callback
, st: ["^","^^","^^^","#^"] // for shift key status display
// ....
// ...  public methods - documented above
// ... private methods
// ...
}