CindyJS

The public interface to CindyJS

Except for some legacy stuff which is now deprecated, CindyJS exports a single object into the global namespace, which is called CindyJS. This method expects a single object as an argument, which in turn contains various parameters.

Example:

CindyJS({ports:[{id:"CindyCanvas"}],
         scripts:"cs*",
         csconsole:null
        });

Parameters

ports

A list of display ports associated with the newly created instance. At the moment, only the first element of this list is actually used. Each port description is a dictionary which may contain the following items:

Either id or element must be given, with the latter taking precedence. The element identified in this way must be a HTMLCanvasElement. Removing the canvas from the DOM tree will shut down the instance.

canvasname

Backwards-compatibility setting. canvasname:"name" is equivalent to ports:[{id:"name"}].

canvas

Backwards-compatibility setting. canvas:elt is equivalent to ports:[{element:elt}].

scripts

If this is a string, it must contain an asterisk *. The name of a possible event handler will replace that * and the resulting string will be used as the id attribute of a <script> element of the HTML document. If a script with that id does exist, its content is used as CindyScript code for the named event. In the example above, a <script id="csdraw"> would contain a script to be invoked every time something needs to be drawn.

The parameter can also be an object. In that case, its attributes are named by event names, and their values will be the CindyScript code to be executed for the given element. So for example scripts:{draw:"draw([0,0])"} will execute the draw command of CindyScript whenever the scene needs redrawing.

Instead of using the single scripts parameter, one can use separate parameters to identify the <script> tag to be used for each event. For example drawscript:"csdraw" would load the same draw script in the example above, but not the content of any other element whose name might accidentially start with cs.

At the moment the following events are defined:

keylistener

If this property is true, then a key listener will be installed for the document containing the instance. This will mean that every key pressed while visiting that page will eventually end up in the CindyJS event handler. If this property is not set to true but there is a keydown script then the canvas will be made focusable, and will receive key events only when focused. To focus the canvas, click it or use the tab key.

transform

The transform property is a list of transformations, applied in sequence. Each transformation is an object, containing a single property. The name of the property describes the kind of transformation, while the value will provide any required parameters.

defaultAppearance

An object providing default values for some appearance settings. The default is defined as follows:

defaultAppearance: {
  clip: "none",
  pointColor: [1,0,0],
  lineColor: [0,0,1],
  pointSize: 5,
  lineSize: 1,
  alpha: 1,
  overhangLine: 1,
  overhangSeg: 1,
  dimDependent: 0.7,
  fontFamily: "sans-serif",
  textsize: 20,
  lineHeight: 1.45
}

Any parameter which stays at this default value doesn't have to be specified at all.

csconsole

This should be either null, set to true or a suitable DOMElement or its id string. If it is an element (passed directly or identified via its id), then messages (in particular those created by the err function) will be appended to that element. If it is true a simple console with a command line will be created automatically. If it is null, error output will be suppressed except for output to the web developer console. If this parameter is absent, then it will be handled like null.

In the past, the absence of this parameter would cause a popup window, but that was more annyoing than useful in most environments.

grid

Backwards-compatibility setting. grid:2 is equivalent to ports:[{…, grid:2}], i.e. to that property being specified inside each port.

snap

Backwards-compatibility setting. snap:true is equivalent to ports:[{…, snap:true}], i.e. to that property being specified inside each port.

geomety

A list containing geometric primitives. See the section “Geometry” for details.

behavior

For physics simulations. See the section “Lab” for details.

images

A list of URLs which will be loaded. Whenever an image is ready, it can be used in the application instance.

animation

An object containing the following properties:

For the sake of backwards compatibility, autoplay may occur as a top level parameter instead of nested in the animation object. Likewise a top level animcontrols can be given instead of animation.controls. But these are deprecated, and only being used if the animation object is not present at all.

oninit

