This repository has been archived by the owner on Apr 20, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 235
/
supported-css3-features.html
454 lines (335 loc) · 21.1 KB
/
supported-css3-features.html
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
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
<!DOCTYPE html>
<html>
<head>
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
<title>PIE Documentation: Supported CSS3 Features</title>
</head>
<body>
<h1>Supported CSS3 Features</h1>
<!-- noformat on -->
<p>The following sections describe in detail the exact levels of support PIE has for certain CSS3 properties
and value types.</p>
<ul>
<li><a href="#border-radius">border-radius</a></li>
<li><a href="#box-shadow">box-shadow</a></li>
<li><a href="#border-image">border-image</a></li>
<li><a href="#pie-background">CSS3 Backgrounds (-pie-background)</a></li>
<li><a href="#gradients">Gradients</a></li>
<li><a href="#rgba">RGBA Color Values</a></li>
<li><a href="#custom">PIE Custom Properties</a>
<ul>
<li><a href="#pie-load-path">-pie-load-path</a></li>
<li><a href="#pie-watch-ancestors">-pie-watch-ancestors</a></li>
<li><a href="#pie-png-fix">PNG alpha transparency and -pie-png-fix</a></li>
<li><a href="#pie-lazy-init">Lazy Initialization (-pie-lazy-init)</a></li>
<li><a href="#pie-poll">Layout polling (-pie-poll)</a></li>
<li><a href="#pie-track-hover">:hover tracking (-pie-track-hover)</a></li>
<li><a href="#pie-track-active">:active tracking (-pie-track-active)</a></li>
</ul>
</li>
</ul>
<h2 id="border-radius">border-radius</h2>
<p>PIE fully supports the <a href="http://www.w3.org/TR/css3-background/#the-border-radius">border-radius
property syntax</a> as defined in the CSS3 Backgrounds and Borders module specification for IE 6-8. IE 9
and up support border-radius natively so PIE does nothing.</p>
<pre class="long">border-radius: [ <length> | <percentage> ]{1,4} [ / [ <length> | <percentage> ]{1,4} ]?</pre>
<p>Only the shorthand version is supported; the longhand
border-top-left-radius etc. properties are not. The shorthand syntax does support different radii per corner, though:</p>
<p><code>border-radius: 5px 10px 15px 20px;</code> (top-left, top-right, bottom-right, bottom-left).</p>
<p>The rounded corners are applied to the element's background area
(including solid background colors, background images, and background
gradients), the element's border, and the box-shadow if specified.</p>
<p>Both the standard border-radius property name as well as a custom
prefixed -pie-border-radius property name are recognized; if both are
present then the prefixed value will take precedence. It is recommended
to only use the standard unprefixed property when possible.</p>
<h2 id="box-shadow">box-shadow</h2>
<p>PIE supports the <a href="http://www.w3.org/TR/css3-background/#the-box-shadow">box-shadow property syntax</a>
as defined in the CSS3 Backgrounds & Borders module, for IE 6-8. IE 9 and up support
box-shadow natively so PIE does nothing.</p>
<pre class="long">box-shadow: none | <shadow> [,<shadow>]*
where <shadow> = inset? && [ <offset-x> <offset-y> <blur-radius>? <spread-radius>? && <color>? ]</pre>
<p>Both the standard box-shadow property name as well as a custom
prefixed -pie-box-shadow property name are recognized; if both are
present the prefixed value will take precedence. It is recommended to
use the non-prefixed property when possible.</p>
<p>When used in conjunction with border-radius, the shape of the shadow
matches the shape of the rounded border box.</p>
<p>The shadow shape rendered by PIE is, unlike other browsers,
<a href="https://github.com/lojjic/PIE/issues/12">opaque in the area behind the element's background</a>.
This means that if your element has a transparent or semi-transparent background, the opaque shadow will
show through. To avoid this you must either give the element a non-transparent background, or remove the
box-shadow.</p>
<p>PIE does not currently support the 'inset' keyword, but support is
planned in a future version (see <a href="http://github.com/lojjic/PIE/issues#issue/3">issue #3</a>.</p>
<p>If you specify an rgba color in conjunction with a blur radius, the color will be rendered at full
opacity in PIE 1.0. This is fixed as of PIE 2.0 beta.</p>
<p>Notes on other browsers:</p>
<p>See the compatibility chart at the bottom of
<a href="https://developer.mozilla.org/En/CSS/-moz-box-shadow">https://developer.mozilla.org/En/CSS/-moz-box-shadow</a></p>
<h2 id="border-image">border-image</h2>
<p>PIE adds support for the border-image property to IE 6-9. This property allows
you to specify an image which gets divided into nine squares which are then drawn as
the corners, sides, and center of the target element.</p>
<p>There are currently a few limitations of PIE's implementation, including:</p>
<ol>
<li>It only supports the 'stretch' scheme in IE 6-8. (The other schemes ('repeat' and 'round') are
fully supported in IE 9.)</li>
<li>It doesn't support the <a href="http://dev.w3.org/csswg/css3-background/#border-image-outset">outset parameter</a>
described in the Backgrounds & Borders module spec, though other browsers don't seem to support
that yet either.</li>
<li>It requires the 'fill' keyword to be present for the center area to be filled in. This is correct
behavior according to the spec but other browsers don't require it and some even fail if 'fill' is
present, so it's a bit tricky making it work consistently across browsers.</li>
<li>In PIE 1.0, there are on rare occasion rounding errors which cause 1px gaps between slices of the
image. I've seen these gaps occur in other browsers too, though. This seems to be fixed as of PIE 2.0 beta.</li>
</ol>
<h2 id="pie-background">CSS3 Backgrounds (-pie-background)</h2>
<p>PIE supports CSS3 multiple background images, linear gradients as
background images, and some of the new CSS3 background aspects such as
background origin and clip. Unfortunately, to get access to these
post-CSS2 values, we have to put them in a property other than the
standard 'background' property, because IE will attempt to parse the
value internally and not allow us access to the original value string.
Therefore we use a custom -pie-background property for holding these
values.</p>
<p>(Note that IE9 and up support multiple background images natively, so PIE only
takes over in IE 6-8. It also takes over in IE 9 when there is a gradient present in the
-pie-background -- see the section on <a href="#gradients">gradients</a> below.)</p>
<p>Only the single -pie-background shorthand value is recognized; longhand values (e.g.
background-origin) are ignored.</p>
<p>For backward-compatibility with browsers which do not support CSS3
backgrounds, be sure to include appropriate fallbacks. For example:</p>
<pre class="long"><code>#myElement {
background: url(bg-image.png) no-repeat #CCC; /*non-CSS3 browsers will use this*/
background: url(bg-image.png) no-repeat, -webkit-gradient(linear, 0 0, 0 100%, from(#CCC) to(#EEE)); /*old webkit*/
background: url(bg-image.png) no-repeat, -webkit-linear-gradient(#CCC, #EEE); /*new webkit*/
background: url(bg-image.png) no-repeat, -moz-linear-gradient(#CCC, #EEE); /*gecko*/
background: url(bg-image.png) no-repeat, -ms-linear-gradient(#CCC, #EEE); /*IE10 preview*/
background: url(bg-image.png) no-repeat, -o-linear-gradient(#CCC, #EEE); /*opera 11.10+*/
background: url(bg-image.png) no-repeat, linear-gradient(#CCC, #EEE); /*future CSS3 browsers*/
-pie-background: url(bg-image.png) no-repeat, linear-gradient(#CCC, #EEE); /*PIE*/
}</code></pre>
<p>While the PIE parser will allow them, the following aspects of the
background shorthand will currently be ignored when rendering in IE 6-8:</p>
<ul>
<li>background-attachment (will always use 'scroll' even if 'fixed'
or 'local' are specified)</li>
<li>background-size (will always use the image's intrinsic size) — this is supported as of PIE 2.0 beta</li>
<li>background-repeat values of 'space' or 'round' (the other repeat
values are supported)</li>
<li>background-origin (will always use 'padding-box') — this is supported as of PIE 2.0 beta</li>
<li>background-clip (will always use 'border-box') — this is supported as of PIE 2.0 beta</li>
<li>background-position values with more than 2 parts</li>
</ul>
<p>Support for these items will be added in future versions as possible.</p>
<p>Note that PNG background images specified using <code>-pie-background</code> will be
rendered with correct alpha channel transparency in IE6. See the section below regarding
<a href="#pie-png-fix">PNG alpha transparency</a> for more information.</p>
<p>Notes on other browsers:</p>
<p>See <a href="https://developer.mozilla.org/en/CSS/Multiple_backgrounds">https://developer.mozilla.org/en/CSS/Multiple_backgrounds</a></p>
<h2 id="gradients">Gradients</h2>
<p>PIE currently supports <code>linear-gradient</code> image values when used in the
-pie-background property, for IE 6-9. Uses of linear-gradient in any contexts other than the -pie-background
are not supported.</p>
<p>The supported syntax matches that of the CSS3 Image Values module — PIE 1.0 uses the old
<a href="http://www.w3.org/TR/2011/WD-css3-images-20110712/#linear-gradients">2011 working draft
syntax</a>, whereas PIE 2.0 beta uses the <a href="http://www.w3.org/TR/css3-images/#linear-gradients">final
syntax</a>. If you upgrade from PIE 1.0 to 2.0 beta, then you must make sure you update your CSS to the
final syntax — e.g. use "to right" instead of "left", and adjust any angles to be clockwise from vertical.</p>
<pre class="long">linear-gradient([<bg-position> || <angle>,]? <color-stop>, <color-stop>[, <color-stop>]*);</pre>
<p>PIE's linear-gradient support in IE 6-8 has a few limitations (all of these work
properly in IE 9):</p>
<ul>
<li>In PIE 1.0, all color stops are rendered fully opaque in IE 6-8, even if
specifying an rgba color value. As of PIE 2.0 beta, rgba alpha is rendered
properly in IE 6-8, but only if the gradient has two color stops. (See
<a href="http://github.com/lojjic/PIE/issues#issue/7">issue #7</a>)</li>
<li>Gradients containing color-stops which lie outside the bounding area
of the element are not currently supported, due to limitations in VML's
gradient rendering.</li>
<li>The background-size/origin/repeat/position parameters are not supported
for gradients in IE 6-8, so you cannot do things like
<a href="http://leaverou.me/2010/12/checkered-stripes-other-background-patterns-with-css3-gradients/">gradient pattern effects</a>.</li>
</ul>
<p>Radial gradients are not supported at this time; this feature is planned
for a future release (see <a href="http://github.com/lojjic/PIE/issues#issue/2">issue #2</a>)
but it may turn out to be impossible to implement in IE 6-8 due to VML's strange radial gradient behavior.</p>
<p>Notes on other browsers:</p>
<p>Some other browsers require a vendor prefix on the linear-gradient name, e.g. -moz-linear-gradient for Firefox
or -webkit-linear-gradient for WebKit browsers.</p>
<p>Adding in PIE's required -pie-background property, you will need a set of styles similar to the following
to get consistent linear gradient backgrounds across browsers:</p>
<pre class="long"><code>#myElement {
background: #CCC; /*fallback for non-CSS3 browsers*/
background: -webkit-gradient(linear, 0 0, 0 100%, from(#CCC) to(#EEE)); /*old webkit*/
background: -webkit-linear-gradient(top, #CCC, #EEE); /*newer webkit*/
background: -moz-linear-gradient(top, #CCC, #EEE); /*old gecko*/
background: -o-linear-gradient(top, #CCC, #EEE); /*opera 11.10+*/
background: linear-gradient(to bottom, #CCC, #EEE); /*firefox 16+, chrome 26+, IE10+, opera 12.10+, future browsers*/
-pie-background: linear-gradient(to bottom, #CCC, #EEE); /*ie 6-9 via PIE*/
behavior: url(PIE.htc);
}</code></pre>
<p>For more detailed information on the current state of linear-gradient across browsers, see this
<a href="http://www.webdirections.org/blog/css3-linear-gradients/">article by John Allsopp</a> and
the <a href="https://developer.mozilla.org/en-US/docs/CSS/linear-gradient">MDN linear-gradient docs</a>.</p>
<h2 id="rgba">RGBA Color Values</h2>
<p>PIE parses RGBA color values wherever they are allowed. However it
is only able to successfully render their opacity value in a few
contexts. In all other contexts they will be rendered with the correct
RGB color, but fully opaque. Here are the supported contexts in which
the opacity will be rendered correctly:</p>
<ul>
<li>The solid background-color as specified in the -pie-background property.</li>
<li>The color value of box-shadow. In PIE 1.0 this works only if the shadow has no blur, but
it works with blur as well in the PIE 2.0 beta.</li>
<li>Color stops in linear-gradient. In PIE 1.0 this works for IE 9 only (rgba colors will be
rendered fully opaque in IE 6-8.) In the PIE 2.0 beta it works for IE 6-8 as well, but only
if the gradient has only two color stops.</li>
</ul>
<h2 id="custom">PIE custom properties</h2>
<h3 id="pie-load-path">-pie-load-path (applies to PIE 2.0 beta only)</h3>
<p>As of PIE 2.0 beta, the PIE.htc behavior file is a very lightweight loader that loads in
a secondary JS file containing the logic needed by the current IE version. By default, it loads
that secondary JS file from the same server path as the PIE.htc behavior file itself.</p>
<p>If you wish to override the location from which the JS files will be loaded, you can add
the custom -pie-load-path property into your CSS for the <html> element:</p>
<pre><code>html {
-pie-load-path: "http://any.server/path/to/pie-js-files/";
}</code></pre>
<p>This can be any path, on any server, and is not subject to the same-domain restriction of the
HTC file. This can be useful, for example, if you want to host the JS files on a
<abbr title="Content Delivery Network">CDN</abbr> to take advantage of geolocated caching
for performance.</p>
<h3 id="pie-watch-ancestors">-pie-watch-ancestors</h3>
<p>PIE automatically listens for any attribute or style property
changes on the element to which the behavior is applied. This means
that if you have scripting which modifies any of the recognized CSS3
properties on the fly, those changes will automatically be picked up
and the rendering will be updated to match. For example:</p>
<pre><code>/* JS: */
myElement.onclick = function() {
this.style.borderRadius = '20px';
};
/* CSS: */
#myElement {
behavior: url(PIE.htc);
border-radius: 10px;
}</code></pre>
<p>Assuming myElement has the PIE.htc behavior attached to it, the
above code will work as expected without any extra effort from the
author of the script or CSS. This seamlessness is a big part of why PIE
is so easy to use.</p>
<p>But common best-practices in scripting dictate that instead of
setting styles directly with element.style.foo, scripts should only
add/remove elements' class names, letting the actual styles
corresponding to those class names be maintained in the CSS. So
reworking the above example:</p>
<pre><code>/* JS: */
myElement.onclick = function() {
this.className += ' poked';
}
/* CSS: */
#myElement {
behavior: url(PIE.htc);
border-radius: 10px;
}
#myElement.poked {
border-radius: 20px;
}</code></pre>
<p>Again, since the className is being changed on the element to which
the behavior is applied, PIE will automatically be notified of the
change and update the border-radius rendering to match the new value.</p>
<p>However, what if the className is changed not on the element itself
but on one of its ancestors?</p>
<pre><code>/* JS: */
myElement.onclick = function() {
this.parentNode.className += ' poked';
}
/* CSS: */
#myElement {
behavior: url(PIE.htc);
border-radius: 10px;
}
.poked #myElement {
border-radius: 20px;
}</code></pre>
<p>This is a very common pattern which allows a lot of flexibility.
However, in this case, PIE will not be automatically notified of the
className change. To be notified, it will also have to add a listener
to the ancestor element. We could brute-force this by automatically
adding propertychange listeners to all the ancestors of every
PIE-targeted element, but that would be bad for performance and memory
usage. So instead, we have introduced a custom CSS property which
allows authors to tell PIE that certain ancestors should be watched:</p>
<pre><code>/* JS: */
myElement.onclick = function() {
this.parentNode.className += ' poked';
}
/* CSS: */
#myElement {
behavior: url(PIE.htc);
border-radius: 10px;
<strong>-pie-watch-ancestors: 1;</strong>
}
.poked #myElement {
border-radius: 20px;
}</code></pre>
<p>This tells PIE that it should watch for changes on ancestors one
level up from the element. It will attach the propertychange listener
to the element's parent and therefore be notified when the parent's
className gets changed, and update the rendering correctly.
</p>
<h3 id="pie-png-fix">PNG alpha transparency and -pie-png-fix</h3>
<p>A nice side-effect of PIE's use of VML for rendering is that it causes PNG images
with alpha channel transparency to be correctly displayed in IE6 when they are rendered
by PIE's engine. This includes:</p>
<ul>
<li>Background images specified using the <a href="#pie-background">-pie-background</a> property</li>
<li>Background images specified using the standard <code>background-image</code> style, when used
in conjunction with other CSS3 properties that trigger re-rendering of the background
(border-radius, border-image)</li>
<li><img> elements that have border-radius applied</li>
</ul>
<p>Sometimes you might want the benefit of the fixed PNG transparency, on elements that do not meet
the criteria above. In that case, you can add the custom property <code>-pie-png-fix: true;</code> to
force re-rendering of the background-image or <img>. (The PIE.htc behavior must also be
attached to the element.)</p>
<h3 id="pie-lazy-init">Lazy Initialization (-pie-lazy-init)</h3>
<p>While PIE has been optimized for speed, there is still a small cost in rendering performance for each element
it is applied to. When you have dozens or hundreds of elements on your page with CSS3 styles applied, this
can add up to a noticeable rendering delay.</p>
<p>When you have that many elements on one page, chances are that only a small number of them are visible
in the browser viewport initially, as viewing the rest would require scrolling. PIE allows an optional
optimization for this case: if you apply the custom <code>-pie-lazy-init:true;</code> property to elements
PIE will delay the initialization of their CSS3 rendering until they are scrolled into the viewport. This
keeps the initial page load snappy without severely limiting the number of elements you can render.</p>
<h3 id="pie-poll">Layout Polling (-pie-poll)</h3>
<p>In general PIE is quite good at detecting changes to the size and position of the elements to which it
is attached and automatically adjusting its rendering to match. It does this by listening to the IE-specific
<code>onmove</code> and <code>onresize</code> events for each target element. In the majority of cases this
works seamlessly; in rare cases, however, IE does not fire these events when it should, and PIE gets out of sync.</p>
<p>To help users get around these cases, PIE has a second method for tracking size and position changes: polling.
When polling is enabled for an element, PIE will manually query that element's layout several times a second, and
if the layout has changed then it will adjust the rendering.</p>
<p>Polling is enabled by default for all elements in IE 8 and 9 (as those version is particularly bad about not firing
the events) and disabled in IE 6 and 7. Users can override these defaults
to force polling on or off for individual elements by setting a custom CSS property: just specify
<code>-pie-poll:true;</code> to force polling on for an element, or <code>-pie-poll:false;</code> to disable it.</p>
<h3 id="pie-track-hover">Hover tracking (-pie-track-hover)</h3>
<p>By default, PIE automatically listens for mouseover/out events and applies any matching <code>:hover</code>
styles if supported by the browser. In addition, it adds a special <code>pie_hover</code> class to the element
which you can use to apply hover styles in versions of IE that don't support it.</p>
<p>If you want to disable this, you can do so by setting the custom CSS style <code>-pie-track-hover:false;</code>
for the element. This might be useful if you notice sluggishness on your page when hovering and you don't need
hover styles.</p>
<h3 id="pie-track-active">Active tracking (-pie-track-active)</h3>
<p>By default, PIE automatically listens for mousedown/up events and applies any matching <code>:active</code>
styles if supported by the browser. In addition, it adds a special <code>pie_active</code> class to the element
which you can use to apply active styles in versions of IE that don't support it.</p>
<p>If you want to disable this, you can do so by setting the custom CSS style <code>-pie-track-active:false;</code>
for the element. This is useful in some situations where the addition of the pie_active class has unwanted
side effects, for instance breaking the behavior of <a href="https://github.com/lojjic/PIE/issues/190">scrollbars in IE7</a>.</p>
<!-- noformat off -->
</body>
</html>