src/chrome/common/extensions/api/browser_action.json

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 [
   6   {
   7     "namespace": "browserAction",
   8     "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>.",
   9     "types": [
  10       {
  11         "id": "ColorArray",
  12         "type": "array",
  13         "items": {
  14           "type": "integer",
  15           "minimum": 0,
  16           "maximum": 255
  17         },
  18         "minItems": 4,
  19         "maxItems": 4
  20       },
  21       {
  22         "id": "ImageDataType",
  23         "type": "object",
  24         "isInstanceOf": "ImageData",
  25         "additionalProperties": { "type": "any" },
  26         "description": "Pixel data for an image. Must be an ImageData object (for example, from a <code>canvas</code> element)."
  27       }
  28     ],
  29     "functions": [
  30       {
  31         "name": "setTitle",
  32         "type": "function",
  33         "description": "Sets the title of the browser action. This shows up in the tooltip.",
  34         "parameters": [
  35           {
  36             "name": "details",
  37             "type": "object",
  38             "properties": {
  39               "title": {
  40                 "type": "string",
  41                 "description": "The string the browser action should display when moused over."
  42               },
  43               "tabId": {
  44                 "type": "integer",
  45                 "optional": true,
  46                 "description": "Limits the change to when a particular tab is selected. Automatically resets when the tab is closed."
  47               }
  48             }
  49           }
  50         ]
  51       },
  52       {
  53         "name": "getTitle",
  54         "type": "function",
  55         "description": "Gets the title of the browser action.",
  56         "parameters": [
  57           {
  58             "name": "details",
  59             "type": "object",
  60             "properties": {
  61               "tabId": {
  62                 "type": "integer",
  63                 "optional": true,
  64                 "description": "Specify the tab to get the title from. If no tab is specified, the non-tab-specific title is returned."
  65               }
  66             }
  67           },
  68           {
  69             "type": "function",
  70             "name": "callback",
  71             "parameters": [
  72               {
  73                 "name": "result",
  74                 "type": "string"
  75               }
  76             ]
  77           }
  78         ]
  79       },
  80       {
  81         "name": "setIcon",
  82         "type": "function",
  83         "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.",
  84         "parameters": [
  85           {
  86             "name": "details",
  87             "type": "object",
  88             "properties": {
  89               "imageData": {
  90                 "choices": [
  91                   { "$ref": "ImageDataType" },
  92                   {
  93                     "type": "object",
  94                     "properties": {
  95                       "19": {"$ref": "ImageDataType", "optional": true},
  96                       "38": {"$ref": "ImageDataType", "optional": true}
  97                      }
  98                   }
  99                 ],
 100                 "optional": true,
 101                 "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}'"
 102               },
 103               "path": {
 104                 "choices": [
 105                   { "type": "string" },
 106                   {
 107                     "type": "object",
 108                     "properties": {
 109                       "19": {"type": "string", "optional": true},
 110                       "38": {"type": "string", "optional": true}
 111                     }
 112                   }
 113                 ],
 114                 "optional": true,
 115                 "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}'"
 116               },
 117               "tabId": {
 118                 "type": "integer",
 119                 "optional": true,
 120                 "description": "Limits the change to when a particular tab is selected. Automatically resets when the tab is closed."
 121               }
 122             }
 123           },
 124           {
 125             "type": "function",
 126             "name": "callback",
 127             "optional": true,
 128             "parameters": []
 129           }
 130         ]
 131       },
 132       {
 133         "name": "setPopup",
 134         "type": "function",
 135         "description": "Sets the html document to be opened as a popup when the user clicks on the browser action's icon.",
 136         "parameters": [
 137           {
 138             "name": "details",
 139             "type": "object",
 140             "properties": {
 141               "tabId": {
 142                 "type": "integer",
 143                 "optional": true,
 144                 "minimum": 0,
 145                 "description": "Limits the change to when a particular tab is selected. Automatically resets when the tab is closed."
 146               },
 147               "popup": {
 148                 "type": "string",
 149                 "description": "The html file to show in a popup.  If set to the empty string (''), no popup is shown."
 150               }
 151             }
 152           }
 153         ]
 154       },
 155       {
 156         "name": "getPopup",
 157         "type": "function",
 158         "description": "Gets the html document set as the popup for this browser action.",
 159         "parameters": [
 160           {
 161             "name": "details",
 162             "type": "object",
 163             "properties": {
 164               "tabId": {
 165                 "type": "integer",
 166                 "optional": true,
 167                 "description": "Specify the tab to get the popup from. If no tab is specified, the non-tab-specific popup is returned."
 168               }
 169             }
 170           },
 171           {
 172             "type": "function",
 173             "name": "callback",
 174             "parameters": [
 175               {
 176                 "name": "result",
 177                 "type": "string"
 178               }
 179             ]
 180           }
 181         ]
 182       },
 183       {
 184         "name": "setBadgeText",
 185         "type": "function",
 186         "description": "Sets the badge text for the browser action. The badge is displayed on top of the icon.",
 187         "parameters": [
 188           {
 189             "name": "details",
 190             "type": "object",
 191             "properties": {
 192               "text": {
 193                 "type": "string",
 194                 "description": "Any number of characters can be passed, but only about four can fit in the space."
 195               },
 196               "tabId": {
 197                 "type": "integer",
 198                 "optional": true,
 199                 "description": "Limits the change to when a particular tab is selected. Automatically resets when the tab is closed."
 200               }
 201             }
 202           }
 203         ]
 204       },
 205       {
 206         "name": "getBadgeText",
 207         "type": "function",
 208         "description": "Gets the badge text of the browser action. If no tab is specified, the non-tab-specific badge text is returned.",
 209         "parameters": [
 210           {
 211             "name": "details",
 212             "type": "object",
 213             "properties": {
 214               "tabId": {
 215                 "type": "integer",
 216                 "optional": true,
 217                 "description": "Specify the tab to get the badge text from. If no tab is specified, the non-tab-specific badge text is returned."
 218               }
 219             }
 220           },
 221           {
 222             "type": "function",
 223             "name": "callback",
 224             "parameters": [
 225               {
 226                 "name": "result",
 227                 "type": "string"
 228               }
 229             ]
 230           }
 231         ]
 232       },
 233       {
 234         "name": "setBadgeBackgroundColor",
 235         "type": "function",
 236         "description": "Sets the background color for the badge.",
 237         "parameters": [
 238           {
 239             "name": "details",
 240             "type": "object",
 241             "properties": {
 242               "color": {
 243                 "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>.",
 244                 "choices": [
 245                   {"type": "string"},
 246                   {"$ref": "ColorArray"}
 247                 ]
 248               },
 249               "tabId": {
 250                 "type": "integer",
 251                 "optional": true,
 252                 "description": "Limits the change to when a particular tab is selected. Automatically resets when the tab is closed."
 253               }
 254             }
 255           }
 256         ]
 257       },
 258       {
 259         "name": "getBadgeBackgroundColor",
 260         "type": "function",
 261         "description": "Gets the background color of the browser action.",
 262         "parameters": [
 263           {
 264             "name": "details",
 265             "type": "object",
 266             "properties": {
 267               "tabId": {
 268                 "type": "integer",
 269                 "optional": true,
 270                 "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."
 271               }
 272             }
 273           },
 274           {
 275             "type": "function",
 276             "name": "callback",
 277             "parameters": [
 278               {
 279                 "name": "result",
 280                 "$ref": "ColorArray"
 281               }
 282             ]
 283           }
 284         ]
 285       },
 286       {
 287         "name": "enable",
 288         "type": "function",
 289         "description": "Enables the browser action for a tab. By default, browser actions are enabled.",
 290         "parameters": [
 291           {
 292             "type": "integer",
 293             "optional": true,
 294             "name": "tabId",
 295             "minimum": 0,
 296             "description": "The id of the tab for which you want to modify the browser action."
 297           }
 298         ]
 299       },
 300       {
 301         "name": "disable",
 302         "type": "function",
 303         "description": "Disables the browser action for a tab.",
 304         "parameters": [
 305           {
 306             "type": "integer",
 307             "optional": true,
 308             "name": "tabId",
 309             "minimum": 0,
 310             "description": "The id of the tab for which you want to modify the browser action."
 311           }
 312         ]
 313       },
 314       {
 315         "name": "openPopup",
 316         "type": "function",
 317         "description": "Opens the extension popup window in the active window but does not grant tab permissions.",
 318         "nodoc": true,
 319         "parameters": [
 320           {
 321             "type": "function",
 322             "name": "callback",
 323             "parameters": [
 324               {
 325                 "name": "popupView",
 326                 "type": "object",
 327                 "optional": true,
 328                 "description": "JavaScript 'window' object for the popup window if it was succesfully opened.",
 329                 "additionalProperties": { "type": "any" }
 330               }
 331             ]
 332           }
 333         ]
 334       }
 335     ],
 336     "events": [
 337       {
 338         "name": "onClicked",
 339         "type": "function",
 340         "description": "Fired when a browser action icon is clicked.  This event will not fire if the browser action has a popup.",
 341         "parameters": [
 342           {
 343             "name": "tab",
 344             "$ref": "tabs.Tab"
 345           }
 346         ]
 347       }
 348     ]
 349   }
 350 ]