Updating the doc to reflect the new experimental.keybinding API.

Adding missing elements from previous API updates (someone forgot to run build.py). Tiny code-change in extension.cc which was suggested during review, but I forgot to do. BUG=27702 TEST=None (doc change) Review URL: https://chromiumcodereview.appspot.com/9465005 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@123724 0039d316-1c4b-4281-b951-d872f2087c98
author: finnur@chromium.org <finnur@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98> 2012-02-27 10:34:27 +0000
committer: finnur@chromium.org <finnur@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98> 2012-02-27 10:34:27 +0000
commit: 97ad50db916b312eb89b0b76517ce85d2084328d (patch)
tree: 273a2c3d8e399116dea68c52b222230ccddb01fc
parent: 8004948ade035d8c402f0074ad92d7c07f28c583 (diff)
download: chromium_src-97ad50db916b312eb89b0b76517ce85d2084328d.zip
chromium_src-97ad50db916b312eb89b0b76517ce85d2084328d.tar.gz
chromium_src-97ad50db916b312eb89b0b76517ce85d2084328d.tar.bz2
6 files changed, 447 insertions, 2 deletions
diff --git a/chrome/common/extensions/api/experimental.keybinding.json b/chrome/common/extensions/api/experimental.keybinding.json
index 04c427d..93a314e 100644
--- a/chrome/common/extensions/api/experimental.keybinding.json
+++ b/chrome/common/extensions/api/experimental.keybinding.json
@@ -1,7 +1,6 @@
 [
   {
     "namespace": "experimental.keybinding",
-    "nodoc": true,
     "events": [
       {
         "name": "onCommand",
diff --git a/chrome/common/extensions/docs/experimental.html b/chrome/common/extensions/docs/experimental.html
index be9ca61..f84ede7 100644
--- a/chrome/common/extensions/docs/experimental.html
+++ b/chrome/common/extensions/docs/experimental.html
@@ -240,6 +240,7 @@ on the following experimental APIs:
   <a href="experimental.devtools.console.html">experimental.devtools.console</a></li><li>
   <a href="experimental.extension.html">experimental.extension</a></li><li>
   <a href="experimental.infobars.html">experimental.infobars</a></li><li>
+  <a href="experimental.keybinding.html">experimental.keybinding</a></li><li>
   <a href="experimental.speechInput.html">experimental.speechInput</a></li>
 </ul>
 <p>
diff --git a/chrome/common/extensions/docs/experimental.keybinding.html b/chrome/common/extensions/docs/experimental.keybinding.html
new file mode 100644
index 0000000..d2cb30f
--- /dev/null
+++ b/chrome/common/extensions/docs/experimental.keybinding.html
@@ -0,0 +1,379 @@
+<!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note:
+    1) The <head> information in this page is significant, should be uniform
+       across api docs and should be edited only with knowledge of the
+       templating mechanism.
+    3) All <body>.innerHTML is genereated as an rendering step. If viewed in a
+       browser, it will be re-generated from the template, json schema and
+       authored overview content.
+    4) The <body>.innerHTML is also generated by an offline step so that this
+       page may easily be indexed by search engines.
+--><html xmlns="http://www.w3.org/1999/xhtml"><head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+    <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css">
+    <link href="css/print.css" rel="stylesheet" type="text/css" media="print">
+    <script type="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js">
+    </script>
+    <script type="text/javascript" src="js/api_page_generator.js"></script>
+    <script type="text/javascript" src="js/bootstrap.js"></script>
+    <script type="text/javascript" src="js/sidebar.js"></script>
+  <meta name="description" content="Documentation for the chrome.experimental.keybinding module, which is part of the Google Chrome  extension APIs."><title>chrome.experimental.keybinding - Google Chrome Extensions - Google Code</title></head>
+  <body>  <div id="devModeWarning" class="displayModeWarning">
+    You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.
+  </div>
+  <div id="branchWarning" class="displayModeWarning">
+    <span>WARNING: This is the <span id="branchName">BETA</span> documentation.
+    It may not work with the stable release of Chrome.</span>
+    <select id="branchChooser">
+      <option>Choose a different version...
+      </option><option value="">Stable
+      </option><option value="beta">Beta
+      </option><option value="dev">Dev
+      </option><option value="trunk">Trunk
+    </option></select>
+  </div>
+  <div id="unofficialWarning" class="displayModeWarning">
+    <span>WARNING: This is unofficial documentation. It may not work with the
+    current release of Chrome.</span>
+    <button id="goToOfficialDocs">Go to the official docs</button>
+  </div>
+  <div id="gc-container" class="labs">
+      <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION -->
+      <!-- In particular, sub-templates that recurse, must be used by allowing
+           jstemplate to make a copy of the template in this section which
+           are not operated on by way of the jsskip="true" -->
+       <!-- /SUBTEMPLATES -->
+  <a id="top"></a>
+    <div id="skipto">
+      <a href="#gc-pagecontent">Skip to page content</a>
+      <a href="#gc-toc">Skip to main navigation</a>
+    </div>
+    <!-- API HEADER -->
+    <table id="header" width="100%" cellspacing="0" border="0">
+      <tbody><tr>
+        <td valign="middle"><a href="http://code.google.com/"><img src="images/code_labs_logo.gif" height="43" width="161" alt="Google Code Labs" style="border:0; margin:0;"></a></td>
+        <td valign="middle" width="100%" style="padding-left:0.6em;">
+          <form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em">
+            <div id="gsc-search-box">
+              <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno">
+              <input type="hidden" name="ie" value="UTF-8">
+              <input type="text" name="q" value="" size="55">
+              <input class="gsc-search-button" type="submit" name="sa" value="Search">
+              <br>
+              <span class="greytext">e.g. "page action" or "tabs"</span>
+            </div>
+          </form>
+          <script type="text/javascript" src="https://www.google.com/jsapi"></script>
+          <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script>
+          <script type="text/javascript" src="https://www.google.com/coop/cse/t13n?form=cse&amp;t13n_langs=en"></script>
+          <script type="text/javascript" src="https://www.google.com/coop/cse/brand?form=cse&amp;lang=en"></script>
+        </td>
+      </tr>
+    </tbody></table>
+    <div id="codesiteContent" class="">
+      <a id="gc-topnav-anchor"></a>
+      <div id="gc-topnav">
+        <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Labs</a>)</h1>
+        <ul id="home" class="gc-topnav-tabs">
+          <li id="home_link">
+            <a href="index.html" title="Google Chrome Extensions home page">Home</a>
+          </li>
+          <li id="docs_link">
+            <a href="docs.html" title="Official Google Chrome Extensions documentation">Docs</a>
+          </li>
+          <li id="faq_link">
+            <a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions">FAQ</a>
+          </li>
+          <li id="samples_link">
+            <a href="samples.html" title="Sample extensions (with source code)">Samples</a>
+          </li>
+          <li id="group_link">
+            <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions" title="Google Chrome Extensions developer forum">Group</a>
+          </li>
+          <li id="so_link">
+            <a href="http://stackoverflow.com/questions/tagged/google-chrome-extension" title="[google-chrome-extension] tag on Stack Overflow">Questions?</a>
+          </li>
+        </ul>
+      </div> <!-- end gc-topnav -->
+    <div class="g-section g-tpl-170">
+      <!-- SIDENAV -->
+      <div class="g-unit g-first" id="gc-toc">
+        <ul>
+          <li><a href="getstarted.html">Getting Started</a></li>
+          <li><a href="overview.html">Overview</a></li>
+          <li><a href="whats_new.html">What's New?</a></li>
+          <li><h2><a href="devguide.html">Developer's Guide</a></h2>
+            <ul>
+              <li>Browser UI
+                <ul>
+                  <li><a href="browserAction.html">Browser Actions</a></li>
+                  <li><a href="contextMenus.html">Context Menus</a></li>
+                  <li><a href="notifications.html">Desktop Notifications</a></li>
+                  <li><a href="omnibox.html">Omnibox</a></li>
+                  <li><a href="options.html">Options Pages</a></li>
+                  <li><a href="override.html">Override Pages</a></li>
+                  <li><a href="pageAction.html">Page Actions</a></li>
+                </ul>
+              </li>
+              <li>Browser Interaction
+                <ul>
+                  <li><a href="bookmarks.html">Bookmarks</a></li>
+                  <li><a href="cookies.html">Cookies</a></li>
+                  <li><a href="devtools.html">Developer Tools</a></li>
+                  <li><a href="events.html">Events</a></li>
+                  <li><a href="history.html">History</a></li>
+                  <li><a href="management.html">Management</a></li>
+                  <li><a href="tabs.html">Tabs</a></li>
+                  <li><a href="windows.html">Windows</a></li>
+                </ul>
+              </li>
+              <li>Implementation
+                <ul>
+                  <li><a href="a11y.html">Accessibility</a></li>
+                  <li><a href="background_pages.html">Background Pages</a></li>
+                  <li><a href="content_scripts.html">Content Scripts</a></li>
+                  <li><a href="xhr.html">Cross-Origin XHR</a></li>
+                  <li><a href="i18n.html">Internationalization</a></li>
+                  <li><a href="messaging.html">Message Passing</a></li>
+                  <li><a href="permissions.html">Optional Permissions</a></li>
+                  <li><a href="npapi.html">NPAPI Plugins</a></li>
+                </ul>
+              </li>
+              <li>Finishing
+                <ul>
+                  <li><a href="hosting.html">Hosting</a></li>
+                  <li><a href="external_extensions.html">Other Deployment Options</a></li>
+                </ul>
+              </li>
+            </ul>
+          </li>
+          <li><h2><a href="apps.html">Packaged Apps</a></h2></li>
+          <li><h2><a href="tutorials.html">Tutorials</a></h2>
+            <ul>
+              <li><a href="tut_debugging.html">Debugging</a></li>
+              <li><a href="tut_analytics.html">Google Analytics</a></li>
+              <li><a href="tut_oauth.html">OAuth</a></li>
+            </ul>
+          </li>
+          <li><h2>Reference</h2>
+            <ul>
+              <li>Formats
+                <ul>
+                  <li><a href="manifest.html">Manifest Files</a></li>
+                  <li><a href="match_patterns.html">Match Patterns</a></li>
+                </ul>
+              </li>
+              <li><a href="permission_warnings.html">Permission Warnings</a></li>
+              <li><a href="api_index.html">chrome.* APIs</a></li>
+              <li><a href="api_other.html">Other APIs</a></li>
+            </ul>
+          </li>
+          <li><h2><a href="samples.html">Samples</a></h2></li>
+          <div class="line"> </div>
+          <li><h2>More</h2>
+            <ul>
+              <li><a href="http://code.google.com/chrome/webstore/docs/index.html">Chrome Web Store</a></li>
+              <li><a href="http://code.google.com/chrome/apps/docs/developers_guide.html">Hosted Apps</a></li>
+              <li><a href="themes.html">Themes</a></li>
+            </ul>
+          </li>
+        </ul>
+      </div>
+      <script>
+        initToggles();
+      </script>
+    <div class="g-unit" id="gc-pagecontent">
+      <div id="pageTitle">
+        <h1 class="page_title">chrome.experimental.keybinding</h1>
+      </div>
+        <!-- TABLE OF CONTENTS -->
+        <div id="toc">
+          <h2>Contents</h2>
+          <ol>
+            <li>
+              <a href="#manifest">Manifest</a>
+              <ol>
+              </ol>
+            </li><li>
+              <a href="#usage">Usage</a>
+              <ol>
+              </ol>
+            </li>
+              <li>
+                <a href="#apiReference">API reference: chrome.experimental.keybinding</a>
+                <ol>
+                  <li>
+            <a href="#global-events">Events</a>
+            <ol>
+              <li>
+                <a href="#event-onCommand">onCommand</a>
+              </li>
+            </ol>
+          </li>
+                </ol>
+              </li>
+          </ol>
+        </div>
+        <!-- /TABLE OF CONTENTS -->
+        <!-- Standard content lead-in for experimental API pages -->
+        <p id="classSummary">
+          For information on how to use experimental APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page.
+        </p>
+        <!-- STATIC CONTENT PLACEHOLDER -->
+        <div id="static"><!-- BEGIN AUTHORED CONTENT -->
+<p>
+The keybinding API allows you to add keyboard shortcuts that trigger actions in
+your extension. An action can be opening the browser action or page action popup
+or sending a command to the extension.
+</p>
+<h2 id="manifest">Manifest</h2>
+<p>
+In addition to the "experimental" permission you must declare the "keybinding"
+permission in your extension's manifest to use this API.
+</p>
+<pre>{
+  "name": "My extension",
+  ...
+<b>  "permissions": [
+    "experimental",
+    "keybinding",
+  ]</b>,
+  ...
+}</pre>
+<h2 id="usage">Usage</h2>
+<p>The keybinding API allows you to define specific commands, and bind them to a
+default key combination. Each command your extension accepts must be listed in
+the manifest as an attribute of the 'commands' manifest key. Note: Combinations
+that involve Ctrl+Alt are not permitted in order to avoid conflicts with the
+AltGr key.</p>
+<pre>{
+  "name": "My extension",
+  ...
+<b>  "commands": {
+    "toggle-feature-foo": {
+      "key": "Ctrl+Shift+Y",
+      "description": "Toggle feature foo"
+    },
+    "browserAction": {
+      "key": "Ctrl+Shift+B"
+    },
+    "pageAction": {
+      "key": "Alt+P"
+    }
+  }</b>,
+  ...
+}</pre>
+<p>In your background page, you can bind a handler to each of the commands
+defined in the manifest (except for 'browserAction' and 'pageAction') via
+onCommand.addListener. For example:</p>
+<pre>chrome.experimental.keybinding.onCommand.addListener(function(command) {
+  console.log('Command:', command);
+});
+</pre>
+<p>The 'browserAction' and 'pageAction' commands are reserved for the action of
+opening your extension's popups. They won't normally generate events that you
+can handle. If you need to take action based on your popup opening, consider
+listening for an 'onDomReady' event inside your popup's code.
+</p>
+<!-- END AUTHORED CONTENT -->
+</div>
+        <!-- API PAGE -->
+        <div class="apiPage">
+        <a name="apiReference"></a>
+        <h2>API reference: chrome.experimental.keybinding</h2>
+          <!-- PROPERTIES -->
+           <!-- /apiGroup -->
+          <!-- METHODS -->
+            <!-- /apiGroup -->
+          <!-- EVENTS -->
+          <div id="eventsTemplate" class="apiGroup">
+            <a name="global-events"></a>
+            <h3>Events</h3>
+            <!-- iterates over all events -->
+            <div class="apiItem">
+              <a name="event-onCommand"></a>
+              <h4>onCommand</h4>
+              <div class="summary">
+                <!-- Note: intentionally longer 80 columns -->
+                <span class="subdued">chrome.experimental.keybinding.</span><span>onCommand</span><span class="subdued">.addListener</span>(function(<span>string command</span>) <span class="subdued">{...}</span><span></span>);
+              </div>
+              <div class="description">
+                <p>Fired when a registered command is activated using a keyboard shortcut.</p>
+                <!-- LISTENER PARAMETERS -->
+                <div>
+                  <h4>Listener parameters</h4>
+                  <dl>
+                    <div>
+                      <div>
+          <dt>
+            <var>command</var>
+              <em>
+                <!-- TYPE -->
+                <div style="display:inline">
+                  (
+                    <span id="typeTemplate">
+                      <span>
+                        <span>string</span>
+                      </span>
+                    </span>
+                  )
+                </div>
+              </em>
+          </dt>
+          <dd class="todo">
+            Undocumented.
+          </dd>
+          <!-- OBJECT PROPERTIES -->
+          <!-- OBJECT METHODS -->
+          <!-- OBJECT EVENT FIELDS -->
+          <!-- FUNCTION PARAMETERS -->
+        </div>
+                    </div>
+                  </dl>
+                </div>
+                <!-- EXTRA PARAMETERS -->
+                <!-- LISTENER RETURN VALUE -->
+                <dl>
+                </dl>
+              </div> <!-- /description -->
+            </div> <!-- /apiItem -->
+          </div> <!-- /apiGroup -->
+          <!-- TYPES -->
+           <!-- /apiGroup -->
+        </div> <!-- /apiPage -->
+      </div> <!-- /gc-pagecontent -->
+    </div> <!-- /g-section -->
+  </div> <!-- /codesiteContent -->
+    <div id="gc-footer" --="">
+      <div class="text">
+  <p>
+  Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>,
+  the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons
+  Attribution 3.0 License</a>, and code samples are licensed under the
+  <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>.
+  </p>
+  <p>
+  ©2011 Google
+  </p>
+<!-- begin analytics -->
+<script src="https://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+<script src="https://www.google-analytics.com/ga.js" type="text/javascript"></script>
+<script type="text/javascript">
+  // chrome doc tracking
+  try {
+    var engdocs = _gat._getTracker("YT-10763712-2");
+    engdocs._trackPageview();
+  } catch(err) {}
+  // code.google.com site-wide tracking
+  try {
+    _uacct="UA-18071-1";
+    _uanchor=1;
+    _uff=0;
+    urchinTracker();
+  }
+  catch(e) {/* urchinTracker not available. */}
+</script>
+<!-- end analytics -->
+      </div>
+    </div> <!-- /gc-footer -->
+  </div> <!-- /gc-container -->
+</body></html>
diff --git a/chrome/common/extensions/docs/js/api_page_generator.js b/chrome/common/extensions/docs/js/api_page_generator.js
index 9dc0b1a..202854e 100644
--- a/chrome/common/extensions/docs/js/api_page_generator.js
+++ b/chrome/common/extensions/docs/js/api_page_generator.js
@@ -40,6 +40,7 @@ var MODULE_SCHEMAS = [
   '../api/experimental.infobars.json',
   '../api/experimental.input.ui.json',
   '../api/experimental.input.virtualKeyboard.json',
+  '../api/experimental.keybinding.json',
   '../api/experimental.processes.json',
   '../api/experimental.rlz.json',
   '../api/experimental.serial.json',
diff --git a/chrome/common/extensions/docs/static/experimental.keybinding.html b/chrome/common/extensions/docs/static/experimental.keybinding.html
new file mode 100644
index 0000000..1148018
--- /dev/null
+++ b/chrome/common/extensions/docs/static/experimental.keybinding.html
@@ -0,0 +1,65 @@
+<!-- BEGIN AUTHORED CONTENT -->
+<p>
+The keybinding API allows you to add keyboard shortcuts that trigger actions in
+your extension. An action can be opening the browser action or page action popup
+or sending a command to the extension.
+</p>
+
+<h2 id="manifest">Manifest</h2>
+<p>
+In addition to the "experimental" permission you must declare the "keybinding"
+permission in your extension's manifest to use this API.
+</p>
+
+<pre>{
+  "name": "My extension",
+  ...
+<b>  "permissions": [
+    "experimental",
+    "keybinding",
+  ]</b>,
+  ...
+}</pre>
+
+<h2 id="usage">Usage</h2>
+<p>The keybinding API allows you to define specific commands, and bind them to a
+default key combination. Each command your extension accepts must be listed in
+the manifest as an attribute of the 'commands' manifest key. Note: Combinations
+that involve Ctrl+Alt are not permitted in order to avoid conflicts with the
+AltGr key.</p>
+
+<pre>{
+  "name": "My extension",
+  ...
+<b>  "commands": {
+    "toggle-feature-foo": {
+      "key": "Ctrl+Shift+Y",
+      "description": "Toggle feature foo"
+    },
+    "browserAction": {
+      "key": "Ctrl+Shift+B"
+    },
+    "pageAction": {
+      "key": "Alt+P"
+    }
+
+  }</b>,
+  ...
+}</pre>
+
+<p>In your background page, you can bind a handler to each of the commands
+defined in the manifest (except for 'browserAction' and 'pageAction') via
+onCommand.addListener. For example:</p>
+
+<pre>
+chrome.experimental.keybinding.onCommand.addListener(function(command) {
+  console.log('Command:', command);
+});
+</pre>
+
+<p>The 'browserAction' and 'pageAction' commands are reserved for the action of
+opening your extension's popups. They won't normally generate events that you
+can handle. If you need to take action based on your popup opening, consider
+listening for an 'onDomReady' event inside your popup's code.
+</p>
+<!-- END AUTHORED CONTENT -->
diff --git a/chrome/common/extensions/extension.cc b/chrome/common/extensions/extension.cc
index 05faad8..be1017f 100644
--- a/chrome/common/extensions/extension.cc
+++ b/chrome/common/extensions/extension.cc
@@ -281,7 +281,7 @@ bool Extension::ExtensionKeybinding::Parse(DictionaryValue* command,
   // We support Ctrl+foo, Alt+foo, Ctrl+Shift+foo, Alt+Shift+foo, but not
   // Ctrl+Alt+foo. For a more detailed reason why we don't support Ctrl+Alt+foo:
   // http://blogs.msdn.com/b/oldnewthing/archive/2004/03/29/101121.aspx.
-  if (key == ui::VKEY_UNKNOWN || (ctrl == true && alt == true)) {
+  if (key == ui::VKEY_UNKNOWN || (ctrl && alt)) {
     *error = ExtensionErrorUtils::FormatErrorMessageUTF16(
         errors::kInvalidKeyBinding,
         base::IntToString(index),
author	finnur@chromium.org <finnur@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98>	2012-02-27 10:34:27 +0000
committer	finnur@chromium.org <finnur@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98>	2012-02-27 10:34:27 +0000
commit	97ad50db916b312eb89b0b76517ce85d2084328d (patch)
tree	273a2c3d8e399116dea68c52b222230ccddb01fc
parent	8004948ade035d8c402f0074ad92d7c07f28c583 (diff)
download	chromium_src-97ad50db916b312eb89b0b76517ce85d2084328d.zip chromium_src-97ad50db916b312eb89b0b76517ce85d2084328d.tar.gz chromium_src-97ad50db916b312eb89b0b76517ce85d2084328d.tar.bz2