-
Notifications
You must be signed in to change notification settings - Fork 790
Expand file tree
/
Copy pathOverview.bs
More file actions
2353 lines (1875 loc) · 90.5 KB
/
Overview.bs
File metadata and controls
2353 lines (1875 loc) · 90.5 KB
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
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<pre class='metadata'>
Title: Media Queries Level 4
Group: csswg
Shortname: mediaqueries
Level: 4
Status: ED
Work Status: Exploring
ED: https://drafts.csswg.org/mediaqueries-4/
TR: https://www.w3.org/TR/mediaqueries-4/
Previous Version: http://www.w3.org/TR/2016/WD-mediaqueries-4-20160126/
Editor: Florian Rivoal, Vivliostyle, florian@rivoal.net, http://vivliostyle.com
Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/
Former Editor: Håkon Wium Lie, Opera, howcome@opera.com
Former Editor: Tantek Çelik, Mozilla, tantek@cs.standard.edu
Former Editor: Daniel Glazman, Disruptive Innovations, daniel@glazman.org
Former Editor: Anne van Kesteren, Mozilla, annevk@annevk.nl
Abstract: <a>Media Queries</a> allow authors to test and query values or features of the user agent or display device, independent of the document being rendered. They are used in the CSS @media rule to conditionally apply styles to a document, and in various other contexts and languages, such as HTML and Javascript.
Abstract:
Abstract: Media Queries Level 4 describes the mechanism and syntax of media queries, media types, and media features. It extends and supersedes the features defined in Media Queries Level 3.
Ignored Terms: min-resolution, max-resolution, none, view-mode, mediaText, DOMString
Link Defaults: css-break-3 (property) break-inside
</pre>
<h2 id="intro">
Introduction</h2>
<em>This section is not normative.</em>
HTML4 [[HTML401]] defined a mechanism to support media-dependent style sheets,
tailored for different <a>media types</a>.
For example, a document may use different style sheets for screen and for print.
In HTML, this can be written as:
<div class="example">
<pre>
<link rel="stylesheet" type="text/css" media="screen" href="style.css">
<link rel="stylesheet" type="text/css" media="print" href="print.css">
</pre>
</div>
CSS adapted and extended this functionality with its ''@media'' and ''@import'' rules,
adding the ability to query the value of individual features:
<div class="example">
Inside a CSS style sheet,
one can declare that sections apply to certain <a>media types</a>:
<pre>
@media screen {
* { font-family: sans-serif }
}
</pre>
Similarly, stylesheets can be conditionally imported based on media queries:
<pre>@import "print-styles.css" print;</pre>
</div>
<a>Media queries</a> can be used with HTML, XHTML, XML [[XMLSTYLE]] and the @import and @media rules of CSS.
<div class="example">
Here is the same example written in HTML, XHTML, XML, @import and @media:
<pre>
<link media="screen and (color), projection and (color)"
rel="stylesheet" href="example.css">
<link media="screen and (color), projection and (color)"
rel="stylesheet" href="example.css" />
<?xml-stylesheet media="screen and (color), projection and (color)"
rel="stylesheet" href="example.css" ?>
@import url(example.css) screen and (color), projection and (color);
@media screen and (color), projection and (color) { … }
</pre>
Note: The [[XMLSTYLE]] specification has not yet been updated to
use media queries in the <code>media</code> pseudo-attribute.
</div>
<h3 id="placement">
Module interactions</h3>
This module replaces and extends the Media Queries, Media Type and Media Features
defined in [[!CSS21]] sections 7 and in [[!MEDIAQ]].
<h3 id="values">
Values</h3>
Value types not defined in this specification, such as <<integer>>,
<<number>> or <<resolution>>, are defined in [[!CSS3VAL]]. Other CSS
modules may expand the definitions of these value types.
<h3 id="units">
Units</h3>
The units used in media queries are the same as in other parts of CSS, as
defined in [[!CSS3VAL]]. For example, the pixel unit represents CSS pixels and
not physical pixels.
<a spec="css-values">Relative length</a> units in media queries are based on the <a>initial value</a>, which means
that units are never based on results of declarations. For example, in HTML,
the ''em'' unit is relative to the <a>initial value</a> of 'font-size',
defined by the user agent or the user's preferences,
not any styling on the page.
<!--
██ ██ ███████
███ ███ ██ ██
████ ████ ██ ██
██ ███ ██ ██ ██
██ ██ ██ ██ ██
██ ██ ██ ██
██ ██ █████ ██
-->
<h2 id="media">
Media Queries</h2>
A <dfn export>media query</dfn> is a method of testing certain aspects of the user agent
or device that the document is being displayed in.
<a>Media queries</a> are (almost) always independent of the contents of the document,
its styling,
or any other internal aspect;
they're only dependent on “external” information
unless another feature explicitly specifies that it affects the resolution of Media Queries,
such as the ''@viewport'' rule.
The syntax of a <a>media query</a> consists of
an optional <a>media query modifier</a>,
an optional <a>media type</a>,
and zero or more <a>media features</a>:
<pre class='railroad'>
Or:
N: media condition
And:
Or: 1
T: only
S:
T: not
N: media type
Opt:
And:
T: and
N: media condition
</pre>
A <a>media query</a> is a logical expression that is either true or false.
A media query is true if:
* the <a>media type</a>,
if specified,
matches the media type of the device where the user agent is running, and
* the <a>media condition</a> is true.
Statements regarding media queries in this section assume the <a href="#mq-syntax">syntax section</a> is followed.
Media queries that do not conform to the syntax are discussed in [[#error-handling]].
I.e. the syntax takes precedence over requirements in this section.
<div class="example">
Here is a simple example written in HTML:
<pre><link rel="stylesheet" media="screen and (color)" href="example.css" /></pre>
This example expresses that a certain style sheet
(<code>example.css</code>) applies to devices of a certain media type
(''screen'') with certain feature (it must be a color screen).
Here is the same media query written in an @import-rule in CSS:
<pre>@import url(example.css) screen and (color);</pre>
</div>
User agents must re-evaluate <a>media queries</a> in response to changes in the user environment that they're aware of,
for example if the device is tiled from landscape to portrait orientation,
and change the behavior of any constructs dependent on those <a>media queries</a> accordingly.
Unless another feature explicitly specifies that it affects the resolution of Media Queries, it is never necessary to apply a style sheet in order to evaluate expressions.
Note: CSS Device Adaptation [[CSS-DEVICE-ADAPT]]]
defines how ''@viewport'' rules interact with Media Queries.
<h3 id='mq-list'>
Combining Media Queries</h3>
Several <a>media queries</a> can be combined into a comma-separated <dfn export>media query list</dfn>.
<pre class='railroad'>
Star:
N: media query
T: ,
</pre>
A <a>media query list</a> is true if <em>any</em> of its component <a>media queries</a> are true,
and false only if <em>all</em> of its component <a>media queries</a> are false.
<div class="example">
For example, the following <a>media query list</a> is true if either
the <a>media type</a> is ''screen'' and it's a color device,
<strong>or</strong> the <a>media type</a> is ''projection'' and it's a color device:
<pre>
@media screen and (color), projection and (color) { … }
</pre>
</div>
An empty <a>media query list</a> evaluates to true.
<div class="example">
For example, these are equivalent:
<pre>
@media all { … }
@media { … }
</pre>
</div>
<h3 id='mq-prefix'>
Media Query Modifiers</h3>
A <a>media query</a> may optionally be prefixed by a single <dfn export>media query modifier</dfn>,
which is a single keyword which alters the meaning of the following <a>media query</a>.
<h4 id='mq-not'>
Negating a Media Query: the ''not'' keyword</h4>
An individual <a>media query</a> can have its result negated
by prefixing it with the keyword <dfn value for="@media">not</dfn>.
If the <a>media query</a> would normally evaluate to true,
prefixing it with ''not'' makes it evaluate to false,
and vice versa.
<div class="example">
For example, the following will apply to everything except color-capable screens.
Note that the entire media query is negated,
not just the <a>media type</a>.
<pre><link rel="stylesheet" media="not screen and (color)" href="example.css" /></pre>
</div>
<h4 id='mq-only'>
Hiding a Media Query From Legacy User Agents: the ''only'' keyword</h4>
The concept of <a>media queries</a> originates from HTML4 [[HTML401]].
That specification only defined <a>media types</a>,
but had a forward-compatible syntax that accommodated the addition of future concepts like <a>media features</a>:
it would consume the characters of a <a>media query</a> up to the first non-alphanumeric character,
and interpret that as a <a>media type</a>,
ignoring the rest.
For example, the <a>media query</a> ''screen and (color)''
would be truncated to just ''screen''.
Unfortunately, this means that legacy user agents using this error-handling behavior
will ignore any <a>media features</a> in a <a>media query</a>,
even if they're far more important than the <a>media type</a> in the query.
This can result in styles accidentally being applied in inappropriate situations.
To hide these <a>media queries</a> from legacy user agents,
the <a>media query</a> can be prefixed with the keyword <dfn value for="@media">only</dfn>.
The ''only'' keyword <strong>has no effect</strong> on the <a>media query</a>’s result,
but will cause the <a>media query</a> to be parsed by legacy user agents
as specifying the unknown <a>media type</a> “only”,
and thus be ignored.
<div class="example">
In this example, the stylesheet specified by the <code><link></code> element
will not be used by legacy user agents,
even if they would normally match the ''screen'' <a>media type</a>.
<pre><link rel="stylesheet" media="only screen and (color)" href="example.css" /></pre>
</div>
Note: Note that the ''only'' keyword can only be used before a <a>media type</a>.
A <a>media query</a> consisting only of <a>media features</a>,
or one with another <a>media query modifier</a> like ''not'',
will be treated as false by legacy user agents automatically.
Note: At the time of publishing this specification,
such legacy user agents are extremely rare,
and so using the ''only'' modifier is rarely, if ever, necessary.
<!--
████████ ██ ██ ████████ ████████ ██████
██ ██ ██ ██ ██ ██ ██ ██
██ ████ ██ ██ ██ ██
██ ██ ████████ ██████ ██████
██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██
██ ██ ██ ████████ ██████
-->
<h3 id='media-types'>
Media Types</h3>
A <dfn export>media type</dfn> is a broad category of user-agent devices
on which a document may be displayed.
The original set of <a>media types</a> were defined in HTML4,
for the <code>media</code> attribute on <code><link></code> elements.
Unfortunately, <a>media types</a> have proven insufficient as a way of discriminating between devices with different styling needs.
Some categories which were originally quite distinct,
such as ''screen'' and ''handheld'',
have blended significantly in the years since their invention.
Others, such as ''tty'' or ''tv'',
expose useful differences from the norm of a full-featured computer monitor,
and so are potentially useful to target with different styling,
but the definition of <a>media types</a> as mutually exclusive
makes it difficult to use them in a reasonable manner;
instead, their exclusive aspects are better expressed as <a>media features</a>
such as 'grid' or 'scan'.
As such, the following <a>media types</a> are defined for use in <a>media queries</a>:
<dl dfn-type=value dfn-for="@media">
<dt><dfn>all</dfn>
<dd>Matches all devices.
<dt><dfn>print</dfn>
<dd>Matches printers, and devices intended to reproduce a printed display,
such as a web browser showing a document in “Print Preview”.
<dt><dfn>screen</dfn>
<dd>Matches all devices that aren't matched by ''print'' or ''speech''.
<dt><dfn>speech</dfn>
<dd>Matches screenreaders and similar devices that “read out” a page.
</dl>
In addition, the following <strong>deprecated</strong> <a>media types</a> are defined.
Authors must not use these <a>media types</a>;
instead, it is recommended that they select appropriate <a>media features</a>
that better represent the aspect of the device that they are attempting to style against.
User agents must recognize the following <a>media types</a> as valid,
but must make them match nothing.
<ul dfn-type=value dfn-for="@media">
<li><dfn>tty</dfn>
<li><dfn>tv</dfn>
<li><dfn>projection</dfn>
<li><dfn>handheld</dfn>
<li><dfn>braille</dfn>
<li><dfn>embossed</dfn>
<li><dfn>aural</dfn>
</ul>
Note: It is expected that all of the media types will also be deprecated in time,
as appropriate <a>media features</a> are defined which capture their important differences.
<!--
████████ ████████ ███ ████████ ██ ██ ████████ ████████ ██████
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██████ ██████ ██ ██ ██ ██ ██ ████████ ██████ ██████
██ ██ █████████ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ████████ ██ ██ ██ ███████ ██ ██ ████████ ██████
-->
<h3 id='mq-features'>
Media Features</h3>
A <dfn export>media feature</dfn> is a more fine-grained test than <a>media types</a>,
testing a single, specific feature of the user agent or display device.
Syntactically, <a>media features</a> resemble CSS properties:
they consist of a feature name, a colon, and a value to test for.
They may also be written in boolean form as just a feature name,
or in range form with a comparison operator.
<pre class='railroad'>
T: (
Choice:
And:
N: feature name
T: :
N: feature value
N: feature name
And:
N: range form
C: (see below)
T: )
</pre>
There are, however, several important differences between properties and media features:
<ul>
<li>
Properties are used to give information about how to present a document.
Media features are used to describe requirements of the output device.
<li>
Media features are always wrapped in parentheses
and combined with the ''and'' keyword,
like ''(color) and (min-width: 600px)'',
rather than being separated with semicolons.
<li>
A media feature may be given with <em>only</em> its name
(omitting the colon and value)
to evaluate the feature in a <a>boolean context</a>.
This is a convenient shorthand for features that have a reasonable value representing 0 or “none”.
For example, ''(color)'' is true is the 'color' <a>media feature</a> is non-zero.
<li>
<a>Media features</a> with “range” type can be written in a <a>range context</a>,
which uses standard mathematical comparison operators rather than a colon,
or have their feature names <a href=#mq-min-max>prefixed with “min-” or “max-”</a>.
<li>
Properties sometimes accept complex values,
e.g., calculations that involve several other values.
<a>Media features</a> only accept single values: one keyword, one number, etc.
</ul>
If a <a>media feature</a> references a concept which does not exist on the device where the UA is running
(for example, speech UAs do not have a concept of “width”),
the <a>media feature</a> must always evaluate to false.
<div class="example">
The media feature ''device-aspect-ratio'' only applies to
visual devices. On an ''speech'' device, expressions involving
''device-aspect-ratio'' will therefore always be false:
<pre>
<link media="speech and (device-aspect-ratio: 16/9)"
rel="stylesheet" href="example.css">
</pre>
</div>
<h4 id='mq-ranges'>
Media Feature Types: “range” and “discrete”</h4>
Every media feature defines its “type” as either “range” or “discrete” in its definition table.
“Discrete” media features,
like 'light-level' or 'scripting',
take their values from a set.
The values may be keywords
or boolean numbers (0 and 1),
but the common factor is that there's no intrinsic “order” to them--
none of the values are “less than” or “greater than” each other.
“Range” media features like 'width', on the other hand,
take their values from a range.
Any two values can be compared to see which is lesser and which is greater.
The only significant difference between the two types is that “range” <a>media features</a>
can be evaluated in a <a>range context</a>
and accept “min-” and “max-” prefixes on their name.
Doing either of these changes the meaning of the feature--
rather than the <a>media feature</a> being true when the feature exactly matches the given value,
it matches when the feature is greater than/less than/equal to the given value.
<div class='example'>
A <span class=css data-link-type=maybe>(width >= 600px)</span> <a>media feature</a> is true
when the viewport's width is ''600px'' <em>or more</em>.
On the other hand, ''(width: 600px)'' by itself is only true
when the viewport's width is <em>exactly</em> ''600px''.
If it's less or greater than ''600px'', it'll be false.
</div>
<!--
████████ ███████ ███████ ██ ████████ ███ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██
████████ ██ ██ ██ ██ ██ ██████ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ █████████ ██ ████
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███
████████ ███████ ███████ ████████ ████████ ██ ██ ██ ██
-->
<h4 id='mq-boolean-context'>
Evaluating Media Features in a Boolean Context</h4>
While <a>media features</a> normally have a syntax similar to CSS properties,
they can also be written more simply as just the feature name,
like ''(color)''.
When written like this, the <a>media feature</a> is evaluated in a <dfn export>boolean context</dfn>.
If the feature would be true for any value
<em>other than</em> the number ''0'',
a <<dimension>> with the value ''0'',
or the keyword ''none'',
the <a>media feature</a> evaluates to true.
Otherwise, it evaluates to false.
<div class='example'>
Some <a>media features</a> are designed to be written like this.
For example, 'scripting' is typically written as ''(scripting)'' to test if scripting is enabled,
or ''not (scripting)'' to see if it's disabled.
It can still be given an explicit value as well,
with ''(scripting: enabled)'' equal to ''(scripting)'',
and ''(scripting: none)'' equal to ''not (scripting)''.
</div>
<div class='example'>
Some numeric <a>media features</a>, like 'width',
are rarely if ever useful to evaluate in a <a>boolean context</a>,
as their values are almost always greater than zero.
Others, like 'color', have meaningful zero values:
''(color)'' is identical to ''(color > 0)'',
indicating that the device is capable of displaying color at all.
</div>
<div class='example'>
Only some of the <a>media features</a> that accept keywords are meaningful in a <a>boolean context</a>.
For example, ''(pointer)'' is useful,
as 'pointer' has a ''pointer/none'' value to indicate there's no pointing device at all on the device.
On the other hand, ''(scan)'' is just always true or always false
(depending on whether it applies at all to the device),
as there's no value that means “false”.
</div>
<!--
████████ ███ ██ ██ ██████ ████████
██ ██ ██ ██ ███ ██ ██ ██ ██
██ ██ ██ ██ ████ ██ ██ ██
████████ ██ ██ ██ ██ ██ ██ ████ ██████
██ ██ █████████ ██ ████ ██ ██ ██
██ ██ ██ ██ ██ ███ ██ ██ ██
██ ██ ██ ██ ██ ██ ██████ ████████
-->
<h4 id="mq-range-context">
Evaluating Media Features in a Range Context</h4>
<a>Media features</a> with a “range” type can be alternately written in a <dfn export>range context</dfn>
that takes advantage of the fact that their values are ordered,
using ordinary mathematical comparison operators:
<pre class='railroad'>
T: (
Choice:
Seq:
N: feature name/value
Choice: 4
T: =
T: <
T: <=
T: >
T: >=
N: feature value/name
Seq:
N: value
Choice:
T: <
T: <=
N: feature name
Choice:
T: <
T: <=
N: value
Seq:
N: value
Choice:
T: >
T: >=
N: feature name
Choice:
T: >
T: >=
N: value
T: )
</pre>
Note: This syntax is new to Level 4 of Mediaqueries,
and thus is not as widely supported at the moment
as the ''min-''/''max-'' prefixes.
The basic form,
consisting of a feature name,
a comparison operator,
and a value,
returns true if the relationship is true.
<div class='example'>
For example, ''(height > 600px)''
(or ''(600px < height)'')
returns true if the viewport height is greater than ''600px''.
</div>
The remaining forms,
with the feature name nested between two value comparisons,
returns true if both comparisons are true.
<div class='example'>
For example, ''(400px < width < 1000px)'' returns true if the viewport width is between ''400px'' and ''1000px''
(but not equal to either).
</div>
<!--
██ ██ ████ ██ ██ ██ ██ ██ ███ ██ ██
███ ███ ██ ███ ██ ██ ███ ███ ██ ██ ██ ██
████ ████ ██ ████ ██ ██ ████ ████ ██ ██ ██ ██
██ ███ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██ ██ ███
██ ██ ██ ██ ████ ██ ██ ██ █████████ ██ ██
██ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ██
██ ██ ████ ██ ██ ██ ██ ██ ██ ██ ██ ██
-->
<h4 id='mq-min-max'>
Using “min-” and “max-” Prefixes On Range Features</h4>
Rather than evaluating a “range” type <a>media feature</a> in a range context,
as described above,
the feature may be written as a normal <a>media feature</a>,
but with a “min-” or “max-” prefix on the feature name.
This is equivalent to evaluating the feature in a <a>range context</a>,
as follows:
<ul>
<li>
Using a “min-” prefix on a feature name is equivalent to using the “>=” operator.
For example, ''(min-height: 600px)'' is equivalent to <span class=css data-link-type=maybe>(height >= 600px)</span>.
<li>
Using a “max-” prefix on a feature name is equivalent to using the “<=” operator.
For example, ''(max-width: 40em)'' is equivalent to <span class=css data-link-type=maybe>(width <= 40em)</span>.
</ul>
“Discrete” type properties do not accept “min-” or “max-” prefixes.
Adding such a prefix to a “discrete” type <a>media feature</a> simply results in an unknown feature name.
<div class='example'>
For example,
''(min-grid: 1)'' is invalid,
because 'grid' is a “discrete” <a>media feature</a>,
and so doesn't accept the prefixes.
(Even though the 'grid' <a>media feature</a> appears to be numeric,
as it accepts the values ''0'' and ''1''.)
</div>
Attempting to evaluate a min/max prefixed <a>media feature</a> in a <a>boolean context</a>
is invalid and a syntax error.
Combining Media Features {#media-conditions}
--------------------------------------------
Multiple <a>media features</a> can be combined together into a <dfn export>media condition</dfn>
using full boolean algebra
(not, and, or).
Issue: TODO: Fill this in.
<!--
██████ ██ ██ ██ ██ ████████ ███ ██ ██
██ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██
██ ████ ████ ██ ██ ██ ██ ██ ██
██████ ██ ██ ██ ██ ██ ██ ██ ███
██ ██ ██ ████ ██ █████████ ██ ██
██ ██ ██ ██ ███ ██ ██ ██ ██ ██
██████ ██ ██ ██ ██ ██ ██ ██ ██
-->
<h2 id='mq-syntax'>
Syntax</h2>
Informal descriptions of the media query syntax appear in the prose and railroad diagrams in previous sections.
The formal media query syntax is described in this section,
with the rule/property grammar syntax defined in [[!CSS3SYN]] and [[!CSS3VAL]].
To parse a <dfn><media-query-list></dfn> production,
<a>parse a comma-separated list of component values</a>,
then parse each entry in the returned list as a <<media-query>>.
Its value is the list of <<media-query>>s so produced.
Note: This explicit definition of <<media-query-list>> parsing
is necessary to make the error-recovery behavior of <a>media query lists</a> well-defined.
Note: This definition of <<media-query-list>> parsing intentionally accepts an empty list.
<pre>
<dfn><media-query></dfn> = <<media-condition>>
| [ not | only ]? <<media-type>> [ and <<media-condition-without-or>> ]?
<dfn><media-type></dfn> = <<ident>>
<dfn><media-condition></dfn> = <<media-not>> | <<media-and>> | <<media-or>> | <<media-in-parens>>
<dfn><media-condition-without-or></dfn> = <<media-not>> | <<media-and>> | <<media-in-parens>>
<dfn><media-not></dfn> = not <<media-in-parens>>
<dfn><media-and></dfn> = <<media-in-parens>> [ and <<media-in-parens>> ]+
<dfn><media-or></dfn> = <<media-in-parens>> [ or <<media-in-parens>> ]+
<dfn><media-in-parens></dfn> = ( <<media-condition>> ) | <<media-feature>> | <<general-enclosed>>
<dfn><media-feature></dfn> = ( [ <<mf-plain>> | <<mf-boolean>> | <<mf-range>> ] )
<dfn><mf-plain></dfn> = <<mf-name>> : <<mf-value>>
<dfn><mf-boolean></dfn> = <<mf-name>>
<dfn><mf-range></dfn> = <<mf-name>> [ '<' | '>' ]? '='? <<mf-value>>
| <<mf-value>> [ '<' | '>' ]? '='? <<mf-name>>
| <<mf-value>> '<' '='? <<mf-name>> '<' '='? <<mf-value>>
| <<mf-value>> '>' '='? <<mf-name>> '>' '='? <<mf-value>>
<dfn><mf-name></dfn> = <<ident>>
<dfn><mf-value></dfn> = <<number>> | <<dimension>> | <<ident>> | <<ratio>>
<dfn><general-enclosed></dfn> = [ <<function-token>> <<any-value>> ) ] | ( <<ident>> <<any-value>> )
</pre>
The <<media-type>> production does not include the keywords ''only'', ''not'', ''and'', and ''or''.
No whitespace is allowed between the “<” or “>” <<delim-token>>s and the following “=” <<delim-token>>,
if it's present.
Whitespace <em>must</em> be present between a ')' character and a ''not'', ''and'', or ''or'' keyword,
and between a ''not'', ''and'', or ''or'' keyword and a '(' character.
When parsing the <<media-in-parens>> production,
the <<general-enclosed>> branch must only be chosen if the input does not match either of the preceding branches.
<span class='note'><<general-enclosed>> exists to allow for future expansion of the grammar in a reasonably compatible way.</span>
Evaluating Media Queries {#evaluating}
--------------------------------------
Each of the major terms of <<media-condition>> or <<media-condition-without-or>> is associated with a boolean result, as follows:
<dl>
<dt><<media-condition>>
<dt><<media-condition-without-or>>
<dt><<media-in-parens>>
<dd>
The result is the result of the child term.
<dt><<media-not>>
<dd>
The result is the negation of the <<media-in-parens>> term.
The negation of unknown is unknown.
<dt><<media-and>>
<dd>
The result is true if all of the <<media-in-parens>> child terms are true,
false if at least one of the <<media-in-parens>> child terms are false,
and unknown otherwise.
<dt><<media-or>>
<dd>
The result is false if all of the <<media-in-parens>> child terms are false,
true if at least one of the <<media-in-parens>> child terms are true,
and unknown otherwise.
<dt><<general-enclosed>>
<dd>
The result is unknown.
Authors must not use <<general-enclosed>> in their stylesheets.
<span class='note'>It exists only for future-compatibility,
so that new syntax additions do not invalidate too much of a <<media-condition>> in older user agents.</span>
<dt><<media-feature>>
<dd>
The result is the result of evaluating the specified media feature.
</dl>
If the result of any of the above productions
is used in any context that expects a two-valued boolean,
“unknown” must be converted to “false”.
Note: This means that,
for example,
when a <a>media query</a> is used in a ''@media'' rule,
if it resolves to “unknown” it's treated as “false”
and fails to match.
<div class="note">
Media Queries use a three-value logic where terms can be “true”, “false”, or “unknown”.
Specifically, it uses the <a href="http://en.wikipedia.org/wiki/Three-valued_logic#Kleene_and_Priest_logics">Kleene 3-valued logic</a>.
In this logic, “unknown” means “either true or false, but we're not sure which yet”.
In general, an unknown value showing up in a formula will cause the formula to be unknown as well,
as substituting “true” for the unknown will give the formula a different result than substituting “false”.
The only way to eliminate an unknown value is to use it in a formula that will give the same result
whether the unknown is replaced with a true or false value.
This occurs when you have “false AND unknown” (evaluates to false regardless)
and “true OR unknown” (evaluates to true regardless).
This logic was adopted because <<general-enclosed>> needs to be assigned a truth value.
In standard boolean logic, the only reasonable value is “false”,
but this means that ''not unknown(function)'' is true,
which can be confusing and unwanted.
Kleen's 3-valued logic ensures that unknown things will prevent a <a>media query</a> from matching,
unless their value is irrelevant to the final result.
</div>
<h3 id="error-handling">
Error Handling</h3>
A media query that does not match the grammar in the previous section must be replaced by ''not all'' during parsing.
Note: Note that a grammar mismatch does <strong>not</strong> wipe out an entire <a>media query list</a>,
just the problematic <a>media query</a>.
The parsing behavior defined above automatically recovers at the next top-level comma.
<div class='example'>
<pre>
@media (example, all,), speech { /* only applicable to speech dev
8D6D
ices */ }
@media &test, speech { /* only applicable to speech devices */ }
</pre>
Both of the above <a>media query lists</a> are turned into ''not all, speech'' during parsing,
which has the same truth value as just ''speech''.
Note that error-recovery only happens at the top-level of a <a>media query</a>;
anything inside of an invalid parenthesized block
will just get turned into ''not all'' as a group.
For example:
<pre>
@media (example, speech { /* rules for speech devices */ }
</pre>
Because the parenthesized block is unclosed,
it will contain the entire rest of the stylesheet from that point
(unless it happens to encounter an unmatched “)” character somewhere in the stylesheet),
and turn the entire thing into a ''not all'' <a>media query</a>.
</div>
An unknown <<media-type>> must be treated as not matching.
<div class='example'>
For example, the media query ''unknown'' is false,
as ''unknown'' is an unknown <a>media type</a>.
But ''not unknown'' is true, as the ''not'' negates the false media type.
</div>
<div class='example'>
Remember that some keywords aren't allowed as <<media-type>>s
and cause parsing to fail entirely:
the media query ''or and (color)'' is turned into ''not all'' during parsing,
rather than just treating the ''or'' as an unknown <a>media type</a>.
</div>
An unknown <<mf-name>> or <<mf-value>>, or disallowed <<mf-value>>,
results in the value “unknown”.
A <<media-query>> whose value is “unknown” must be replaced with ''not all''.
<div class="example">
<pre><link media="screen and (max-weight: 3kg) and (color), (color)"
rel="stylesheet" href="example.css" /></pre>
As ''max-weight'' is an unknown <a>media feature</a>,
this <a>media query list</a> is turned into ''not all, (color)'',
which is equivalent to just ''(color)''.
</div>
<div class="example">
<pre>@media (min-orientation:portrait) { … }</pre>
The 'orientation' feature does not accept prefixes,
so this is considered an unknown <a>media feature</a>,
and turned into ''not all''.
</div>
<div class="example">
The media query ''(color:20example)'' specifies an unknown value for the 'color' media feature
and is therefore turned into ''not all''.
</div>
<div class="example">
This media query is turned into ''not all'' because negative lengths are not allowed for the 'width' media feature:
<pre>@media (min-width: -100px) { … }</pre>
</div>
<div class='note'>
Note that <a>media queries</a> are also subject to the parsing rules of the host language.
For example, take the following CSS snippet:
<pre> @media test;,all { body { background:lime } }</pre>
The media query ''test;,all'' is, parsed by itself,
equivalent to ''not all, all'', which is always true.
However, CSS's parsing rules cause the ''@media'' rule,
and thus the <a>media query</a>,
to end at the semicolon.
The remainder of the text is treated as a style rule
with an invalid selector and contents.
</div>
<!--
████████ ████ ██ ██ ████████ ██ ██ ██████ ████ ███████ ██ ██ ██████
██ ██ ██ ███ ███ ██ ███ ██ ██ ██ ██ ██ ██ ███ ██ ██ ██
██ ██ ██ ████ ████ ██ ████ ██ ██ ██ ██ ██ ████ ██ ██
██ ██ ██ ██ ███ ██ ██████ ██ ██ ██ ██████ ██ ██ ██ ██ ██ ██ ██████
██ ██ ██ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ████ ██
██ ██ ██ ██ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ███ ██ ██
████████ ████ ██ ██ ████████ ██ ██ ██████ ████ ███████ ██ ██ ██████
-->
<h2 id="mf-dimensions">
Screen/Device Dimensions Media Features</h2>
<h3 id="width">
width</h3>
<pre class='descdef mq'>
Name: width
Value: <<length>>
For: @media
Type: range
</pre>
The '@media/width' media feature describes the width of the targeted display area of the output device.
For continuous media, this is the width of the viewport
(as described by CSS2, section 9.1.1 [[!CSS21]])
including the size of a rendered scroll bar (if any).
For paged media, this is the width of the page box
(as described by CSS2, section 13.2 [[!CSS21]]).
<<length>>s are interpreted according to [[#units]].
Negative <<length>>s are invalid.
<div class="example">
For example, this media query expresses that the style sheet is used on printed output wider than 25cm:
<pre><link rel="stylesheet" media="print and (min-width: 25cm)" href="http://…" /></pre>
</div>
<div class="example">
This media query expresses that the style sheet is used on devices with viewport
(the part of the screen/paper where the document is rendered)
widths between 400 and 700 pixels:
<pre>@media (400px <= min-width <= 700px) { … }</pre>
</div>
<div class="example">
This media query expresses that style sheet is used if the width of the viewport is greater than 20em.
<pre>@media (min-width: 20em) { … }</pre>
The ''em'' value is relative to the <a>initial value</a> of 'font-size'.
</div>
<h3 id="height">
height</h3>
<pre class='descdef mq'>
Name: height
Value: <<length>>
For: @media
Type: range
</pre>
The 'height' media feature describes the height of the targeted display area of the output device.
For continuous media, this is the height of the viewport including the size of a rendered scroll bar (if any).
For paged media, this is the height of the page box.
<<length>>s are interpreted according to [[#units]].
Negative <<length>>s are invalid.
<h3 id='aspect-ratio'>
aspect-ratio</h3>
<pre class='descdef mq'>
Name: aspect-ratio
Value: <<ratio>>
For: @media
Type: range
</pre>
The 'aspect-ratio' media feature is defined as the ratio of the value of the 'width' media feature
to the value of the 'height' media feature.
The <dfn type><ratio></dfn> value type is a positive (not zero or negative)
<<integer>> followed by optional whitespace, followed by a solidus ('/'),
followed by optional whitespace, followed by a positive <<integer>>.
<<ratio>>s can be ordered or compared by transforming them into the number
obtained by dividing their first <<integer>> by their second <<integer>>.
<h3 id='orientation'>
orientation</h3>
<pre class='descdef mq'>
Name: orientation
Value: portrait | landscape
For: @media
Type: discrete
</pre>
<dl dfn-type=value dfn-for="@media/orientation">
<dt><dfn>portrait</dfn>
<dd>The 'orientation' media feature is ''portrait''
when the value of the 'height' media feature is greater than or equal to
the value of the 'width' media feature.
<dt><dfn>landscape</dfn>
<dd>Otherwise 'orientation' is ''landscape''.