• ----- 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.len­gth-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

    • uiSliExample.png
About

Avatar for allObjects @allObjects started