Modular and extensible UI framework and ui elements.

[espruino-discuss3]

Posted at 2016-09-18 by @allObjects

1 of n posts

Tip for best display of code sections without line wrapping : change browser window to the sweet spot where no line wrapping happens.

A while ago I played around with touch screen displays that resulted in a quite terse, resource frugal UI implementation: UI Module w/ Buttons, Checkboxes,... for Display w/ Touchscreen.

Recently I picked up where left of and completed what I was originally going for. Several serious refactoring cycles lead to the 'thing' I'd like to share, to contribute as generally available Espruino modules, and also to provide some tutorials to introduce the rich options... last but not least an introduction how to build and integrate your own ui element extensions.

Already too many words, therefore a picture right away... actually more than one... See image attachments showing Buttons, Check Boxes, Radio Buttons, Sliders and even a soft '101'-Key keyboard, all on a touchscreen LCD (...which you get for a few bucks).

More out of a need or constraint than intentionally, I developed a simple cross development environment in the Web browser - after all, it is with display, and the browser has what is needed: display AND JavaScript. The browser gets the modules from the same sand box folder as the Espruino Web IDE and thus validation in the real environment is just an upload click away... (...is as close as an upload click... on the same screen, just in different window). I'll share crosses development as well. At this point it is developed to the point to support this particular ui framework development work, but it has the core ingredients - such as the cache - that allows to add emulating modules for many hard ware modules to run complete applications.

Attachments:

• ui_displayR.jpg
  
• ui_espruinoCrossDevRuntie.png
  
• ui_displayWithBoardR.jpg

[espruino-discuss3]

Posted at 2016-09-18 by @allObjects

2 of n posts

To provide a first glimps into the components, here some code facts:

• ui.js uses 247 variables for code and data.
• uiBtn.js uses 90 variables for code, and about 25 variables for each instance.

The numbers for the slider ui element have not exactly settled yet, but are around the double of a plain button... considering the capabilities, still a very small foot print...

...and this is the actual code:

Tip for best display of code sections without line wrapping : change browser window to the sweet spot where no line wrapping happens.

// ----- pull in dispaly and touchscreen
var dsp, dMod = require("ILI9341"),
    touch, tMod = require("XPT2046");

// ----- pull in ui base and ui element
var ui = require("ui")
      .add(require("uiBtn"))
      ;

// ----- define callbacks (to log ui element id and value)
var cb = function(id,v) { console.log(id + ": " + v); };
 
// ----- define UI (in level 0, so it does not use memory for source)

//   0  1     2       3  4     5    6    7   8
// flgs clazz id      x  y     w    h   bc  fc
//      btn                 ->x2 ->y2         
ui.c(3,"btn","b1"  ,  5, 40,  65,  35,  4,   4

//                    9       10  11 
//                    valObj  cb,  l (label array obj)
//                                 fv tc    x  y  label text
                   , "B_1",   cb,  [15, 7,  13, 9, "RED"  ]);
                   
ui.c(3,"btn","b2"  , 70, 40,  65,  35,  5,   6
                   , {v:1},   cb,  [15, 0,   9, 9, "Y-w-B"]);

// ----- run UI
function onInit() {
  SPI1.setup({sck:B3, miso:B4, mosi:B5, baud: 1000000});
                   // spi, dc, cs, rst, callback
  dsp = dMod.connect(SPI1, B7, B6, A8, function() {
      dsp.clear(); A5.set(); // display clear and back light on
      // connect ui to dsp and display it
      ui.connect(dsp)
        .w(0,0,239,319) // wipe screen w/ background color
        .d() // display all elements
        .di=true; // set display changes to immediate
      // setup touchscreen and connect it to ui
      SPI2.setup({sck:B13, miso:B14, mosi:B15, baud: 2000000});
      touch = tMod.connect(
          // spi, cs, irq, callback, calc (calibration calc function)
          SPI2, B10, B1, function(x,y) { ui.evt(x,y);
          }, function(yr, xr, d) {
            return [ Math.round(xr / -121.44          + 259.70685111989) 
                   , Math.round(yr /   88.90357142857 + -19.78130398103)
                   ];
      });
      if (touch._eRegisterCanvas) { // only in emulation and before listen
          touch._eRegisterCanvas("dspCanvas", 10, 10); }
  });
  if (dsp._eRegisterCanvas) { // only in emulation dev and before drawing
      dsp._eRegisterCanvas("dspCanvas", 240, 320); }
}

onInit(); // development convenience only... not part of final, saved application code.

The onInit() invocation - last line in the code - does not really belong to the application code... but while developing, it is is very convenient, because the system behaves the same way as with saved code on power-cycling but without actually having to save the code and do a power-cycling... ;-)

To understand touch screen related lines 45..47, take a look at recent Touchscreen conversation.

Lines 49..50 and 52..53 are cross development environment related and were a quick (and dirty) compromise to keep the emulating modules application independent... These lines do not belong into Espruino, and that's why they are conditioned and do therefore no harm...

As in above paragraph, emulation shows... but really marginal... and with some smart thinking - or (with some not so beloved) conventions - emulation can become completely transparent.

The code shows how the Espruino code is prefixed in order to run in cross development. Below few javascript lines are the only required entries to precede the Espruino code to run it in an plain html document in a Web browser:

<script src="_emulationConfig.js"></script>

<script>function _eeLoad(eComponentName) {
  document.writeln(['<scri','pt src="',_eEmulationPath,eComponentName,'.js"></scri','pt>'].join("")); }
</script>            

<script>_eeLoad("_eEspruinoJsShim");</script>
<script>_eeLoad("_eEspruinoPicoShim");</script>

<script> // (pre) load emulating modules - emulating code upload to board
_eeLoad("ILI9341"   );
_eeLoad("TouchRD");
</script>

<script> // (pre) load (non emulating) modules - emulating code upload to board
_emLoad("ui");    // ui base (code and runtime data holder)
_emLoad("uiBtn"); // uiBtn (Button)      element
</script>

As obvious, a plain .html file is used. To avoid a Web server, it is all pulled with just file:// protocol from directories which are configured in line 1 - pulled in as well from a java script fragment while the page is loaded... same concept as files are uploaded into Espruino, they get evaluated... and so does the html with embedded code when pulled in by the browser.

Lines 3..5 show this loader that adds javascript on the go, as you see in lines

• 7..8: Espruino ecosystem with emulated board
• 11..12: Emulated display and touchscreen modules
• 16..17: ui base and uiBtn ui element modules

I was surprised how well the UI behaves regarding speed - even though the communication with the display is serial... Text (drawString()) still drags its feet - understandably - but all other things are extremely snappy, such as visual touch feedback. I guess it is thanks to @jumjum who recently made some speed enhancement when using the Graphics objects - the 'inner' implementing of the LCD displays...

[espruino-discuss3]

Posted at 2017-07-17 by Pinnchus

Have you posted the module somewhere accessible?

Thanks,

[espruino-discuss3]

Posted at 2017-07-17 by @allObjects

...got a bit stuck in doc and work... will show in public in a bit...

[espruino-discuss3]

Posted at 2017-07-18 by @allObjects

@user54159 , check your forum messages...

[espruino-discuss3]

Posted at 2017-07-18 by Pinnchus

@allObjects Thanks!!!!

[espruino-discuss3]

Posted at 2019-09-20 by @allObjects

uiReadMe.txt

Hi,

The modular and extensible ui framework for Espruino from allObjects - is now ready for use 'as is' (finishing touches still ongoing).

6 folders - _sbx (an espruino sandbox ready to be used), _ecomponents, uidev, edev, uidoc and uixsrcmaterial - and this post as text in ui.zip file fort download below.

Unzip them into any directory. Make _sbx the sandbox folder in Espruino Web IDE. Upload the (example) projects to run them on your Espruino board.

Not the right hardware (yet) at hand? or: Not much time either for a sneak peek? - No problem:

Look at and play around with the very same examples in your Browser...

To run / develop the same modules and projects in emulation / cross development mode in Browser: open .html files - uiExample.html - in uidev folder and click link all.

uxscrmaterial folder contains many useful examples and older, simpler versions of the ui, most of them still working. Some of them will migrate over time into the actual modules and projects folders.

Goal is to harden the modules, grow the example pool, add examples for various hardware, also hardware without touch screen support, and make it all available on the Espruino site - as modules and as tutorial(s).

best js hacks - @allObjects

---

Attached: shot showing zip file content, ui_20190927.zip (zipped ui folder w/ all you need for ui). - ui_20191119.zip - newer version (still in work)

