DOMUtils.jsm

Go to the documentation of this file.

/* -*- Mode: Java; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set sw=2 :miv */
/*
 *=BEGIN SONGBIRD GPL
 *
 * This file is part of the Songbird web player.
 *
 * Copyright(c) 2005-2010 POTI, Inc.
 * http://www.songbirdnest.com
 *
 * This file may be licensed under the terms of of the
 * GNU General Public License Version 2 (the ``GPL'').
 *
 * Software distributed under the License is distributed
 * on an ``AS IS'' basis, WITHOUT WARRANTY OF ANY KIND, either
 * express or implied. See the GPL for the specific language
 * governing rights and limitations.
 *
 * You should have received a copy of the GPL along with this
 * program. If not, go to http://www.gnu.org/licenses/gpl.html
 * or write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 *
 *=END SONGBIRD GPL
 */

//------------------------------------------------------------------------------
//
// DOM utility JSM configuration.
//
//------------------------------------------------------------------------------

EXPORTED_SYMBOLS = [ "DOMUtils",
                     "sbDOMHighlighter",
                     "DOMEventListenerSet",
                     "sbColorUtils" ];


//------------------------------------------------------------------------------
//
// DOM utility defs.
//
//------------------------------------------------------------------------------

const Cc = Components.classes;
const Ci = Components.interfaces;
const Cr = Components.results
const Cu = Components.utils


//------------------------------------------------------------------------------
//
// DOM utility services.
//
//------------------------------------------------------------------------------

