1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
<div id="pageData-name" class="pageData">Browser Actions</div>
<!-- BEGIN AUTHORED CONTENT -->
<p>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>.
</p>
<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="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>
<p class="caution">
<strong>Note:</strong>
Packaged apps cannot use browser actions.
</p>
<!-- [PENDING: We should show tooltips and badges, as well.] -->
<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": "images/icon19.png", <em>// optional</em>
"default_title": "Google Mail", <em>// optional; shown in tooltip</em>
"default_popup": "popup.html" <em>// optional</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 pixels wide and high.
Larger icons are resized to fit, but for best results,
use a 19-pixel 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 <a href="#method-setIcon">setIcon()</a> method.
<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 <a href="#method-setTitle">setTitle()</a> 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
<a href="#method-setBadgeText">setBadgeText()</a> and
<a href="#method-setBadgeBackgroundColor">setBadgeBackgroundColor()</a>,
respectively.
<!-- [PENDING: if you have a color but no text, will anything display?] -->
</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
<a href="#method-setPopup">setPopup()</a> method.
</p>
<h2>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 "wrench" 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>
<!-- END AUTHORED CONTENT -->
|
