home *** CD-ROM | disk | FTP | other *** search
/ Freelog 112 / FreelogNo112-NovembreDecembre2012.iso / Multimedia / Songbird / Songbird_2.0.0-2311_windows-i686-msvc8.exe / jsmodules / SBDataRemoteUtils.jsm < prev    next >
Text File  |  2012-06-08  |  10KB  |  324 lines
  1. /* -*- Mode: Java; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* vim: set sw=2 :miv */
  3. /*
  4.  *=BEGIN SONGBIRD GPL
  5.  *
  6.  * This file is part of the Songbird web player.
  7.  *
  8.  * Copyright(c) 2005-2009 POTI, Inc.
  9.  * http://www.songbirdnest.com
  10.  *
  11.  * This file may be licensed under the terms of of the
  12.  * GNU General Public License Version 2 (the ``GPL'').
  13.  *
  14.  * Software distributed under the License is distributed
  15.  * on an ``AS IS'' basis, WITHOUT WARRANTY OF ANY KIND, either
  16.  * express or implied. See the GPL for the specific language
  17.  * governing rights and limitations.
  18.  *
  19.  * You should have received a copy of the GPL along with this
  20.  * program. If not, go to http://www.gnu.org/licenses/gpl.html
  21.  * or write to the Free Software Foundation, Inc.,
  22.  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  23.  *
  24.  *=END SONGBIRD GPL
  25.  */
  26.  
  27. /**
  28.  * \file  SBDataRemoteUtils.jsm
  29.  * \brief Javascript source for the Songbird data remote utility services.
  30.  */
  31.  
  32. //------------------------------------------------------------------------------
  33. //
  34. // Songbird data remote utility JSM configuration.
  35. //
  36. //------------------------------------------------------------------------------
  37.  
  38. EXPORTED_SYMBOLS =
  39. [
  40.   "SBNewDataRemote",
  41.   "SBDataGetStringValue",
  42.   "SBDataGetIntValue",
  43.   "SBDataGetBoolValue",
  44.   "SBDataSetStringValue",
  45.   "SBDataSetBoolValue",
  46.   "SBDataSetIntValue",
  47.   "SBDataIncrementValue",
  48.   "SBDataDecrementValue",
  49.   "SBDataToggleBoolValue",
  50.   "SBDataFireEvent",
  51.   "SBDataDeleteBranch"
  52. ];
  53.  
  54.  
  55. //------------------------------------------------------------------------------
  56. //
  57. // Songbird data remote utility defs.
  58. //
  59. //------------------------------------------------------------------------------
  60.  
  61. // Component manager defs.
  62. if (typeof(Cc) == "undefined")
  63.   var Cc = Components.classes;
  64. if (typeof(Ci) == "undefined")
  65.   var Ci = Components.interfaces;
  66. if (typeof(Cr) == "undefined")
  67.   var Cr = Components.results;
  68. if (typeof(Cu) == "undefined")
  69.   var Cu = Components.utils;
  70.  
  71.  
  72. //------------------------------------------------------------------------------
  73. //
  74. // sbIDataRemote wrapper
  75. //
  76. //  This object provides the ability to set key-value pairs
  77. //  into a global "data store," and to have various callback
  78. //  effects occur when anyone changes an observed value.
  79. //
  80. //  The callback binding can be placed on a dom element to
  81. //  change its properties or attributes based upon the value
  82. //  (either directly, or as a boolean, and/or as the result
  83. //  of a given evaluation expression).
  84. //
  85. //  The mozilla preferences system is used as the underlying
  86. //  data storage layer to power this interface.  Because the
  87. //  preferences are available to all open windows in xulrunner,
  88. //  these data remotes should function as globals across
  89. //  the application.  This is both powerful and dangerous, and
  90. //  while this interface is available to all, everyone should
  91. //  be very careful to properly namespace their data strings.
  92. //
  93. //  SBDataBindElementProperty Param List:
  94. //   key  - The data ID to bind upon
  95. //   elem - The element ID to be bound
  96. //   attr - The name of the property or attribute to change
  97. //   bool - Optionally assign the data as BOOLEAN data (true/false props,
  98. //          "true"/"false" attrs)
  99. //   not  - Optionally assign the data as a boolean NOT of the value
  100. //   eval - Optionally apply an eval string where `value = eval( eval_string );`
  101. //XXXeps add data remote DOM utilities.
  102. //
  103. //------------------------------------------------------------------------------
  104.  
  105. /**
  106.  * \brief Create a new data remote object.
  107.  *
  108.  * \param aKey - The string identifier for the data to watch
  109.  * \param aRoot - OPTIONAL - If present this defines a prefix to the key
  110.  *
  111.  * \return - A data remote object.
  112.  * \internal
  113.  * \note This function is not exported.
  114.  */
  115.  
  116. function SB_NewDataRemote( aKey, aRoot )
  117. {
  118.   var dataRemote = Cc["@songbirdnest.com/Songbird/DataRemote;1"]
  119.                      .createInstance(Ci.sbIDataRemote);
  120.   dataRemote.init( aKey, aRoot );
  121.   return dataRemote;
  122. }
  123.  
  124. /**
  125.  * \brief Create a new data remote object
  126.  * \param aKey - The string identifier for the data to watch
  127.  * \param aRoot - OPTIONAL - If present this defines a prefix to the key
  128.  *
  129.  * \return - A data remote object.
  130.  */
  131. function SBNewDataRemote( aKey, aRoot )
  132. {
  133.   return SB_NewDataRemote( aKey, aRoot );
  134. }
  135.  
  136. /**
  137.  * \brief Get the value of the data in string format.
  138.  *
  139.  * \param aKey - The string identifier for the data to be changed.
  140.  * \return - The string value of the data. If the data has not been set the
  141.  *           return value will be the empty string ("");
  142.  * \sa DatatRemote
  143.  */
  144. function SBDataGetStringValue( aKey )
  145. {
  146.   var data = SB_NewDataRemote( aKey, null );
  147.   return data.stringValue;
  148. }
  149.  
  150. /**
  151.  * \brief Get the value of the data in integer format
  152.  *
  153.  * \param aKey - The string identifier for the data to be changed.
  154.  * \return - The integer value of the data. If the data has not been set or
  155.  *           the data is not convertible to an integer the return value will
  156.  *           be NaN.
  157.  * \sa DatatRemote
  158.  */
  159. function SBDataGetIntValue( aKey )
  160. {
  161.   var data = SB_NewDataRemote( aKey, null );
  162.   return data.intValue;
  163. }
  164.  
  165. /**
  166.  * \brief Get the value of the data in boolean format.
  167.  *
  168.  * \param aKey - The string identifier for the data to be retrieved.
  169.  * \return - The boolean value of the data.
  170.  * \sa DatatRemote
  171.  */
  172. function SBDataGetBoolValue( aKey )
  173. {
  174.   var data = SB_NewDataRemote( aKey, null );
  175.   return data.boolValue;
  176. }
  177.  
  178. /**
  179.  * \brief Set a string value.
  180.  * Changes the value of the data remote to the boolean passed in, regardless
  181.  *   of its value before.
  182.  *
  183.  * \param aKey - The string identifier for the data to be changed.
  184.  * \param aBoolValue - A boolean value.
  185.  * \return - The new value of the data.
  186.  * \sa DatatRemote
  187.  */
  188. function SBDataSetStringValue( aKey, aStringValue )
  189. {
  190.   var data = SB_NewDataRemote( aKey, null );
  191.   data.stringValue = aStringValue;
  192.   return aStringValue;
  193. }
  194.  
  195. /**
  196.  * \brief Set a boolean value.
  197.  * Changes the value of the data remote to the boolean passed in, regardless
  198.  *   of its value before.
  199.  *
  200.  * \param aKey - The string identifier for the data to be changed.
  201.  * \param aBoolValue - A boolean value.
  202.  * \return - The new value of the data.
  203.  * \sa DatatRemote
  204.  */
  205. function SBDataSetBoolValue( aKey, aBoolValue )
  206. {
  207.   var data = SB_NewDataRemote( aKey, null );
  208.   data.boolValue = aBoolValue;
  209.   return aBoolValue;
  210. }
  211.  
  212. /**
  213.  * \brief Set an integer value.
  214.  * Changes the value of the data remote to the integer passed in, regardless
  215.  *   of its value before.
  216.  *
  217.  * \param aKey - The string identifier for the data to be changed.
  218.  * \param aIntValue - An integer (or string convertable to an integer) value.
  219.  * \return - The new value of the data.
  220.  * \sa DatatRemote
  221.  */
  222. function SBDataSetIntValue( aKey, aIntValue )
  223. {
  224.   var data = SB_NewDataRemote( aKey, null );
  225.   data.intValue = aIntValue;
  226.   return aIntValue;
  227. }
  228.  
  229. /**
  230.  * \brief Increment the integer value.
  231.  *  Increment the integer value associated with the key passed in. If a ceiling
  232.  *    value is passed in the new value will be no greater than the ceiling.
  233.  *
  234.  * \param aKey - The string identifier for the data to be changed.
  235.  * \param aCeiling - Optional, if specified the data will be at most, this value
  236.  * \return - The new value of the data.
  237.  * \sa DatatRemote
  238.  */
  239. function SBDataIncrementValue( aKey, aCeiling )
  240. {
  241.   // if no ceiling is given use the *ceiling*
  242.   if ( aCeiling == null || isNaN(aCeiling) )
  243.     aCeiling = Number.MAX_VALUE;
  244.  
  245.   var data = SB_NewDataRemote( aKey, null );
  246.   var newVal = (data.intValue + 1);  // getter call
  247.   if ( newVal > aCeiling )
  248.     newVal = aCeiling;
  249.   data.intValue = newVal;            // setter call
  250.   return newVal;
  251. }
  252.  
  253. /**
  254.  * \brief Decrement the integer value.
  255.  *  Decrement the integer value associated with the key passed in. If a floor
  256.  *    value is passed in the new value will be no less than the floor.
  257.  *
  258.  * \param aKey - The string identifier for the data to be changed.
  259.  * \param aFloor - Optional, if specified the data will be no less than this
  260.  *                 value
  261.  * \return - The new value of the data.
  262.  * \sa DatatRemote
  263.  */
  264. function SBDataDecrementValue( aKey, aFloor )
  265. {
  266.   // if no floor is given, use the *floor*
  267.   if ( aFloor == null || isNaN(aFloor) )
  268.     aFloor = -Number.MAX_VALUE;
  269.  
  270.   var data = SB_NewDataRemote(aKey, null);
  271.   var newVal = (data.intValue - 1);  // getter call
  272.   if ( newVal < aFloor )
  273.     newVal = aFloor;
  274.   data.intValue = newVal;            // setter call
  275.   return newVal;
  276. }
  277.  
  278. /**
  279.  * \brief Change the boolean value.
  280.  * The true/false value of the data associated with the key will be reversed.
  281.  *
  282.  * \param aKey - The string identifier for the data to be changed.
  283.  * \return - The new value of the data.
  284.  * \sa DatatRemote
  285.  */
  286. function SBDataToggleBoolValue( aKey )
  287. {
  288.   var data = SB_NewDataRemote(aKey, null);
  289.   var newVal = !data.boolValue;
  290.   data.boolValue = newVal;
  291.   return newVal;
  292. }
  293.  
  294. /**
  295.  * \brief Cause a notification to be fired.
  296.  * The data associated with the key will be modified so that observers will
  297.  *   be called about the change. The actual value of the data should not be
  298.  *   counted on.
  299.  *
  300.  * \param aKey - The data about which the event is being fired
  301.  * \param aKey - The string identifier for the data about which the event is
  302.  *               being fired.
  303.  * \return - The new value of the data.
  304.  * \sa DatatRemote
  305.  */
  306. function SBDataFireEvent( aKey )
  307. {
  308.   var data = SB_NewDataRemote( aKey, null );
  309.   return ++data.intValue;
  310. }
  311.  
  312. /**
  313.  * \brief Called to remove the data remote specified by aKey and all its
  314.  *        children.
  315.  *
  316.  * \param aKey - The data remove to remove.
  317.  */
  318. function SBDataDeleteBranch( aKey )
  319. {
  320.   var data = SB_NewDataRemote( aKey, null );
  321.   data.deleteBranch();
  322. }
  323.  
  324.