var DOMUtils = {
  //----------------------------------------------------------------------------
  //
  // DOM utility services.
  //
  //----------------------------------------------------------------------------

  loadDocument: function DOMUtils_loadDocument(aDocumentURI) {
    // Open the document.
    var ioSvc = Cc["@mozilla.org/network/io-service;1"]
                  .getService(Ci.nsIIOService);
    var channel = ioSvc.newChannel(aDocumentURI, null, null);
    var inputStream = channel.open();

    // Load and return the document.
    var domParser = Cc["@mozilla.org/xmlextras/domparser;1"]
                      .createInstance(Ci.nsIDOMParser);
    return domParser.parseFromStream(inputStream,
                                     null,
                                     channel.contentLength,
                                     "text/xml");
  },


  importChildElements: function DOMUtils_importChildElements(aDstNode,
                                                             aSrcDocument,
                                                             aSrcParentID,
                                                             aChildAttrList) {
    // Get the destination document and the list of source children.
    var dstDoc = aDstNode.ownerDocument;
    var srcChildList = aSrcDocument.getElementById(aSrcParentID).childNodes;

    // Import the source elements.
    for (var i = 0; i < srcChildList.length; i++) {
      // Get the next source child.  Skip if not an element.
      var srcChild = srcChildList[i];
      if (srcChild.nodeType != Ci.nsIDOMNode.ELEMENT_NODE)
        continue;

      // Import the source child into the destination document.
      var dstChild = dstDoc.importNode(srcChild, true);

      // Add the child to the destination node.
      aDstNode.appendChild(dstChild);

      // Add the child attributes.
      for (var attrName in aChildAttrList) {
        dstChild.setAttribute(attrName, aChildAttrList[attrName]);
      }
    }
  },


  copyAttributes: function DOMUtils_copyAttributes(aSrcElem,
                                                   aDstElem,
                                                   aAttributeList,
                                                   aRemoveAttributes) {
    // Copy the attributes.
    for (var i = 0; i < aAttributeList.length; i++) {
      // Get attribute name.
      var attribute = aAttributeList[i];

      // If source element does not have the attribute, do nothing or remove
      // the attribute as specified.
      if (!aSrcElem.hasAttribute(attribute)) {
        if (aRemoveAttributes)
          aDstElem.removeAttribute(attribute);
        continue;
      }

      // Copy the attribute from the source element to the destination if the
      // attribute values differ.
      var srcAttributeVal = aSrcElem.getAttribute(attribute);
      var dstAttributeVal = aDstElem.getAttribute(attribute);
      if (srcAttributeVal != dstAttributeVal)
        aDstElem.setAttribute(attribute, srcAttributeVal);
    }
  },


  getElementsByAttribute: function DOMUtils_getElementsByAttribute(aRootElem,
                                                                   aAttrName,
                                                                   aAttrValue) {
    // Start searching for elements from the root.
    var matchList = [];
    this._getElementsByAttribute(aRootElem, aAttrName, aAttrValue, matchList);

    return matchList;
  },

  _getElementsByAttribute: function
                             DOMUtils__getElementsByAttribute(aRootElem,
                                                              aAttrName,
                                                              aAttrValue,
                                                              aMatchList) {
    // Search each of the children.
    var childList = aRootElem.childNodes;
    for (var i = 0; i < childList.length; i++) {
      // Check the child node for a match.
      var child = childList[i];
      if (child.hasAttributes() && child.hasAttribute(aAttrName)) {
        if (!aAttrValue || (child.getAttribute(aAttrName) == aAttrValue))
          aMatchList.push(child);
      }

      // Check each of the child's children.
      this._getElementsByAttribute(child, aAttrName, aAttrValue, aMatchList);
    }
  },


  encodeTextForXML: function DOMUtils_encodeTextForXML(aText) {
    // Create an XML text node.
    var xmlDocument = Cc["@mozilla.org/xml/xml-document;1"]
                        .createInstance(Ci.nsIDOMDocument);
    var xmlTextNode = xmlDocument.createTextNode(aText);

    // Produce the encoded XML text by serializing the XML text node.
    var domSerializer = Cc["@mozilla.org/xmlextras/xmlserializer;1"]
                          .createInstance(Ci.nsIDOMSerializer);
    var encodedXMLText = domSerializer.serializeToString(xmlTextNode);

    return encodedXMLText;
  },


  rebindXBL: function DOMUtils_rebindXBL(aElem) {
    // Clone the node to force a rebinding.  The clone is not needed.
    //XXXeps there may be a better way to do this, but this works for now
    aElem.cloneNode(false);
  },


  //----------------------------------------------------------------------------
  //
  // DOM class attribute services.
  //
  //----------------------------------------------------------------------------

  setClass: function DOMUtils_setClass(aElem, aClass) {
    // Get the class attribute.  If it's empty, just set the class and return.
    var classAttr = aElem.getAttribute("class");
    if (!classAttr) {
      aElem.setAttribute("class", aClass);
      return;
    }

    // Set class if not already set.
    var classList = classAttr.split(" ");
    if (classList.indexOf(aClass) < 0) {
      classList.push(aClass);
      aElem.setAttribute("class", classList.join(" "));
    }
  },


  clearClass: function DOMUtils_clearClass(aElem, aClass) {
    // Get the class attribute.  If it's empty, just return.
    var classAttr = aElem.getAttribute("class");
    if (!classAttr)
      return;

    // Clear specified class from class attribute.
    var classList = classAttr.split(" ");
    var classCount = classList.length;
    for (var i = classCount - 1; i >= 0; i--) {
      if (classList[i] == aClass)
        classList.splice(i, 1);
    }
    if (classList.length < classCount)
      aElem.setAttribute("class", classList.join(" "));
  },


  isClassSet: function DOMUtils_isClassSet(aElem, aClass) {
    var classAttr = aElem.getAttribute("class");
    var classList = classAttr.split(" ");
    if (classList.indexOf(aClass) < 0)
      return false;

    return true;
  },


  //----------------------------------------------------------------------------
  //
  // DOM node destruction services.
  //
  //   When a node is removed from a DOM tree, any XBL bindings bound to that
  // node or its children are not detached.  Thus, the binding destructors are
  // not called.  The XBL bindings are not detached until the owner document is
  // destroyed.  This can lead to memory leaks if XBL bound nodes are
  // dynamically added and removed from a document.
  //   The DOM node destruction services provide support for releasing XBL
  // binding resources before the XBL binding is detached.  An XBL binding may
  // add a destroy function by calling addNodeDestroyFunc.  Multiple destroy
  // functions may be added for an XBL binding (e.g., for extended bindings).
  //   Before a node is removed from a document, destroyNode should be called.
  // This function recursively calls the destroy functions for all of the nodes
  // children, including the anonymous children.  Note that destroyNode must be
  // called before node removal since node removal removes XBL binding content.
  // If destroyNode is called after node removal, anonymous child nodes will not
  // be destroyed.
  //
  //----------------------------------------------------------------------------

  addNodeDestroyFunc: function DOMUtils_addNodeDestroyFunc(aNode,
                                                           aFunc) {
    // Ensure the destroy function list exists.
    if (!aNode.destroyFuncList)
      aNode.destroyFuncList = [];

    // Push the destroy function on the end of the list.
    aNode.destroyFuncList.push(aFunc);
  },


  destroyNode: function DOMUtils_destroyNode(aNode) {
    /* Can only destroy element nodes. */
    if (aNode.nodeType != Ci.nsIDOMNode.ELEMENT_NODE)
      return;

    // Destroy all of the node's children, including the anonymous children.
    var nodeDocument = aNode.ownerDocument;
    this.destroyNodeList(nodeDocument.getAnonymousNodes(aNode));
    this.destroyNodeList(aNode.childNodes);

    // Call the node destroy functions.
    while (aNode.destroyFuncList) {
      // Pop the next destroy function from the end of the list and call it.
      var destroyFunc = aNode.destroyFuncList.pop();
      try {
        destroyFunc();
      } catch (ex) {
        var msg = "Exception: " + ex +
                  " at " + ex.fileName +
                  ", line " + ex.lineNumber;
        Cu.reportError(msg);
      }

      // If the destroy function list is empty, remove it.
      if (!aNode.destroyFuncList.length)
        aNode.destroyFuncList = null;
    }
  },


  destroyNodeList: function DOMUtils_destroyNodeList(aNodeList) {
    if (!aNodeList)
      return;

    for (var i = 0; i < aNodeList.length; i++) {
      this.destroyNode(aNodeList[i]);
    }
  }
};