Attachments:

• ui_20190927.zip
  
• uiZipContent.png
• ui_20191117.zip

[espruino-discuss3]

Posted at 2019-09-20 by @allObjects

----- ui_ ------------------------- 20190927 - intro

*** modular and extensible (graphical) ui framework - regular version.

The framework consists of a bases module which provides the infrastructure
for individual out of box and custom ui elements and utility extensions.
Out of box ui elements include (for now):

• plain button
• check box
• radio button
• slider
• input field
• keyboard (soft keyboard / touch keyboard)

An out of box extension provides utility and convenience functions and
is required for more complex ui elements - for now - for - out of box -
radio button, and is also useful for the application to easy access
ui elements.

Creating and integrating custom ui elements and extensions as needed
is easy based on the architecture and available documentation and
ready to run examples. Examples can be run on actual Espruino and
display with and - soon also - without touch screen. Most of the
examples run also emulated in cross development environment in any browser
as html sharing the Espruino JavaScript files - that's how and where
the ui framework and ui elements are developed and maintained for most
of their functionality.

All ui elements handled by ui framework have roughly 12 (13) common
properties in same and similar structure(s):

• flags - hidden/displayed, touch active, read/display-only, in focus,...
• clazz - btn-Button, chk-Checkbox, rad-Radiobutton, sli-Slider, inp-Inputfield,...
• id of ui element - enabling sharing callbacks and other nifty things,
  such as keeping additional, application specific state and behavior
  the ui framework does not cater for (yet) or will never do or can...
• x and y position - left-top of ui elements bounding box
• width and height
• border and fill colors
• a value (object) enabling sharing callbacks and other nifty things
• a preferred callback - fired on untouch after touch down on same ui element
• some label object(s) - plain, static text but also as renders (functions)
• (optional, NON-preferred, experimental callback called on all touch events)

Only the 1st 9 of the 12 (13) properties are really mandatory. Same
values in same structures have lead to an implementation of the ui
elements as light weight, lean 'array objects' in order to save memory
/ variables.

Details about the ui element specific properties for construction and
runtime are documented for each ui element separately.

The ui communicates input (and other) events through callbacks. The
callback arguments include all pertinent information to allow a straight
forward, from simple to sophisticated use in the application and keep the
code terse in order to save memory / variables:

• id of ui element
• value (object) of ui element
• ui singleton (module) for accessing all statuses / ui elements / ui aspects
• ui element subject to touch event (for optional query/change by application)
• touch event object (touch/untouch and position on display / ui element, flags)

Attached shot: ui start up w/ all ui element types and keyboard (in emulation).

Attachments:

• startupExample.png

[espruino-discuss3]

Posted at 2019-09-20 by @allObjects

----- ui_ ------------------------- 20190919 - intro

*** ui framework - base module - intro

The ui base module takes care of most of the plumbing, logic and data
flow between touch screen (or physical buttons) and display as input and
output components and controling application.

--- Implementation approach

The ui base module is currently implemented as singleton, literally constructed
when loaded (required). At runtime it does not only hold on to its own code and
data but also the mixed in code for the various ui element 'types' as
needed (as loaded on demand by require() ) and the data of the
created ui elements. The ui elements are implemented a light weight array
objects: just data and - where needed - some format function(s).

--- Memory / Variable usage

Below some (ballpark) figures on various usage, categorized as U
for unminified vs. M for minified and I for individual vs C for cumulated.

// vars (Idividual|Cumulated)  IU /  IM -   CU -   CM  B (Un|Minified)
var ui = require("ui")     // 314 / 282 -  361 -  302 20       (-Base)
    .add(require("uiExt")) // 237 / 214 -  598 -  515
    .add(require("uiRad")) // 190 / 168 -  788 -  683
    ;
var ui = require("ui")     // 314 / 282 -  361 -  302 20
    .add(require("uiBtn"))
    .add(require("uiChk"))
    .add(require("uiExt")) // 237 / 214 -  598 -  515
    .add(require("uiRad")) // 190 / 168 -  788 -  683
    ;

Minification setting in Espruino Web IDE: Esprima (offline) for both code
in Editor window and from modules.

*** Basic Application of ui base and - as example - use of uiBtn (Button) element

Get ui base and ui elements and build ui - like a DOM - by ui definitions in
level 0. The build is executed on upload to Espruino. save() will save
the built ui. The onInit() function will start the already built ui
on power up, after save() or - while under development - manually by
invocation in console or automatically in a setTimeout() (see below).

--- Require ui components

Get ui base and ui elements to the extent as needed into the system,
such as uiBtn, uiSli(der), etc.

var ui = require("ui")     // getting ui base code (w/ 8 default colors)
    .add(require("uiBtn")) // add / mixin btn ui elt support into ui
    ;

----- Define UI and add elements

Definition of UI(s) - creation of 'DOM'(s) - best happen (with Espruino)
on code upload and is/are as such then saved on save(), but not displayed
(rendered) yet. Creating it dynamically is possible as well. Example UI
below defines ui with two (2) buttons - b1 and b2 - which on
release (untouch, tap) will call the example callback cb . Button ui
element definition includes just data and requires out of box no format
functions. For more details see uiBtn module (unminified code) and related
documentation.

//    0 1      2      3   4   5   6   7   8  9      10  11 
// flas clazz  id     x   y   w   h  bc  fc  valObj cb,  l (label array obj)
//      btn                ->x2->y2                        fv tc    x  y   text
ui.c( 3,"btn","b1" ,  5, 40, 65, 35,  4,  4, "B_1", cb,  [15, 7,  13, 9, "RED"  ]);
ui.c( 3,"btn","b2" , 70, 40, 65, 35,  5,  6, {v:1}, cb,  [15, 0,   9, 9, "Y-w-B"]);
// bc/fc/tc: border/fill/text colors; cb=callback(id, v, ui, e, t): id: button id,
// such as "b1"; v, ui, e, t provide btn value, ui, elt and touch event runtime
// data; colors: 3-bit depth coded: 0b### ###=rgb (0=black, 7=white, 4=red,...)

--- Define application stuff

The application acts on ui events that are communicated thru callbacks.
This sample callback cb - for simplicity reason - just logs the
buttons' id and value (object) in the console.

function cb(id,v,_,e,t) { console.log(id+": "+v); } // sample callback

--- Do devices stuff

Device stuff happens on upload - once - and defines the display and the
touch instance and module variables and sets latter accordingly.

The ILI9341 display controller used in the examples is a 240 x 320
pixel, max 16-bit color, TFT display controller. Other controller can be
used as well with adjusted width and height values and color definitions.

If the touch screen has a controller, use its module - like XPT2046
for resistive touch screen (XPT2046 works also for the ADS7843
controller); otherwise use the module that can handle a resistive touch
screen directly (TouchRD - from: Touchscreen, Resistive, where membrane
edge traces are Directly connected to Espruino pins and controlled and
sensed by Espruino).

// instance and module variables:
//
var dsp,  dspMod = require("ILI9341");   // display 

var touch,touchMod = require("XPT2046"); // touch screen controller
  // or:
var touch,touchMod = require("TouchRD"); // touch screen w/o controller

--- Define the onInit() function

Function onInit() {...} gets everything initialized, connected and
started. The code below shows touch screen controller module for touch
screen connection (XPT2046 can also be used for equally
specified ADS7843). Pins used are related to PICO.

function onInit() { // on power on/save() setting up all from scratch
  // setup and connect display, then ui and input (touch | phys btns)
  SPI2.setup({sck:B13, miso:B14, mosi:B15, baud: 1000000}); // display
  dsp = dspMod.connect(SPI2, B10, B1,  A4, function() { // using...
                  // ...spi,  dc, cs, rst, callback
    dsp.clear(); A1.set();  // display clear and turn back light on
    ui.connect(dsp)         // connect ui to dsp and display it
      .w(0,0,dspW-1,dspH-1) // wipe screen (rect) w/ default / bg color
      .d()                  // display all elements
      .di = true;           // set display changes to immediate
    SPI1.setup({sck:A5, miso:A6, mosi:A7, baud: 1000000}); // touch inp
    touch = touchMod.connect(SPI1, A3,  A2, function(x,y){ ui.evt(x,y);}
                        // ...spi, cs, irq, callback, /. calibrated...
        , function(yr, xr, d) { // ...function, maps touch to x/y of dsp
            return [ Math.round(xr / -121.44          + 259.70685111989)
                   , Math.round(yr /   88.90357142857 + -19.78130398103)
                   ];
    } ).listen(); // for XPT2046 module (ADS7843: not needed/supported)
  } );
} // /onInit()

