Skip to content

Commit

Permalink
Scope 'non-normative' header to individual sections in Introduction (w…
Browse files Browse the repository at this point in the history 
…3c#51)

Currently the "*This section is non-normative*" disclaimer is applied to all of section '1. Introduction', even though the "Introduction" contains several subsections that define terms and contain other non-normative text.

Scope the "non-normative" header to only the sections that are fully non-normative.

In the future we should consider refactoring such that the sub-sections with normative text are pulled out of the Introduction section.
  • Loading branch information
@dandclark
dandclark committed Jun 6, 2023
1 parent fb4918f commit 12e643b
Showing 1 changed file with 27 additions and 26 deletions.
53 changes: 27 additions & 26 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,9 @@
<p>
</p>
</section>
<section class="informative">
<section>
<h2>Introduction</h2>
<section id="background">
<section id="background" class="informative">
<h3>Background and Motivation</h3>
<p>Modern operating systems provide mechanisms to produce text in a variety of ways: speech-to-text, virtual keyboards, handwriting recognition and many more. When an app wants to consume text input from these various sources, it must first provide a view of its currently editable text to the operating system. The view of editable text provides a common language that apps (having a variety of different document models) and sources of text (having a variety of different input methods) can both understand. Both the apps and input sources communicate with one another by expressing their desired changes to the state of the common view as an event that the other can handle to facilitate the text input process.</p>
<p>For the purposes of this document, a producer of text is known as a <dfn>Text Input Method</dfn>. The view provided by an app which wants to consume text is called a <dfn>Text Edit Context</dfn>. The service provided by the OS to facilitate the editing of text in the [=Text Edit Context=] by the [=Text Input Methods=] is called a <dfn>Text Input Service</dfn>.</p>
Expand Down Expand Up @@ -264,21 +264,22 @@ <h4>EditContext events</h4>
</p>
</li>
</ul>
<h4>Examples</h4>
<p>Using an {{EditContext}}, an author can mark a region of the document editable by <a data-lt="associated element">associating</a> an {{EditContext}} object with an element as shown in the example below: </p>
<aside class="example" title="Associate an EditContext with an Element">
<pre><xmp><script type="module">
let canvas = document.querySelector("canvas")
canvas.editContext = new EditContext()
// When the associated element is focused, the EditContext is automatically activated.
canvas.focus();
</script>
<canvas></canvas></xmp></pre></aside>
<section id="examples" class="informative">
<h4>Examples</h4>
<p>Using an {{EditContext}}, an author can mark a region of the document editable by <a data-lt="associated element">associating</a> an {{EditContext}} object with an element as shown in the example below: </p>
<aside class="example" title="Associate an EditContext with an Element">
<pre><xmp><script type="module">
let canvas = document.querySelector("canvas")
canvas.editContext = new EditContext()
// When the associated element is focused, the EditContext is automatically activated.
canvas.focus();
</script>
<canvas></canvas></xmp></pre></aside>

<p>In the example below, the author is using a canvas to draw an editable region that allows the user to input a single line of text rendered with a monospace font. The text for the editable region is maintained by the author as a String. The text offsets for the selection in the editable region are maintained by the author as a pair of Numbers: selectionStart and selectionEnd. The Numbers refer to the count of the number of UTF-16 codepoints to the left of the start and end of the selection respectively. For the sake of communicating the bounding boxes for the current selection and the editable region of the document to Text Input Services, the author also computes the bounding rectangle in CSS pixels for the selection and the editable region of the document. The offset of the rectangle is expressed relative to the origin of the canvas element since that is the element to which the author has <a data-lt="associated element">associated</a> an EditContext. Since the model for the author’s representation of text and selection location matches the form expected by the EditContext API, the author can simply assign those properties to the EditContext <a data-lt="associated element">associated</a> with the canvas whenever those values change. </p>
<p>In the example below, the author is using a canvas to draw an editable region that allows the user to input a single line of text rendered with a monospace font. The text for the editable region is maintained by the author as a String. The text offsets for the selection in the editable region are maintained by the author as a pair of Numbers: selectionStart and selectionEnd. The Numbers refer to the count of the number of UTF-16 codepoints to the left of the start and end of the selection respectively. For the sake of communicating the bounding boxes for the current selection and the editable region of the document to Text Input Services, the author also computes the bounding rectangle in CSS pixels for the selection and the editable region of the document. The offset of the rectangle is expressed relative to the origin of the canvas element since that is the element to which the author has <a data-lt="associated element">associated</a> an EditContext. Since the model for the author’s representation of text and selection location matches the form expected by the EditContext API, the author can simply assign those properties to the EditContext <a data-lt="associated element">associated</a> with the canvas whenever those values change. </p>

<aside class="example" title="Using EditContext with editing model, view, and controller">
<pre><xmp><script type="module">
<aside class="example" title="Using EditContext with editing model, view, and controller">
<pre><xmp><script type="module">
// This example is built on top of example 1.
// Only the added logic is shown here for brevity.
class EditingModel {
Expand Down Expand Up @@ -350,15 +351,15 @@ <h4>Examples</h4>
editingController.render()
</script>
<canvas></canvas></xmp></pre>
</aside>
</aside>

<p>Building on the previous example, in response to user input, authors should handle the events of both the editable element (in this case a canvas) and the EditContext.</p>

<p>Input events against the DOM continue to describe the user’s intent</p>

<p>The below example shows how to handle {{TextUpdateEvent}}, {{TextFormatUpdateEvent}}, and {{CharacterBoundsUpdateEvent}} to update the model and render the result to the canvas.</p>
<aside class="example" title="Event handlers for TextUpdateEvent, TextFormatUpdateEvent, and CharacterBoundsUpdateEvent">
<pre><xmp><script>
<p>Building on the previous example, in response to user input, authors should handle the events of both the editable element (in this case a canvas) and the EditContext.</p>
<p>Input events against the DOM continue to describe the user’s intent</p>
<p>The below example shows how to handle {{TextUpdateEvent}}, {{TextFormatUpdateEvent}}, and {{CharacterBoundsUpdateEvent}} to update the model and render the result to the canvas.</p>
<aside class="example" title="Event handlers for TextUpdateEvent, TextFormatUpdateEvent, and CharacterBoundsUpdateEvent">
<pre><xmp><script>
// This example is built on top of example 1 and example 2.
// Only the added logic is shown here for brevity.
class EditingModel {
Expand Down Expand Up @@ -452,10 +453,10 @@ <h4>Examples</h4>
editingcontroller.handleCharacterBoundsUpdate(e.rangeStart, e.rangeEnd);
});
</script></xmp></pre>
</aside>

</aside>
</section>
</section>
<section id="interactions">
<section id="interactions" class="informative">
<h3>Interactions with Other Editing Primitives </h3>
<p>An author doesn’t have to use a canvas element with an EditContext. In the example below the author uses a div to establish an editable region of the document and renders the contents into that editable region using various other styled elements, images and text. This allows the author to leverage other built-in editing primitives from the user agent such as selection and spellcheck. </p>

Expand Down

0 comments on commit 12e643b

Please sign in to comment.