WIP: Migrate Wiki content over to src/docs

docs/page_action_ap_iv2.md

+# Introduction
+
+We currently have a page actions API, but it is very weird because we were learning what we liked as we were building it. We also now have a BrowserActions API that we like a lot more, but it stinks that it is very different from the page actions API.

[Bons, 2015/08/20 20:16:50]

delete due to staleness?

+
+This proposal is for a new version of the page actions API that is more like the browser actions one. Because the two APIs are so similar, please see [that document](BrowserActions.md) for more details.
+
+There can be at most one browser or page action per-extension.
+
+The difference between browser actions and page actions is that page actions only have the lifetime of a particular document. They are shown for a specific tab, but always go away when that tab navigates.
+
+## Manifest
+
+```
+{
+  "name": "My extension that has a page action",
+  "version": "1",
+  "page_action": {
+    "default_icon": "foo.png",  // optional
+    "default_title": "Click here for foo",  // required
+    "popup": "popup.html"  // optional
+  }
+}
+```
+
+## Programmatic API
+
+```
+// Show the page action. The page action is shown whenever the tab is selected.
+void chrome.pageAction.show(int tabId);
+
+// Hide the page action.
+void chrome.pageAction.hide(int tabId);
+
+// 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.pageAction.setIcon({optional ImageData imageData,
+                                optional string path,
+                                int tabId});
+
+// Set the title of the page action. This is displayed in a tooltip over the
+// page action.
+void chrome.pageAction.setTitle({string title, 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.pageAction.setBadgeBackgroundColor({int[] color, 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.pageAction.setBadgeTextColor({int[] color, int tabId});
+
+// Set the badge text. This can be any string, but practically speaking, it is
+// limited to about 4 characters.
+void chrome.pageAction.setBadgeText({string text, int tabId});
+
+// Fired when the page action is clicked.
+event chrome.pageAction.onClicked(Tab tab);
+```