ext/Preferences.js

 * Version: MPL 1.1/GPL 2.0/LGPL 2.1

 *

 * The contents of this file are subject to the Mozilla Public License Version

 * 1.1 (the "License"); you may not use this file except in compliance with

 * the License. You may obtain a copy of the License at

 * http://www.mozilla.org/MPL/

 *

 * Software distributed under the License is distributed on an "AS IS" basis,

 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License

 * for the specific language governing rights and limitations under the

 * License.

 *

 * The Original Code is Preferences.

 *

 * The Initial Developer of the Original Code is Mozilla.

 * Portions created by the Initial Developer are Copyright (C) 2008

 * the Initial Developer. All Rights Reserved.

 *

 * Contributor(s):

 *   Myk Melez <myk@mozilla.org>

 *   Daniel Aquino <mr.danielaquino@gmail.com>

 *

 * Alternatively, the contents of this file may be used under the terms of

 * either the GNU General Public License Version 2 or later (the "GPL"), or

 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),

 * in which case the provisions of the GPL or the LGPL are applicable instead

 * of those above. If you wish to allow use of your version of this file only

 * under the terms of either the GPL or the LGPL, and not to allow others to

 * use your version of this file under the terms of the MPL, indicate your

 * decision by deleting the provisions above and replace them with the notice

 * and other provisions required by the GPL or the LGPL. If you do not delete

 * the provisions above, a recipient may use your version of this file under

 * the terms of any one of the MPL, the GPL or the LGPL.

 *

 * ***** END LICENSE BLOCK ***** */

// The minimum and maximum integers that can be set as preferences.

// The range of valid values is narrower than the range of valid JS values

// because the native preferences code treats integers as NSPR PRInt32s,

