Modular and extensible UI framework and ui elements.

----- uiInp ------------------------- 20190927

*** ui input field module

ui input module extends ui base module with input field ui element.

Note: requires uiExt(ension) module (see uiExt.js module)

--- Enable ui with uiInp element functions:

var ui = require("ui")       // load ui base module
      .add(require("iuExt")) // add module into base and remove from cache
      .add(require("uiInp")) // add module into base and remove from cache
      ;

--- Create and add to ui an active(2), visible(1) =(3) input field at x/y
(left/top: 45/7) of size width/height (195/28), turkis border color (3),
white. Callback clears content when tap lasted longer than 550ms and there
is content. Not checking for content runs into stack overflow, because .u(e,"")
triggers again a callback because it is a change of value...

Colors are bit-coded with 3-bit color-depth according ui.clrs=[...] setup.

//    0  1     2       3   4   5   6   7   8  9       10  11 
// flgs  clazz id      x   y   w   h  bc  fc  valObj  cb   ls (arr of label ([[..],..]))
//       btn                ->x2->y2                  callback clears on tap > 550ms
ui.c( 3,"inp","i1"  , 45,  7,195, 28,  3,  7,"modular UI"
       ,function(i,v,_,e){ if (getTime()-_.tt>0.55   // [0] fv tc    x  y  mxLen typ fmt
                           && v.length) _.u(e,""); } // [1] fv tc    x  y  label text
                                                         ,[[13, 0,   5, 6, 16,   0,  0]
                                                          ,[13, 7,-233, 6, "Field"    ]
                                                          ]);

Callback cb is called on release (untouch) and change and
provides id, v, ui, e, t as arguments:

args[] sym   description 
  0    id  : button id ("x")
  1    v   : value (object) - type dependent (for now just string)
  2    ui  : ui (THE ui object)
  3    e   : uiInp element (inp 'object' (runtime data structure))
  4    t   : touch info x, y,...  (where last touched)
        { x : x coordinate
        , y : y coordinate
        , t : touched (truey) / untouched (falsey)
        , f : flags
        }

For detailed ui setup, including color depth and custom colors, connecting
to display and touch screen, soft key board or buttons, see ui module and
example material (in the ui.zip file and sources with comments). Take a
look at the example that shows all ui elements on one single
display - uiExampleAll.js - project file in the _sbx Espruino sandbox projects
folder. Make it the Espruino Web IDE sandbox folder and run the ready-made
examples on your Espruino board. Espruino forum has several entries about
the modules and hardware. Search in (google) for: Espruino Forum allObjects touch screen display modular ui framework.

No board or display with touch screen yet? No Problem: Open uiExample.html
in uidev folder in Web browser to run the same example in the Cross
Development / Emulation environment (where modules are developed and
maintained).

For helpful details to use the ui base and ui element APIs, take a look
at documentation in ui base and uiBtn modules.

--- inp ui element constructor arguments (a[]) and runtime data structure (e[]) are:

arg runtime 'object' instance of 'clazz' inp - input field
a[]  e[]
 0   [0] f  - flags focus(4), active(2), visible(1)
 .    .         0bxx1 visible &1 visible 
 .    .         0bx1x active  &2 active / senses touches vs read/display-only
 .    .         0b1xx focus   &4 focus by touch down, drag w/in bounding box
 1   [1] c  - clazz "inp"
 2   [2] i  - id eg "i01", short, at least 2..3 chars,  ui globally unique.
              Single letter ui element ids are 'reserved' (for keyboard(s)).
 3   [3] x  - x ((left ) of focus / touch bounding box)
 4   [4] y  - y ((top  ) of focus / touch bounding box)
 5       w  - width (of focus / touch box,... 
     [5] x2 - x ((right) of focus / touch bounding box: x - w + 1)
 6       h  - height (of focus / touch box,...
     [6] y2 - y ((bot  ) of focus / touch bounding box: y - h + 1)
 7   [7] bc - border color
 8   [8] fc - fill color
 9   [9] v  - value - (string) value to start with
10  [10] cb - simple, preferred callback on untouch after touchdown
11  [11] ls - labels - array of labels of which 1st is also value related   
      ls[0] label (info) for value related info, array with:
         l[0]  fv - fontVector (size)
         l[1]  tc - (label) text color (index)
         l[2]  x     - x offset from focus box x ( bounding box left )
         l[3]  y     - y offset from focus box y ( bounding box top  )
         l[4]  mxLen - maximum length
         l[5]  type  - opt type (absent & 0:plain string, only type for now)
         l[6]  frmt  - opt format function to use to format value for label
      ls[1,2,3,...] any number of additional labels, but mostly just two...
         l[0]  fv - fontVector (size)                     ...for min and max
         l[1]  tc - (label) text color (index)
         l[2]  x  - x offset from focus box x ( bounding box left )
         l[3]  y  - y offset from focus box y ( bounding box top  )
         l[4]  tx - label text to display (using .drawString())

Attached shot: 'cleared' entry field tapping x in top right corner; 'typed' on keyboard by tapping: 1 x shift (one shot shift sh1 ^^) - Key K - 3 x shift or long tap (num lock #^) - key 3 - 1 x shift (back to no shift sh0 ^) - y key, 2 x shift (shift lock sh2 ^^^) - Keys B O A R D - 2 x shift (back to no shift sh0 ^) - key x - long tap bottom right button - back space / bs - removes last keyed x.

1 Attachment