2009/dap/file-system file-writer.html,1.36,1.37

Update of /sources/public/2009/dap/file-system
In directory hutz:/tmp/cvs-serv27698/d

Modified Files:
	file-writer.html 
Log Message:
Update references to DOM4 [specify version, add authors], FILE-API [just authors].
Rework and define progress events in FileWriter.


Index: file-writer.html
===================================================================
RCS file: /sources/public/2009/dap/file-system/file-writer.html,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -d -r1.36 -r1.37
--- file-writer.html	6 Mar 2012 01:40:35 -0000	1.36
+++ file-writer.html	6 Mar 2012 21:28:39 -0000	1.37
@@ -108,7 +108,7 @@
       </p>
       <p>
         When this specification refers to a <dfn>write method</dfn>, it includes
-        both <a>write</a> and <a>truncate</a>.
+        both <code>write</code> and <code>truncate</code>.
       </p>
       <p>
         When this specification refers to a <dfn>write algorithm</dfn>, it
@@ -122,6 +122,35 @@
         terminated by an abort() call.
       </p>
       <p>
+        When this specification says to <dfn>make progress notifications</dfn>,
+        the following are normative:
+        <ul>
+          <li>While the <a>write method</a> is processing, <a>queue a task</a>
+          to <a>fire a progress event</a> called <code>progress</code> at the
+          <a>FileSaver</a> object about every 50ms or for every byte written,
+          whichever is less frequent.</li>
+          <li>At least one event called <code>progress</code>
+          MUST fire before <code>write</code> is fired, and at 100% completion
+          of the write operation; if 100% of the file can written in less than
+          50ms, user agents MUST fire a progress event called
+          <code>progress</code> at completion.</li>
+        </ul>
+      </p>
+      <p>
+        When this specification says to <dfn>fire a progress event</dfn> called
+        <code>e</code> (for some <code>ProgressEvent</code> <code>e</code>), the
+        following are normative:
+        <ul>
+          <li>The progress event <code>e</code> does not bubble.
+          <code>e.bubbles</code> MUST be false [[!DOM4]].</li>
+          <li>The progress event <code>e</code> is NOT cancelable.
+          <code>e.cancelable</code> MUST be false [[!DOM4]].</li>
+          <li>The term "fire an event" is defined in DOM Core [[!DOM4]].
+          Progress events are defined in Progress Events
+          [[!PROGRESS-EVENTS]].</li>
+        </ul>
+      </p>
+      <p>
         The term <dfn>Blob</dfn> is defined by the File API specification
         [[!FILE-API]].
       </p>
@@ -154,7 +183,7 @@
         with synchronous and asynchronous file-writing interfaces.  As with
         reading, writing files on the main thread should happen asynchronously
         to avoid blocking UI actions.  Long-running writes provide status
-        information through delivery of progress events.
+        information through delivery of <a>progress events</a>.
       </p>
       <section>
         <h2>Examples</h2>
@@ -336,8 +365,8 @@
               processed.</li>
               <li>Set the <code>error</code> attribute to a FileError object
                 with the code <a>ABORT_ERR</a>.</li>
-              <li>Dispatch a progress event called abort</li>
-              <li>Dispatch a progress event called writeend</li>
+              <li><a>Fire a progress event</a> called <code>abort</code></li>
+              <li><a>Fire a progress event</a> called <code>writeend</code></li>
               <li>Terminate this algorithm.</li>
             </ol>
           </p>
@@ -449,7 +478,13 @@
         <dfn>FileSaver write algorithm</dfn>.
         </p>
         <ol>
-          <li>Set <code>readyState</code> to <code>WRITING</code>.</li>
+          <li>Set <code>readyState</code> to <code>WRITING</code>.<div
+          class=issue>FileSaver should really set readyState to WRITING before
+          the user gets a handle to it, so that abort works.  But FileWriter
+          shouldn't, so it can't be an enforced part of the inherited
+          interface.  Also, writestart should be tied to the INIT->WRITING
+          transition, so how would the holder of a FileSaver that wasn't a
+          FileWriter ever see that?</div></li>
           <li>If an error occurs during file write, proceed to the error steps
           below.
               <ol>
@@ -460,25 +495,27 @@
                     <code>FileError</code> object with a valid error code that
                     indicates the kind of file error that has occurred.</li>
                     <li>Set readyState to <code>DONE</code>.</li>
-                    <li>Dispatch a progress event called
+                    <li><a>Fire a progress event</a> called
                         <code>error</code>.</li>
