Various changes to the Extension Settings API.

Goals:
1  - Make it so that chrome.experimental.settings.get() can take an object with the default values to return in settings if any settings aren't set.
2 - Make it so that options pages get change events when the background page changes a setting.
3  - To solve the above: make it so that onChanged events are sent to all registered listeners, not just those which are on different processes (i.e. the incognito extension process).
4 - Remove any result in the callback from chrome.experimental.settings.set(), so that there is an unambiguous way to get changed settings (the event). It's also just generally pointless.

BUG=100825,101452,101459
TEST=*ExtensionSetting*

Review URL: http://codereview.chromium.org/8465002

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@109155 0039d316-1c4b-4281-b951-d872f2087c98

2 files changed, 18 insertions, 85 deletions

diff --git a/chrome/common/extensions/api/extension_api.json b/chrome/common/extensions/api/extension_api.json
index 51c5428..60aecc8 100644
--- a/chrome/common/extensions/api/extension_api.json
+++ b/chrome/common/extensions/api/extension_api.json
@@ -1033,10 +1033,16 @@
           {
             "name": "keys",
             "choices": [
-              {"type": "string"},
-              {"type": "array", "items": {"type": "string"}, "minItems": 1}
+              { "type": "string" },
+              { "type": "array", "items": { "type": "string" } },
+              {
+                "type": "object",
+                "description": "Settings object to return in the callback, where the values are replaced with those from settings if they exist.",
+                "properties": {},
+                "additionalProperties": { "type": "any" }
+              }
             ],
-            "description": "A single key or a list of keys to get from settings. Leave empty to get the entire contents of settings; this should only be used for debugging.",
+            "description": "A single key to get, list of keys to get, or a dictionary specifying default values (see description of the object).  An empty list or object will return an empty settings object.  Pass in null or undefined to get the entire contents of settings; this should only be used for debugging.",
             "optional": true
           },
           {
@@ -1070,16 +1076,8 @@
           {
             "name": "callback",
             "type": "function",
-            "description": "Callback with settings values, or on failure (in which case lastError will be set).",
-            "parameters": [
-              {
-                "name": "settings",
-                "type": "object",
-                "properties": {},
-                "additionalProperties": { "type": "any" },
-                "description": "Object with given keys set to settings values."
-              }
-            ],
+            "description": "Callback on success, or on failure (in which case lastError will be set).",
+            "parameters": [],
             "optional": true
           }
         ]
diff --git a/chrome/common/extensions/docs/experimental.settings.html b/chrome/common/extensions/docs/experimental.settings.html
index 3c1b347..4f5ff9c 100644
--- a/chrome/common/extensions/docs/experimental.settings.html
+++ b/chrome/common/extensions/docs/experimental.settings.html
@@ -542,7 +542,7 @@
 
               <div class="summary"><span style="display: none; ">void</span>
                   <!-- Note: intentionally longer 80 columns -->
-                  <span>chrome.experimental.settings.get</span>(<span class="optional"><span style="display: none; ">, </span><span>string or array of string</span>
+                  <span>chrome.experimental.settings.get</span>(<span class="optional"><span style="display: none; ">, </span><span>string or array of string or object</span>
                       <var><span>keys</span></var></span><span class="null"><span>, </span><span>function</span>
                       <var><span>callback</span></var></span>)</div>
 
@@ -572,7 +572,7 @@
                         <span style="display: none; ">
                           array of <span><span></span></span>
                         </span>
-                        <span>string or array of string</span>
+                        <span>string or array of string or object</span>
                         <span style="display: none; "></span>
                       </span>
                     </span>
@@ -584,7 +584,7 @@
           <dd class="todo" style="display: none; ">
             Undocumented.
           </dd>
-          <dd>A single key or a list of keys to get from settings. Leave empty to get the entire contents of settings; this should only be used for debugging.</dd>
+          <dd>A single key to get, list of keys to get, or a dictionary specifying default values (see description of the object).  An empty list or object will return an empty settings object.  Pass in null or undefined to get the entire contents of settings; this should only be used for debugging.</dd>
           <dd style="display: none; ">
             This parameter was added in version
             <b><span></span></b>.
@@ -1113,7 +1113,7 @@
           <dd class="todo" style="display: none; ">
             Undocumented.
           </dd>
-          <dd>Callback with settings values, or on failure (in which case lastError will be set).</dd>
+          <dd>Callback on success, or on failure (in which case lastError will be set).</dd>
           <dd style="display: none; ">
             This parameter was added in version
             <b><span></span></b>.
@@ -1176,76 +1176,11 @@
                   </p>
 
                   <!-- Note: intentionally longer 80 columns -->
-                  <pre>function(<span>object settings</span>) <span class="subdued">{...}</span>;</pre>
+                  <pre>function(<span></span>) <span class="subdued">{...}</span>;</pre>
                   <dl>
-                    <div>
+                    <div style="display: none; ">
                       <div>
-          <dt>
-            <var>settings</var>
-              <em>
-
-                <!-- TYPE -->
-                <div style="display:inline">
-                  (
-                    <span class="optional" style="display: none; ">optional</span>
-                    <span class="enum" style="display: none; ">enumerated</span>
-                    <span id="typeTemplate">
-                      <span style="display: none; ">
-                        <a> Type</a>
-                      </span>
-                      <span>
-                        <span style="display: none; ">
-                          array of <span><span></span></span>
-                        </span>
-                        <span>object</span>
-                        <span style="display: none; "></span>
-                      </span>
-                    </span>
-                  )
-                </div>
-
-              </em>
-          </dt>
-          <dd class="todo" style="display: none; ">
-            Undocumented.
-          </dd>
-          <dd>Object with given keys set to settings values.</dd>
-          <dd style="display: none; ">
-            This parameter was added in version
-            <b><span></span></b>.
-            You must omit this parameter in earlier versions,
-            and you may omit it in any version.  If you require this
-            parameter, the manifest key
-            <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a>
-            can ensure that your extension won't be run in an earlier browser version.
-          </dd>
-
-          <!-- OBJECT PROPERTIES -->
-          <dd>
-            <dl>
-              <div style="display: none; ">
-                <div>
-                </div>
-              </div>
-            </dl>
-          </dd>
-
-          <!-- OBJECT METHODS -->
-          <dd style="display: none; ">
-            <div></div>
-          </dd>
-
-          <!-- OBJECT EVENT FIELDS -->
-          <dd style="display: none; ">
-            <div></div>
-          </dd>
-
-          <!-- FUNCTION PARAMETERS -->
-          <dd style="display: none; ">
-            <div></div>
-          </dd>
-
-        </div>
+                      </div>
                     </div>
                   </dl>
                   </div>