210 lines
7.5 KiB
ReStructuredText
210 lines
7.5 KiB
ReStructuredText
.. _api-object:
|
|
|
|
*********************************************
|
|
The MathJax Object-Oriented Programming Model
|
|
*********************************************
|
|
|
|
MathJax uses an object-oriented programming model for its main
|
|
components, such as the `Input jax`, `Output jax`, and `Element jax`.
|
|
The model is intended to be light-weight and is based on JavaScript's
|
|
prototype inheritance mechanism. Object classes are created by making
|
|
subclasses of `MathJax.Object` or one of its subclasses, and are
|
|
instantiated by calling the object class as you would a function.
|
|
|
|
For example:
|
|
|
|
.. code-block:: javascript
|
|
|
|
MathJax.Object.Foo = MathJax.Object.Subclass({
|
|
Init: function (x) {this.SetX(x)},
|
|
getX: function () {return this.x},
|
|
setX: function (x) {this.x = x}
|
|
});
|
|
var foo = MathJax.Object.Foo("bar");
|
|
foo.getX(); // returns "bar"
|
|
foo.setX("foobar");
|
|
foo.getX(); // returns "foobar"
|
|
|
|
Object classes can have static properties and methods, which are
|
|
accessed via the object class variable. E.g.,
|
|
``MathJax.Object.Foo.SUPER`` or ``MathJax.Object.Foo.Augment()`` for
|
|
the object in the example above. Static values are not inherited by
|
|
subclasses.
|
|
|
|
|
|
Static Properties
|
|
=================
|
|
|
|
.. describe:: SUPER
|
|
|
|
Pointer to the super class for this subclass. (It is a reference to
|
|
`MathJax.Object` in the example above.)
|
|
|
|
|
|
Static Methods
|
|
==============
|
|
|
|
.. method:: Subclass(def[,static])
|
|
|
|
Creates a subclass of the given class using the contents of the
|
|
`def` object to define new methods and properties of the object
|
|
class, and the contents of the optional `static` object to define
|
|
new static methods and properties.
|
|
|
|
:Parameters:
|
|
- **def** --- object that defines the properties and methods
|
|
- **static** --- object that defines static properties and methods
|
|
:Returns: the new object class
|
|
|
|
.. method:: Augment(def[,static])
|
|
|
|
Adds new properties and methods to the class prototype. All
|
|
instances of the object already in existence will receive the new
|
|
properties and methods automatically.
|
|
|
|
:Parameters:
|
|
- **def** --- object that defines the properties and methods
|
|
- **static** --- object that defines static properties and methods
|
|
:Returns: the object class itself
|
|
|
|
|
|
Properties
|
|
==========
|
|
|
|
.. describe:: constructor
|
|
|
|
Pointer to the constructor function for this class. E.g.,
|
|
``foo.constructor`` would be a reference to ``MathJax.Object.Foo``
|
|
in the example above.
|
|
|
|
Methods
|
|
=======
|
|
|
|
.. method:: Init([data])
|
|
|
|
An optional function that is called when an instance of the class
|
|
is created. When called, the `this` variable is set to the newly
|
|
instantiated object, and the `data` is whatever was passed to the
|
|
object constructor. For instance, in the example above, the
|
|
variable ``foo`` is created by calling
|
|
``MathJax.Object.Foo("bar")``, which calls the
|
|
``MathJax.Object.Foo`` object's :meth:`Init()` method with `data`
|
|
equal to ``"bar"``. If desired, the :meth:`Init()` method can
|
|
create a *different* object, and return that, in which case this
|
|
becomes the return value for the object constructor.
|
|
|
|
:Parameters:
|
|
- **data** --- the data from the constructor call
|
|
:Returns: ``null`` or the object to be returned by the constructor
|
|
|
|
|
|
.. method:: isa(class)
|
|
|
|
Returns ``true`` if the object is an instance of the given class,
|
|
or of a subclass of the given class, and ``false`` otherwise. So
|
|
using the ``foo`` value defined above,
|
|
|
|
.. code-block:: javascript
|
|
|
|
foo.isa(MathJax.Object); // returns true
|
|
foo.isa(MathJax.Object.Foo); // returns true
|
|
foo.isa(MathJax.InputJax); // returns false
|
|
|
|
.. method:: can(method)
|
|
|
|
Checks if the object has the given `method` and returns ``true``
|
|
if so, otherwise returns ``false``. This allows you to test if an
|
|
object has a particular function available before trying to call
|
|
it (i.e., if an object implements a particular feature). For example:
|
|
|
|
.. code-block:: javascript
|
|
|
|
foo.can("getX"); // returns true
|
|
foo.can("bar"); // returns false
|
|
|
|
.. method:: has(property)
|
|
|
|
Checks if the object has the given `property` and returns ``true``
|
|
if so, otherwise returns ``false``. This allows you to test if an
|
|
object has a particular property available before trying to use
|
|
it. For example:
|
|
|
|
.. code-block:: javascript
|
|
|
|
foo.has("getX"); // returns true
|
|
foo.has("x"); // returns true
|
|
foo.has("bar"); // returns false
|
|
|
|
|
|
Accessing the Super Class
|
|
=========================
|
|
|
|
If a subclass overrides a method of its parent class, it may want to
|
|
call the original function as part of its replacement method. The
|
|
semantics for this are a bit awkward, but work efficiently. Within a
|
|
method, the value ``arguments.callee.SUPER`` refers to the super
|
|
class, so you can access any method of the superclass using that. In
|
|
order to have `this` refer to the current object when you call the
|
|
super class, however, you need to use ``call()`` or
|
|
``apply()`` to access the given method.
|
|
|
|
For example, ``arguments.callee.SUPER.method.call(this,data)`` would
|
|
call the superclass' `method` and pass it `data` as its argument,
|
|
properly passing the current object as `this`. Alternatively, you can
|
|
use ``this.SUPER(arguments)`` in place of ``arguments.callee.SUPER``.
|
|
It is also possible to refer to the super class explicitly rather than
|
|
through ``arguments.callee.SUPER``, as in the following example:
|
|
|
|
.. code-block:: javascript
|
|
|
|
MathJax.Class1 = MathJax.Object.Subclass({
|
|
Init: function(x) {this.x = x},
|
|
XandY: function(y) {return "Class1: x and y = " + this.x + " and " + y}
|
|
});
|
|
|
|
MathJax.Class2 = MathJax.Class1.Subclass({
|
|
XandY: function (y) {return "Class2: "+arguments.callee.SUPER.XandY.call(this,y)}
|
|
});
|
|
|
|
MathJax.Class3 = MathJax.Class2.Subclass({
|
|
XandY: function (y) {return "Class3: "+MathJax.Class2.prototype.XandY.call(this,y)}
|
|
});
|
|
|
|
MathJax.Class4 = MathJax.Class1.Subclass({
|
|
XandY: function (y) {return "Class4: "+this.SUPER(arguments).XandY.call(this,y)}
|
|
});
|
|
|
|
var foo = MathJax.Class2("foo");
|
|
foo.XandY("bar"); // returns "Class2: Class1: x and y = foo and bar"
|
|
var bar = MathJax.Class3("bar");
|
|
bar.XandY("foo"); // returns "Class3: Class2: Class1: x and y = bar and foo"
|
|
var moo = MathJax.Class4("moo");
|
|
moo.XandY("cow"); // returns "Class4: Class1: x and y = moo and cow"
|
|
|
|
Since both of these mechanisms are rather awkward, MathJax provides an
|
|
alternative syntax that is easier on the programmer, but at the cost
|
|
of some inefficiency in creating the subclass and in calling methods
|
|
that access the super class.
|
|
|
|
Since most calls to the super class are to the overridden method, not
|
|
to some other method, the method name and the ``call()`` are
|
|
essentially redundant. You can get a more convenient syntax by
|
|
wrapping the `def` for the :meth:`Subclass()` call in a call to
|
|
``MathJax.Object.SimpleSUPER()``, as in the following example:
|
|
|
|
.. code-block:: javascript
|
|
|
|
MathJax.Class1 = MathJax.Object.Subclass({
|
|
Init: function (x) {this.x = x},
|
|
XandY: function (y) {return "Class1: x and y = " + this.x + " and " + y}
|
|
});
|
|
|
|
MathJax.Class2 = MathJax.Class1.Subclass(
|
|
MathJax.Object.SimpleSUPER({
|
|
XandY: function (y) {return "Class2: "+this.SUPER(y)},
|
|
AnotherMethod: function () {return this.x} // it's OK if a method doesn't use SUPER
|
|
})
|
|
);
|
|
|
|
var foo = MathJax.Class2("foo");
|
|
foo.XandY("bar"); // returns "Class2: Class1: x and y = foo and bar"
|