Skip to content

[css-variables] Add User Agent properties and constant() #1817

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

[css-variables] Add User Agent properties and constant() #1817

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 141 additions & 0 deletions css-variables/Overview.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -634,6 +634,66 @@ Variables in Shorthand Properties</h3>
then the serialized value of the shorthand must be the empty string.


<h2 id='user-agent-properties'>
User Agent Properties</h2>

This specification defines an open-ended set of properties called <a>User Agent properties</a>,
which, among other things, are used to define potential <a lt="substitute a constant()">substitution values</a>
of ''constant()'' functions.

<pre class='propdef'>
Name: (various)
Value: <<declaration-value>>
Initial: (nothing, see prose)
Applies to: all elements
Inherited: yes
Computed value: specified value with variables substituted (but see prose for "invalid variables")
Media: all
Animatable: no
</pre>

A <dfn export>User Agent property</dfn> is not specified in a style sheet. User Agent properties
instead define variables, referenced with the ''constant()'' notation.
For example, a page that wants to use the user's requested font sizing, and page
background:

<div class='example'>
<pre>
:root {
font-size: constant(user-font-size);
}

body {
background-color: constant(user-background-color);
}
</pre>

Note that 'user-font-size' and 'user-background-color' are
simply used as examples here. They do not (currently) exist
as User Agent properties.
</div>

Unlike other CSS properties,
User Agent property names are <a>case-sensitive</a>.

User agent properties are <strong>not</strong> reset by the 'all' property.
If a style rule attempts to define a value for a User Agent property, it is ignored.


<h2 id='using-constant'>
Using User Agent properties: the ''constant()'' notation</h2>

The value of a <a>User Agent property</a> can be substituted into the value of another property
with the ''constant()'' function.
The syntax of ''constant()'' is:

<pre class='prod'>
<dfn>constant()</dfn> = constant( <<user-agent-property-name>> [, <<declaration-value>> ]? )
</pre>

The ''constant()'' function is used in the same manner, and follows the same rules,
as the ''var()'' function.


<!--
AAA PPPPPPPPPPPPPPPPP IIIIIIIIII
Expand Down Expand Up @@ -675,7 +735,88 @@ Serializing Custom Properties</h3>
property names are restricted to the ASCII range and are <a>ASCII case-insensitive</a>,
so implementations typically serialize the name lowercased.

<h3 id='user-agent-property-api'>
Accessing and watching User Agent properties</h3>

User Agent property values are available via the {{CSS}} interface.

<pre class='idl'>
partial interface CSS {
static readonly CSSUserAgentPropertyMap userAgentProperties;
};

interface CSSUserAgentPropertyMap : EventTarget {
readonly maplike&lt;CSSOMString, CSSOMString&gt;;

void addListener(EventListener? listener);
void removeListener(EventListener? listener);
attribute EventHandler onchange;
}
</pre>

The <dfn method for=CSSUserAgentPropertyMap>addListener(<var>listener</var>)</dfn> method must run these steps:

1. If <var>listener</var> is null, terminate these steps.
1. Append an <a>event listener</a> to the associated list of <a>event listeners</a>
with <b>type</b> set to <code>change</code>,
<b>callback</b> set to <var>listener</var>,
and <b>capture</b> set to false,
unless there already is an <a>event listener</a> in that list
with the same <b>type</b>, <b>callback</b>, and <b>capture</b>.

The <dfn method for=CSSUserAgentPropertyMap>removeListener(<var>listener</var>)</dfn> method must run these steps:

1. Remove an <a>event listener</a> from the associated list of <a>event listeners</a>,
whose <b>type</b> is <code>change</code>,
<b>callback</b> is <var>listener</var>,
and <b>capture</b> is false.

The following are the <a>event handlers</a>
(and their corresponding <a>event handler event types</a>) that must be supported,
as <a>event handler IDL attributes</a>, by all objects implementing the {{CSSUserAgentPropertyMap}} interface:

<table class="complex data">
<thead>
<tr>
<th><a>Event handler</a>
<th><a>Event handler event type</a>
<tbody>
<tr>
<td><dfn attribute for=CSSUserAgentPropertyMap>onchange</dfn>
<td><a event>change</a>
</table>

<pre class=idl>
[Constructor(CSSOMString type, optional CSSUserAgentPropertyMapEventInit eventInitDict)]
interface CSSUserAgentPropertyMapEvent : Event {
readonly attribute CSSOMString property;
};

dictionary CSSUserAgentPropertyMapEventInit : EventInit {
CSSOMString property = "";
};
</pre>

The <dfn attribute for=CSSUserAgentPropertyMapEvent>property</dfn> attribute must return the value it was initialized to.

<h4 id=cssuseragentproperty-event-summary>Event summary</h4>

<i>This section is non-normative.</i>

<table class="complex data">
<thead>
<tr>
<th>Event
<th>Interface
<th>Interesting targets
<th>Description
<tbody>
<tr>
<td><dfn event for=CSSUserAgentPropertyMap>change</dfn>
<td>{{Event}}
<td>{{CSSUserAgentPropertyMap}}
<td>Fired at the {{CSSUserAgentPropertyMap}} when the value of the User Agent property changes.
</table>

<h2 id='changes'>
Changes since the May 6 2014 Last Call Working Draft</h2>
Expand Down