--- Start the code after uploadis

After uploading the code, enter onInit() in the Espruino IDE console
to get the code started. For convenience you can add the following line as
last line in the code, which gets the code automatically going after
upload has successfully completed. Note though to remove or comment this
line on the last upload before saving the code with save():

setTimeout(onInit,999); // for dev; remove before upload for save()

*** Description of (graphical) ui base module and touch controller interface

--- Functions / methods of ui base module

The ui base module provides also convenience functions/methods to be
used in application to deal with ui elements as well as plain graphics. Due to
ui's extensibility, you can add easily your own ui element or plain function
extensions as desired (with .add(module); ).

• .evt(x,y) - main entry point for touch and touch emulating functions (tap
  function in uiExt module). A tap starts with invocation of .evt(x,y)
  with x and y values; subsequent invocations with x and y values
  indicate dragging, and invocation without x and y indicate an un-touch,
  which completes a tap or touch. ui base module keeps track of the
  changes and makes them available to the application thru callbacks
  with the ui singleton - variable ui / _ - and touch event
  object t with detailed flags t.f . Any other 'entries' can
  be used but keeping the states consistent become the burden of the
  application and is not recommended.
• .iib(x,y,e) - returns true when x and y (of touch) lay in bounding box of
  ui element e
• .foc(e) - set focus to element e (and takes it away from element that had
  it so far)
• .blr(e) - blur/unfocus element e (if .blr(), element currently in focus is
  blurred)
• .w(x,y,w,h,c) - wipe rectangular area at x/y and w(idth)/h(eight) of
  display w/ optional color c; default color is background color (.bc).
