dep-ui.js: Add some debugging machinery.

[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 () { with (DEP_UI) {

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

DEP_UI.debug = function(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.trap = function(what, func) {
  try {
    func();
  } catch (e) {
    debug('caught exception in ' + what + ': ' + e);
    throw e;
  }
}

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

DEP_UI.add_elt_class = function (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.rm_elt_class = function (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*'), ' ');
}

/* A gadget which can arrange to perform an idempotent action (the FUNC
 * argument) again `soon'.
 */
DEP_UI.Soon = function (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);
  }
};

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

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

DEP_UI.convert_to_numeric = function (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_from_numeric = function (num) {
  /* Convert the argument number NUM to a string, in a useful way. */
  return num.toFixed(3);
}

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

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

DEP_UI.input_field = function (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);
  e.addEventListener('blur', kick_soon);
  e.addEventListener('keypress', kick_soon);

  // 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_radio = function (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);
  e.addEventListener('changed', kick_soon);

  // 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.output_field = function (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();
}

/*----- 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);

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