[dep-ui] / dep-ui.js

/* -*-javascript-*-
 *
 * Dependency-based user interface in a web page.
 *
 * (c) 2013 Mark Wooding
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Library General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, see <http://www.gnu.org/licenses/>.
 */

var DEP_UI = {}; (function () {

/*----- Utility functions and classes -------------------------------------*/

function debug(msg) {
  /* Write the string MSG to the `trace' element, if there is one. */

  var e = elt('trace');
  if (e !== null) e.textContent += msg;
}
DEP_UI.debug = debug;

function trap(what, func) {
  try {
    func();
  } catch (e) {
    debug('caught exception in ' + what + ': ' + e);
    throw e;
  }
}
DEP_UI.trap = trap;

function elt(id) {
  /* Find and return the element with the given ID. */
  return document.getElementById(id);
}
DEP_UI.elt = elt;

function add_elt_class(elt, cls) {
  /* Add the class name CLS to element ELT's `class' attribute. */

  if (!elt.className.match('\\b' + cls + '\\b'))
    elt.className += ' ' + cls
}
DEP_UI.add_elt_class = add_elt_class;

function rm_elt_class(elt, cls) {
  /* Remove the class name CLS from element ELT's `class' attribute. */

  elt.className = elt.className.replace(
    new RegExp ('\\s*\\b' + cls + '\\b\\s*'), ' ');
}
DEP_UI.rm_elt_class = rm_elt_class;

/* A gadget which can arrange to perform an idempotent action (the FUNC
 * argument) again `soon'.
 */
function Soon(func) {
  this.timer = null;
  this.func = func;
}
Soon.prototype = {
  kick: function () {
    /* Make sure the function is called again soon.  If we've already been
     * kicked, then put off the action for a bit more (in case things need
     * time to settle).
     */

    var me = this;
    if (this.timer !== null) clearTimeout(this.timer);
    this.timer = setTimeout(function () { me.func(); }, 50);
  }
};
DEP.Soon = Soon;

/*----- Conversion machinery ----------------------------------------------*/

/* An exception, thrown if a conversion function doesn't like what it
 * sees.
 */
BadValue = new DEP.Tag('BadValue'); DEP.BadValue = BadValue;

function convert_to_numeric(string) {
  /* Convert the argument STRING to a number. */

  if (!string.match('\\S')) throw BadValue;
  var n = Number(string);
  if (n !== n) throw BadValue;
  return n;
}
DEP_UI.convert_to_numeric = convert_to_numeric;

function convert_from_numeric(num) {
  /* Convert the argument number NUM to a string, in a useful way. */
  return num.toFixed(3);
}
DEP_UI.convert_from_numeric = convert_from_numeric;

/*----- User interface functions ------------------------------------------*/

/* A list of input fields which might need periodic kicking. */
var KICK_INPUT_FIELDS = [];

function input_field(id, dep, convert) {
  /* Bind an input field (with the given ID) to a DEP, converting the user's
   * input with the CONVERT function.
   */

  var e = elt(id);

  function kick() {
    /* Update the dep from the element content.  If the convert function
     * doesn't like the input then mark the dep as bad and highlight the
     * input element.
     */

    var val, err;

    try {
      val = convert(e.value);
      if (!dep.goodp())
        rm_elt_class(e, 'bad');
      dep.set_value(val);
    } catch (err) {
      if (err !== BadValue) throw err;
      dep.make_bad();
      add_elt_class(e, 'bad');
    }
  }

  // Name the dep after our id.
  dep.name = id;

  // Arrange to update the dep `shortly after' updates.
  var soon = new Soon(kick);
  function kick_soon() { soon.kick(); }
  e.addEventListener('click', kick_soon, false);
  e.addEventListener('blur', kick_soon, false);
  e.addEventListener('keypress', kick_soon, false);

  // Sadly, the collection of events above isn't comprehensive, because we
  // don't actually get told about edits as a result of clipboard operations,
  // or even (sometimes) deletes, so add our `kick' function to a list of
  // such functions to be run periodically just in case.
  KICK_INPUT_FIELDS.push(kick);
}
DEP_UI.input_field = input_field;

function input_radio(id, dep) {
  /* Bind a radio button (with the given ID) to a DEP.  When the user frobs
   * the button, set the dep to the element's `value' attribute.
   */

  var e = elt(id);

  function kick() {
    // Make sure we're actually chosen.  We get called periodically
    // regardless of user input.
    if (e.checked) dep.set_value(e.value);
  };

  // Name the dep after our id.
  dep.name = id;

  // Arrange to update the dep `shortly after' updates.
  var soon = new Soon(kick);
  function kick_soon() { soon.kick(); }
  e.addEventListener('click', kick_soon, false);
  e.addEventListener('changed', kick_soon, false);

  // The situation for radio buttons doesn't seem as bad as for text widgets,
  // but let's be on the safe side.
  KICK_INPUT_FIELDS.push(kick);
}
DEP_UI.input_radio = input_radio;

function output_field(id, dep, convert) {
  /* Bind a DEP to an output element (given by ID), converting the dep's
   * value using the CONVERT function.
   */

  var e = elt(id);

  function kicked() {
    /* Update the element, highlighting it if the dep is bad. */
    if (dep.goodp()) {
      rm_elt_class(e, 'bad');
      e.value = convert(dep.value());
    } else {
      add_elt_class(e, 'bad');
      e.value = '';
    }
  }

  // Name the dep after our id.
  dep.name = id;

  // Keep track of the dep's value.
  dep.add_listener(kicked);
  kicked();
}
DEP_UI.output_field = output_field;

/*----- Periodic maintenance ----------------------------------------------*/

function kick_all() {
  /* Kick all of the input fields we know about.  Their `kick' functions are
   * all on the list `KICK_INPUT_FIELDS'.
   */
  DEP.dolist(KICK_INPUT_FIELDS, function (func) { func(); });
}

// Update the input fields relatively frequently.
setInterval(kick_all, 500);

// And make sure we get everything started when the page is fully loaded.
window.addEventListener('load', kick_all, false);

/*----- That's all, folks -------------------------------------------------*/
})();