BangleApps/modules/Slider.md

Slider Library

Take a look at README.md for hints on developing with this library.

Usage

var Slider = require("Slider");
var slider =  Slider(callbackFunction, configObject);

Bangle.on("drag", slider.f.dragSlider);

// If the slider should take precedent over other drag handlers use (fw2v18 and up):
// Bangle.prependListener("drag", slider.f.dragSlider);

callbackFunction (cb) (first argument) determines what slider is used for. slider will pass two arguments, mode and feedback (fb), into callbackFunction (if slider is interactive or auto progressing). The different mode/feedback combinations to expect are:

• "map", o.v.level | current level when interacting by mapping interface.
• "incr", incr | where incr == +/-1, when interacting by incrementing interface.
• "remove", o.v.level | last level when the slider times out.
• "auto", o.v.level | when auto progressing.

configObject (conf) (second argument, optional) has the following defaults:

R = Bangle.appRect; // For use when determining defaults below.

{
initLevel:       0,                     // The level to initialize the slider with.
horizontal:      false,                 // Slider should be horizontal?
xStart:          R.x2-R.w/4-4,          // Leftmost x-coordinate. (Uppermost y-coordinate if horizontal)
width:           R.w/4,                 // Width of the slider. (Height if horizontal)
yStart:          R.y+4,                 // Uppermost y-coordinate. (Rightmost x-coordinate if horizontal)
height:          R.h-10,                // Height of the slider. (Width if horizontal)
steps:           30,                    // Number of discrete steps of the slider.

dragableSlider:  true,                  // Should supply the sliders standard interaction mechanisms?
dragRect:        R,                     // Accept input within this rectangle.
mode:            "incr",                // What mode of draging to use: "map", "incr" or "mapincr".
oversizeR:       0,                     // Determines if the mapping area should be extend outside the indicator (Right/Up).
oversizeL:       0,                     // Determines if the mapping area should be extend outside the indicator (Left/Down).
propagateDrag:   false,                 // Pass the drag event on down the handler chain?
timeout:         1,                     // Seconds until the slider times out.

drawableSlider:  true,                  // Should supply the sliders standard drawing mechanism?
colorFG:         g.theme.fg2,           // Foreground color.
colorBG:         g.theme.bg2,           // Background color.
rounded:         true,                  // Slider should have rounded corners?
outerBorderSize: Math.round(2*R.w/176), // The size of the visual border. Scaled in relation to Bangle.js 2 screen width/typical app rectangle widths.
innerBorderSize: Math.round(2*R.w/176), // The distance between visual border and the slider.

autoProgress:    false,                 // The slider should be able to progress automatically?
}

A slider initiated in the Web IDE terminal window reveals its internals to a degree:

>slider = require("Slider").create(()=>{}, {autoProgress:true})
={
  v: { level: 0, ebLast: 0, dy: 0 },
  f: {
    wasOnDragRect: function (exFirst,eyFirst) { ... },
    wasOnIndicator: function (exFirst) { ... },
    dragSlider: function (e) { ... },
    remove: function () { ... },
    updateBar: function (levelHeight) { ... },
    draw: function (level) { ... },
    autoUpdate: function () { ... },
    initAutoValues: function () { ... },
    startAutoUpdate: function () { ... },
    stopAutoUpdate: function () { ... }
   },
  c: { initLevel: 0, horizontal: false, xStart: 127, width: 44,
    yStart: 4, height: 166, steps: 30, dragableSlider: true,
    dragRect: { x: 0, y: 0, w: 176, h: 176,
      x2: 175, y2: 175 },
    mode: "incr",
    oversizeR: 0, oversizeL: 0, propagateDrag: false, timeout: 1, drawableSlider: true,
    colorFG: 63488, colorBG: 8, rounded: 22, outerBorderSize: 2, innerBorderSize: 2,
    autoProgress: true, _rounded: 18, _xStart: 131, _width: 36, _yStart: 8,
    _height: 158, STEP_SIZE: 4.06666666666,
    r: { x: 127, y: 4, x2: 171, y2: 170,
      w: 44, h: 166 },
    borderRect: { x: 127, y: 4, w: 44, h: 166,
      r: 22 },
    hollowRect: { x: 129, y: 6, w: 40, h: 162,
      r: 22 }
   }
 }
>

Tips

You can implement custom graphics for a slider in the callbackFunction. The slider test app mentioned in the links below do this. To draw on top of the included slider graphics you need to wrap the drawing code in a timeout somewhat like so: setTimeout(drawingFunction,0,fb) (see setTimeout documentation).

Links

There is a slider test app on thyttan's personal app loader (at time of writing). Looking at its code is a good way to see how the slider is used in app development.

The version of Remote for Spotify on thyttan's personal app loader (at time of writing) also utilizes the Slider module. Here is the code.