SBDataRemoteUtils.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-2009 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
 */

//------------------------------------------------------------------------------
//
// Songbird data remote utility JSM configuration.
//
//------------------------------------------------------------------------------

EXPORTED_SYMBOLS =
[
  "SBNewDataRemote",
  "SBDataGetStringValue",
  "SBDataGetIntValue",
  "SBDataGetBoolValue",
  "SBDataSetStringValue",
  "SBDataSetBoolValue",
  "SBDataSetIntValue",
  "SBDataIncrementValue",
  "SBDataDecrementValue",
  "SBDataToggleBoolValue",
  "SBDataFireEvent",
  "SBDataDeleteBranch"
];


//------------------------------------------------------------------------------
//
// Songbird data remote utility defs.
//
//------------------------------------------------------------------------------

// Component manager defs.
if (typeof(Cc) == "undefined")
  var Cc = Components.classes;
if (typeof(Ci) == "undefined")
  var Ci = Components.interfaces;
if (typeof(Cr) == "undefined")
  var Cr = Components.results;
if (typeof(Cu) == "undefined")
  var Cu = Components.utils;


//------------------------------------------------------------------------------
//
// sbIDataRemote wrapper
//
//  This object provides the ability to set key-value pairs
//  into a global "data store," and to have various callback
//  effects occur when anyone changes an observed value.
//
//  The callback binding can be placed on a dom element to
//  change its properties or attributes based upon the value
//  (either directly, or as a boolean, and/or as the result
//  of a given evaluation expression).
//
//  The mozilla preferences system is used as the underlying
//  data storage layer to power this interface.  Because the
//  preferences are available to all open windows in xulrunner,
//  these data remotes should function as globals across
//  the application.  This is both powerful and dangerous, and
//  while this interface is available to all, everyone should
//  be very careful to properly namespace their data strings.
//
//  SBDataBindElementProperty Param List:
//   key  - The data ID to bind upon
//   elem - The element ID to be bound
//   attr - The name of the property or attribute to change
//   bool - Optionally assign the data as BOOLEAN data (true/false props,
//          "true"/"false" attrs)
//   not  - Optionally assign the data as a boolean NOT of the value
//   eval - Optionally apply an eval string where `value = eval( eval_string );`
//XXXeps add data remote DOM utilities.
//
//------------------------------------------------------------------------------

function SB_NewDataRemote( aKey, aRoot )
{
  var dataRemote = Cc["@songbirdnest.com/Songbird/DataRemote;1"]
                     .createInstance(Ci.sbIDataRemote);
  dataRemote.init( aKey, aRoot );
  return dataRemote;
}

function SBNewDataRemote( aKey, aRoot )
{
  return SB_NewDataRemote( aKey, aRoot );
}

function SBDataGetStringValue( aKey )
{
  var data = SB_NewDataRemote( aKey, null );
  return data.stringValue;
}

function SBDataGetIntValue( aKey )
{
  var data = SB_NewDataRemote( aKey, null );
  return data.intValue;
}

function SBDataGetBoolValue( aKey )
{
  var data = SB_NewDataRemote( aKey, null );
  return data.boolValue;
}

function SBDataSetStringValue( aKey, aStringValue )
{
  var data = SB_NewDataRemote( aKey, null );
  data.stringValue = aStringValue;
  return aStringValue;
}

function SBDataSetBoolValue( aKey, aBoolValue )
{
  var data = SB_NewDataRemote( aKey, null );
  data.boolValue = aBoolValue;
  return aBoolValue;
}

function SBDataSetIntValue( aKey, aIntValue )
{
  var data = SB_NewDataRemote( aKey, null );
  data.intValue = aIntValue;
  return aIntValue;
}

function SBDataIncrementValue( aKey, aCeiling )
{
  // if no ceiling is given use the *ceiling*
  if ( aCeiling == null || isNaN(aCeiling) )
    aCeiling = Number.MAX_VALUE;

  var data = SB_NewDataRemote( aKey, null );
  var newVal = (data.intValue + 1);  // getter call
  if ( newVal > aCeiling )
    newVal = aCeiling;
  data.intValue = newVal;            // setter call
  return newVal;
}

function SBDataDecrementValue( aKey, aFloor )
{
  // if no floor is given, use the *floor*
  if ( aFloor == null || isNaN(aFloor) )
    aFloor = -Number.MAX_VALUE;

  var data = SB_NewDataRemote(aKey, null);
  var newVal = (data.intValue - 1);  // getter call
  if ( newVal < aFloor )
    newVal = aFloor;
  data.intValue = newVal;            // setter call
  return newVal;
}

function SBDataToggleBoolValue( aKey )
{
  var data = SB_NewDataRemote(aKey, null);
  var newVal = !data.boolValue;
  data.boolValue = newVal;
  return newVal;
}

function SBDataFireEvent( aKey )
{
  var data = SB_NewDataRemote( aKey, null );
  return ++data.intValue;
}

function SBDataDeleteBranch( aKey )
{
  var data = SB_NewDataRemote( aKey, null );
  data.deleteBranch();
}