// which are 32-bit signed integers on all platforms.

    }

}

  /**

   * Get the value of a pref, if any; otherwise return the default value.

   *

   * @param   prefName  {String|Array}

   *          the pref to get, or an array of prefs to get

   *

   * @param   defaultValue

   *          the default value, if any, for prefs that don't have one

   *

   * @returns the value of the pref, if any; otherwise the default value

   */

  },

        // This should never happen.

    }

  },

  },

  /**

   * Set a preference to a value.

   *

   * You can set multiple prefs by passing an object as the only parameter.

   * In that case, this method will treat the properties of the object

   * as preferences to set, where each property name is the name of a pref

   * and its corresponding property value is the value of the pref.

   *

   * @param   prefName  {String|Object}

   *          the name of the pref to set; or an object containing a set

   *          of prefs to set

   *

   * @param   prefValue {String|Number|Boolean}

   *          the value to which to set the pref

   *

   * Note: Preferences cannot store non-integer numbers or numbers outside

   * the signed 32-bit range -(2^31-1) to 2^31-1, If you have such a number,

   * store it as a string by calling toString() on the number before passing

   * it to this method, i.e.:

   *   Preferences.set("pi", 3.14159.toString())

   *   Preferences.set("big", Math.pow(2, 31).toString()).

   */

    }

  },

        }

        // We throw if the number is outside the range, since the result

        // will never be what the consumer wanted to store, but we only warn

        // if the number is non-integer, since the consumer might not mind

        // the loss of precision.

  },

  },

  /**

   * Whether or not the given pref has a value.  This is different from isSet

   * because it returns true whether the value of the pref is a default value

   * or a user-set value, while isSet only returns true if the value

   * is a user-set value.

   *

   * @param   prefName  {String|Array}

   *          the pref to check, or an array of prefs to check

   *

   * @returns {Boolean|Array}

   *          whether or not the pref has a value; or, if the caller provided

   *          an array of pref names, an array of booleans indicating whether

   *          or not the prefs have values

   */

  },

  },

  },

  /**

   * Whether or not the given pref has a user-set value.  This is different

   * from |has| because it returns true only if the value of the pref is a user-

   * set value, while |has| returns true if the value of the pref is a default

   * value or a user-set value.

   *

   * @param   prefName  {String|Array}

   *          the pref to check, or an array of prefs to check

   *

   * @returns {Boolean|Array}

   *          whether or not the pref has a user-set value; or, if the caller

   *          provided an array of pref names, an array of booleans indicating

   *          whether or not the prefs have user-set values

   */

  },

  /**

   * Whether or not the given pref has a user-set value. Use isSet instead,

   * which is equivalent.

   * @deprecated

   */

    }

  },

    }

      // The pref service throws NS_ERROR_UNEXPECTED when the caller tries

      // to reset a pref that doesn't exist or is already set to its default

      // value.  This interface fails silently in those cases, so callers

      // can unconditionally reset a pref without having to check if it needs

      // resetting first or trap exceptions after the fact.  It passes through

      // other exceptions, however, so callers know about them, since we don't

      // know what other exceptions might be thrown and what they might mean.

  },

  },

  /**

   * Lock a pref so it can't be changed.

   *

   * @param   prefName  {String|Array}

   *          the pref to lock, or an array of prefs to lock

   */

  },

  /**

   * Unlock a pref so it can be changed.

   *

   * @param   prefName  {String|Array}

   *          the pref to lock, or an array of prefs to lock

   */

  },

  /**

   * Whether or not the given pref is locked against changes.

   *

   * @param   prefName  {String|Array}

   *          the pref to check, or an array of prefs to check

   *

   * @returns {Boolean|Array}

   *          whether or not the pref has a user-set value; or, if the caller

   *          provided an array of pref names, an array of booleans indicating

   *          whether or not the prefs have user-set values

   */

  },

  /**

   * Start observing a pref.

   *

   * The callback can be a function or any object that implements nsIObserver.

   * When the callback is a function and thisObject is provided, it gets called

   * as a method of thisObject.

   *

   * @param   prefName    {String}

   *          the name of the pref to observe

   *

   * @param   callback    {Function|Object}

   *          the code to notify when the pref changes;

   *

   * @param   thisObject  {Object}  [optional]

   *          the object to use as |this| when calling a Function callback;

   *

   * @returns the wrapped observer

   */

  },

  /**

   * Stop observing a pref.

   *

   * You must call this method with the same prefName, callback, and thisObject

   * with which you originally registered the observer.  However, you don't have

   * to call this method on the same exact instance of Preferences; you can call

   * it on any instance.  For example, the following code first starts and then

   * stops observing the "foo.bar.baz" preference:

   *

   *   let observer = function() {...};

   *   Preferences.observe("foo.bar.baz", observer);

   *   new Preferences("foo.bar.").ignore("baz", observer);

   *

   * @param   prefName    {String}

   *          the name of the pref being observed

   *

   * @param   callback    {Function|Object}

   *          the code being notified when the pref changes

   *

   * @param   thisObject  {Object}  [optional]

   *          the object being used as |this| when calling a Function callback

   */

    // This seems fairly inefficient, but I'm not sure how much better we can

    // make it.  We could index by fullBranch, but we can't index by callback

    // or thisObject, as far as I know, since the keys to JavaScript hashes

    // (a.k.a. objects) can apparently only be primitive values.

    }

  },

    }

      // The current implementation of nsIPrefBranch in Mozilla

      // doesn't implement resetBranch, so we do it ourselves.

    }

  },

  /**

   * The branch of the preferences tree to which this instance provides access.

   * @private

   */

  },

  /**

   * Preferences Service

   * @private

   */

  },

  /**

   * IO Service

   * @private

   */

  },

  /**

   * Site Preferences Service

   * @private

   */

  }

};

// Give the constructor the same prototype as its instances, so users can access

// preferences directly via the constructor without having to create an instance

// first.

/**

 * A cache of pref observers.

 *

 * We use this to remove observers when a caller calls Preferences::ignore.

 *

 * All Preferences instances share this object, because we want callers to be

 * able to remove an observer using a different Preferences object than the one

 * with which they added it.  That means we have to identify the observers

 * in this object by their complete pref name, not just their name relative to

 * the root branch of the Preferences object with which they were created.

 */

}

    // The pref service only observes whole branches, but we only observe

    // individual preferences, so we check here that the pref that changed

    // is the exact one we're observing (and not some sub-pref on the branch).

    }

  }

};

  // We can't check for |val.constructor == Array| here, since the value

  // might be from a different context whose Array constructor is not the same

  // as ours, so instead we match based on the name of the constructor.

}

  // We can't check for |val.constructor == Object| here, since the value

  // might be from a different context whose Object constructor is not the same

  // as ours, so instead we match based on the name of the constructor.