//------------------------------------------------------------------------------
//
// DOM highlighter services.
//
//   These services may be used to apply highlighting effects to DOM elements.
//   Highlighting is applied by setting a DOM element attribute to a particular
// value.
//   The highlighting effect blinks the highlighting for a specified period of
// time and then leaves the highlight applied.  When the user clicks anywhere,
// the highlighting is removed.
//
//------------------------------------------------------------------------------

function sbDOMHighlighter(aWindow,
                          aElement,
                          aValue,
                          aAttribute,
                          aBlinkDuration) {
  // Get the attribute to highlight, defaulting to "class".
  var attribute = aAttribute;
  if (!attribute)
    attribute = "class";

  // Get the attribute value with which to highlight.  Choose an appropriate
  // default if no value was specified.
  var value = aValue;
  if (!value) {
    if (attribute == "class") {
      value = "highlight";
    }
    else {
      value = "true";
    }
  }

  // Get the blink duration.
  var blinkDuration = aBlinkDuration;
  if (!blinkDuration)
    blinkDuration = this.defaultBlinkDuration;

  // Save parameters.
  this._window = aWindow;
  this._element = aElement;
  this._value = value;
  this._attribute = attribute;
  this._blinkDuration = blinkDuration;
}


sbDOMHighlighter.highlightElement =
  function sbDOMHighlighter_highlightElement(aWindow,
                                             aElement,
                                             aValue,
                                             aAttribute,
                                             aBlinkDuration) {
  // Create and start a highlighter.
  var highlighter = new sbDOMHighlighter(aWindow,
                                         aElement,
                                         aValue,
                                         aAttribute,
                                         aBlinkDuration);
  highlighter.start();

  return highlighter;
}


