Modular and extensible UI framework and ui elements.

----- uiSli ------------------------- 20190927

*** ui slider module

ui slider module extends ui base with slider ui element.

--- Enable ui base with uiSli and create a slider with callback on untouch:

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

--- Create - specify - a slider

var s2 = // hold on to "s2" slider ui element for direct access app later on.
//    0   1    2       3   4   5   6   7   8  9      10  11 
// flgs  clazz id      x   y   w   h  bc  fs  valObj cb,  ls (arr of label ([[...],..]))
//	     sli                ->x2->y2                     [0] fv tc   x  y  min max s flgs
ui.c( 3,"sli","s2"  , 30,175,180, 26, -4,[-4,0],{v:33},cb, [[12, 6, 70, 6,   0,100,3,168
//                                                          [0][8] format (function)
                                                            ,function(v,_){ // (val, ui)
        var s="", f=_.te.f; return (!(f==0 || f&184)) ? s : ((v<1)?"0":"") // 128+32+16+8
             +(s=Math.round(v*10)+"%").substr(0,s.length-2)+"."+s.substr(-2); } ] // val
//                                                     [>0] fv tc    x  y  label text
                                                          ,[12, 7, -25, 6, "%:0"] // frnt
                                                          ,[12, 7, 182, 6, "100"] // back
                                                          ]);

Creates, adds to ui, conditionally displays and returns and stores in
global variable s2 a 0..100% slider of 3 pixel change value touch
sensitivity with bit coded callback activation flags, custom colored
(-4) border and same colored 'left' filling, black (0) 'right'filling,
shows % range from min 0% to max 100% as text labels left and right of
of it and current value as label in center on it by custom formatter
function.

Custom formatter has dual purpose:

• render more than just the bare value
  
• avoid slowing down sliding by rendering (if needed)
  
  

Because rendering - drawing strings on a display - can be slow, rendering
the actual value while sliding has to be kept to a minimum to keep sliding
snappy. Providing the formatter function that returns an non-empty string
only on desired conditions and an empty one else does the trick: rendering
an empty string is not noticeably slowing down sliding; ui element value
(v), ui and touch event states / flags (_, _.te.f) can be used to form
the desired condition to return empty or not empty string.

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

Since slider has two (2) areas to fill - left and right side of slider -
fill colors - fs - are specified as array:

• fs[0] is fill color for the 'left' / 'filled' side of the slider.
  
• fs[1] is fill color for the 'right' / 'empty' side of the slider.
  
  

Since slider has drag aspects callback and should also be able to deliver
values to the application while sliding, callback conditions can be
specified by flags as defined for the ui event flags. These flags also
control whether the new changed value is set and custom formatter function
is invoked or not. On untouch though, the new value is and formatter is
invoked no matter whether the untouch flag(s) is(are) set or not.

Callback is called with id, v, ui, e, t as arguments:

args[] sym   description 
  0    id  : button id ("c01")
  1    v   : value object (usually a number)
  2    ui  : ui (THE ui object)
  3    e   : uiSli element (sli '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.

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

arg runtime 'object' instance of 'clazz' slider
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 - "rad"
 2   [2] id - eg "s02", short, at least 3 chars, and 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] fs - fill colors array
       fs[0] fill color for 'left side' of slider
       fs[1] fill color for 'right side' of slider
 9   [9] v  - value - a number
10  [10] cb - callback on touch, value change, untouch
11  [11] ls - labels - array of labels of which first one is 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]  mn - minimum value ( at left  border )
         l[5]  mx - maximum value ( at right border )
         l[6]  s  - sensitivity (in pixels to detect change and redraw)
         l[7]  fm - optional format function to format value 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: Slider s1 and slider s2 moved / 'dragged'.

1 Attachment