Abstract
This
specification
defines
a
means
to
receive
events
that
correspond
to
a
light
sensor
detecting
the
presence
of
a
light.
Status
of
This
Document
This
section
describes
the
status
of
this
document
at
the
time
of
its
publication.
Other
documents
may
supersede
this
document.
A
list
of
current
W3C
publications
and
the
latest
revision
of
this
technical
report
can
be
found
in
the
W3C
technical
reports
index
at
http://www.w3.org/TR/.
The
following
changes
have
been
made
since
the
W3C
Candidate
Recommendation
01
October
2013
:
The
functionality
described
in
this
specification
was
initially
specified
as
part
of
the
Sensor
API
but
has
been
extracted
in
order
to
be
more
straightforward
to
implement,
and
in
order
to
produce
a
specification
that
could
be
implemented
on
its
own
merits
without
interference
with
other
features.
Changes
since
Last
Call
include
addition
of
a
new
security
considerations
section,
clarification
of
lux
level
light
values,
clarifications
to
the
text
and
processing
description
and
updated
references
and
the
addition
of
a
WebIDL
reference.
These
changes
include
updates
to
address
Last
Call
comments
that
were
received
(
disposition
of
comments
).
A
diff
showing
changes
since
the
Last
Call
publication
is
available
(
diff
).
The
CR
exit
criterion
is
two
interoperable
deployed
implementations
of
each
feature,
with
no
features
marked
as
'at-risk'.
The
group
will
create
an
Implementation
Report
.
This
document
was
published
by
the
Device
APIs
Working
Group
as
a
Candidate
Recommendation.
Last
Call
Working
Draft.
This
document
is
intended
to
become
a
W3C
Recommendation.
If
you
wish
to
make
comments
regarding
this
document,
please
send
them
to
public-device-apis@w3.org
(
subscribe
,
archives
).
W3C
publishes
a
Candidate
Recommendation
to
indicate
that
the
document
is
believed
to
be
stable
and
to
encourage
implementation
by
the
developer
community.
This
Candidate
Recommendation
is
expected
to
advance
to
Proposed
Recommendation
no
earlier
than
21
November
2013.
The
Last
Call
period
ends
24
July
2014.
All
comments
are
welcome.
Publication
as
a
Candidate
Recommendation
Last
Call
Working
Draft
does
not
imply
endorsement
by
the
W3C
Membership.
This
is
a
draft
document
and
may
be
updated,
replaced
or
obsoleted
by
other
documents
at
any
time.
It
is
inappropriate
to
cite
this
document
as
other
than
work
in
progress.
This
is
a
Last
Call
Working
Draft
and
thus
the
Working
Group
has
determined
that
this
document
has
satisfied
the
relevant
technical
requirements
and
is
sufficiently
stable
to
advance
through
the
Technical
Recommendation
process.
This
document
was
produced
by
a
group
operating
under
the
5
February
2004
W3C
Patent
Policy
.
W3C
maintains
a
public
list
of
any
patent
disclosures
made
in
connection
with
the
deliverables
of
the
group;
that
page
also
includes
instructions
for
disclosing
a
patent.
An
individual
who
has
actual
knowledge
of
a
patent
which
the
individual
believes
contains
Essential
Claim(s)
must
disclose
the
information
in
accordance
with
section
6
of
the
W3C
Patent
Policy
.
5.
Device
Light
The
5.1
Extensions
to
DeviceLightEvent
Window
interface
provides
information
about
the
ambient
light
levels,
as
detected
by
the
device's
light
detector,
in
terms
of
lux
units.
Interface
The
HTML5
specification
[
HTML5
]
defines
a
Window
interface,
which
this
specification
extends:
partial interface Window {
attribute EventHandler ondevicelight;
};
The
ondevicelight
event
handler
and
its
corresponding
event
handler
event
type
devicelight
MUST
be
supported
as
an
IDL
attribute
by
all
objects
implementing
the
Window
interface.
{
dictionary DeviceLightEventInit : EventInit {
unrestricted double value;
};
[Constructor (DOMString type, optional DeviceLightEventInit eventInitDict)]
interface {
interface DeviceLightEvent : Event {
readonly attribute unrestricted double value;
};
The
value
attribute
of
the
DeviceLightEvent
interface
MUST
return
the
value
it
was
initialized
to.
When
the
object
is
created,
this
attribute
MUST
be
initialized
to
positive
Infinity.
It
represents
the
current
light
level
.
Note
The
precise
lux
value
reported
by
different
devices
in
the
same
light
can
be
different,
due
to
differences
in
detection
method,
sensor
construction
etc.
When
a
user
agent
is
required
to
fire
a
device
light
event
,
the
user
agent
MUST
run
the
following
steps:
-
Create
an
event
that
uses
the
DeviceLightEvent
interface,
with
the
name
devicelight
,
which
bubbles,
is
not
cancelable,
and
has
no
default
action,
that
also
meets
the
following
conditions:
-
If
the
implementation
is
unable
to
report
the
current
light
level
,
initialize
the
value
attribute
to
positive
Infinity,
otherwise
initialize
the
attribute
to
the
current
light
level
.
When
the
current
light
level
changes,
the
user
agent
MUST
queue
a
task
to
fire
a
device
light
event
at
the
top-level
browsing
context
's
Window
object.
Note
The
definition
of
granularity
i.e.
how
often
the
event
is
fired
is
left
to
the
implementation.
Implementations
can
fire
the
event
if
they
have
reason
to
believe
that
the
page
does
not
have
sufficiently
fresh
data.
5.1.1
5.2.1
Event
handlers
The
following
are
the
event
handlers
(and
their
corresponding
event
handler
event
types
)
that
MUST
be
supported
as
attributes
by
the
Window
object:
|
event
handler
|
event
handler
event
type
|
ondevicelight
|
devicelight
|
6.
Light
Level
The
LightLevelEvent
interface
provides
information
about
the
ambient
light
levels,
as
detected
by
the
device's
light
detector,
in
terms
of
three
general
range:
"dim",
"normal",
or
"bright".
The
HTML5
specification
[
HTML5
]
defines
a
Window
interface,
which
this
specification
extends:
{
};
The
onlightlevel
event
handler
and
its
corresponding
event
handler
event
type
lightlevel
MUST
be
supported
as
an
IDL
attribute
by
all
objects
implementing
the
Window
interface.
6.1
LightLevelEvent
Interface
{
"",
"",
"",
""
}; {
};]
interface {
};
The
value
attribute
of
the
LightLevelEvent
interface
MUST
return
the
value
it
was
initialized
to.
When
the
object
is
created,
this
attribute
MUST
be
initialized
to
an
empty
string
.
It
represents
the
current
light
level
state
.
When
a
user
agent
is
required
to
fire
a
light
level
event
,
the
user
agent
MUST
run
the
following
steps:
Create
an
event
that
uses
the
LightLevelEvent
interface,
with
the
name
lightlevel
,
which
bubbles,
is
not
cancelable,
and
has
no
default
action,
that
also
meets
the
following
conditions:
If
the
implementation
is
unable
to
report
the
current
light
level
state
,
initialize
the
value
attribute
to
an
empty
string
,
otherwise
initialize
the
attribute
to
the
current
light
level
state
,
which
MUST
be
one
of
the
following
values:
dim
normal
bright
Note
The
lux
ranges
that
map
to
the
current
light
level
state
s
are
left
to
the
implementation,
as
devices
with
different
sensitivities
could
map
them
slightly
differently.
However,
it
is
recommended
that
"
dim
"
correspond
to
ambient
light
below
50
lux
(dark
enough
that
the
light
produced
by
a
white
background
is
eye-straining
or
distracting),
"
normal
"
correspond
to
light
between
50
lux
and
10000
lux
(office
building
hallway,
very
dark
overcast
day,
office
lighting,
sunrise
or
sunset
on
a
clear
day,
overcast
day,
or
similar),
and
"
bright
"
correspond
to
light
above
10000
lux
(direct
sunlight,
or
similarly
bright
conditions
that
make
it
hard
to
see
things
that
aren't
high-contrast).
When
the
current
light
level
state
changes,
the
user
agent
MUST
queue
a
task
to
fire
a
user
proximity
event
at
the
top-level
browsing
context
's
Window
object.
Note
The
definition
of
granularity
i.e.
how
often
the
event
is
fired
is
left
to
the
implementation.
Implementations
can
fire
the
event
if
they
have
reason
to
believe
that
the
page
does
not
have
sufficiently
fresh
data.
6.1.1
Event
handlers
The
following
are
the
event
handlers
(and
their
corresponding
event
handler
event
types
)
that
MUST
be
supported
as
attributes
by
the
Window
object:
event
handler
event
handler
event
type
onlightlevel
lightlevel
A.
Acknowledgements
Doug
Turner
for
the
initial
prototype
and
Marcos
Caceres
for
the
test
suite.