// Define the class.
sbDOMHighlighter.prototype = {
  // Set the constructor.
  constructor: sbDOMHighlighter,

  //
  // DOM highlighter configuration.
  //
  //   blinkPeriod              Blink period in milliseconds.
  //   defaultBlinkDuration     Default blink duration in milliseconds.
  //

  blinkPeriod: 250,
  defaultBlinkDuration: 2000,


  //
  // DOM highlighter fields.
  //
  //   _window                  Window containing element.
  //   _element                 Element to highlight.
  //   _attribute               Attribute to use to highlight.
  //   _value                   Value to set highlight.
  //   _blinkDuration           Duration of blinking.
  //   _domEventListenerSet     Set of DOM event listeners.
  //   _blinkTimer              Timer used for blinking.
  //   _blinkStart              Timestamp of start of blinking.
  //   _isHighlighted           If true, element is currently highlighted.
  //

  _window: null,
  _element: null,
  _attribute: null,
  _value: null,
  _blinkDuration: -1,
  _domEventListenerSet: null,
  _blinkTimer: null,
  _blinkStart: 0,
  _isHighlighted: false,


  start: function sbDOMHighlighter_start() {
    var self = this;
    var func;

    // Create a DOM event listener set.
    this._domEventListenerSet = new DOMEventListenerSet();

    // Listen to document click and window unload events.
    func = function _onClickWrapper() { self._onClick(); };
    this._domEventListenerSet.add(this._element.ownerDocument,
                                  "click",
                                  func,
                                  true);
    if (this._window) {
      func = function _onUnloadWrapper() { self._onUnload(); };
      this._domEventListenerSet.add(this._window, "unload", func, false);
    }

    // Highlight element.
    this.setHighlight();

    // Start blinking.
    this._blinkStart = Date.now();
    var self = this;
    var func = function _blinkWrapper() { self._blink(); };
    this._blinkTimer = Cc["@mozilla.org/timer;1"].createInstance(Ci.nsITimer);
    this._blinkTimer.initWithCallback(func,
                                      this.blinkPeriod,
                                      Ci.nsITimer.TYPE_REPEATING_SLACK);
  },


  cancel: function sbDOMHighlighter_cancel() {
    // Remove DOM event listeners.
    if (this._domEventListenerSet)
      this._domEventListenerSet.removeAll();

    // Cancel blink timer.
    if (this._blinkTimer)
      this._blinkTimer.cancel();

    // Remove object references.
    this._element = null;
    this._domEventListenerSet = null;
    this._blinkTimer = null;
  },


  setHighlight: function sbDOMHighlighter_setHighlight() {
    // Apply highlight.
    if (this._attribute == "class") {
      DOMUtils.setClass(this._element, this._value);
    }
    else {
      this._element.setAttribute(this._attribute, this._value);
    }

    // Indicate that the element is now highlighted.
    this._isHighlighted = true;
  },


  clearHighlight: function sbDOMHighlighter_clearHighlight() {
    // Remove highlight.
    if (this._attribute == "class") {
      DOMUtils.clearClass(this._element, this._value);
    }
    else {
      this._element.removeAttribute(this._attribute);
    }

    // Indicate that the element is no longer highlighted.
    this._isHighlighted = false;
  },


  //----------------------------------------------------------------------------
  //
  // Internal DOM highlighter services.
  //
  //----------------------------------------------------------------------------

  _blink: function sbDOMHighlighter__blink() {
    // If the blink duration has been reached, set the highlight and stop the
    // blinking.
    var blinkTime = Date.now() - this._blinkStart;
    if (blinkTime >= this._blinkDuration) {
      this._blinkTimer.cancel();
      this._blinkTimer = null;
      this.setHighlight();
      return;
    }

    // Blink the element highlight.
    if (this._isHighlighted) {
      this.clearHighlight();
    }
    else {
      this.setHighlight();
    }
  },


  _onClick: function sbDOMHighlighter__onClick() {
    // Clear highlight and cancel highlighter.
    this.clearHighlight();
    this.cancel();
  },


  _onUnload: function sbDOMHighlighter__onUnload() {
    // Cancel highlighter.
    this.cancel();
  }
};


//------------------------------------------------------------------------------
//
// DOM event listener set services.
//
//   These services may be used to maintain a set of DOM event listeners and to
// facilitate the removal of DOM event listeners.
//
//------------------------------------------------------------------------------

function DOMEventListenerSet()
{
  // Initialize some fields.
  this._eventListenerList = {};
}

// Set constructor.
DOMEventListenerSet.prototype.constructor = DOMEventListenerSet;

