- From: Eric Uhrhane via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 06 Mar 2012 21:28:41 +0000
- To: public-dap-commits@w3.org
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