From 3dff810fe0cc4962a5fa554318e9bf8bc45f5274 Mon Sep 17 00:00:00 2001 From: Kristian Monsen Date: Tue, 26 Jul 2011 12:15:06 +0100 Subject: Merge Chromium at 12.0.742.130: Initial merge by git Fix for bug 5080607 Update external/chromium to latest revision Change-Id: I5c98b0d2845fccca4cbcdcea506e8f1759ba5416 --- chrome/common/extensions/docs/css/ApiRefStyles.css | 4 + chrome/common/extensions/docs/overview.html | 147 ++++++++++++++++++++- chrome/common/extensions/docs/static/overview.html | 138 ++++++++++++++++++- .../common/extensions/docs/static/whats_new.html | 58 ++++---- chrome/common/extensions/docs/whats_new.html | 58 ++++---- 5 files changed, 353 insertions(+), 52 deletions(-) (limited to 'chrome/common/extensions/docs') diff --git a/chrome/common/extensions/docs/css/ApiRefStyles.css b/chrome/common/extensions/docs/css/ApiRefStyles.css index 3a7040f..ef33312 100644 --- a/chrome/common/extensions/docs/css/ApiRefStyles.css +++ b/chrome/common/extensions/docs/css/ApiRefStyles.css @@ -84,6 +84,10 @@ pre b { background:yellow } +.linenumber { + color: #999999; +} + code,pre { font-family:monospace; color:#007000 diff --git a/chrome/common/extensions/docs/overview.html b/chrome/common/extensions/docs/overview.html index f91d3aa..e5c7c8d 100644 --- a/chrome/common/extensions/docs/overview.html +++ b/chrome/common/extensions/docs/overview.html @@ -287,6 +287,17 @@
  • + Using the chrome.* APIs +
      +
    1. + Asynchronous vs. synchronous methods +
    2. + Example: Using a callback +
    3. + More details +
      4. +
    +
  • Communication between pages
    1. @@ -628,7 +639,7 @@ Here are some examples of extensions that usually An extension with a content script that doesn't use cross-origin XMLHttpRequests or localStorage, and that doesn't need to use - extension APIs. + extension APIs.
    2. An extension that has no UI except for an options page. @@ -650,7 +661,7 @@ Any extension can have an options page, which lets users customize how the extension works. Another type of special page is the override page. And finally, you can -use chrome.tabs.create() +use chrome.tabs.create() or window.open() to display any other HTML files that are in the extension.

      @@ -743,6 +754,138 @@ see Content Scripts.

      +

      Using the chrome.* APIs

      + +

      +In addition to having access to all the APIs that web pages and apps can use, +extensions can also use Chrome-only APIs +(often called chrome.* APIs) +that allow tight integration with the browser. +For example, any extension or web app can use the +standard window.open() method to open a URL. +But if you want to specify which window that URL should be displayed in, +your extension can use the Chrome-only +chrome.tabs.create() +method instead. +

      + +

      Asynchronous vs. synchronous methods

      +

      +Most methods in the chrome.* APIs are asynchronous: +they return immediately, without waiting for the operation to finish. +If you need to know the outcome of that operation, +then you pass a callback function into the method. +That callback is executed later (potentially much later), +sometime after the method returns. +Here's an example of the signature for an asynchronous method: +

      + +

      + +chrome.tabs.create(object createProperties, function callback) + +

      + +

      +Other chrome.* methods are synchronous. +Synchronous methods never have a callback +because they don't return until they've completed all their work. +Often, synchronous methods have a return type. +Consider the +chrome.extensions.getBackgroundPage() method: +

      + +

      + +DOMWindow chrome.extension.getBackgroundPage() + +

      + +

      +This method has no callback and a return type of DOMWindow +because it synchronously returns the background page +and performs no other, asynchronous work. +

      + + +

      Example: Using a callback

      + +

      +Say you want to navigate +the user's currently selected tab to a new URL. +To do this, you need to get the current tab's ID +(using chrome.tabs.getSelected()) +and then make that tab go to the new URL +(using chrome.tabs.update()). +

      + +

      +If getSelected() were synchronous, +you might write code like this: +

      + +
         //THIS CODE DOESN'T WORK
+1: var tab = chrome.tabs.getSelected(null); //WRONG!!!
+2: chrome.tabs.update(tab.id, {url:newUrl});
+3: someOtherFunction();
+
      + +

      +That approach fails +because getSelected() is asynchronous. +It returns without waiting for its work to complete, +and it doesn't even return a value +(although some asynchronous methods do). +You can tell that getSelected() is asynchronous +by the callback parameter in its signature: + +

      + +chrome.tabs.getSelected(integer windowId, function callback) + +

      + +

      +To fix the preceding code, +you must use that callback parameter. +The following code shows +how to define a callback function +that gets the results from getSelected() +(as a parameter named tab) +and calls update(). +

      + +
         //THIS CODE WORKS
+1: chrome.tabs.getSelected(null, function(tab) {
+2:   chrome.tabs.update(tab.id, {url:newUrl});
+3: });
+4: someOtherFunction();
+
      + +

      +In this example, the lines are executed in the following order: 1, 4, 2. +The callback function specified to getSelected is called +(and line 2 executed) +only after information about the currently selected tab is available, +which is sometime after getSelected() returns. +Although update() is asynchronous, +this example doesn't use its callback parameter, +since we don't do anything about the results of the update. +

      + + +

      More details

      + +

      +For more information, see the +chrome.* API docs +and watch this video: +

      + +

      + +

      +

      Communication between pages

      diff --git a/chrome/common/extensions/docs/static/overview.html b/chrome/common/extensions/docs/static/overview.html index dabc217..1da4f38 100644 --- a/chrome/common/extensions/docs/static/overview.html +++ b/chrome/common/extensions/docs/static/overview.html @@ -283,7 +283,7 @@ Here are some examples of extensions that usually An extension with a content script that doesn't use cross-origin XMLHttpRequests or localStorage, and that doesn't need to use - extension APIs. + extension APIs.

    3. An extension that has no UI except for an options page. @@ -305,7 +305,7 @@ Any extension can have an options page, which lets users customize how the extension works. Another type of special page is the override page. And finally, you can -use chrome.tabs.create() +use chrome.tabs.create() or window.open() to display any other HTML files that are in the extension.

      @@ -404,6 +404,140 @@ see Content Scripts.

      +

      Using the chrome.* APIs

      + +

      +In addition to having access to all the APIs that web pages and apps can use, +extensions can also use Chrome-only APIs +(often called chrome.* APIs) +that allow tight integration with the browser. +For example, any extension or web app can use the +standard window.open() method to open a URL. +But if you want to specify which window that URL should be displayed in, +your extension can use the Chrome-only +chrome.tabs.create() +method instead. +

      + +

      Asynchronous vs. synchronous methods

      +

      +Most methods in the chrome.* APIs are asynchronous: +they return immediately, without waiting for the operation to finish. +If you need to know the outcome of that operation, +then you pass a callback function into the method. +That callback is executed later (potentially much later), +sometime after the method returns. +Here's an example of the signature for an asynchronous method: +

      + +

      + +chrome.tabs.create(object createProperties, function callback) + +

      + +

      +Other chrome.* methods are synchronous. +Synchronous methods never have a callback +because they don't return until they've completed all their work. +Often, synchronous methods have a return type. +Consider the +chrome.extensions.getBackgroundPage() method: +

      + +

      + +DOMWindow chrome.extension.getBackgroundPage() + +

      + +

      +This method has no callback and a return type of DOMWindow +because it synchronously returns the background page +and performs no other, asynchronous work. +

      + + +

      Example: Using a callback

      + +

      +Say you want to navigate +the user's currently selected tab to a new URL. +To do this, you need to get the current tab's ID +(using chrome.tabs.getSelected()) +and then make that tab go to the new URL +(using chrome.tabs.update()). +

      + +

      +If getSelected() were synchronous, +you might write code like this: +

      + +
      +   //THIS CODE DOESN'T WORK
+1: var tab = chrome.tabs.getSelected(null); //WRONG!!!
+2: chrome.tabs.update(tab.id, {url:newUrl});
+3: someOtherFunction();
+
      + +

      +That approach fails +because getSelected() is asynchronous. +It returns without waiting for its work to complete, +and it doesn't even return a value +(although some asynchronous methods do). +You can tell that getSelected() is asynchronous +by the callback parameter in its signature: + +

      + +chrome.tabs.getSelected(integer windowId, function callback) + +

      + +

      +To fix the preceding code, +you must use that callback parameter. +The following code shows +how to define a callback function +that gets the results from getSelected() +(as a parameter named tab) +and calls update(). +

      + +
      +   //THIS CODE WORKS
+1: chrome.tabs.getSelected(null, function(tab) {
+2:   chrome.tabs.update(tab.id, {url:newUrl});
+3: });
+4: someOtherFunction();
+
      + +

      +In this example, the lines are executed in the following order: 1, 4, 2. +The callback function specified to getSelected is called +(and line 2 executed) +only after information about the currently selected tab is available, +which is sometime after getSelected() returns. +Although update() is asynchronous, +this example doesn't use its callback parameter, +since we don't do anything about the results of the update. +

      + + +

      More details

      + +

      +For more information, see the +chrome.* API docs +and watch this video: +

      + +

      + +

      +

      Communication between pages

      diff --git a/chrome/common/extensions/docs/static/whats_new.html b/chrome/common/extensions/docs/static/whats_new.html index 437e9cd..5c1bd6e 100644 --- a/chrome/common/extensions/docs/static/whats_new.html +++ b/chrome/common/extensions/docs/static/whats_new.html @@ -7,6 +7,7 @@ made in recent releases.

      +

      Google Chrome 12

      + +

      Additions to existing APIs

      +
        +
      • Two new chrome.extension + methods—isAllowedFileSchemeAccess() and + isAllowedIncognitoAccess()—let you + determine whether your extension has increased access, + which the user specifies using the extensions management page + (chrome://extensions). +
        • +
      • The chrome.windows.create() + method can now take a focused value. + Previously, all new windows had the keyboard focus; + now you can create windows without interrupting the user's typing. +
        • +
      • If the manifest specifies "experimental" permission, + your extension can specify "panel" as the value of + the type field in + the chrome.windows.create() + method + or the Window type. +
        • +
      • The onChanged + event of chrome.cookies + now has a cause parameter.
        • +
      • The chrome.contextMenus + create() and + update() + methods now let you specify a context value of "frame". +
      +

      Google Chrome 11

      Changes to existing APIs

      @@ -66,7 +99,7 @@ made in recent releases.

      Additions to existing APIs

      • The chrome.windows.create() - method now has a tabId parameter. + method now has a tabId field. You can use it to move a tab or panel into a new window.

        Note: @@ -88,9 +121,6 @@ made in recent releases.

      • The homepage_url field lets you specify the extension or app's homepage.
      - - -

      Additions to existing APIs

        @@ -143,18 +173,6 @@ No API or manifest changes worth noting.
      - -

      Google Chrome 6

      @@ -168,14 +186,6 @@ No API or manifest changes worth noting. machine's idle state changes.
      4. -

      New experimental APIs

      -
        -
      • The omnibox API allows you to - add functionality to the browser's address bar.
        • -
      • The infobars API allows you - to add a UI panel across the top of a tab.
        • -
      -

      Additions to existing APIs

      • The +

        Google Chrome 12

        + +

        Additions to existing APIs

        +
          +
        • Two new chrome.extension + methods—isAllowedFileSchemeAccess() and + isAllowedIncognitoAccess()—let you + determine whether your extension has increased access, + which the user specifies using the extensions management page + (chrome://extensions). +
          • +
        • The chrome.windows.create() + method can now take a focused value. + Previously, all new windows had the keyboard focus; + now you can create windows without interrupting the user's typing. +
          • +
        • If the manifest specifies "experimental" permission, + your extension can specify "panel" as the value of + the type field in + the chrome.windows.create() + method + or the Window type. +
          • +
        • The onChanged + event of chrome.cookies + now has a cause parameter.
          • +
        • The chrome.contextMenus + create() and + update() + methods now let you specify a context value of "frame". +
        +

        Google Chrome 11

        Changes to existing APIs

        @@ -380,7 +413,7 @@ made in recent releases.

        Additions to existing APIs

        • The chrome.windows.create() - method now has a tabId parameter. + method now has a tabId field. You can use it to move a tab or panel into a new window.

          Note: @@ -403,9 +436,6 @@ made in recent releases. lets you specify the extension or app's homepage.

        - - -

        Additions to existing APIs

        • The Tab object @@ -457,18 +487,6 @@ No API or manifest changes worth noting.
        - -

        Google Chrome 6

        @@ -482,14 +500,6 @@ No API or manifest changes worth noting. machine's idle state changes.
      -

      New experimental APIs

      -
        -
      • The omnibox API allows you to - add functionality to the browser's address bar.
        • -
      • The infobars API allows you - to add a UI panel across the top of a tab.
        • -
      -

      Additions to existing APIs