js/page/speaker.html

88 lines
2.3 KiB
HTML

<link rel="stylesheet" href="style.css">
<script type="module" src="codeblock.js"></script>
<script type="module" src="scrollToTop.js"></script>
<scroll-to-top>
</scroll-to-top>
<a class="back" href="..">Module Index</a>
<h1 class="js module">speaker.js</h1>
<code-block>import {Speaker} from 'speaker.js'</code-block>
<section>
<h2>Description</h2>
<p>
A publish/subscribe helper class that uses micro-tasks to relay messages to many subscribers.
</p>
</section>
<section>
<h2>Example</h2>
<code-block>
const speaker = new Speaker()
speaker.listen(message =&gt; { document.title = message })
speaker.listen(message =&gt; { console.log(`Message received: ${message}`) })
speaker.speak("New page title")
console.log("This line runs before any of the callbacks")
</code-block>
<p>
Note that the callbacks don't run immediately.
They are scheduled to a micro-task to be called later on.
</p>
</section>
<section>
<h2>Methods</h2>
<dl>
<dt><code>new Speaker(...initial) : Speaker</code></dt>
<dd>
Constructs a new speaker.
All arguments passed to the constructor will be retained and returned
by any call to <code>listen</code> before the first time <code>speak</code>
is called.
</dd>
<dt><code>Speaker.listen(callback : (...args) =&gt; undefined) : [...args]</code></dt>
<dd>
Registers a callback to be called on every new message.
Returns an array containing the retained arguments of the last message.
</dd>
<dt><code>Speaker.speak(...args)</code></dt>
<dd>
Relays a message of zero or more arguments to all registered callbacks.
As mentioned above, callbacks will not be called immediately, but scheduled in a new micro-task.
The arguments are retained until <code>speak</code> is called again.
</dd>
<dt><code>Speaker.forget(callback)</code></dt>
<dd>
Removes a single callback function from its list of callbacks.
</dd>
<dt><code>Speaker.silence()</code></dt>
<dd>
Clears the list of callbacks completely.
</dd>
</dl>
</section>
<section>
<h2>Immediate Speaker</h2>
<p>
Additionally, the module exposts the <code>ImmediateSpeaker</code> class,
which does the exact same as a normal speaker,
but executes its callbacks immediately instead of scheduling a micro-task.
</p>
<p>
The API is the <em>exact same</em> as a normal <code>Speaker</code>.
</p>
</section>