A JavaScript function to be called when the application instance is ready. More specifically, the script is executed after all scripts have been compiled, but before the init script gets executed, and before the canvas listeners are installed.

exclusive

If set to true, this will cause all previous instances of the application to be shut down when this instance is ready to start up.

plugins

An object providing plugins in addition to those registered by CindyJS.registerPlugin. The key is the plugin name, the value a plugin initialization callback.

language

The language of the page, given as a two-letter string. This is used to provide matching translations from the translations dictonary using the tr function. It is also returned using currentlanguage. This should always match the language of the rest of the containing page.

translations

A dictionary of dictionaries. The outer key is the two-letter language abbreviation. The inner key is the string passed to the tr function. The corresponding value will be returned in response.

angleUnit

The unit to use when printing angles, given as a string. Supported values include rad, °=deg=degree, gra=grad, turn=cyc=rev=rot, π=pi and quad. The given name is also be printed as the unit, so the settings described as equal will print the same value but with a different notation for the unit. The default is °. An empty string will cause angles to be printed in radians with no unit. To enter the special symbols when editing the data in a non-Unicode environment, you can enter ° as \u00b0 and π as \u03c0.

Instance Methods

The object returned from a call to CindyJS has a number of methods which may be of use.

startup

This method is usually called automatically once the DOM has been fully loaded. It initializes the instance and registers all required listeners. This method must not be invoked more than once.

shutdown

This method should be invoked whenever the instance is no longer active. Some care has been taken to call this method automatically in appropriate situations. One such situation is when the canvas element is removed from the document. Another is the creation of a second instance using the exclusive parameter. But it never hurts to explicitely shut down an instance nown to be no longer in use. Repeated invocation of this method is without effect. For example, starting two instances for the same canvas will cause both of them to remain active, which may cause problems. Removing some parent of the canvas from the document will not cause an automatic shutdown on some older browsers (those not supporting mutation observers).

evokeCS

This function accepts a string containing CindyScript code. It will execute that code immediately inside the scope of this instance.

play

Start animating the content.

pause

Pause the animation. The next call to start will resume the animation from the current position.

stop

Stop the animation. The configuration will be reset to the situation where play was invoked.

saveState

Saves the state of the widget. Currently only the geometric elements are stored, but it is well conceivable that a future version might store state for script variables and the likes as well. Each stored portion of the widget is represented as one property of the returned object, so currently that object will contain a property called geometry representing the geometric elements, formatted the same way as the corresponding input property.

Static Functions

The CindyJS function has a number of additional functions defined as its members.

newInstance

The CindyJS.newInstance function behaves mostly like CindyJS itself, but it will not automatically invoke the startup method of the newly created instance. Use this in special cases where custom control over startup and shutdown is required.

waitFor

The CindyJS.waitFor function will return a function which can be used as a callback. Created instances will only be started automatically after all callbacks created in this way have been executed. This method must be called in the header of the HTML document, before the DOMContentLoaded event has been triggered. That is because internally there is one such wait for that event, and once all events have been waited for it is an error to specify additional waiting conditions.

registerPlugin

This function takes three arguments. The first is the version number of the API to be used. Currently only version 1 is supported. The second parameter is the name of the plugin. The third is a callback function. It will be called when the init script of some content requests that plugin using the use operation of CindyScript. The details of the Plugin API will one day be described in some other document.

dumpState

This logs the geometric state of the widget to the web development console. An optional integer argument can be used to specify the index of the widget in case there is more than one. It is suggested to call this function and save its output if a specific geometric configuration exposes some kind of bug, so that the problematic situation can be reproduced more easily.

debugState

In theory it should be possible for most widgets to save the state and then restart the widget using that state in order to reproduce the same situation again. This function helps verifying this by doing exactly such a save then reload cycle for each widget in the current document.

Specifying non-script construction elements

Geometry

This section remains to be written. It should specify the structure of a geometric straight line program.

Lab

This section remains to be written.