305 lines
No EOL
24 KiB
HTML
305 lines
No EOL
24 KiB
HTML
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
|
|
<title>Using Callbacks — MathJax v1.0 documentation</title>
|
|
<link rel="stylesheet" href="_static/mj.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT: '',
|
|
VERSION: '1.0',
|
|
COLLAPSE_INDEX: false,
|
|
FILE_SUFFIX: '.html',
|
|
HAS_SOURCE: true
|
|
};
|
|
</script>
|
|
<script type="text/javascript" src="_static/jquery.js"></script>
|
|
<script type="text/javascript" src="_static/underscore.js"></script>
|
|
<script type="text/javascript" src="_static/doctools.js"></script>
|
|
<link rel="top" title="MathJax v1.0 documentation" href="index.html" />
|
|
<link rel="up" title="Synchronizing your code with MathJax" href="synchronize.html" />
|
|
<link rel="next" title="Using Queues" href="queues.html" />
|
|
<link rel="prev" title="Synchronizing your code with MathJax" href="synchronize.html" />
|
|
</head>
|
|
<body>
|
|
<div class="related">
|
|
<h3>Navigation</h3>
|
|
<ul>
|
|
<li class="right" style="margin-right: 10px">
|
|
<a href="genindex.html" title="General Index"
|
|
accesskey="I">index</a></li>
|
|
<li class="right" >
|
|
<a href="queues.html" title="Using Queues"
|
|
accesskey="N">next</a> |</li>
|
|
<li class="right" >
|
|
<a href="synchronize.html" title="Synchronizing your code with MathJax"
|
|
accesskey="P">previous</a> |</li>
|
|
<li><a href="index.html">MathJax v1.0 documentation</a> »</li>
|
|
<li><a href="synchronize.html" accesskey="U">Synchronizing your code with MathJax</a> »</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="document">
|
|
<div class="documentwrapper">
|
|
<div class="bodywrapper">
|
|
<div class="body">
|
|
|
|
<div class="section" id="using-callbacks">
|
|
<span id="id1"></span><h1>Using Callbacks<a class="headerlink" href="#using-callbacks" title="Permalink to this headline">¶</a></h1>
|
|
<p>A “callback” is a function that MathJax calls when it completes an
|
|
action that may occur asynchronously (like loading a file). Many of
|
|
MathJax’s functions operate asynchronously, and MathJax uses callbacks
|
|
to allow you to synchronize your code with the action of those
|
|
functions. The <cite>MathJax.Callback</cite> structure manages these callbacks.
|
|
Callbacks can include not only a function to call, but also data to be
|
|
passed to the function, and an object to act as the JavaScript <cite>this</cite>
|
|
value in the resulting call (i.e., the object on which the callback is
|
|
to execute).</p>
|
|
<p>Callbacks can be collected into <a class="reference internal" href="queues.html#using-queues"><em>Queues</em></a> where the
|
|
callbacks will be processed in order, with later callbacks waiting
|
|
until previous ones have completed before they are called. They are
|
|
also used with <a class="reference internal" href="signals.html#using-signals"><em>Signals</em></a> as the means of
|
|
receiving information about the signals as they occur.</p>
|
|
<p>A number of methods in <cite>MathJax.Hub</cite> and <cite>MathJax.Ajax</cite> accept
|
|
callback specifications as arguments and return callback structures.
|
|
These routines always will return a callback even when none was
|
|
specified in the arguments, and in that case, the callback is a “do
|
|
nothing” callback. The reason for this is so that the resulting
|
|
callback can be used can be used in a <cite>MathJax.Callback.Queue</cite> for
|
|
synchronization purposes, so that the actions following it in the
|
|
queue will not be performed until after the callback has been fired.</p>
|
|
<p>For example, the <tt class="xref py py-meth docutils literal"><span class="pre">MathJax.Ajax.Require()</span></tt> method can be used to
|
|
load external files, and it returns a callback that is called when the
|
|
file has been loaded and executed. If you want to load several files
|
|
and wait for them all to be loaded before performing some action, you
|
|
can create a <cite>Queue</cite> into which you push the results of the
|
|
<tt class="xref py py-meth docutils literal"><span class="pre">MathJax.Ajax.Require()</span></tt> calls, and then push a callback for the
|
|
action. The final action will not be performed until all the
|
|
file-load callbacks (which preceed it int he queue) have been called;
|
|
i.e., the action will not occur until all the files are loaded.</p>
|
|
<div class="section" id="specifying-a-callback">
|
|
<h2>Specifying a Callback<a class="headerlink" href="#specifying-a-callback" title="Permalink to this headline">¶</a></h2>
|
|
<p>Callbacks can be specified in a number of different ways, depending on
|
|
the functionality that is required of the callback. The easiest case
|
|
is to simply provide a function to be called, but it is also possible
|
|
to include data to pass to the function when it is called, and to
|
|
specify the object that will be used as <cite>this</cite> when the function is
|
|
called.</p>
|
|
<p>For example, the <tt class="xref py py-meth docutils literal"><span class="pre">MathJax.Ajax.Require()</span></tt> method can accept a
|
|
callback as its second argument (it will be called when the file given
|
|
as the first argument is loaded and executed). So you can call</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="s2">"[MathJax]/config/myConfig.js"</span><span class="p">,</span><span class="kd">function</span> <span class="p">()</span> <span class="p">{</span>
|
|
<span class="nx">alert</span><span class="p">(</span><span class="s2">"My configuration file is loaded"</span><span class="p">);</span>
|
|
<span class="p">});</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>and an alert will appear when the file is loaded. An example of
|
|
passing arguments to the callback function includes the following:</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="kd">function</span> <span class="nx">loadHook</span> <span class="p">(</span><span class="nx">x</span><span class="p">)</span> <span class="p">{</span><span class="nx">alert</span><span class="p">(</span><span class="s2">"loadHook: "</span><span class="o">+</span><span class="nx">x</span><span class="p">)}</span>
|
|
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="s2">"[MathJax]/config/myConfig.js"</span><span class="p">,[</span><span class="nx">loadHook</span><span class="p">,</span><span class="s2">"myConfig"</span><span class="p">]);</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Here, the <tt class="docutils literal"><span class="pre">loadHook()</span></tt> function accepts one argument and generates
|
|
an alert that includes the value passed to it. The callback in the
|
|
<tt class="xref py py-meth docutils literal"><span class="pre">MathJax.Ajax.Require()</span></tt> call is <tt class="docutils literal"><span class="pre">[loadHook,"myConfig"]</span></tt>,
|
|
which means that (the equivalent of) <tt class="docutils literal"><span class="pre">loadHook("myConfig")</span></tt> will be
|
|
performed when the file is loaded. The result should be an alert with
|
|
the text <cite>loadHook: myConfig</cite>.</p>
|
|
<p>The callback for the <tt class="xref py py-meth docutils literal"><span class="pre">MathJax.Ajax.Require()</span></tt> method actually
|
|
gets called with a status value, in addition to any parameters already
|
|
included in the callback specification, that indicates whether the
|
|
file loaded successfully, or failed for some reason (perhaps the file
|
|
couldn’t be found, or it failed to compile and run). So you could use</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="s2">"[MathJax]/config/myConfig.js"</span><span class="p">,</span><span class="kd">function</span> <span class="p">(</span><span class="nx">status</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="k">if</span> <span class="p">(</span><span class="nx">status</span> <span class="o">===</span> <span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">STATUS</span><span class="p">.</span><span class="nx">OK</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="nx">alert</span><span class="p">(</span><span class="s2">"My configuration file is loaded"</span><span class="p">);</span>
|
|
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
|
|
<span class="nx">alert</span><span class="p">(</span><span class="s2">"My configuration file failed to load!"</span><span class="p">);</span>
|
|
<span class="p">}</span>
|
|
<span class="p">});</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>to check if the file loaded properly. With additional parameters, the
|
|
example might be</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="kd">function</span> <span class="nx">loadHook</span> <span class="p">(</span><span class="nx">x</span><span class="p">,</span><span class="nx">status</span><span class="p">)</span> <span class="p">{</span><span class="nx">alert</span><span class="p">(</span><span class="s2">"loadHook: "</span><span class="o">+</span><span class="nx">x</span><span class="o">+</span><span class="s2">" has status "</span><span class="o">+</span><span class="nx">status</span><span class="p">)}</span>
|
|
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="s2">"[MathJax]/config/myConfig.js"</span><span class="p">,[</span><span class="nx">loadHook</span><span class="p">,</span><span class="s2">"myConfig"</span><span class="p">]);</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Note that the parameters given in the callback specification are used
|
|
first, and then additional parameters from the call to the callback
|
|
come afterward.</p>
|
|
<div class="section" id="callbacks-to-object-methods">
|
|
<h3>Callbacks to Object Methods<a class="headerlink" href="#callbacks-to-object-methods" title="Permalink to this headline">¶</a></h3>
|
|
<p>When you use a method of a JavaScript object, a special variable
|
|
called <cite>this</cite> is defined that refers to the object whose method is
|
|
being called. It allows you to access other methods or properties of
|
|
the object without knowing explicitly where the object is stored.</p>
|
|
<p>For example,</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">aPerson</span> <span class="o">=</span> <span class="p">{</span>
|
|
<span class="nx">firstname</span><span class="o">:</span> <span class="s2">"John"</span><span class="p">,</span>
|
|
<span class="nx">lastname</span><span class="o">:</span> <span class="s2">"Smith"</span><span class="p">,</span>
|
|
<span class="nx">showName</span><span class="o">:</span> <span class="kd">function</span> <span class="p">()</span> <span class="p">{</span><span class="nx">alert</span><span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">firstname</span><span class="o">+</span><span class="s2">" "</span><span class="o">+</span><span class="k">this</span><span class="p">.</span><span class="nx">lastname</span><span class="p">)}</span>
|
|
<span class="p">};</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>creates an object that contains three items, a <cite>firstname</cite>, and
|
|
<cite>lastname</cite>, and a method that shows the person’s full name in an
|
|
alert. So <tt class="docutils literal"><span class="pre">aPerson.fullName()</span></tt> would cause an alert with the text
|
|
<tt class="docutils literal"><span class="pre">John</span> <span class="pre">Smith</span></tt> to appear. Note, however that this only works if the
|
|
method is called as <tt class="docutils literal"><span class="pre">aPerson.showName()</span></tt>; if instead you did</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">f</span> <span class="o">=</span> <span class="nx">aPerson</span><span class="p">.</span><span class="nx">showName</span><span class="p">;</span> <span class="c1">// assign f the function from aPerson</span>
|
|
<span class="nx">f</span><span class="p">();</span> <span class="c1">// and call the function</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>the association of the function with the data in <tt class="docutils literal"><span class="pre">aPerson</span></tt> is lost,
|
|
and the alert will probably show <tt class="docutils literal"><span class="pre">undefined</span> <span class="pre">undefined</span></tt>. (In this
|
|
case, <tt class="docutils literal"><span class="pre">f</span></tt> will be called with <tt class="docutils literal"><span class="pre">this</span></tt> set to the <tt class="docutils literal"><span class="pre">window</span></tt>
|
|
variable, and so <tt class="docutils literal"><span class="pre">this.firstname</span></tt> and <tt class="docutils literal"><span class="pre">this.lastname</span></tt> will refer
|
|
to undefined values.)</p>
|
|
<p>Because of this, it is difficult to use an object’s method as a
|
|
callback if you refer to it as a function directly. For example,</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">aFile</span> <span class="o">=</span> <span class="p">{</span>
|
|
<span class="nx">name</span><span class="o">:</span> <span class="s2">"[MathJax]/config/myConfig.js"</span><span class="p">,</span>
|
|
<span class="nx">onload</span><span class="o">:</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">status</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="nx">alert</span><span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">name</span><span class="o">+</span><span class="s2">" is loaded with status "</span><span class="o">+</span><span class="nx">status</span><span class="p">);</span>
|
|
<span class="p">}</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="nx">aFile</span><span class="p">.</span><span class="nx">name</span><span class="p">,</span><span class="nx">aFile</span><span class="p">.</span><span class="nx">onload</span><span class="p">);</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>would produce an alert indicating that “undefined” was loaded with a
|
|
particular status. That is because <tt class="docutils literal"><span class="pre">aFile.onload</span></tt> is a reference to
|
|
the <cite>onload</cite> method, which is just a function, and the association
|
|
with the <cite>aFile</cite> object is lost. One could do</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="nx">aFile</span><span class="p">.</span><span class="nx">name</span><span class="p">,</span><span class="kd">function</span> <span class="p">(</span><span class="nx">status</span><span class="p">)</span> <span class="p">{</span><span class="nx">aFile</span><span class="p">.</span><span class="nx">onload</span><span class="p">(</span><span class="nx">status</span><span class="p">)});</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>but that seems needlessly verbose, and it produces a closure when one
|
|
is not really needed. Instead, MathJax provides an alternative
|
|
specification for a callback that allows you to specify both the
|
|
method and the object it comes from:</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="nx">aFile</span><span class="p">.</span><span class="nx">name</span><span class="p">,[</span><span class="s2">"onload"</span><span class="p">,</span><span class="nx">aFile</span><span class="p">]);</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>This requests that the callback should call <tt class="docutils literal"><span class="pre">aFile.onload</span></tt> as the
|
|
function, which will maintain the connection between <tt class="docutils literal"><span class="pre">aFile</span></tt> and its
|
|
method, thus preserving the correct value for <cite>this</cite> within the method.</p>
|
|
<p>As in the previous cases, you can pass parameters to the method as
|
|
well by including them in the array that specifies the callback:</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="s2">"filename"</span><span class="p">,[</span><span class="s2">"method"</span><span class="p">,</span><span class="nx">object</span><span class="p">,</span><span class="nx">arg1</span><span class="p">,</span><span class="nx">arg2</span><span class="p">,...]);</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>This approach is useful when you are pushing a callback for one one
|
|
MathJax’s Hub routines into the MathJax processing queue. For example,</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">MathJax</span><span class="p">.</span><span class="nx">Hub</span><span class="p">.</span><span class="nx">Queue</span><span class="p">([</span><span class="s2">"Typeset"</span><span class="p">,</span><span class="nx">MathJax</span><span class="p">.</span><span class="nx">Hub</span><span class="p">,</span><span class="s2">"MathDiv"</span><span class="p">]);</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>pushes the equivalent of <tt class="docutils literal"><span class="pre">MathJax.Hub.Typeset("MathDiv")</span></tt> into the
|
|
processing queue.</p>
|
|
<p>See the <a class="reference internal" href="api/callback.html#api-callback"><em>Callback Object</em></a> reference pages for more
|
|
information about the valid methods of specifying a callback.</p>
|
|
</div>
|
|
<div class="section" id="creating-a-callback-explicitly">
|
|
<h3>Creating a Callback Explicitly<a class="headerlink" href="#creating-a-callback-explicitly" title="Permalink to this headline">¶</a></h3>
|
|
<p>When you call a method that accpets a callback, you usually pass it a
|
|
callback specification (like in the examples above), which <em>describes</em>
|
|
a callback (the method will create the actual <cite>Callback</cite> object, and
|
|
return that to you as its return value). You don’t usually create
|
|
<cite>Callback</cite> objects directly yourself.</p>
|
|
<p>There are times, however, when you may wish to create a callback
|
|
object for use with functions that don’t create callbacks for you.
|
|
For example, the <tt class="docutils literal"><span class="pre">setTimeout()</span></tt> function can take a function as its
|
|
argument, and you may want that function to be a method of an object,
|
|
and would run into the problem described in the previous section if
|
|
you simply passed the object’s method to <tt class="docutils literal"><span class="pre">setTimeout()</span></tt>. Or you
|
|
might want to pass an argument to the function called by
|
|
<tt class="docutils literal"><span class="pre">setTimeout()</span></tt>. (Altough the <tt class="docutils literal"><span class="pre">setTimeout()</span></tt> function can accept
|
|
additional arguements that are supposed to be passed on to the code
|
|
when it is called, Internet Explorer does not implement that feature,
|
|
so you can’t rely on it.) You can use a <cite>Callback</cite> object to
|
|
do this, and the <tt class="xref py py-meth docutils literal"><span class="pre">MathJax.Callback()</span></tt> method will create one for
|
|
you. For example,</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="kd">function</span> <span class="nx">myTimer</span> <span class="p">(</span><span class="nx">x</span><span class="p">)</span> <span class="p">{</span><span class="nx">alert</span><span class="p">(</span><span class="s2">"x = "</span><span class="o">+</span><span class="nx">x</span><span class="p">)}</span>
|
|
<span class="nx">setTimeout</span><span class="p">(</span><span class="nx">MathJax</span><span class="p">.</span><span class="nx">Callback</span><span class="p">([</span><span class="nx">f</span><span class="p">,</span><span class="s2">"Hello World!"</span><span class="p">]),</span><span class="mi">500</span><span class="p">);</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>would create a callback that calls <tt class="docutils literal"><span class="pre">f("Hello</span> <span class="pre">World!")</span></tt>, and
|
|
schedules it to be called in half a second.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sphinxsidebar">
|
|
<div class="sphinxsidebarwrapper">
|
|
<h3><a href="index.html">Table Of Contents</a></h3>
|
|
<ul>
|
|
<li><a class="reference internal" href="#">Using Callbacks</a><ul>
|
|
<li><a class="reference internal" href="#specifying-a-callback">Specifying a Callback</a><ul>
|
|
<li><a class="reference internal" href="#callbacks-to-object-methods">Callbacks to Object Methods</a></li>
|
|
<li><a class="reference internal" href="#creating-a-callback-explicitly">Creating a Callback Explicitly</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h4>Previous topic</h4>
|
|
<p class="topless"><a href="synchronize.html"
|
|
title="previous chapter">Synchronizing your code with MathJax</a></p>
|
|
<h4>Next topic</h4>
|
|
<p class="topless"><a href="queues.html"
|
|
title="next chapter">Using Queues</a></p>
|
|
<h3>This Page</h3>
|
|
<ul class="this-page-menu">
|
|
<li><a href="_sources/callbacks.txt"
|
|
rel="nofollow">Show Source</a></li>
|
|
</ul>
|
|
<div id="searchbox" style="display: none">
|
|
<h3>Quick search</h3>
|
|
<form class="search" action="search.html" method="get">
|
|
<input type="text" name="q" size="18" />
|
|
<input type="submit" value="Go" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
<p class="searchtip" style="font-size: 90%">
|
|
Enter search terms or a module, class or function name.
|
|
</p>
|
|
</div>
|
|
<script type="text/javascript">$('#searchbox').show(0);</script>
|
|
</div>
|
|
</div>
|
|
<div class="clearer"></div>
|
|
</div>
|
|
<div class="related">
|
|
<h3>Navigation</h3>
|
|
<ul>
|
|
<li class="right" style="margin-right: 10px">
|
|
<a href="genindex.html" title="General Index"
|
|
>index</a></li>
|
|
<li class="right" >
|
|
<a href="queues.html" title="Using Queues"
|
|
>next</a> |</li>
|
|
<li class="right" >
|
|
<a href="synchronize.html" title="Synchronizing your code with MathJax"
|
|
>previous</a> |</li>
|
|
<li><a href="index.html">MathJax v1.0 documentation</a> »</li>
|
|
<li><a href="synchronize.html" >Synchronizing your code with MathJax</a> »</li>
|
|
</ul>
|
|
</div>
|
|
<div class="footer">
|
|
© Copyright 2010 Design Science.
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0b2.
|
|
</div>
|
|
</body>
|
|
</html> |