Re-land alexbost's experimental offscreenTabs API.

chrome/common/extensions/api/experimental.offscreenTabs.json

+[
+  {
+    "namespace": "experimental.offscreenTabs",
+    "types": [
+      {
+        "id": "OffscreenTab",
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer", 
+            "minimum": 0, 
+            "description": "The ID of the offscreen tab. Tab IDs are unique within a browser session."
+          },
+          "url": {
+            "type": 
+            "string", 
+            "description": "URL of the offscreen tab."
+          },
+          "width": {
+            "type": "integer", 
+            "minimum": 0, 
+            "description": "Width of the window."
+          },
+          "height": {
+            "type": "integer", 
+            "minimum": 0, 
+            "description": "Height of the window."
+          }
+        }
+      }
+    ],
+    "functions": [
+      {
+        "name": "create",
+        "type": "function",
+        "description": "Creates a new offscreen tab.",
+        "parameters": [
+          {
+            "name": "createProperties",
+            "type": "object",
+            "properties": {
+              "url": {
+                "type": "string",
+                "description": "The URL to navigate the offscreen tab to initially. Fully-qualified URLs must include a scheme (i.e. 'http://www.google.com', not 'www.google.com'). Relative URLs will be relative to the current page within the extension."

[asargent_no_longer_on_chrome, 2012/02/29 18:20:52]

During the API review meeting we did for this many months ago, one of the
important points of discussion was whether the lifetime of the created offscreen
tab was scoped to the lifetime of the context of its caller (browser action
popup, etc.), or if we were going to rely on extension authors to remember to
call remove. 

I haven't looked at the implementation yet to see what the current behavior is,
but we should be sure to note in the description here something about that.

[jstritar, 2012/03/12 14:53:06]

Added a note about offscreen tab lifetime.

+              },
+              "width": {
+                "type": "integer",
+                "optional": true,
+                "minimum": 0,
+                "description": "Width of the offscreen tab. Defaults to width of the current tab."
+              },
+              "height": {
+                "type": "integer",
+                "optional": true,
+                "minimum": 0,
+                "description": "Height of the offscreen tab. Defaults to height of the current tab."
+              }
+            }
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "optional": true,      
+            "parameters": [
+              {
+                "name": "offscreenTab",
+                "$ref": "OffscreenTab",
+                "optional": true,
+                "description": "Details of the offscreen tab."
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "name": "get",
+        "type": "function",
+        "description": "Gets details about the specified offscreen tab.",
+        "parameters": [
+          {
+            "name": "offscreenTabId",
+            "type": "integer",
+            "minimum": 0,
+            "description": "ID of the offscreen tab."
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "parameters": [
+              {
+                "name": "offscreenTab",
+                "$ref": "OffscreenTab",
+                "description": "Details of the offscreen tab."
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "name": "getAll",
+        "type": "function",
+        "description": "Gets an array of all offscreen tabs.",
+        "parameters": [
+          {
+            "name": "callback",
+            "type": "function",
+            "parameters": [
+              {
+                "name": "offscreenTabs",
+                "type": "array", 
+                "items": { 
+                  "$ref": "OffscreenTab" 
+                } 
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "name": "remove",
+        "type": "function",
+        "description": "Removes an offscreen tab.",
+        "parameters": [
+          {
+            "name": "offscreenTabId",
+            "type": "integer",
+            "minimum": 0,
+            "description": "ID of the offscreen tab."
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "optional": true
+          }
+        ]
+      },
+      {
+        "name": "sendMouseEvent",
+        "type": "function",
+        "description": "Dispatches a mouse event in the offscreen tab.",
+        "parameters": [
+          {
+            "name": "offscreenTabId",
+            "type": "integer",
+            "minimum": 0,
+            "description": "ID of the offscreen tab."
+          },
+          {
+            "name": "mouseEvent",
+            "type": "any",

[asargent_no_longer_on_chrome, 2012/02/29 18:20:52]

Any reason the type here can't be "MouseEvent" instead of "any" to get the
benefits of type checking? Or maybe you want:

"type": "object",
"isInstanceOf": "MouseEvent"

(see some of the other .json files for examples)

[jstritar, 2012/03/12 14:53:06]

Think we can leave this as is for now? We've been creating events with simple
objects like { type: 'mousedown', button: 0, .... }, whereas there are many more
parameters involved when creating real events.

[asargent_no_longer_on_chrome, 2012/03/13 00:06:02]

Ok - let's at least leave it as type "object" for now. BTW, I think you might be
able to specify a list of required and optional properties inline here for
object types, so you could still get the benefit of type checking. Or, maybe
create an full-fledged type (like Tab, Window, etc. for the tabs or windows
APIs). 

[jstritar, 2012/03/15 22:31:41]

We end up only using a fraction of the properties on the mouse and keyboard
events, so I defined MouseEvent and KeyboardEvents (like how OffscreenTab is
defined). This should be easier for extensions too since creating actual JS
mouse/keyboard events is kind of a pain.

+            "description": "A JavaScript MouseEvent object. Supported event types: <i>mousedown</i>, <i>mouseup</i>, <i>click</i>, <i>mousemove</i>, <i>mousewheel</i>."
+          },
+          {
+            "name": "x",
+            "type": "integer",
+            "optional": true,
+            "minimum": 0,
+            "description": "X position of where the mouse event should be dispatched on the offscreen web page. Not required in the case of a mousewheel event."
+          },
+          {
+            "name": "y",
+            "type": "integer",
+            "optional": true,
+            "minimum": 0,
+            "description": "Y position of where the mouse event should be dispatched on the offscreen web page. Not required in the case of a mousewheel event."
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "optional": true,
+            "parameters": [
+              {
+                "name": "offscreenTab",
+                "$ref": "OffscreenTab",

[asargent_no_longer_on_chrome, 2012/02/29 18:20:52]

It's unusual to be returning the OffscreenTab object here in the callback for
the sendMouseEvent function. I would have expected just the typical
success/failure information, and then the developer would rely on the onUpdated
event if they are interested in seeing changes in e.g. the url of an offscreen
tab. 

[jstritar, 2012/03/12 14:53:06]

Done. Removed the OffscreenTab parameter from the sendKeyboardEvent,
sendMouseEvent and update methods. I originally avoided changing the interface,
since there are demos written against this. These are minimal and easy to
migrate though.

+                "description": "Details of the offscreen tab."
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "name": "sendKeyboardEvent",
+        "type": "function",
+        "description": "Dispatches a keyboard event in the offscreen tab.",
+        "parameters": [
+          {
+            "name": "offscreenTabId",
+            "type": "integer",
+            "minimum": 0,
+            "description": "ID of the offscreen tab."
+          },
+          {
+            "name": "keyboardEvent",
+            "type": "any",

[asargent_no_longer_on_chrome, 2012/02/29 18:20:52]

same question here about type

[jstritar, 2012/03/12 14:53:06]

Done.

+            "description": "A JavaScript KeyboardEvent object. Supported event types: <i>keydown</i>, <i>keyup</i>, <i>keypress</i>. Note, only <i>keypress</i> produces a visible result on screen."
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "optional": true,  
+            "parameters": [
+              {
+                "name": "offscreenTab",
+                "$ref": "OffscreenTab",

[asargent_no_longer_on_chrome, 2012/02/29 18:20:52]

same thing here - weird to return the OffscreenTab to the callback for this
function

[jstritar, 2012/03/12 14:53:06]

Done.

+                "description": "Details of the offscreen tab."
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "name": "toDataUrl",

[asargent_no_longer_on_chrome, 2012/02/29 18:20:52]

Instead returning the tab contents as a data url, I wonder if we'd get better
performance returning the result as a Blob (or have an option for one or the
other). It might be worth looking into what jcivelli did for the
pageCapture.saveAsMHTML function. 

http://www.w3.org/TR/FileAPI/ defines Blobs.

[Ken Russell (switch to Gerrit), 2012/02/29 18:36:07]

The eventual goal is to avoid reading back the contents of the offscreen tab
altogether, and instead allow WebGL code in the extension using this API to
directly reference the GPU texture containing the page's rendered output. That's
the only way that high performance will be achieved. So it may not be worth
trying to further optimize this code path.

[asargent_no_longer_on_chrome, 2012/03/01 00:20:05]

Ok, fine by me.

+        "type": "function",
+        "description": "Captures the visible area of an offscreen tab. ",
+        "parameters": [
+          {
+            "name": "offscreenTabId",
+            "type": "integer",
+            "minimum": 0,
+            "description": "The ID of the offscreen tab."
+          },
+          {
+            "name": "options",
+            "type": "object",
+            "optional": true,
+            "description": "Set parameters of image capture, such as the format of the resulting image.",
+            "properties": {
+              "format": {
+                "type": "string",
+                "optional": true,
+                "enum": ["jpeg", "png"],
+                "description": "The format of the resulting image. Default is jpeg."
+              },
+              "quality": {
+                "type": "integer",
+                "optional": true,
+                "minimum": 0,
+                "maximum": 100,
+                "description": "When format is 'jpeg', controls the quality of the resulting image. This value is ignored for PNG images. As quality is decreased, the resulting image will have more visual artifacts, and the number of bytes needed to store it will decrease."
+              }
+            }
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "parameters": [
+              {
+                "name": "dataUrl",
+                "type": "string",
+                "description": "A data URL which encodes an image of the visible area of the captured offscreen tab. May be assigned to the 'src' property of an HTML Image element or WebGL texture source for display."
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "name": "update",
+        "type": "function",
+        "description": "Modifies the properties of an offscreen tab. Properties that are not specified in updateProperties are not modified.",
+        "parameters": [
+          {
+            "name": "offscreenTabId",
+            "type": "integer", 
+            "minimum": 0,
+            "description": "The ID of the offscreen tab."
+          },
+          {
+            "name": "updateProperties",
+            "type": "object",
+            "properties": {
+              "url": {
+                "type": "string",
+                "optional": true,
+                "description": "The URL the offscreen tab is displaying."
+              },
+              "width": {
+                "type": "integer",
+                "optional": true,
+                "minimum": 0,
+                "description": "Width of the window."
+              },
+              "height": {
+                "type": "integer",
+                "optional": true,
+                "minimum": 0,
+                "description": "Height of the window."
+              }
+            }
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "optional": true,
+            "parameters": [
+              {
+                "name": "offscreenTab",
+                "$ref": "OffscreenTab",

[asargent_no_longer_on_chrome, 2012/02/29 18:20:52]

again, weird to return OffscreenTab here

[jstritar, 2012/03/12 14:53:06]

Done.

+                "description": "Details of the offscreen tab."
+              }
+            ]
+          }
+        ]
+      }
+    ],
+    "events": [
+      {
+        "name": "onUpdated",
+        "type": "function",
+        "description": "Fires when an offscreen tab is updated. ",
+        "parameters": [
+          {
+            "name": "offscreenTabId",
+            "type": "integer",
+            "minimum": 0,
+            "description": "ID of the updated offscreen tab"
+          },
+          {
+            "name": "changeInfo",
+            "type": "object",
+            "description": "Lists the changes to the state of the offscreen tab that was updated.",
+            "properties": {
+              "url": {
+                "type": "string",
+                "optional": true,
+                "description": "The offscreen tab's URL if it has changed."
+              }
+            }
+          },
+          {
+            "name": "offscreenTab",
+            "$ref": "OffscreenTab",
+            "description": "Details of the offscreen tab."
+          }
+        ]
+      }
+    ]
+  }
+]