<!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note: 1) The <head> information in this page is significant, should be uniform across api docs and should be edited only with knowledge of the templating mechanism. 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a browser, it will be re-generated from the template, json schema and authored overview content. 4) The <body>.innerHTML is also generated by an offline step so that this page may easily be indexed by search engines. --><html xmlns="http://www.w3.org/1999/xhtml"><head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css"> <link href="css/print.css" rel="stylesheet" type="text/css" media="print"> <script type="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js"> </script> <script type="text/javascript" src="js/api_page_generator.js"></script> <script type="text/javascript" src="js/bootstrap.js"></script> <title>Browser Actions</title></head><body> <div id="container"> <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION --> <!-- In particular, sub-templates that recurse, must be used by allowing jstemplate to make a copy of the template in this section which are not operated on by way of the jsskip="true" --> <div style="display:none"> <!-- VALUE --> <div id="valueTemplate"> <dt> <var>paramName</var> <em> <!-- TYPE --> <div style="display:inline"> ( <span class="optional">optional</span> <span id="typeTemplate"> <span> <a> Type</a> </span> <span> <span> array of <span><span></span></span> </span> <span>paramType</span> </span> </span> ) </div> </em> </dt> <dd class="todo"> Undocumented. </dd> <dd> Description of this parameter from the json schema. </dd> <!-- OBJECT PROPERTIES --> <dd> <dl> <div> <div> </div> </div> </dl> </dd> </div> <!-- /VALUE --> </div> <!-- /SUBTEMPLATES --> <a name="top"> </a> <!-- API HEADER --> <div id="pageHeader"> <div id="searchbox"> <form action="http://www.google.com/cse" id="cse-search-box"> <div> <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno"> <input type="hidden" name="ie" value="UTF-8"> <input type="text" name="q" size="31"> <input type="submit" name="sa" value="Search"> </div> </form> <script type="text/javascript" src="http://www.google.com/jsapi"></script> <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script> <script type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse-search-box&t13n_langs=en"></script> <script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse-search-box&lang=en"></script> </div> <div id="pageTitle"> <h1>Browser Actions</h1> </div> </div> <!-- /pageHeader --> <div id="pageContent"> <!-- SIDENAV --> <div id="leftNav"> <ul> <li> <a href="index.html">Home</a></li> <li> <a href="getstarted.html">Getting Started</a></li> <li> <a href="overview.html">Overview</a></li> <li> <a href="devguide.html"><div>Developer's Guide</div></a> <ul> <li> UI Surfaces <ul> <li class="leftNavSelected">Browser Actions</li> <li><a href="pageAction.html">Page Actions</a></li> <li><a href="themes.html">Themes</a></li> </ul> </li> <li> More Interaction <ul> <li><a href="bookmarks.html">Bookmarks</a></li> <li><a href="events.html">Events</a></li> <li><a href="tabs.html">Tabs</a></li> <li><a href="windows.html">Windows</a></li> </ul> </li> <li> Implementation <ul> <li><a href="background_pages.html">Background Pages</a></li> <li><a href="content_scripts.html">Content Scripts</a></li> <li><a href="xhr.html">Cross-Origin XHR</a></li> <li><a href="npapi.html">NPAPI Plugins</a></li> </ul> </li> <li> Finishing <ul> <li><a href="autoupdate.html">Autoupdating</a></li> <li><a href="packaging.html">Packaging</a></li> </ul> </li> </ul> </li> <li><a href="tutorials.html"><div>Tutorials</div></a> <ul> <li><a href="tut_debugging.html">Debugging</a></li> </ul> </li> <li>Reference <ul> <li> Formats <ul> <li><a href="manifest.html">Manifest Files</a></li> <li><a href="match_patterns.html">Match Patterns</a></li> <!-- <li>Packages (.crx)</li> --> </ul> </li> <li> <a href="api_index.html">chrome.* APIs</a> </li> <li> <a href="api_other.html">Other APIs</a> </li> </ul> </li> <li><a href="http://dev.chromium.org/developers/design-documents/extensions/samples">Samples</a></li> </ul> </div> <div id="mainColumn"> <!-- TABLE OF CONTENTS --> <div id="toc"> <p>Contents</p> <ol> <li jsinstance="0"> <a href="#icons">Icons</a> <ol> <li jsinstance="*0" style="display: none; "> <a>h3Name</a> </li> </ol> </li><li jsinstance="1"> <a href="#badges">Badges</a> <ol> <li jsinstance="*0" style="display: none; "> <a>h3Name</a> </li> </ol> </li><li jsinstance="2"> <a href="#popups">Popups</a> <ol> <li jsinstance="*0" style="display: none; "> <a>h3Name</a> </li> </ol> </li><li jsinstance="3"> <a href="#H2-3">Style Guide</a> <ol> <li jsinstance="*0" style="display: none; "> <a>h3Name</a> </li> </ol> </li><li jsinstance="*4"> <a href="#manifest">Manifest</a> <ol> <li jsinstance="*0" style="display: none; "> <a>h3Name</a> </li> </ol> </li> <div> <li> <a href="#apiReference">API reference: chrome.browserAction</a> <ol> <li style="display: none; "> <a href="#properties">Properties</a> <ol> <li> <a href="#property-anchor">propertyName</a> </li> </ol> </li> <li> <a href="#methods">Methods</a> <ol> <li jsinstance="0"> <a href="#method-setBadgeBackgroundColor">setBadgeBackgroundColor</a> </li><li jsinstance="1"> <a href="#method-setBadgeText">setBadgeText</a> </li><li jsinstance="2"> <a href="#method-setIcon">setIcon</a> </li><li jsinstance="*3"> <a href="#method-setTitle">setTitle</a> </li> </ol> </li> <li> <a href="#events">Events</a> <ol> <li jsinstance="*0"> <a href="#event-onClicked">onClicked</a> </li> </ol> </li> <li style="display: none; "> <a href="#types">Types</a> <ol> <li> <a href="#id-anchor">id</a> </li> </ol> </li> </ol> </li> </div> </ol> </div> <!-- /TABLE OF CONTENTS --> <!-- STATIC CONTENT PLACEHOLDER --> <div id="static"><div id="pageData-title" class="pageData">Browser Actions</div> <!-- BEGIN AUTHORED CONTENT --> <p>Browser actions are buttons that are displayed in the main Chrome toolbar to the right of the omnibox.</p> <img src="images/browser-action.png" width="363" height="226"> <h2 id="icons">Icons</h2> <p>Browser action icons can be up to 19px square. Larger icons will be resized to fit, but for best results, using a 19px icon is recommended.</p> <p>Icons can be set two ways: using a static image or using the HTML5 <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html">canvas element</a>. Using static images is easier for simple applications, but you can do more dynamic UIs using the canvas element. </p><p>Static images can be in any format WebKit can display. These include: png, bmp, ico, jpg, gif.</p> <h2 id="badges">Badges</h2> <p>Browser actions can optionally display a badge, which is a bit of text that is layered over the icon. Badges make it easy to update the browser action to display a small amount of information about the state of the extension.</p> <p>The badge APIs allow any length of text, but limiting badges to a max of four characters is recommended.</p> <h2 id="popups">Popups</h2> <p>Popups allow browser actions to show additional UI when the user activates them. Popups contents are implemented using HTML and the popup is automatically sized to the content size.</p> <a name="H2-3"></a><h2>Style Guide</h2> <p>For the best visual impact, we recommend observing the following guidelines:</p> <ul> <li><b>Do</b> use browser actions for features that make sense on most pages. </li><li><b>Don't</b> use browser actions for features that only make sense for a few pages. Use <a href="pageAction.html">page actions</a> instead. </li><li><b>Do</b> use big, colorful icons that fully utilize the 19px square space. Browser action icons should seem a little bigger and heavier than page action icons. </li><li><b>Don't</b> attempt to mimic Chrome's monochrome "wrench" and "page" icons. This won't work well with themes, and anyway, extensions should stand out a little. </li><li><b>Do</b> use alpha transparency to add soft edges to your icon. Remember: many users theme Chrome, so your icon should look nice on a variety of background colors. </li><li><b>Don't</b> constantly animate your icon. That's just annoying. </li></ul> <h2 id="manifest">Manifest</h2> <p>Developers declare their browser action using the following syntax:</p> <pre>"browser_action": { "default_title": "Google Mail", // Optional. Shown in tooltip. "default_icon": "images/icon19.png", // Optional. "popup": "popup.html" // Optional }</pre> <p><b>Note:</b> Even if you don't include any of the values, you must include an empty browser_action entry in your manifest so that the system knows to reserve space for your browser action in the toolbar.</p> <!-- END AUTHORED CONTENT --> </div> <!-- API PAGE --> <div class="apiPage"> <a name="apiReference"></a> <h2>API reference: chrome.browserAction</h2> <!-- PROPERTIES --> <div class="apiGroup" style="display: none; "> <a name="properties"></a> <h3 id="properties">Properties</h3> <div> <a></a> <h4>getLastError</h4> <div class="summary"> <!-- Note: intentionally longer 80 columns --> <span>chrome.extension</span><span>lastError</span> </div> <div> </div> </div> </div> <!-- /apiGroup --> <!-- METHODS --> <div class="apiGroup" id="methods"> <a name="methods"></a> <h3>Methods</h3> <!-- iterates over all functions --> <div class="apiItem" jsinstance="0"> <a name="method-setBadgeBackgroundColor"></a> <!-- method-anchor --> <h4>setBadgeBackgroundColor</h4> <div class="summary"><span style="display: none; ">void</span> <!-- Note: intentionally longer 80 columns --> <span>chrome.browserAction.setBadgeBackgroundColor</span>(<span jsinstance="*0" class="null"><span style="display: none; ">, </span><span>object</span> <var><span>details</span></var></span>)</div> <div class="description"> <p class="todo" style="display: none; ">Undocumented.</p> <p>Sets the background color for the badge.</p> <!-- PARAMETERS --> <h4>Parameters</h4> <dl> <div jsinstance="*0"> <div> <dt> <var>details</var> <em> <!-- TYPE --> <div style="display:inline"> ( <span class="optional" style="display: none; ">optional</span> <span id="typeTemplate"> <span style="display: none; "> <a> Type</a> </span> <span> <span style="display: none; "> array of <span><span></span></span> </span> <span>object</span> </span> </span> ) </div> </em> </dt> <dd class="todo"> Undocumented. </dd> <dd style="display: none; "> Description of this parameter from the json schema. </dd> <!-- OBJECT PROPERTIES --> <dd> <dl> <div jsinstance="*0"> <div> <dt> <var>color</var> <em> <!-- TYPE --> <div style="display:inline"> ( <span class="optional" style="display: none; ">optional</span> <span id="typeTemplate"> <span style="display: none; "> <a> Type</a> </span> <span> <span> array of <span><span> <span style="display: none; "> <a> Type</a> </span> <span> <span style="display: none; "> array of <span><span></span></span> </span> <span>integer</span> </span> </span></span> </span> <span style="display: none; ">paramType</span> </span> </span> ) </div> </em> </dt> <dd class="todo" style="display: none; "> Undocumented. </dd> <dd>An array of four integers in the range [0,255] that make up the ARGB color for the bakground of the badge.</dd> <!-- OBJECT PROPERTIES --> <dd style="display: none; "> <dl> <div> <div> </div> </div> </dl> </dd> </div> </div> </dl> </dd> </div> </div> </dl> <!-- RETURNS --> <h4 style="display: none; ">Returns</h4> <dl> <div style="display: none; "> <div> </div> </div> </dl> <!-- CALLBACK --> <div style="display: none; "> <div> <h4>Callback function</h4> <p> If you specify the <em>callback</em> parameter, it should specify a function that looks like this: </p> <!-- Note: intentionally longer 80 columns --> <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>);</pre> <dl> <div> <div> </div> </div> </dl> </div> </div> </div> <!-- /description --> </div><div class="apiItem" jsinstance="1"> <a name="method-setBadgeText"></a> <!-- method-anchor --> <h4>setBadgeText</h4> <div class="summary"><span style="display: none; ">void</span> <!-- Note: intentionally longer 80 columns --> <span>chrome.browserAction.setBadgeText</span>(<span jsinstance="*0" class="null"><span style="display: none; ">, </span><span>object</span> <var><span>details</span></var></span>)</div> <div class="description"> <p class="todo" style="display: none; ">Undocumented.</p> <p>Sets the badge text for the browser action. This is printed on top of the icon.</p> <!-- PARAMETERS --> <h4>Parameters</h4> <dl> <div jsinstance="*0"> <div> <dt> <var>details</var> <em> <!-- TYPE --> <div style="display:inline"> ( <span class="optional" style="display: none; ">optional</span> <span id="typeTemplate"> <span style="display: none; "> <a> Type</a> </span> <span> <span style="display: none; "> array of <span><span></span></span> </span> <span>object</span> </span> </span> ) </div> </em> </dt> <dd class="todo"> Undocumented. </dd> <dd style="display: none; "> Description of this parameter from the json schema. </dd> <!-- OBJECT PROPERTIES --> <dd> <dl> <div jsinstance="*0"> <div> <dt> <var>text</var> <em> <!-- TYPE --> <div style="display:inline"> ( <span class="optional" style="display: none; ">optional</span> <span id="typeTemplate"> <span style="display: none; "> <a> Type</a> </span> <span> <span style="display: none; "> array of <span><span></span></span> </span> <span>string</span> </span> </span> ) </div> </em> </dt> <dd class="todo" style="display: none; "> Undocumented. </dd> <dd>Any number of characters can be passed, but only about four can fit in the space.</dd> <!-- OBJECT PROPERTIES --> <dd style="display: none; "> <dl> <div> <div> </div> </div> </dl> </dd> </div> </div> </dl> </dd> </div> </div> </dl> <!-- RETURNS --> <h4 style="display: none; ">Returns</h4> <dl> <div style="display: none; "> <div> </div> </div> </dl> <!-- CALLBACK --> <div style="display: none; "> <div> <h4>Callback function</h4> <p> If you specify the <em>callback</em> parameter, it should specify a function that looks like this: </p> <!-- Note: intentionally longer 80 columns --> <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>);</pre> <dl> <div> <div> </div> </div> </dl> </div> </div> </div> <!-- /description --> </div><div class="apiItem" jsinstance="2"> <a name="method-setIcon"></a> <!-- method-anchor --> <h4>setIcon</h4> <div class="summary"><span style="display: none; ">void</span> <!-- Note: intentionally longer 80 columns --> <span>chrome.browserAction.setIcon</span>(<span jsinstance="*0" class="null"><span style="display: none; ">, </span><span>object</span> <var><span>details</span></var></span>)</div> <div class="description"> <p class="todo" style="display: none; ">Undocumented.</p> <p>Sets the icon for the browser action. The icon can be specified either as the index of one of the icons that was pre-specified in the manifest, or as the pixel data from a Canvas element. Either the path or the imageData property must be specified.</p> <!-- PARAMETERS --> <h4>Parameters</h4> <dl> <div jsinstance="*0"> <div> <dt> <var>details</var> <em> <!-- TYPE --> <div style="display:inline"> ( <span class="optional" style="display: none; ">optional</span> <span id="typeTemplate"> <span style="display: none; "> <a> Type</a> </span> <span> <span style="display: none; "> array of <span><span></span></span> </span> <span>object</span> </span> </span> ) </div> </em> </dt> <dd class="todo"> Undocumented. </dd> <dd style="display: none; "> Description of this parameter from the json schema. </dd> <!-- OBJECT PROPERTIES --> <dd> <dl> <div jsinstance="0"> <div> <dt> <var>imageData</var> <em> <!-- TYPE --> <div style="display:inline"> ( <span class="optional">optional</span> <span id="typeTemplate"> <span style="display: none; "> <a> Type</a> </span> <span> <span style="display: none; "> array of <span><span></span></span> </span> <span>any</span> </span> </span> ) </div> </em> </dt> <dd class="todo" style="display: none; "> Undocumented. </dd> <dd>Pixel data for an image. Must be an ImageData object (eg from a <code>canvas</code> element).</dd> <!-- OBJECT PROPERTIES --> <dd style="display: none; "> <dl> <div> <div> </div> </div> </dl> </dd> </div> </div><div jsinstance="1"> <div> <dt> <var>iconIndex</var> <em> <!-- TYPE --> <div style="display:inline"> ( <span class="optional">optional</span> <span id="typeTemplate"> <span style="display: none; "> <a> Type</a> </span> <span> <span style="display: none; "> array of <span><span></span></span> </span> <span>integer</span> </span> </span> ) </div> </em> </dt> <dd class="todo" style="display: none; "> Undocumented. </dd> <dd><b>Deprecated.</b> The zero-based index into the |icons| vector specified in the manifest.</dd> <!-- OBJECT PROPERTIES --> <dd style="display: none; "> <dl> <div> <div> </div> </div> </dl> </dd> </div> </div><div jsinstance="*2"> <div> <dt> <var>path</var> <em> <!-- TYPE --> <div style="display:inline"> ( <span class="optional">optional</span> <span id="typeTemplate"> <span style="display: none; "> <a> Type</a> </span> <span> <span style="display: none; "> array of <span><span></span></span> </span> <span>string</span> </span> </span> ) </div> </em> </dt> <dd class="todo" style="display: none; "> Undocumented. </dd> <dd>Relative path to an image in the extension to show in the browser action.</dd> <!-- OBJECT PROPERTIES --> <dd style="display: none; "> <dl> <div> <div> </div> </div> </dl> </dd> </div> </div> </dl> </dd> </div> </div> </dl> <!-- RETURNS --> <h4 style="display: none; ">Returns</h4> <dl> <div style="display: none; "> <div> </div> </div> </dl> <!-- CALLBACK --> <div style="display: none; "> <div> <h4>Callback function</h4> <p> If you specify the <em>callback</em> parameter, it should specify a function that looks like this: </p> <!-- Note: intentionally longer 80 columns --> <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>);</pre> <dl> <div> <div> </div> </div> </dl> </div> </div> </div> <!-- /description --> </div><div class="apiItem" jsinstance="*3"> <a name="method-setTitle"></a> <!-- method-anchor --> <h4>setTitle</h4> <div class="summary"><span style="display: none; ">void</span> <!-- Note: intentionally longer 80 columns --> <span>chrome.browserAction.setTitle</span>(<span jsinstance="*0" class="null"><span style="display: none; ">, </span><span>object</span> <var><span>details</span></var></span>)</div> <div class="description"> <p class="todo" style="display: none; ">Undocumented.</p> <p>Sets the title of the browser action. Shows up in the tooltip if the browser action is visible, and in the menu item.</p> <!-- PARAMETERS --> <h4>Parameters</h4> <dl> <div jsinstance="*0"> <div> <dt> <var>details</var> <em> <!-- TYPE --> <div style="display:inline"> ( <span class="optional" style="display: none; ">optional</span> <span id="typeTemplate"> <span style="display: none; "> <a> Type</a> </span> <span> <span style="display: none; "> array of <span><span></span></span> </span> <span>object</span> </span> </span> ) </div> </em> </dt> <dd class="todo"> Undocumented. </dd> <dd style="display: none; "> Description of this parameter from the json schema. </dd> <!-- OBJECT PROPERTIES --> <dd> <dl> <div jsinstance="*0"> <div> <dt> <var>title</var> <em> <!-- TYPE --> <div style="display:inline"> ( <span class="optional" style="display: none; ">optional</span> <span id="typeTemplate"> <span style="display: none; "> <a> Type</a> </span> <span> <span style="display: none; "> array of <span><span></span></span> </span> <span>string</span> </span> </span> ) </div> </em> </dt> <dd class="todo" style="display: none; "> Undocumented. </dd> <dd>The string the browser action should display when moused over.</dd> <!-- OBJECT PROPERTIES --> <dd style="display: none; "> <dl> <div> <div> </div> </div> </dl> </dd> </div> </div> </dl> </dd> </div> </div> </dl> <!-- RETURNS --> <h4 style="display: none; ">Returns</h4> <dl> <div style="display: none; "> <div> </div> </div> </dl> <!-- CALLBACK --> <div style="display: none; "> <div> <h4>Callback function</h4> <p> If you specify the <em>callback</em> parameter, it should specify a function that looks like this: </p> <!-- Note: intentionally longer 80 columns --> <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>);</pre> <dl> <div> <div> </div> </div> </dl> </div> </div> </div> <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- EVENTS --> <div class="apiGroup"> <a name="events"></a> <h3 id="events">Events</h3> <!-- iterates over all events --> <div class="apiItem" jsinstance="*0"> <a name="event-onClicked"></a> <h4>onClicked</h4> <div class="summary"> <!-- Note: intentionally longer 80 columns --> <span class="subdued">chrome.browserAction.</span><span>onClicked</span><span class="subdued">.addListener</span>(function(<span>Tab tab</span>) <span class="subdued">{...}</span>); </div> <div class="description"> <p class="todo" style="display: none; ">Undocumented.</p> <p>Fired when a page action button is clicked.</p> <!-- PARAMETERS --> <h4>Parameters</h4> <dl> <div jsinstance="*0"> <div> <dt> <var>tab</var> <em> <!-- TYPE --> <div style="display:inline"> ( <span class="optional" style="display: none; ">optional</span> <span id="typeTemplate"> <span> <a href="tabs.html#type-Tab">Tab</a> </span> <span style="display: none; "> <span> array of <span><span></span></span> </span> <span>paramType</span> </span> </span> ) </div> </em> </dt> <dd class="todo"> Undocumented. </dd> <dd style="display: none; "> Description of this parameter from the json schema. </dd> <!-- OBJECT PROPERTIES --> <dd style="display: none; "> <dl> <div> <div> </div> </div> </dl> </dd> </div> </div> </dl> </div> <!-- /decription --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> <div class="apiGroup" style="display: none; "> <a name="types.sort(sortByName)"></a> <h3 id="types">Types</h3> <!-- iterates over all types --> <div class="apiItem"> <a></a> <h4>type name</h4> <div> </div> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> </div> <!-- /apiPage --> </div> <!-- /mainColumn --> </div> <!-- /pageContent --> <div id="pageFooter" --=""> <p> Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 License</a>, and code samples are licensed under the <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. </p> <p> ©2009 Google </p> <!-- begin analytics --> <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> <script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script> <script type="text/javascript"> // chrome doc tracking try { var engdocs = _gat._getTracker("YT-10763712-2"); engdocs._trackPageview(); } catch(err) {} // code.google.com site-wide tracking try { _uacct="UA-18071-1"; _uanchor=1; _uff=0; urchinTracker(); } catch(e) {/* urchinTracker not available. */} </script> <!-- end analytics --> </div> <!-- /pageFooter --> </div> <!-- /container --> </body></html>