WIP: Migrate Wiki content over to src/docs

docs/browser_actions.md

+# Proposal
+
+Browser actions are an idea to be able to add simple buttons to the main toolbar of Chrome.
+
+![http://www.youngpup.net/z_dropbox/browser_action.png](http://www.youngpup.net/z_dropbox/browser_action.png)
+
+For more pretty pictures, see the attachments to http://crbug.com/22099.
+
+Browser actions can optionally support a popup. The popup displays an HTML page, and is shown when the browser action is pressed. Either way, an event is fired in the extension when a browser actions is pressed that the extension can do something with.
+
+At most, one browser action or page action is allowed per-extension.
+
+They are registered in the manifest like so:
+
+```
+{
+  "name": "My extension that has a browser action",
+  "version": "1",
+  "browser_action": {
+    "default_icon": "foo.png",  // optional
+    "default_title": "Click here for foo",  // required
+    "popup": "popup.html"  // optional
+  }
+}
+```
+
+And they also have a programmatic API:
+
+```
+// Set the icon. Can be specified using either a path to a static icon inside
+// the extension, or by using raw image data from an HTML5 canvas element
+// (see: http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#imagedata)
+// Either the imageData or path property must be set.
+void chrome.browserAction.setIcon({optional ImageData imageData,
+                                   optional string path,
+                                   optional int tabId});
+
+// Set the browser action title. This shows up in the tooltip on mouseover, and
+// in the overflow menu next to the icon.
+void chrome.browserAction.setTitle({string title, optional int tabId});
+
+// Set the badge background color. The |color| array is an array of four integers
+// in the range [0-255] that specify the ARGB color for the badge background.
+void chrome.browserAction.setBadgeBackgroundColor({int[] color, optional int tabId});
+
+// Set the badge text color. The |color| array is an array of four integers
+// in the range [0-255] that specify the ARGB color for the text background.
+void chrome.browserAction.setBadgeTextColor({int[] color, optional int tabId});
+
+// Set the badge text. This can be any string, but practically speaking, it is
+// limited to about 4 characters.
+void chrome.browserAction.setBadgeText({string text, optional int tabId});
+
+// Fired when the browser action is clicked.
+event chrome.browserAction.onClicked(Tab tab);
+```
+
+## Per-tab details
+
+There are two common use cases for browser actions: global notifiers (eg Gmail notifier), and things that can affect any tab (eg bookmark this page in delicious).
+
+For the first case, you can call each API without the optional tabId parameter. It sets the default details for the browser action in each window.
+
+With the tabId specified, the API call only affects the browser action when the specified tab is selected.
+
+## Dynamic images
+
+One of the overloads to setIcon allows authors to create their own images using the HTML canvas element. The implementation of this method in extension\_process\_bindings.js would need to convert the ImageData object into something that we could send over IPC. Probably a string.
+
+## Static image paths do not need to be prespecified
+
+When setIcon() is called, it specifies the relative path to an image inside the extension. This can be implemented without any extra sandbox gymnastics by using a canvas element internally in the implementation of the API to load the image, populate a canvas, and then call setIcon({imageData...});
+
+## Sizing, positioning, and overflow
+
+As an advanced (v2) feature, users should be able to reposition the browser actions within the container using drag and drop.
+
+The browser action container will grow larger until the omnibox reaches some minimum size. After that, browser actions will overflow. Users should be able to drag+drop into the overflow area.
+
+## Hiding browser actions
+
+As an advanced (v2) feature, it should be possible for users to hide a browser action by right-clicking it. They could get it back by right-clicking the container and selecting from a list of checkmarked buttons.
+
+## Popups
+
+If you specify a popup, you will still get the browserAction.onClicked event (EK: I would prefer if this wasn't the case.  They can accomplish the equivalent in their popup's HTML code, and that will likely encourage less racy designs.). In the future, there should also be a popup closed event.  Popups can be closed programmatically using window.close(). Initial popup dimensions are determined dynamically based on content size, but constrained within a sensible minimum and maximum.