| <p> |
| In the following figure, |
| the multicolored square |
| to the right of the address bar |
| is the icon for a browser action. |
| A popup is below the icon. |
| </p> |
| |
| <img src="{{static}}/images/browser-action.png" |
| width="363" height="226" /> |
| |
| <p> |
| If you want to create an icon that isn't always visible, |
| use a <a href="pageAction.html">page action</a> |
| instead of a browser action. |
| </p> |
| |
| <h2 id="manifest">Manifest</h2> |
| |
| <p> |
| Register your browser action in the |
| <a href="manifest.html">extension manifest</a> |
| like this: |
| </p> |
| |
| <pre>{ |
| "name": "My extension", |
| ... |
| <b>"browser_action": { |
| "default_icon": { <em>// optional</em> |
| "19": "images/icon19.png", <em>// optional</em> |
| "38": "images/icon38.png" <em>// optional</em> |
| }, |
| "default_title": "Google Mail", <em>// optional; shown in tooltip</em> |
| "default_popup": "popup.html" <em>// optional</em> |
| }</b>, |
| ... |
| }</pre> |
| |
| <p> |
| If you only provide one of the 19px or 38px icon size, the extension system will |
| scale the icon you provide to the pixel density of the user's display, which |
| can lose detail or make it look fuzzy. The old syntax for registering the |
| default icon is still supported: |
| </p> |
| |
| <pre>{ |
| "name": "My extension", |
| ... |
| <b>"browser_action": { |
| ... |
| "default_icon": "images/icon19.png" <em>// optional</em> |
| <em>// equivalent to "default_icon": { "19": "images/icon19.png" }</em> |
| }</b>, |
| ... |
| }</pre> |
| |
| <h2 id="ui">Parts of the UI</h2> |
| |
| <p> |
| A browser action can have an <a href="#icon">icon</a>, |
| a <a href="#tooltip">tooltip</a>, |
| a <a href="#badge">badge</a>, |
| and a <a href="#popups">popup</a>. |
| </p> |
| |
| <h3 id="icon">Icon</h3> |
| |
| <p>Browser action icons can be up to 19 dips (device-independent pixels) |
| wide and high. Larger icons are resized to fit, but for best results, |
| use a 19-dip square icon.</p> |
| |
| <p>You can set the icon in 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 create more dynamic UIs — |
| such as smooth animation — |
| using the canvas element. |
| </p> |
| |
| <p>Static images can be in any format WebKit can display, |
| including BMP, GIF, ICO, JPEG, or PNG. |
| </p> |
| |
| <p>To set the icon, |
| use the <b>default_icon</b> field of <b>browser_action</b> |
| in the <a href="#manifest">manifest</a>, |
| or call the $ref:browserAction.setIcon method. |
| </p> |
| |
| <p>To properly display icon when screen pixel density (ratio |
| <code>size_in_pixel / size_in_dip</code>) is different than 1, |
| the icon can be defined as set of images with different sizes. |
| The actual image to display will be selected from the set to |
| best fit the pixel size of 19 dip icon. |
| At the moment, the icon set can contain images with pixel sizes 19 and 38. |
| </p> |
| |
| <h3 id="tooltip">Tooltip</h3> |
| |
| <p> |
| To set the tooltip, |
| use the <b>default_title</b> field of <b>browser_action</b> |
| in the <a href="#manifest">manifest</a>, |
| or call the $ref:browserAction.setTitle method. |
| You can specify locale-specific strings for the <b>default_title</b> field; |
| see <a href="i18n.html">Internationalization</a> for details. |
| </p> |
| |
| <h3 id="badge">Badge</h3> |
| |
| <p>Browser actions can optionally display a <em>badge</em> — |
| 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>Because the badge has limited space, |
| it should have 4 characters or less. |
| </p> |
| |
| <p> |
| Set the text and color of the badge using |
| $ref:browserAction.setBadgeText and |
| $ref:browserAction.setBadgeBackgroundColor, |
| respectively. |
| |
| </p> |
| |
| |
| <h3 id="popups">Popup</h3> |
| |
| <p>If a browser action has a popup, |
| the popup appears when the user clicks the icon. |
| The popup can contain any HTML contents that you like, |
| and it's automatically sized to fit its contents. |
| </p> |
| |
| <p> |
| To add a popup to your browser action, |
| create an HTML file with the popup's contents. |
| Specify the HTML file in the <b>default_popup</b> field of <b>browser_action</b> |
| in the <a href="#manifest">manifest</a>, or call the |
| $ref:browserAction.setPopup method. |
| </p> |
| |
| <h2 id="tips">Tips</h2> |
| |
| <p>For the best visual impact, |
| follow these guidelines:</p> |
| |
| <ul> |
| <li><b>Do</b> use browser actions for features |
| that make sense on most pages. |
| <li><b>Don't</b> use browser actions for features |
| that make sense for only a few pages. |
| Use <a href="pageAction.html">page actions</a> instead. |
| <li><b>Do</b> use big, colorful icons that make the most of |
| the 19x19-pixel space. |
| Browser action icons should seem a little bigger |
| and heavier than page action icons. |
| <li><b>Don't</b> attempt to mimic |
| Google Chrome's monochrome menu icon. |
| That doesn't work well with themes, and anyway, |
| extensions should stand out a little. |
| <li><b>Do</b> use alpha transparency |
| to add soft edges to your icon. |
| Because many people use themes, |
| your icon should look nice |
| on a variety of background colors. |
| <li><b>Don't</b> constantly animate your icon. |
| That's just annoying. |
| </ul> |
| |
| <h2 id="examples"> Examples </h2> |
| |
| <p> |
| You can find simple examples of using browser actions in the |
| <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/browserAction/">examples/api/browserAction</a> |
| directory. |
| For other examples and for help in viewing the source code, see |
| <a href="samples.html">Samples</a>. |
| </p> |