blob: 696412df11c70929579b1e9df983869f98a823ad [file] [log] [blame]
// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
[
{
"namespace": "browserAction",
"description": "Use browser actions to put icons in the main Google Chrome toolbar, to the right of the address bar. In addition to its <a href='browserAction#icon'>icon</a>, a browser action can have a <a href='browserAction#tooltip'>tooltip</a>, a <a href='browserAction#badge'>badge</a>, and a <a href='browserAction#popups'>popup</a>.",
"compiler_options": {
"implemented_in": "chrome/browser/extensions/api/extension_action/extension_action_api.h"
},
"types": [
{
"id": "ColorArray",
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 255
},
"minItems": 4,
"maxItems": 4
},
{
"id": "ImageDataType",
"type": "object",
"isInstanceOf": "ImageData",
"additionalProperties": { "type": "any" },
"description": "Pixel data for an image. Must be an ImageData object; for example, from a <code>canvas</code> element."
},
{
"id": "TabDetails",
"type": "object",
"properties": {
"tabId": { "type": "integer", "optional": true, "minimum": 0, "description": "The ID of the tab to query state for. If no tab is specified, the non-tab-specific state is returned." }
}
}
],
"functions": [
{
"name": "setTitle",
"type": "function",
"description": "Sets the title of the browser action. This title appears in the tooltip.",
"parameters": [
{
"name": "details",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The string the browser action should display when moused over."
},
"tabId": {
"type": "integer",
"optional": true,
"description": "Limits the change to when a particular tab is selected. Automatically resets when the tab is closed."
}
}
}
],
"returns_async": {"name": "callback", "parameters": [], "optional": true}
},
{
"name": "getTitle",
"type": "function",
"description": "Gets the title of the browser action.",
"parameters": [
{
"name": "details",
"$ref": "TabDetails"
}
],
"returns_async": {
"name": "callback",
"parameters": [
{
"name": "result",
"type": "string"
}
]
}
},
{
"name": "setIcon",
"type": "function",
"description": "Sets the icon for the browser action. The icon can be specified as the path to an image file, as the pixel data from a canvas element, or as a dictionary of one of those. Either the <code>path</code> or the <code>imageData</code> property must be specified.",
"parameters": [
{
"name": "details",
"type": "object",
"properties": {
"imageData": {
"choices": [
{ "$ref": "ImageDataType" },
{
"type": "object",
"additionalProperties": { "type": "any" }
}
],
"optional": true,
"description": "Either an ImageData object or a dictionary {size -> ImageData} representing an icon to be set. If the icon is specified as a dictionary, the image used is chosen depending on the screen's pixel density. If the number of image pixels that fit into one screen space unit equals <code>scale</code>, then an image with size <code>scale</code> * n is selected, where <i>n</i> is the size of the icon in the UI. At least one image must be specified. Note that 'details.imageData = foo' is equivalent to 'details.imageData = {'16': foo}'"
},
"path": {
"choices": [
{ "type": "string" },
{
"type": "object",
"additionalProperties": { "type": "any" }
}
],
"optional": true,
"description": "Either a relative image path or a dictionary {size -> relative image path} pointing to an icon to be set. If the icon is specified as a dictionary, the image used is chosen depending on the screen's pixel density. If the number of image pixels that fit into one screen space unit equals <code>scale</code>, then an image with size <code>scale</code> * n is selected, where <i>n</i> is the size of the icon in the UI. At least one image must be specified. Note that 'details.path = foo' is equivalent to 'details.path = {'16': foo}'"
},
"tabId": {
"type": "integer",
"optional": true,
"description": "Limits the change to when a particular tab is selected. Automatically resets when the tab is closed."
}
}
},
{
"type": "function",
"name": "callback",
"optional": true,
"parameters": []
}
]
},
{
"name": "setPopup",
"type": "function",
"description": "Sets the HTML document to be opened as a popup when the user clicks the browser action icon.",
"parameters": [
{
"name": "details",
"type": "object",
"properties": {
"tabId": {
"type": "integer",
"optional": true,
"minimum": 0,
"description": "Limits the change to when a particular tab is selected. Automatically resets when the tab is closed."
},
"popup": {
"type": "string",
"description": "The relative path to the HTML file to show in a popup. If set to the empty string (<code>''</code>), no popup is shown."
}
}
}
],
"returns_async": {"name": "callback", "parameters": [], "optional": true}
},
{
"name": "getPopup",
"type": "function",
"description": "Gets the HTML document that is set as the popup for this browser action.",
"parameters": [
{
"name": "details",
"$ref": "TabDetails"
}
],
"returns_async": {
"name": "callback",
"parameters": [
{
"name": "result",
"type": "string"
}
]
}
},
{
"name": "setBadgeText",
"type": "function",
"description": "Sets the badge text for the browser action. The badge is displayed on top of the icon.",
"parameters": [
{
"name": "details",
"type": "object",
"properties": {
"text": {
"type": "string",
"optional": true,
"description": "Any number of characters can be passed, but only about four can fit into the space. If an empty string (<code>''</code>) is passed, the badge text is cleared. If <code>tabId</code> is specified and <code>text</code> is null, the text for the specified tab is cleared and defaults to the global badge text."
},
"tabId": {
"type": "integer",
"optional": true,
"description": "Limits the change to when a particular tab is selected. Automatically resets when the tab is closed."
}
}
}
],
"returns_async": {"name": "callback", "parameters": [], "optional": true}
},
{
"name": "getBadgeText",
"type": "function",
"description": "Gets the badge text of the browser action. If no tab is specified, the non-tab-specific badge text is returned.",
"parameters": [
{
"name": "details",
"$ref": "TabDetails"
}
],
"returns_async": {
"name": "callback",
"parameters": [
{
"name": "result",
"type": "string"
}
]
}
},
{
"name": "setBadgeBackgroundColor",
"type": "function",
"description": "Sets the background color for the badge.",
"parameters": [
{
"name": "details",
"type": "object",
"properties": {
"color": {
"description": "An array of four integers in the range 0-255 that make up the RGBA color of the badge. Can also be a string with a CSS hex color value; for example, <code>#FF0000</code> or <code>#F00</code> (red). Renders colors at full opacity.",
"choices": [
{"type": "string"},
{"$ref": "ColorArray"}
]
},
"tabId": {
"type": "integer",
"optional": true,
"description": "Limits the change to when a particular tab is selected. Automatically resets when the tab is closed."
}
}
}
],
"returns_async": {"name": "callback", "parameters": [], "optional": true}
},
{
"name": "getBadgeBackgroundColor",
"type": "function",
"description": "Gets the background color of the browser action.",
"parameters": [
{
"name": "details",
"$ref": "TabDetails"
}
],
"returns_async": {
"name": "callback",
"parameters": [
{
"name": "result",
"$ref": "ColorArray"
}
]
}
},
{
"name": "enable",
"type": "function",
"description": "Enables the browser action for a tab. Defaults to enabled.",
"parameters": [
{
"type": "integer",
"optional": true,
"name": "tabId",
"minimum": 0,
"description": "The ID of the tab for which to modify the browser action."
}
],
"returns_async": {"name": "callback", "parameters": [], "optional": true}
},
{
"name": "disable",
"type": "function",
"description": "Disables the browser action for a tab.",
"parameters": [
{
"type": "integer",
"optional": true,
"name": "tabId",
"minimum": 0,
"description": "The ID of the tab for which to modify the browser action."
}
],
"returns_async": {"name": "callback", "parameters": [], "optional": true}
},
{
"name": "openPopup",
"type": "function",
"description": "Opens the extension popup window in the active window but does not grant tab permissions.",
"nodoc": true,
"parameters": [
{
"type": "function",
"name": "callback",
"parameters": [
{
"name": "popupView",
"type": "object",
"optional": true,
"description": "JavaScript 'window' object for the popup window if it was succesfully opened.",
"additionalProperties": { "type": "any" }
}
]
}
]
}
],
"events": [
{
"name": "onClicked",
"type": "function",
"description": "Fired when a browser action icon is clicked. Does not fire if the browser action has a popup.",
"parameters": [
{
"name": "tab",
"$ref": "tabs.Tab"
}
]
}
]
}
]