• .c(arguments) generic, single point entry for creating ui elements. Uses
  first arguments[1] as class or type name and concatenates it with "C"
  for specific create entry. To create a custom ui element and
  integrate it (with .add(require("customUiElementModule")) is
  discussed in a separate publication.
• .d(e) - (re) draw element e, and when just .d(), redraw the whole ui (all ui
  elements). In general, a ui is built on upload without displaying it
  to save variables and displayed on demand or in onInit() to
  re-display on every re-power up or reset. Note ui elements with
  custom (label) renderers / formatters that use ui () or touch
  event states / flags (.te.f, t.f), these states / flags in their
  logic, such as the optional value renderer / formatter of the slider,
  this logic needs adjustment, or, the state(s) / flag(s) need to be
  set accordingly, latter though without interfering with their overall
  life cycle or their dependents (ui components' logic).
• .clr(c,i) - set color according this.clrs{0](c,i) (customizable) function.
  Default is set for bit coded value for 3-bit (rgb) color depth and
  provides 8 colors: b&000=0=black, b&111=7=white, b&100=4=red, etc.
  this.clrs0 can be customized to support any color depth - coded,
  table looked up, or literal. For details see Colors and color
  definitions section below.
• .fnt(fv) - set fontVector (size) ...currently w/ no frills, as opposed to
  .clr(). More font options will be implemented at a later time.
• .ld(x,y,l(abelInfoArray)) - label draw function; label info array:
  • l[0] : fontVector (size)
  • l[1] : color (see Colors section
  • l[2] : xOffset to x - left of bounding box of label (.drawString(...))
  • l[3] : yOffset to y - top of bounding box of label (.drawString(...))
  • l[4] : label text (used in .drawString(...))
    Note: the reason for x and xOffset - and y and yOffset - is because
    .ld() is used in conjunction with a ui element that has a bounding
    box that provides x and y - usually left-top corner and xOffset
    and yOffset are used to place the label relative to the ui
    element's corner coordinates. For plain, direct use with absolute
    coordinates, either xOffset and yOffset have to be set to 0. For
    reuse of label at same position, it is better to set both x and
    y to 0.
• .add(module,keep) - extend ui module with ui element and other extensions
  to support modularity. After module code is merged into ui base code,
  module is removed from cache to save variables. For that purpose, the
  module has to know its name in module name property mn. For example,
  for a module onOff.js for switching back light on/off on pin
  B2, exports = { mn:"onOff"
, on: function(on) { digitalWrite(B2, on || on===undefined); }
  defines the module code, ui.add(require("onOff")) adds it to the
  ui.js base code in order to be used as ui.on();. Without building
  a file, modules can also be put into cache directly on upload in level
  0 (and served with require() with module name provided as variable to
  escape regular module detection and pre-upload from modules
  sources): Modules.addCached(mName,'{ mn:"onOff",on: function(on) {'
+ digitalWrite(B2, on || on===undefined); }'); , and added
  with ui.add("onOff"); .

--- **UI (touch) event object (passed in callbacks)**is

The touch event object t and other objects, such as the ui
/ _ and the ui element e themselves, are passed around for easy
access in the ui base and ui element implementation as well as in the
application. The touch event object has this structure:

t = // (touch) event
   { x: x // current or last touched x coordinate
   , y: y // current or last touched y coordinate
   , t: t // touching: (truey), not touching (anymore): falsey
   , f: f // touch event flags (experimental)
   }

Touch event flags t.f - some experimental - are:

0000 0000 0000    0 unexpected (invalid?)
0000 0000 0001    1 untouch
0000 0000 0010    2 touching
0000 0000 0100    4 touch down
0000 0000 1000    8 'untouch' focused element while not in focus - _.lf
0000 0001 0000   16 untouched focused elt while in focus (typical untouch)
0000 0010 0000   32 moved out of focused element (touched down element)
0000 0100 0000   64 touching in focused elt (touched down elt) - _.ef / _.lf
0000 1000 0000  128 touching / focused 1st time or re-focused - _.ef / _.lf
0001 0000 0000  256 untouch on dragged over non-touched-down, alt elt - _.af
0010 0000 0000  512 moved out of non-touched-down, alternate focused elt
0100 0000 0000 1024 touching in non-touched-down, alternate focused element
1000 0000 0000 2048 touching 1st time in non-touched-down, alt. focused elt

Re-focusing happens when having touched down, dragged out of the element
and now draging back 'into' the initially focused element (touched down
element (_.ef / _.lf).

In preferred callback, a typical untouch - touch down on a ui element and
untouch on same ui element - set these flags:
conditions:

0000 0001 0001   7 = 16 untouched focused element while in focus (simple,
                    +  1 untouch event

Untouching after moving / dragging out of the bounding box of the touched
down ui element sets these flags:

0000 0001 1001   25 = 16 untouched focused element while in focus (simple,
                         regular untouch event)
                    +  8 'untouch' focused element while not in focus
                         (_.lf) - last registered focused element, now not
                         in focus anymore (_.fe), but may need cleanup
                         or reset when element has been modified on other
                         events using alternative callback
                    +  1 untouch event

In the preferred callback fired on ontouch only - touch started with
touch down and ended with untouch on same ui element - requires usually
no or only rarely interpretation of touch event flags.

The alternative callback fires on every kind of touch event and demands
significant interpretation of the flags from the application and ui
status items - passed as well in the callback - in order to take
appropriate action(s) in the application. The multitude of flags
allows to determine - next to untouch - touch down, dragging within,
leaving and re-entering bounding box of touched down ui element as well
as same events of the alternate - not touched down - element (and can
be used to implement drag and drop).

--- Colors and Color Definitions

ui base module includes a default color converter that supports 3-bit
color depth - 1 bit each per red, green and blue base color - coded as
single RGB integer value, yielding 8 colors: 2^1^3 = 8 colors (3 LSB -
Least Significant Bits of an integer). The color converter is a
function and is first element - index [0] - of an array which is set
and stored as ui.clrs[] array property:

ui.clrs = [ function(c,i){ var v=(i)?c^7:c;
                           return [v>>2&1,v>>1&1,v&1]; }.bind(exports) ]

The default color converter accepts for c a value from 0..7 for the basic
8 colors and returns them as triplets of 0s and 1s (array of three (3)
elements of values 0 and 1). It accepts an optional second parameter to
invert the color when truey. The inverted, complementary color contrasts
the non-inverted color and is defined by the color specified by the
1-complement of color c. For example, for a the 3-bit color depth defined
color with value 4 , [1r,0g,0b] or red , the inverted,
contrasting complementary color value is 3 , [0r,1g,1b]
or aqua.

The color converter is is invoked by ui's color setting method ui.clr(c,i)
with same arguments. Any color converter delivers - has to deliver -
the normalized values 0..1 for each of the RGB colors as
[r, g, b] triplet, because hat values triplet is parameter for setting the
color by invoking the set-color method .setColor(r, g, b) of the
Espruino Graphics object. The display module knows how to pass the color
onto the display's controller to make the display show the proper color.

--- Enhanced Color Converter

With the enhanced color converter as below, colors can be specified in
three ways:

1. bit-coded as single positive value
2. (negative) index into palette of [r,g,b] triplets
3. literal [r,g,b] triplet

The n custom colors of the custom color palette are stored in the same
array as the color converter as 2nd to n-th + 1 element - index 1..n. The
color converter has to be built to accept 'negative' color values -1 .. -n
to pick a color from the custom palette: it takes the negative value as
positive index into the ui.clrs[] array property tp pick a color
from the custom color palette and return it as value-normalized
[0..1r,0..1g,0..1b] triplet. The way the custom colors of the custom color
palette are specified determines the implementation of the converter.

ui.clrs = // 'imply' color depth and populate table w/ converter and define
          // user colors / palette (colors accessed w/ negative index)
  [function(c,i) { // converts 'custom color info / spec' to [r,g,b]...
       var v, s=isNaN(c); // ...@ idx 0; internally called: _.clrs[0](...)
       if (s || c<0) { // c<0 (looked up [R,G,B]) or c=[R,G,B]
         return ( ((s) ? c : this.clrs[-c]).map( // convert 0..255->0.0..1.0
                               function(v){ return ((i)?v^255:v)/256; } ) );
       } else {        // c>=0 bit coded rgb color (0b001,010,011,100,...111
         v = (i) ? c^7 : c;  // (default 3-bit color depth w/ 2^1^3=8 colors)
         return [v>>2&1,v>>1&1,v&1]; }
     }.bind(ui)  // custom color palette (converter knows to convert spec)
  ,[216,216,216] // user color -1: light grey // keyboard special keys
  ,[192,192,192] // user color -2: medium light grey
  ,[128,128,128] // user color -3: medium gray
  ,[192,128,192] // user color -4: light purple
  ,[0  ,160, 64] // user color -5: kind of a 'darker' green
  ];
ui.bc = 0; // ui (screen) background color (override default w/ other value)
ui.tc = 7; // ui (screen) touch / focus color (override default w/ oth. val)

For [r,g,b] specification, Espruino Graphics modules accepts for each
r,g,b base color the normalized value 0.0 .. 1.0. Under the hood and with
help of the module for the display, this normalized color specification is
transformed - most of the time - into a bit coded color again, but in a
different, more elaborate / complicated encoding, especially when
different number of bits are used for each of the base r, g and b colors,
for example, (display specific) 5, 6, 5 bits for r, g, b. The module also
handles the conversion the sequence of the r, g and b colors when needed,
for example, [r,g,b] to [r,b,g].

Normalized color specification value is mapped to actual color based on
color depth specified for or implied by the display (module) used in
conjunction with the Espruino's Graphics object. The ui base module
already includes a default color converter from bit coded rgb value to
Espruino's normalized [r,g,b] values triplet. Passing the normalized
values triplets makes bit coded colors in the ui independent from the
display's version of bit coding.

The n custom colors of the custom color palette are stored in the same
array as the color converter as 2nd to n-th + 1 element - index 1..n.
The color converter has to be built to accept 'negative' color values
in range of -1 .. -n to pick a color from the custom palette: it takes
the negative value as positive index into the ui.clrs[] array to
properly pick a color from the custom color palette and return it
converted to value-normalized [0.0..1.0r, 0.0..1.0g, 0.0..1.0b] triplet.
The way the custom colors of the custom color palette are specified
determines the implementation of the converter.

--- Custom ui elements and extensions

In order to not collide with future development of the ui components
out of the box and for easy distinction, choose for custom ui elements
clazz names of 5 characters or more, use for mixed in properties -
variables and methods - names with 6 or more characters. Also, add a
custom parallel array object or real js object rather than adding
elements to the existing array object.

--- More...

The unminified sources and examples have in-line documentation - same
as this - and in-line comments. Latter is useful when reading the code
to grok 'what is going on'. Feedback - in general and in particular -
and (improving) contributions are welcome (@ allObjects).

--- ui - base code into which elements and custom code are mixed in

exports = // ui base / 'DOM'/ui e(lement) data & code holder, singleton, for mixins)
{ dsp: null // display (Espruino Graphics object)
, mn: "ui"  // reserved, used temporary
, bc: 0     // dsp background color >=0: r*g*b* bit coded; <0: looked up [...,[R,G,B],...]
, tc: 7     // touch / focus color; >=0: r*g*b* bit coded; <0: looked up [...,[R,G,B],...]
, di: false // display instantly on create/change (not defer until after save())
, es: []    // ui elements
, ef: null  // (primary ui) element (in visual) focus (by touch down / hovering)
, lf: null  // (primary ui element) last (in visual) focus (by touch down / not hovering)
, af: null  // alternate (ui element in non-visual) focus (by drag over / hovering)
, it: false // (display) is touched
, td: false // is touch down (event)
, tt: 0     // touch down time
, lx: 0     // last x (touched)
, ly: 0     // last y (touched)
, dx: -1    // (last) x (touch) down
, dy: -1    // (last) y (touch) down
, te: {f:0} // (last) touch event
, clrs:     // default - bit coded color of 3-bit color-depth - 2^1^3(rgb) = 8 colors
// ....
// ...  public methods - documented above
// ... private methods
// ...
}

Attached shot: Button b1 and then button b2 'tapped'.

Attachments:

• uiBtnExample.png

[espruino-discuss3]

Posted at 2019-09-20 by @allObjects

----- uiBtn ------------------------- 20190927

*** ui button module

The ui button module extends ui base with button ui element.

Implementation note: vs3 overlaps/is duplicates of uiExt module and
will overwrite each other. Therefore - on changes - changes have to
be applied to both of them to maintain consistent outcome. It is
duplicated in the ui checkbox so that ui extensions does not need to
be loaded when not used. It saves memory / vars with simple UIs.

--- Enable ui base with uiBtn and create a button with callback on untouch:

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

--- Create - specify - plain buttons

// flgs  clazz id   x  y  w  h b f  value object /. callback on 'untouch'
ui.c( 3,"btn","b1",10,20,50,30,4,7,"B_1"
                  ,function() { (LED1.read()) ? LED1.reset() : LED1.set() }
                  ,[20,0,5,15,"RED"]);
//                  fv t x y   label text

Creates, adds to ui, conditionally displays and returns an active(2),
visible(1) =(3) button ("btn") with id "b01". Button is positioned at
10 @ 20 (left @ top, x @ y) and is sized 50 x 30 (width x height), has
4(red) / 7(white) border / fill colors, has value object string "B_1",
has (arguments ignoring) callback that toggles red LED1, and is labeled
"RED" on top of it in fontVector (size) 20, text (font) color 0 (black
on white button fill color) and x / y-offset of 5 / 15 from left top
corner of button's bounding box.

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

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

args[] sym   description 
  0    id  : button id ("b1")
  1    v   : value object ("B_1" - can be any object)
  2    ui  : ui (THE ui object)
  3    e   : uiBtn element (btn '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 ui base, color, label, and callback details see (also) ui base module.

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).

--- Some more details

A button with border and fill colors equal to display background
color (ui.bc) creates a tap-able area that is useful to make anything,
such as a displayed image, to act like a button...

uiBtn can be changed within callback: for example in example above, the
label can be changed to indicate whether tapping will turn the LED on or
off. In order to make the ui framework redraw the button and make the
label change visible, the callback has to return truey ('JS true'). The
button / callback definition for label changing button looks like this:

// flgs clazz id   x  y  w  h  b f  value object /. callback on 'untouch'
ui.c(3,"btn","b01",10,20,50,30,4,7,"B_1"
                  ,function(id, v, ui, e, t) { // on untouch event
                     if (LED1.read()) {
                       LED1.reset();
                       e[11][4] = "RED on"; // label text
                     } else {
                       LED1.set(); 
                       e[11][4] = "RED off"; // label text
                     }
                     return true; // truey forces button to be re-drawn
                   }
                  ,[20,0,5,15,"RED on"]);
//                  fv t x y   label text

The same callback shared by multiple uiBtns can produce button specific
results when callback takes into account the each buttone's unique id or
value (object) as passed to the callback as 2nd argument. Example code for
label change above shows that callback parameters include the value object
of the button (as well as the button element itself). This allows to use
the same callback with different outcome based on button value object (or
button's fill color). Multiple, different colored buttons can be used to
light up an RGB LED (string) in the button's colors as defined by the
value object (and/or fill a rectangle somewhere on the display with the
same color as the button's color using one and the same callback to keep
the code terse and save space (variables).

Note: The preferred touch event to invoke the callback is on untouch,
because it has these advantages:

• UI behavior is simple in sequence and behavior.
• Enables cancel of touchdown: releasing / untouch AFTER 'moving /
  dragging the touch' out of the bounding box of the initially touched
  button (touched on touch down) will not invoke the untouch callback
  that otherwise would be the inevitable consequence on touchdown on
  the button.
• Implementation of callback is simpler because it is time-wise less
  critical for delivering a UX behavior with timely, intuitive (visual)
  feedback to user and no delay on execution of the callback.

To use the (experimental) alternative callback called on all touch events,
the 11th ([10]) argument value for the preferred callback 11in the
constructor - ui.c(...); - has to be a falsey value best is
undefined) and the 13th [12] has to be the callback function. The
alternative callback is called with the same arguments as the preferred
one. The touch event object t has 12 bit coded flags - t.f ,
for example, for the untouch event is 0b000000011001 or 25 -
which describe the touch event in detail. For details see ui base module.

Using a synchronous implementation for callback on touch down may delay
the visual feedback to the user about the accepted touch down when it
takes noticeable time to complete. Therefore, the callback should invoke
the heavy lifting code in a setTimeout(function(...){...},10,...);
function as the last thing in the (otherwise 'empty') callback. The 10
millisecond timeout is a value to start with. If it is not working, find
the best value empirically by working thru the application varying the
value.

If the button has to change to give additional visual feedback to the user
that the callback is in execution, then that change has to be coded
BEFORE* the setTimeout() and the callback has to return truey in
order to trigger the redrawing of the button in the ui base module.
Changing the button again after completion of the heavy lifting
of the callback, it has to happen as last thing IN
the setTimeout(function(...){...; e[#]=...; ... _.d(e); },10,...);
(with _ being the ui singleton (ui base module) object, passed
as the 3rd argument to the callback).

To prevent additional touch down events on the button to prevent
triggering the callback again before its completion, disabling of the
button has to happen before setTimeout() as well
with e[1]=e|1]|2-2; . Re-enabling as absolutely last item IN
the setTimeout(){...; e[1]=|2; } code, even after the redraw (see
above). A more radical approach is to control the touch listener if it
supports the method touch.listen(false) (and the opposite,
touch.listen(), which is the same as touch.listen(true)... or 0 and 1
for false and true argument values, respective). Doing latter though,
you loose the ability to issue a cancel of a long running callback
(which of course has to yield once in a while to the touch controller
module using chained setTimeout()s until done.

Example of a button with both untouch and touchdown event callback:

// flgs clazz id   x  y  w  h  b f  value object
ui.c(3,"btn","b01",10,20,50,30,4,7,"B_1"
                  ,undefined
                  ,[20,0,5,15,"RED"]
//                  fv t x y   label text
                  ,function(id,v,_,e,t){ console.log(id+" "+t.f); } );

If you use both callbacks and put 'the (heavy) work' of the touch down
callback into a setTimeout(function(...){...},10,...);, you may
consider to put 'the work' of both callbacks into a setTimeout();
(with equal timeout value) to ensure proper sequence (to prevent touchdown
callback being triggered first...). Having 'the work' of the untouch in
a setTimout();, it is recommended to implement button changes the same
way as it has to be done in the touchdown callback by invoking the redraw
in the callback with _.d(e); and let the callback return nothing
(which is the same as falsey).

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

arg runtime 'object' instance of 'clazz' ` btn` (button)
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 "btn"
 2   [2] i  - id eg "b01", 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 - any object, from simple string to number to
              complex { } object (returned when button pressed) 
10  [10] cb - simple, preferred callback on untouch after touchdown
11  [11] l  - label (info), array with:
      l[0]  fv - fontVector (size)
      l[1]  tc - (label) text color
      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())
12  [12] ca - NON-preferred, experimental callback on any touch event

Attached shot: uiBtn - button - example (in emulation) - touching down on b1, dragging over b2 and back to b1 and then untouch b1 = tapping b1.

Attachments:

• uiBtn_b1_touch_drag_over_b2_back_b1_untouch_tap_b1.png

[espruino-discuss3]

Posted at 2019-09-20 by @allObjects

----- uiChk ------------------------- 20190927

*** ui checkbox module

The ui checkbox module extends ui base with checkbox ui element.

Implementation note: vs2 overlaps/is duplicates of uiExt module and
uwill overwrite each other. Therefore - on changes - changes have to
be applied to both of them to maintain consistent outcome. It is
duplicated in the ui checkbox so that ui extensions does not need to
be loaded when not used. It saves memory / vars with simple UIs.

--- Enable ui base with uiChk and create a checkbox with callback on untouch:

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

--- Create - specify - check box

// flgs clazz  id    x  y  w s b f  value object /. callback on 'untouch'
ui.c( 3,"chk","c1",140,45,25,0,2,7,"H"
                  ,function(id,v){ (v) ? LED2.set() : LED2.reset() }
                  ,[12,7,3,5,"On"]);
//                  fv t x y  label text

Creates, adds to ui, conditionally displays and returns an active(2),
visible(1) =(3) checkbox ("chk") with id "c01". Checkbox is positioned
at 145 @ 40 (left @ top, x @ y) and sized 25 square (both width and
height), has 2(blue) / 7(white) border / fill colors, is initially
unchecked (0, but any falsey works), has value object "H" (when checked
and undefined when unchecked), has callback that sets and resets green
LED2 accordingly, and is labeled "On" right next to it in fontVector
(size) 12, text (font) color 7(white) on black screen background color
and x / y-offset of 3 / 5 from left top corner of checkbox's bounding box.

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

For ui base, color, label, and callback details see (also) ui base module.

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

args[] sym   description 
  0    id  : button id ("c1")
  1    v   : value object ("H" - can be any object);
             NOTE: is undefined when check box is unchecked
  2    ui  : ui (THE ui object)
  3    e   : uiChk element (chk '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.

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

arg runtime 'object' instance of 'clazz' chk (chkbox)
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 "chk"
 2   [2] i  - id eg "c01", 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 and height (of focus / touch bounding box)
     [5] x2 - x ((right) of focus / touch bounding box: x - w + 1)
 6       s  - initial checked(truey/1)/unchecked(falsy/0) state used
              with [9] value info
     [6] y2 - y ((bot  ) of focus / touch bounding box: y - h + 1)
 7   [7] bc - border color
 8   [8] fc - fill color
 9       v  - value (returned value when checked)
     [9] vi - value info array w/ state and value
         [0] - truey/falsey for checked/unchecked state of checkbox
         [1] - value object (returned when checkbox is checked)
10  [10] cb - simple, preferred callback on untouch after touchdown
11  [11] l  - label (info), array with:
      l[0]  fv - fontVector (size)
      l[1]  tc - (label) text color
      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())
12  [12] ca - NON-preferred, experimental callback on any touch event

Attached shot: Check box c1 and then check box c2 'tapped'.

Attachments:

• uiChkExample.png

[espruino-discuss3]

Posted at 2019-09-20 by @allObjects

----- uiExt ------------------------- 20190927

The ui extension extends ui base with service and convenience functions for
ui frame work as well for your application .

ui extension is currently required by:

• uiRad - Radio button ui element
• uiKb3x10B - Soft / touch keyboard / keypad
• uiEBC - extension for hardware push button controlled ui
  (in addition to available touch screen or on absence thereof,
  such as Pixle.js or any other board w/ display with no touch)

--- Brief documentation of the methods / functions available

For your application .g(iie) and .u(iie,p) are most relevant:

• .g(iie) lets your application retrieve a ui entered value and apply it
• .u(iie,p) lets our application set and display a sensor driven value,
  for example, analog input (voltage) value in a ui-read/only slider or
  digital (pin state) input (0/1/truey/falsy) value in a ui-r/0 checkbox.

Full list in alphabetic order:

• .cb(iie) and .cb(iie,cb,ca) - getter and setter of callback; getter is
  with both cb and ca being undefined by value or absence of value.
• .e(iie) - return ui element by idx, id or elt. If by id and not found,
  undefined is returned.
• .ff(a,f,s,_) - find and return first element in array a starting
  with start index s (if absent, s=0 assumed) that makes function
  f(element, _auxiliaryVar) return truey; if not found,
  return undefined . Argument _ (_auxiliaryVar) is also
  passed to the function and can be any value the application needs. If
  application has no use for it, it is just left away in the call and
  function.
• .fx(a,f,s,_) - find and return index of first element in array a
  that makes function f(element) return truey; if not found,
  return -1. Argument _ (_auxiliaryVar) is also
  passed to the function and can be any value the application needs. If
  application has no use for it, it is just left away in the call and
  function.
• .g(iie) - get element value (obj) - runtime e[9] - by idx, id or elt.
• .t(iie,ud) - tap on ui element by idx or id or ui element. If element is
  found, x and y coordinates of center are passed to ui and processing
  happens as if the element would be touched on a touch screen and then
  un-touched - with the default or overwritten untouch delay .ud.
  Providing proper un-touch delays yields full control over touch-time
  sensitive ui elements, such as key board keys, where, for example,
  long touch of keys with numbers in uiKbc3x10B module will return
  the number character instead of the alpha character.
• .u(iie,p) - update value object by element idx or id with or without
  propagation (calling callback). Be aware how the value (object) is
  defined creation of the ui element.

--- ext - ui extension properties - variables and methods - mixed into ui base

exports = // ui (generic) ext(ension/utils: vertices(circle,...) find elt/idx in arr,...)
{ mn: "uiExt" // module 'clazz' name - globally unique (used to remove code from cache)
, ud: 100 // default tap duration defined as u-ntouch d-elay / timeout
, cg1: [2,-5,4,-4,5,-2,6,0,5,2,4,4,2,5,0,6,-2,5,-4,4,-5,2,-6,0,-5,-2,-4,-4,-2,-5]
// ...
// ... public methods - as documented above
// ... private methods
// ...
}

Attached shot: shows the browser developer / debug view with the browser console log, to which the ui framework is logging to by injected functions.

Attachments:

• uiXDEdebugExample.png

[espruino-discuss3]

Posted at 2019-09-20 by @allObjects

----- uiRad ------------------------- 201909227

*** ui radio button module

The ui radio button module extends ui base with radio button ui element.

Note: It requires the uiExt - ui extension module - to be loaded first.

--- Enable ui base with uiRad element functions:

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

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

--- Create - specify - radio buttons

// flgs clazz  id      x  y  w s b f value callback on 'untouch'
ui.c( 3,"rad","r1.a",  5,80,37,0,6,2,"L",  cb, [12,7,5,10,"Large"]);
ui.c( 3,"rad","r1.b", 95,85,27,1,3,1,"M",  0 , [12,7,5, 7,"Med"  ]);
ui.c( 3,"rad","r1.c",170,90,17,1,5,2,"S",  0 , [12,7,5, 2,"Small"]);
//                                             fv t x  y label text

Crates and add to ui three active(2), visible(1) =(3) radio buttons at
x/y (left/top: 5/80, 95/85 and 170/90) of different sizes/widths/diameters
(37, 27 and 17) with size related values ("L", "M" and "S") and labels
("Large", "Medium" and "Small"), with group name "r1." (dot is part of
group name). Medium sized radio button is set/checked (first set/checked
radio button wins... therefore small one is not set/checked even though
specified as such). Border colors (6, 3 and 5) and fill colors (2,1 and 2)
are all different (by choice). Unset/unchecked radiobuttons show ui
display background color (ui.bc). Label array definitions include
fontVector (size), font color, x/y offset from right/top (x2/y) corner of
touch sensitive bounding box, and text.

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

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

args[] sym   description 
  0    id  : button id ("r1.a")
  1    v   : value object ("L"|"M"|"S" - can be any object)
             NOTE: is undefined when check box is unchecked
  2    ui  : ui (THE ui object)
  3    e   : uiRad element (rad 'object' (runtime data structure) just untouched)
  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.

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

arg runtime 'object' instance of 'clazz' chk (chkbox)
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] i  - id - eg "r01.a","r01.b","r01.c",.. short, at least 2 or 3
              chars for radio button group id, and globally unique.
              Single letter ui element ids are 'reserved' (for keyboard(s)).
              Radio button id consist of two elements:
                - Radio button group id - the part *before* the dot.
                - Radio button individual id - the part *after* the dot.
              Radio button group id is used to make the buttons in the
              group behave like radio buttons: any 'pressed' button
              'releases' all others, or in other words, only one radio
              button can be 'pressed' - or on - at one time.
 3   [3] x  - x ((left ) of focus / touch bounding box)
 4   [4] y  - y ((top  ) of focus / touch bounding box)
 5       w  - width and hight (of focus / touch box,... 
     [5] x2 - x ((right) of focus / touch bounding box: x - w + 1)
 6       s  - initial checked(truey/1)/unchecked(falsey/0) state
              used w/ [9] value info; note that only one radio
              button can be set / checked / on at one time
     [6] y2 - y ((bot  ) of focus / touch bounding box: y - h + 1)
 7   [7] bc - border color
 8   [8] fc - fill color
 9       v  - value (returned value when checked)
     [9] vi - value info array w/ state and value object
         [0] - truey / falsey indicating state checked/unchecked
         [1] - value object (returned when radio button is checked)
10       cb - simple, preferred callback on untouch after touchdown;
    [10] g  - radio button group management array object
         [0] - radio button group id, eg. "r1." (incl. dot)
         [1] - preferred callback (1st encountered truey cb) 
         [2] - alternate callback (1st encountered truey ca)
         [3] - checked radio button ui element (or null / falsey)
         [4...] - group radio button ui elements
              Note that first encountered truey callback - cb or ca wins
              and cb wins over ca. Therefore only one needs to be
              specified per group cb over ca priority. The others can be
              left undefined, they are ignored anyway.
11  [11] l  - label (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]  tx - label text to display (using .drawString())
12  [12] ca - NON-preferred, experimental callback on any touch event

Attached shot: Tabbed thru uiRad - radio buttons.

Attachments:

• uiRadExample.png

[espruino-discuss3]

Posted at 2019-09-20 by @allObjects

----- 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'.

Attachments:

• uiSliExample.png

[espruino-discuss3]

Posted at 2019-09-20 by @allObjects

----- 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.

Attachments:

• uiInpAndkeyBoardExample.png

[espruino-discuss3]

Posted at 2019-09-20 by @allObjects

----- 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
// ...
}

[espruino-discuss3]

Posted at 2019-09-20 by @allObjects

ui varia 3 - tbp

[espruino-discuss3]

Posted at 2019-09-25 by @allObjects

----- 2019-09-24 Update -----

Finally some rework and review round trip completed to share things that had its design in 2015, some rework in 2016 and 2017 and just now.

Updated zip file is to be found in --->post #7 .

Reviewing and getting code and some doc ready for pub did not go without some enhancements and adding a few vars to the foot print.

Event categorization with flags and handling got a significant lift to give more control to the user and application. Also the slider got a technical as well as a face lift. Some issues got resolved, such as ui elements changing unintended their values by just dragging over them.

Input field is still a bit bare bones and kept as such... last but not least because of slowness of (communication to) most displays. Have to come up w/ some enhanced version... being a different ui element 'clazz' though to keep the simple version with small foot print.

The general idea of publishing in this conversation is to get it out and get feedback. Over time these posts will change including the zip file uploaded in post #8 with all the code - modules, examples and cross development components (on functional changes). Old versions will be kept there as long as possible.

After a while things will move into regular site's modules folder and into module and tutorial pages.

Cu after reading up from ---> post #7 on.

[espruino-discuss3]

Posted at 2019-09-28 by @allObjects

----- 2019-09-27 Update -----

As new extension module has been added: support for control with watched push buttons rather than with touch screen - see ---> post #17 . Same time, the keyboard, the input fields and the uiExt extension got some enhancements, last but not least to support watched buttons to drive the ui. So far all but the sliders can be used - with three (3) buttons it is very comfortable: two (2) buttons to cycle forward and backward thru he ui elements and the third - 'Enter' / Tap - button is for tapping. Timing the tapping - how long the push button has been pressed and passing it when calling the tap selected ui element - .ts(...) - gives access to also the timed functions:

• short tap / touch / press the button: < 140 ms
• medium tap / touch / press the button: 140..450 ms
• long tap / touch / press the button: >450 ms

The input field has a callback that checks tap time, and when it is more than 550 ms, the input field is cleared. The delete x in the top right corner of the input field is part of the ui element and not one of its own, so it cannot be reached with cycling through the ui elements. Having separate buttons for navigation / 'moving' the selection and the action tapping makes operation safe. Increasing the time for clearing the input field to make it distinctive from cycling backwards with a long press.

Other, non-functional changes is the renaming of the example: replacing the DspTouch infix in the names with just Example provides room the examples to also include button operation vs touch operation. Both can be used simultaneously... (with one caveat: touchscreen tapping does not preserve the visual cue what ui element is selected at times.

Updated zip file is to be found in --->post #7 .

[espruino-discuss3]

Posted at 2019-09-28 by Robin

Sat 2019.09.28

What a fantastic contribution @allObjects

I'm sure you are proud of the final result, now with the finish line in sight!!

Had a hunch there would be a fair amount of updating content when I recognized the dozen of link earmarked entries a week ago.

Although I won't have immediate time to delve into your accomplishment right now, will set aside some time this winter.

Well done. Congrats!
Robin

EDIT: (ten minutes later)
Curiosity got the better of me:

Love the immediate run/launch with the Html pages. Just tried the button press uiExample.html and it works without configuration in Chrome on Windows10, just launch and go. Simple, intuitive, impressive. BRAVO!

[espruino-discuss3]

Posted at 2019-10-01 by @allObjects

----- 2019-09-30 Update -----

Espruino Pixl makes its debut the ui framework... see the Preview in ---> post #18.

From #post 18, download, unzip the attached zip file with the _sbx Sandbox folder, make Espruino Web IDE point to this sandbox folder and load the uiExamplePixl.js project file.

[espruino-discuss3]

Posted at 2019-11-27 by @allObjects

New update - with work in progress - that includes Emulations for Pixle.js and even Bangle.js... some work is still going on, especially for handling the non-touch and limited touch screens. Navigation from element to element in the ui works, 'clicking' on (regular) buttons, checkboxes and radio buttons work. Clicking on horizontal and vertical slider are setting their values so far - matter fact of touch emulation in the center - to the middle value. More to come there. Since all is JavaScript you can write code to practically emulate what ever you think of... You would just not emulate on the very low level hardware, but on the module level, add value input fileds and buttons to the html view to bring the module to life and let your application handle it properly in the emulation. This way even coding and emulating of time sensitive / ui dynamic applications are possible. The code already includes Pins and Buttons - specified in the board includes - and setWatch/clearWatch for buttons in the emulator HTML view. If you miss a behavior or item, just extend existing item or add a new one.

Updated zip file is to be found in --->post #7 .

Attachments:

• uiLCDTFTXDev2.jpg
  
• uiSlidersTFF.png
  
• bangle_emulationFirstShot.png

[espruino-discuss3]

Posted at 2019-11-27 by @MaBecker

Have you tried your UI with the Bangle Emulator?

[espruino-discuss3]

Posted at 2019-11-27 by @allObjects

Yes I did and I like it very much... I know that - for some - an emulator may take a bit the push away to get a real board... on the other hand it makes development of logic so much easier, especially since the upload over BLE 'snails'.

[espruino-discuss3]

Posted at 2025-01-19 by @MaBecker

@allObjects

[ ] How to use firmware included touch screens with ui?

Bangle2 Emulator

>Bangle.on('touch', function(zone,e) {print(zone,e);})
=undefined
1 { "x": 33, "y": 36, "type": 0 }
2 { "x": 121, "y": 36, "type": 0 }
... 

ESP32 CYD

E.on('touch',(e)=>{print(e);});
=undefined
// b = 1 : touch, b = 0 : released
{ "x": 197, "y": 116, "b": 1 }
{ "x": 197, "y": 116, "b": 0 }
...

[ ] How to use build in fonts with ui?

// Bangle2 Emulator
>g.getFonts()
=[
  "4x6",
  "6x8",
  "12x20",
  "6x15",
  "Vector"
 ]
> 

// ESP32 CYD
>g.getFonts()
=[
  "4x6",
  "6x8",
  "Vector"
 ]

check for setFontXXXXX functions show that setFont6x8 is missing because it is different included than 6x15.

g.setF
setFont             setFont12x20
setFont6x15         setFontAlign
setFontBitmap       setFontCustom
setFontPBF          setFontVector

Solution: Including "6x8" directly into the ui.fnts array and make sure it can set via g.setFont6x8

// add included Font
ui.fnts.push('setFont6x8');
g.setFont6x8 = function(){g.setFont("6x8");};

[ ] Any plans to include uiG(auge) as module?

[espruino-discuss3]

Posted at 2025-01-19 by @allObjects

@MaBecker,

looks like that these are you questions:

a. [ ] How to use firmware included touch screens with ui?
b. [ ] How to use built-in fonts with ui?
c. [ ] Any plans to include uiG(auge) as module?

Generally speaking: starting out with a (custom named and referenced) wrapper that is housing the built-in things - touch / font - is good to start with. The reason for that is that when the UI was built, bangles weren't around yet... But it should then be easy to modify the code to drop the wrapper and use the built-in appliances directly. All is pulled in as modules, so changes can happen gradually.

Since displays have quite some variations, take a look at how colors and fonts are referenced in the ui definition and how the respective support mapes it into the hw context. Modules are also pulled by name dynamically, so control can happen in a single place w/ a config-like object, which then can be made dependent on the context / hw ID.

ttyl.

ao

[espruino-discuss3]

Posted at 2025-01-19 by @MaBecker

Yes and have one more for now.

d. [ ] Can ui switch to Anti-Aliasing functions if available?

[espruino-discuss3]

Posted at 2025-01-19 by @allObjects

It could affect some functionality if the font goes too close to the borders. I show a frame around an active field to show focus and clear it w/ the redrawing the same frame with back ground color. When anti-aliasing goes 'too close' to such frame, you may notice interferences.

In the context where and for what the UI was done, memory is on short supply... so no layering... layering would have been the answer to many things.

[espruino-discuss3]

Posted at 2025-01-19 by @allObjects

Since the UI framework was conceived, a lot has changed in Espruino world. The most impacting change is that Bangle2 has a built in touch screen and firmware functions way superior to the touch modules ever existed.

Basic touch modules deliver two (2) types of events:

1. touch w/ x and y populated in the callback (as 1st touch down event and subsequent events on dragging
2. untouch w/ x and y *** NOT *** populated in the callback (undefined)

That is the reason that the ui.evt(x,y) is passed no information wether it is a touch or untouch, because an even with x or/and y being undefined provides the touch or untouch distinction. Since the untouch has no coordinates, the ui module kept track of what the last x and y was.

Rewriting of ui.evt(x,y) is an option, but before going there, using event Bangle.drag logically by emulating the simple touch with x, y and untouch without x, y will do the job, and lets ui module keep the handling of x and y on untouch...

Two (2) sections the introductory page at espruino.com/ui - UI Framework for microcontrollers are affected:

1. Devices - is to be skipped, since for Bangle2 all is there already.
2. Define the onInit() function - looks much simpler:

function onInit() {
  // connect ui to dsp and display it
  ui.connect(g)
    .w(0,0,176-1,176-1) // wipe screen (rect) w/ default / bg color
    .d()                // display all elements
    .di = true;         // set display changes to immediate
  // connect touch sreen to ui
  Bangle.on("drag",(t)=>{ if (t.b) ui.evt(t.x,t.y); else ui.evt(); }); 
} // /onInit()

Take a look at the complete code - same example as documented at [https://www.espruino.com/uiExampleBtn](UI Example - Buttons):

// ----- setup lon and log() (considering emulating _eConsole)
var lon = true // logging is on / off
  , log = function() { if (lon) { var lgr;(lgr=(typeof _eConsole
       =="object")?_eConsole:console).log.apply(lgr,arguments);}};

// ----- pull in ui base and ui element(s)
var ui = require("ui")
    .adx(require("uiExt")) // only when push button control is required / no touch
    .adx(require("uiEBC")) // only when push button control is required / no touch
    .adx(require("uiBtn")) // ui plain button element
    .adx(require("Font8x16"),-2,"Font8x16") // fs: -1 - custom bitmap font
    ;

// ----- define callback(s): preferred (untouch) / generic (all) touch event(s)
var cb = function(id, v, _, e, t) { log( "id:",id,"val:",v
        ,(t)?((t.t)?"":"un")+"touch focused":t); }
  , ca = ( (typeof ca === "undefined")
         ? function(id, v, _, e, t) { var s=(t.f|65536).toString(2); // log flags
             log("c:",e[1],"c:",e[1],"id:",id,"v:",v,"f:",[s.substr(5,4),s.substr(9,4),s.substr(13,4)].join(" "),t.f); }
         : ca )
  , u; // for space / memory / var saving value of * undefined *

// ----- define UI (in level 0 - built to be saved)

//---------- Button examples ----------
//
//    0  1     2       3   4   5   6   7   8  9       10  11                         12
// flgs  clazz id      x   y   w   h  bc  fc  valObj  cb,  l (label array obj)
//       btn                ->x2->y2                        fs tc    x  y label txt  ca
ui.c( 3,"btn","b1"  ,  5, 40, 65, 35,  4,  4, "B_1",  cb,  [15, 7,  19,12, "RED"  ]);
ui.c( 3,"btn","b2"  , 70, 40, 65, 35,  5,  6, {v:1},  u ,  [-1, 0,  10,10, "BonYbg"],ca);

// ----- run UI
function onInit() {
  // connect ui to dsp and display it
  ui.connect(g)
    .w(0,0,176-1,176-1) // wipe screen (rect) w/ default / bg color
    .d()                // display all elements
    .di = true;         // set display changes to immediate
  // connect touch sreen to ui
  Bangle.on("drag",(t)=>{ if (t.b) ui.evt(t.x,t.y); else ui.evt(); }); 
} // /onInit()

setTimeout(onInit,999); // for dev only, remove before upload for save()

Since dealing with (vector) fonts is always a bit a lottery, the position of the RED button label needed some adjustment.... Interestingly, the label in the second button did just fine...

@MaBecker pointed out that there are some other things that need minor changes... one is related to how (default) fonts are loaded and set in current Espruino Graphics object. More about that from @gfwilliams or me, later on.

As a closing icing on the cake, I'd like to introduce - re-introduced - a more elaborate callback for the RED button:

1. RED Button turns (emulated) red LED on and off - see attached screenshot!
2. RED Button shows in label what pressing the button will do: turn the LED off or on.

1st change:

...
var redLED = false // defines the red LED1 (initial) state
  , cb = function(id, v, _, e, t) { digitalWrite(LED1, redLED = !redLED); } // toggles the red LED1
...

2nd change:

...
var redLED = false
  , cb = function(id, v, _, e, t) {
             digitalWrite(LED1, redLED = !redLED);
             e[11][4] = "RED " + (redLED) ? "off" : "on"; // Set (just) the label text
             // e is the ui element, [11]th property is label, and [4]th is the text
             console.log(e); // dump ui element e in console to show its state
             return true; // make the button to be redrawn
         }
...

The 2nd change needs also some layout changes because of the longer button label text (widening the RED button by 5 px (w+5) to 70 and moving the 2nd button 5 pixel (x+5) to the right to 70):

//---------- Button examples ----------
//
//    0  1     2       3   4   5   6   7   8  9       10  11                         12
// flgs  clazz id      x   y   w   h  bc  fc  valObj  cb,  l (label array obj)
//       btn                ->x2->y2                        fs tc    x  y label txt  ca
ui.c( 3,"btn","b1"  ,  5, 40, 70, 35,  4,  4, "B_1",  cb,  [15, 7,   8,11, "RED on"]);
ui.c( 3,"btn","b2"  , 75, 40, 65, 35,  5,  6, {v:1},  u ,  [-1, 0,  10,10, "BonYbg"],ca);

Running the second change (after all those years) became a surprise:

Unfortunately, something has changed in the Espruino js interpreter when it comes to address an array literally with a 0 as the console points out:

[ 7,
  "btn",
  "b1",
  5, 40, 74, 74, 4, 4,
  "B_1",
  function (id,v,_,e,t) {
  digitalWrite(LED1, redLED = !redLED);
             e[11][4] = "RED " + ((redLED) ? "off" : "on"); // Set (just) the label text
             // e is the ui element, [11]th property is label, and [4]th is the text
             console.log(e);
             return true;
},
  [ 15, 7, 8, 11,
    "off"
   ],
  undefined ]
Uncaught Error: Field or method "0" does not already exist, and can't create it on Number
 at line 1 col 7
if(e[0]&1)_[e[1]+"D"].apply(_,e)
      ^
in function called from line 1 col 84
...1)_[e[1]+"D"].apply(_,e)},_);if(f)f(_,e);return _
                              ^
in function "d" called from line 1 col 54
if(c=c&&(c=e[10])?c:e[12])if(c(e[2],e[9],_,e,t))_.d(e)
                                                     ^
in function "btn" called from line 2 col 422
...t.f|=16;if(!_[e[1]](_,e,t,1))_.blr(e)}[_.lf,o=_.af].forEach(...
                              ^
in function "evt" called from line 1 col 39
if (t.b) ui.evt(t.x,t.y); else ui.evt();
                                      ^
in function called from system
> 

Something weird... because when duping the element in the console, it shows value 7 - 4 flags set - in its array (state members of the ui element)... even when dumping it after the error happened...

Weird, because when accessing the value in console's REPL, it can do so:

=[ 7,
  "btn",
  "b1",
  5, 40, 74, 74, 4, 4,
  "B_1",
  function (id,v,_,e,t) { ... },
  [ 15, 7, 8, 11,
    "off"
   ],
  undefined ]
>ui.es[0][0] // accessing 1st property of 1st ui element (directly)
=7
>var e = ui.es[0]; // ...indirectly... via variable...
=[ 7,
  "btn",
  "b1",
  5, 40, 74, 74, 4, 4,
  "B_1",
  function (id,v,_,e,t) { ... },
  [ 15, 7, 8, 11,
    "off"
   ],>ui.es[0]
=[ 7,
  "btn",
  "b1",
  5, 40, 74, 74, 4, 4,
  "B_1",
  function (id,v,_,e,t) { ... },
  [ 15, 7, 8, 11,
    "off"
   ],
  undefined ]
>ui.es[0][0]
=7
>var e = ui.es[0];
=[ 7,
  "btn",
  "b1",
  5, 40, 74, 74, 4, 4,
  "B_1",
  function (id,v,_,e,t) { ... },
  [ 15, 7, 8, 11,
    "off"
   ],
  undefined ]
>e[0]
=7  undefined ]
>e[0] // ...accessing via variable...
=7

Looking at the ui.js module code - .d(e,f){...} display function - it shows the following construct:

, d: function(e,f) { // display / redraw ui element e, redraw all if e falsy,
                     // and if f, call f w/ ui,e f for extra 'drawings' or action
    var _=_||this
         , es = (e) // if ui element e is passed, build array w/ e as its only item
              ? [e]
              : _.es.slice(_.b,_.n);
    es.forEach(function(e){ // iterate over array - all ui elements in the array
      if (e[0]&1) // if visible flag is set...   <<<<<===== interpreter issue???
           _[e[1]+"D"].apply(_,e); // ... call element's Display method
    });
    if (f) f(_,e); // do the extra things...
    return _;
  }

From looking at the code and its syntax, the error message makes no sense what so ever... The literal integer number 0 should be recognized by the interpreter as such and used as the index... and not as a not defined variable / symbol...

(Yes, the construct re-uses the variable e in the iterators function as local parameter... but it has its own scope... does it?)

---

Attachments:

• uiButtonsInBangle2.png

[espruino-discuss3]

Posted at 2025-01-20 by @allObjects

...ooops, I was wrong to conclude from the error that the interpreter has an issue... I looked at the source code I had and did not notice that the ui module version in espruino.com/modules - where you get it with require, has a bug in the display method (`,d: function(...){}).

There several 2 ways to fix this until module is fixed.

a) you can download a version from forum as documented there () and load the modules from y9ou local modules folder...

b) you load the broken module, and then override .d(){} method afterwards as follows:

.....
var ui = require("ui"....
.....
.....
.....
   ;
.....

ui.d = function(e,f){var _=_||this,es=(e)?[e]:_.es;es.forEach(function(e){if(e[0]&1)_[e[1]+"D"].apply(_,e)},_);if(f)f(_,e);return _}
.....

Above fix works for both minified and non minified version...

[espruino-discuss3]

Posted at 2025-01-20 by @allObjects

Notice the change in the callback for the 2nd enhancement to set the label of the button depending the state of the RED LED1:

     e[11][4] =  "RED " + ((redLED) ? "off" : "on");

Without the parenthesis around the ternary operator statement, it fails.