extensions/api/browser_action.json

// 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='#icon'>icon</a>, a browser action can also have a <a href='#tooltip'>tooltip</a>, a <a href='#badge'>badge</a>, and a <a href = '#popups'>popup</a>.",
    "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)."
      }
    ],
    "functions": [
      {
        "name": "setTitle",
        "type": "function",
        "description": "Sets the title of the browser action. This shows up 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."
              }
            }
          }
        ]
      },
      {
        "name": "getTitle",
        "type": "function",
        "description": "Gets the title of the browser action.",
        "parameters": [
          {
            "name": "details",
            "type": "object",
            "properties": {
              "tabId": {
                "type": "integer",
                "optional": true,
                "description": "Specify the tab to get the title from. If no tab is specified, the non-tab-specific title is returned."
              }
            }
          },
          {
            "type": "function",
            "name": "callback",
            "parameters": [
              {
                "name": "result",
                "type": "string"
              }
            ]
          }
        ]
      },
      {
        "name": "setIcon",
        "type": "function",
        "description": "Sets the icon for the browser action. The icon can be specified either as the path to an image file or as the pixel data from a canvas element, or as dictionary of either one of those. Either the <b>path</b> or the <b>imageData</b> property must be specified.",
        "parameters": [
          {
            "name": "details",
            "type": "object",
            "properties": {
              "imageData": {
                "choices": [
                  { "$ref": "ImageDataType" },
                  {
                    "type": "object",
                    "properties": {
                      "19": {"$ref": "ImageDataType", "optional": true},
                      "38": {"$ref": "ImageDataType", "optional": true}
                     }
                  }
                ],
                "optional": true,
                "description": "Either an ImageData object or a dictionary {size -> ImageData} representing icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on screen's pixel density. If the number of image pixels that fit into one screen space unit equals <code>scale</code>, then image with size <code>scale</code> * 19 will be selected. Initially only scales 1 and 2 will be supported. At least one image must be specified. Note that 'details.imageData = foo' is equivalent to 'details.imageData = {'19': foo}'"
              },
              "path": {
                "choices": [
                  { "type": "string" },
                  {
                    "type": "object",
                    "properties": {
                      "19": {"type": "string", "optional": true},
                      "38": {"type": "string", "optional": true}
                    }
                  }
                ],
                "optional": true,
                "description": "Either a relative image path or a dictionary {size -> relative image path} pointing to icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on screen's pixel density. If the number of image pixels that fit into one screen space unit equals <code>scale</code>, then image with size <code>scale</code> * 19 will be selected. Initially only scales 1 and 2 will be supported. At least one image must be specified. Note that 'details.path = foo' is equivalent to 'details.imageData = {'19': 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 on the browser action's 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 html file to show in a popup.  If set to the empty string (''), no popup is shown."
              }
            }
          }
        ]
      },
      {
        "name": "getPopup",
        "type": "function",
        "description": "Gets the html document set as the popup for this browser action.",
        "parameters": [
          {
            "name": "details",
            "type": "object",
            "properties": {
              "tabId": {
                "type": "integer",
                "optional": true,
                "description": "Specify the tab to get the popup from. If no tab is specified, the non-tab-specific popup is returned."
              }
            }
          },
          {
            "type": "function",
            "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",
                "description": "Any number of characters can be passed, but only about four can fit in the space."
              },
              "tabId": {
                "type": "integer",
                "optional": true,
                "description": "Limits the change to when a particular tab is selected. Automatically resets when the tab is closed."
              }
            }
          }
        ]
      },
      {
        "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",
            "type": "object",
            "properties": {
              "tabId": {
                "type": "integer",
                "optional": true,
                "description": "Specify the tab to get the badge text from. If no tab is specified, the non-tab-specific badge text is returned."
              }
            }
          },
          {
            "type": "function",
            "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. For example, opaque red is <code>[255, 0, 0, 255]</code>. Can also be a string with a CSS value, with opaque red being <code>#FF0000</code> or <code>#F00</code>.",
                "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."
              }
            }
          }
        ]
      },
      {
        "name": "getBadgeBackgroundColor",
        "type": "function",
        "description": "Gets the background color of the browser action.",
        "parameters": [
          {
            "name": "details",
            "type": "object",
            "properties": {
              "tabId": {
                "type": "integer",
                "optional": true,
                "description": "Specify the tab to get the badge background color from. If no tab is specified, the non-tab-specific badge background color is returned."
              }
            }
          },
          {
            "type": "function",
            "name": "callback",
            "parameters": [
              {
                "name": "result",
                "$ref": "ColorArray"
              }
            ]
          }
        ]
      },
      {
        "name": "enable",
        "type": "function",
        "description": "Enables the browser action for a tab. By default, browser actions are enabled.",
        "parameters": [
          {
            "type": "integer",
            "optional": true,
            "name": "tabId",
            "minimum": 0,
            "description": "The id of the tab for which you want to modify the browser action."
          }
        ]
      },
      {
        "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 you want to modify the browser action."
          }
        ]
      }
    ],
    "events": [
      {
        "name": "onClicked",
        "type": "function",
        "description": "Fired when a browser action icon is clicked.  This event will not fire if the browser action has a popup.",
        "parameters": [
          {
            "name": "tab",
            "$ref": "tabs.Tab"
          }
        ]
      }
    ]
  }
]