// Define the class.
DOMEventListenerSet.prototype = {
  //
  // DOM event listener set fields.
  //
  //   _eventListenerList       List of event listeners.
  //   _nextEventListenerID     Next event listener ID.
  //

  _eventListenerList: null,
  _nextEventListenerID: 0,


  add: function DOMEventListenerSet_add(aElement,
                                        aType,
                                        aListener,
                                        aUseCapture,
                                        aOneShot,
                                        aWantsUntrusted) {
    // Create the event listener object.
    var eventListener = {};
    eventListener.id = this._nextEventListenerID++;
    eventListener.element = aElement;
    eventListener.type = aType;
    eventListener.listener = aListener;
    eventListener.useCapture = aUseCapture;
    eventListener.oneShot = aOneShot;
    eventListener.wantsUntrusted = aWantsUntrusted == true ? true : false;

    // Use one-shot function if listener is a one-shot listener.
    var listenerFunc = eventListener.listener;
    if (eventListener.oneShot) {
      var _this = this;
      listenerFunc =
        function(aEvent) { return _this._doOneShot(aEvent, eventListener); };
    }
    eventListener.addedListener = listenerFunc;

    // Add the event listener.
    eventListener.element.addEventListener(eventListener.type,
                                           eventListener.addedListener,
                                           eventListener.useCapture,
                                           eventListener.wantsUntrusted);
    this._eventListenerList[eventListener.id] = eventListener;

    return (eventListener.id);
  },


  remove: function DOMEventListenerSet_remove(aEventListenerID) {
    // Get the event listener.  Do nothing if not found.
    var eventListener = this._eventListenerList[aEventListenerID];
    if (!eventListener)
      return;

    // Remove the event listener.
    eventListener.element.removeEventListener(eventListener.type,
                                              eventListener.addedListener,
                                              eventListener.useCapture);
    delete this._eventListenerList[aEventListenerID];
  },


  removeAll: function DOMEventListenerSet_removeAll() {
    // Remove all event listeners.
    for (var id in this._eventListenerList) {
      this.remove(id);
    }
    this._eventListenerList = {};
  },


  //----------------------------------------------------------------------------
  //
  // Internal DOM event listener set services.
  //
  //----------------------------------------------------------------------------

  _doOneShot: function DOMEventListenerSet__doOneShot(aEvent, aEventListener) {
    // Remove event listener if one-shot.
    if (aEventListener.oneShot)
      this.remove(aEventListener.id);

    // Dispatch event to listener.
    return aEventListener.listener(aEvent);
  }
};


//------------------------------------------------------------------------------
//
// Color utility services.
//
//   These utilities provide services for handling colors specified in DOM
// attributes or in CSS.
//   These utilities make use of color objects with the following fields:
//
//     red                      Number from 0.0 to 1.0.
//     green                    Number from 0.0 to 1.0.
//     blue                     Number from 0.0 to 1.0.
//     alpha                    Number from 0.0 to 1.0.
//
//------------------------------------------------------------------------------

var sbColorUtils = {
  getColorFromCSSColor: function sbColorUtils_getCSSColor(aCSSColor) {
    // Parse out the color components substring from the CSS color string.
    var rgba = aCSSColor.match(/^rgba?\((.*)\)/)
    if (!rgba || (rgba.length < 2))
      return null;
    rgba = rgba[1];

    // Split the color components substring into an array.
    rgba = rgba.split(",");
    if (rgba.length < 3)
      return null;

    // Parse the color components into a color object.
    var color = {
      red:   parseFloat(rgba[0]) / 255.0,
      green: parseFloat(rgba[1]) / 255.0,
      blue:  parseFloat(rgba[2]) / 255.0
    };
    if (rgba.length > 3)
      color.alpha = parseFloat(rgba[3])
    else
      color.alpha = 1.0;

    return color;
  },


  getDOMColorString: function sbColorUtils_getDOMColorString(aColor) {
    // Convert the colors to integer values from 0 to 255.
    var red = Math.round(aColor.red * 255.0);
    var green = Math.round(aColor.green * 255.0);
    var blue = Math.round(aColor.blue * 255.0);

    // Combine the individual color values into a single 32-bit rgb value.
    var colorValue = (red << 16) | (green << 8) | blue;

    // Convert the 32-bit rgb value to the form "#xxxxxx", adding leading zeros
    // to ensure there are 6 digits.
    var colorString = (0x01000000 + colorValue).toString(16);
    colorString = "#" + colorString.slice(1);

    return colorString;
  }
};