-                    <li>Dispatch a progress event called
+                    <li><a>Fire a progress event</a> called
                         <code>writeend</code>.</li>
                   </ol></li>
                 <li>Terminate this overall set of steps.</li>
               </ol>
           </li>
-          <li><a>Queue a task</a> to dispatch a progress event called
+          <li><a>Queue a task</a> to <a>fire a progress event</a> called
             <code>writestart</code>.</li>
-          <li>Make progress notifications.</li>
-          <li>When the data has been fully written, <a>queue a task</a> that will:
+          <li><a>Make progress notifications</a>.</li>
+          <li>On completion of the write, queue a task to:
             <ol>
               <li>Set readyState to <code>DONE</code>.</li>
-              <li>Dispatch a progress event called <code>write</code></li>
-              <li>Dispatch a progress event called <code>writeend</code></li>
+              <li><a>Fire a progress event</a> called
+                  <code>write</code>.</li>
+              <li><a>Fire a progress event</a> called
+                  <code>writeend</code>.</li>
+              <li>Terminate this overall set of steps.</li>
             </ol>
           </li>
-          <li>Terminate this overall set of steps.</li>
         </ol>
       </section>
       <section>
@@ -601,9 +638,9 @@
                   <code>FileError</code> object with a valid error code that
                   indicates the kind of file error that has occurred.</li>
                   <li>Set readyState to <code>DONE</code>.</li>
-                  <li>Dispatch a progress event called
+                  <li><a>Fire a progress event</a> called
                       <code>error</code>.</li>
-                  <li>Dispatch a progress event called
+                  <li><a>Fire a progress event</a> called
                       <code>writeend</code></li>
                   <li>On getting, the <code>length</code> and
                     <code>position</code> attributes SHOULD indicate any
@@ -611,13 +648,15 @@
                   <li>Terminate this overall set of steps.</li>
                 </ol>
               </li>
-              <li>Dispatch a progress event called <code>writestart</code>.</li>
+              <li><a>Fire a progress event</a> called
+                <code>writestart</code>.</li>
               <li>Return from the write method, but continue processing
               the other steps in this algorithm.</li>
-              <li>Make progress notifications.  On getting, while processing the
-                <code>write</code> method, the <code>length</code> and
-                <code>position</code> attributes MUST indicate the progress
-                made in writing the file as of the last progress notification.
+              <li><a>Make progress notifications<a>.  On getting, while
+                processing the <code>write</code> method, the
+                <code>length</code> and <code>position</code> attributes MUST
+                indicate the progress made in writing the file as of the last
+                progress notification.
               </li>
               <li>
                 Upon successful completion of a write:
@@ -630,9 +669,9 @@
                   <li>Queue a task to:
                     <ol>
                       <li>Set readyState to <code>DONE</code>.</li>
-                      <li>Dispatch a progress event called
+                      <li><a>Fire a progress event</a> called
                           <code>write</code>.</li>
-                      <li>Dispatch a progress event called
+                      <li><a>Fire a progress event</a> called
                           <code>writeend</code>.</li>
                       <li>Terminate this overall set of steps.</li>
                     </ol>
@@ -707,9 +746,9 @@
                   <code>FileError</code> object with a valid error code that
                   indicates the kind of file error that has occurred.</li>
                   <li>Set readyState to <code>DONE</code>.</li>
-                  <li>Dispatch a progress event called
+                  <li><a>Fire a progress event</a> called
                       <code>error</code>.</li>
-                  <li>Dispatch a progress event called
+                  <li><a>Fire a progress event</a> called
                       <code>writeend</code></li>
                   <li>On getting, the <code>length</code> and
                     <code>position</code> attributes SHOULD indicate any
@@ -717,7 +756,8 @@
                   <li>Terminate this overall set of steps.</li>
                 </ol>
             </li>
-            <li>Dispatch a progress event called <code>writestart</code>.</li>
+            <li><a>Fire a progress event</a> called
+              <code>writestart</code>.</li>
             <li>Return from the truncate method, but continue processing the
             other steps in this algorithm.</li>
             <li>Upon successful completion:
@@ -732,8 +772,9 @@
                 <li>Queue a task to:
                   <ol>
                     <li>Set readyState to <code>DONE</code>.</li>
-                    <li>Dispatch a progress event called <code>write</code></li>
-                    <li>Dispatch a progress event called
+                    <li><a>Fire a progress event</a> called
+                        <code>write</code></li>
+                    <li><a>Fire a progress event</a> called
                         <code>writeend</code></li>
                     <li>Terminate this overall set of steps.</li>
                   </ol>

Received on Tuesday, 6 March 2012 21:28:46 UTC