1 <div id="pageData-name" class="pageData">Browser Actions</div> 2 3 <!-- BEGIN AUTHORED CONTENT --> 4 <p>Use browser actions to put icons 5 in the main Google Chrome toolbar, 6 to the right of the address bar. 7 In addition to its <a href="#icon">icon</a>, 8 a browser action can also have 9 a <a href="#tooltip">tooltip</a>, 10 a <a href="#badge">badge</a>, 11 and a <a href="#popups">popup</a>. 12 </p> 13 14 <p> 15 In the following figure, 16 the multicolored square 17 to the right of the address bar 18 is the icon for a browser action. 19 A popup is below the icon. 20 </p> 21 22 <img src="images/browser-action.png" 23 width="363" height="226" /> 24 25 <p> 26 If you want to create an icon that isn't always visible, 27 use a <a href="pageAction.html">page action</a> 28 instead of a browser action. 29 </p> 30 31 <p class="caution"> 32 <strong>Note:</strong> 33 Packaged apps cannot use browser actions. 34 </p> 35 36 <!-- [PENDING: We should show tooltips and badges, as well.] --> 37 38 <h2 id="manifest">Manifest</h2> 39 40 <p> 41 Register your browser action in the 42 <a href="manifest.html">extension manifest</a> 43 like this: 44 </p> 45 46 <pre>{ 47 "name": "My extension", 48 ... 49 <b>"browser_action": { 50 "default_icon": "images/icon19.png", <em>// optional</em> 51 "default_title": "Google Mail", <em>// optional; shown in tooltip</em> 52 "default_popup": "popup.html" <em>// optional</em> 53 }</b>, 54 ... 55 }</pre> 56 57 <h2 id="ui">Parts of the UI</h2> 58 59 <p> 60 A browser action can have an <a href="#icon">icon</a>, 61 a <a href="#tooltip">tooltip</a>, 62 a <a href="#badge">badge</a>, 63 and a <a href="#popups">popup</a>. 64 </p> 65 66 <h3 id="icon">Icon</h3> 67 68 <p>Browser action icons can be up to 19 pixels wide and high. 69 Larger icons are resized to fit, but for best results, 70 use a 19-pixel square icon.</p> 71 72 <p>You can set the icon in two ways: 73 using a static image or using the 74 HTML5 <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html">canvas element</a>. 75 Using static images is easier for simple applications, 76 but you can create more dynamic UIs — 77 such as smooth animation — 78 using the canvas element. 79 </p> 80 81 <p>Static images can be in any format WebKit can display, 82 including BMP, GIF, ICO, JPEG, or PNG. 83 </p> 84 85 <p>To set the icon, 86 use the <b>default_icon</b> field of <b>browser_action</b> 87 in the <a href="#manifest">manifest</a>, 88 or call the <a href="#method-setIcon">setIcon()</a> method. 89 90 91 <h3 id="tooltip">Tooltip</h3> 92 93 <p> 94 To set the tooltip, 95 use the <b>default_title</b> field of <b>browser_action</b> 96 in the <a href="#manifest">manifest</a>, 97 or call the <a href="#method-setTitle">setTitle()</a> method. 98 You can specify locale-specific strings for the <b>default_title</b> field; 99 see <a href="i18n.html">Internationalization</a> for details. 100 </p> 101 102 <h3 id="badge">Badge</h3> 103 104 <p>Browser actions can optionally display a <em>badge</em> — 105 a bit of text that is layered over the icon. 106 Badges make it easy to update the browser action 107 to display a small amount of information 108 about the state of the extension.</p> 109 110 <p>Because the badge has limited space, 111 it should have 4 characters or less. 112 </p> 113 114 <p> 115 Set the text and color of the badge using 116 <a href="#method-setBadgeText">setBadgeText()</a> and 117 <a href="#method-setBadgeBackgroundColor">setBadgeBackgroundColor()</a>, 118 respectively. 119 <!-- [PENDING: if you have a color but no text, will anything display?] --> 120 </p> 121 122 123 <h3 id="popups">Popup</h3> 124 125 <p>If a browser action has a popup, 126 the popup appears when the user clicks the icon. 127 The popup can contain any HTML contents that you like, 128 and it's automatically sized to fit its contents. 129 </p> 130 131 <p> 132 To add a popup to your browser action, 133 create an HTML file with the popup's contents. 134 Specify the HTML file in the <b>default_popup</b> field of <b>browser_action</b> 135 in the <a href="#manifest">manifest</a>, or call the 136 <a href="#method-setPopup">setPopup()</a> method. 137 </p> 138 139 <h2>Tips</h2> 140 141 <p>For the best visual impact, 142 follow these guidelines:</p> 143 144 <ul> 145 <li><b>Do</b> use browser actions for features 146 that make sense on most pages. 147 <li><b>Don't</b> use browser actions for features 148 that make sense for only a few pages. 149 Use <a href="pageAction.html">page actions</a> instead. 150 <li><b>Do</b> use big, colorful icons that make the most of 151 the 19x19-pixel space. 152 Browser action icons should seem a little bigger 153 and heavier than page action icons. 154 <li><b>Don't</b> attempt to mimic 155 Google Chrome's monochrome "wrench" icon. 156 That doesn't work well with themes, and anyway, 157 extensions should stand out a little. 158 <li><b>Do</b> use alpha transparency 159 to add soft edges to your icon. 160 Because many people use themes, 161 your icon should look nice 162 on a variety of background colors. 163 <li><b>Don't</b> constantly animate your icon. 164 That's just annoying. 165 </ul> 166 167 <h2 id="examples"> Examples </h2> 168 169 <p> 170 You can find simple examples of using browser actions in the 171 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/browserAction/">examples/api/browserAction</a> 172 directory. 173 For other examples and for help in viewing the source code, see 174 <a href="samples.html">Samples</a>. 175 </p> 176 177 <!-- END AUTHORED CONTENT --> 178
