Skip to content

Commit

Permalink
Add change event to PreferenceObject
Browse files Browse the repository at this point in the history
Fixes #33
  • Loading branch information
lukewarlow committed Jan 15, 2024
1 parent 4400ef2 commit a4bab8d
Showing 1 changed file with 27 additions and 2 deletions.
29 changes: 27 additions & 2 deletions index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -182,13 +182,15 @@ If an override is set for this preference:

<script type=idl>
[Exposed=Window, SecureContext]
interface PreferenceObject {
interface PreferenceObject : EventTarget {
readonly attribute DOMString? override;
readonly attribute DOMString value;
readonly attribute FrozenArray<DOMString> validValues;

undefined clearOverride();
Promise<undefined> requestOverride(DOMString? value);

attribute EventHandler onchange;
};
</script>

Expand Down Expand Up @@ -234,10 +236,27 @@ Note: "no-preference" is deliberately not an allowed value for any preference.
This is to mitigate the risk of sites misusing the API to the detriment of user experience.
Authors should instead clear the preference override. See [#30](https://github.com/WICG/web-preferences-api/issues/30) for more details.

### {{onchange}} event handler attribute ### {#onchange-attribute}

The <dfn attribute for=PreferenceObject>onchange</dfn> attribute is an [=event handler IDL attribute=] for
the {{onchange}} [=event handler=], whose [=event handler event type=]
is <dfn class="event" data-dfn-for="PreferenceObject">change</dfn>.

<div algorithm>
Whenever the [=user agent=] is aware that the state of a {{PreferenceObject}}
instance |value| has changed, it asynchronously runs the <dfn>`PreferenceObject`
update steps</dfn>:

1. Let |preference| be the {{PreferenceObject}} object that |value| is associated with.
1. If [=this=]'s [=relevant global object=] is a {{Window}} object, then:
1. Let |document| be |preference|'s [=relevant global object=]'s [=associated Document=].
1. If |document| is null or |document| is not [=Document/fully active=], terminate this algorithm.
1. Queue a task on the [=preferences task source=] to <a>fire an event</a> named <code>change</code> at |preference|.

### {{requestOverride()}} method ### {#request-override-method}

<div algorithm='request preference override'>
The <dfn method for=PreferenceObject>requestOverride()</dfn> method, when invoked, must run these steps:
The <dfn method for=PreferenceObject>requestOverride(value)</dfn> method, when invoked, must run these steps:

1. Let |result| be [=a new promise=].
1. Let |allowed| be `false`.
Expand Down Expand Up @@ -281,6 +300,12 @@ Issue: Is TypeError correct here?
1. Clear the override for |preference|.
</div>

### Garbage Collection

A {{PreferenceObject}} object MUST NOT be garbage collected if it has an [=event listener=] whose type is `change`.

The <dfn>preferences task source</dfn> is a [=task source=] that is used to queue [=tasks=] that are related to the {{PreferenceObject}} interface.

# Usage Examples # {#usage-examples}

*This section is non-normative.*
Expand Down

0 comments on commit a4bab8d

Please sign in to comment.