Namespace dimctrl

Global namespace for functions dealing with the dimctrl state
Defined in: dimctrl.js.

Namespace Summary
Constructor Attributes	Constructor Name and Description
	dimctrl

Method Summary
Method Attributes	Method Name and Description
<static>	dimctrl.defineState(index, name, decription) Define a new internal state.
<static>	dimctrl.getState() Get the current internal state.
<static>	dimctrl.setInterruptHandler(func) Set an interrupt handler, a function which is called if an interrupt is received, e.g.
<static>	dimctrl.setState(state) Change the internal state.
<static>	dimctrl.triggerInterrupt(argument) You can also issue an interrupt from anywhere in your code.

Namespace Detail

dimctrl

Author: Thomas Bretz.

Method Detail

<static> {Boolean} dimctrl.defineState(index, name, decription)

Define a new internal state. States should be defined when a script is started.

    dim.defineState(10, "StateTen", "This is state number ten");

Parameters:
{Integer} index: The intgeger number assigned to the new state. Only numbers in the range [10, 255] are allowed.
{String} name Optional: A short name describing the state. According the the convention used throughout FACT++, it it must not contain whitespaces or underscores. Ever word should start with a capital letter, e.g. 'TriggerOn'
{String} decription Optional: A user defined string which gives a more conscise explanation of the meaning of the state and can also be displayed in the GUI or anywhere else automatically, e.g. "System setup and trigger switched on"

Throws:
: if something is wrong with the supplied arguments (type, number)
when the index is out of range [10,255]
the given state name is empty
the given state name contains a colon or an equal sign
when a state with the same name or index was already
set since the script was started.

Returns:: {Boolean} A boolean whether the state was newly added (true) or an existing one overwritten (false).

<static> {Object} dimctrl.getState()

Get the current internal state.

    var state = dim.getState();
    console.out(JSON.stringify(state));

Throws:
: if arguments are supplied

Returns:: {Object} An object with the properties index {Number}, name {String} and description {String}. Note that name and description might be an empty string.

<static> dimctrl.setInterruptHandler(func)

Set an interrupt handler, a function which is called if an interrupt is received, e.g. via dim (dimctrl --interrupt). Note that the interrupt handler is executed in its own JavaScript thread. Thus it interrupts the execution of the script, but does not stop its execution. Please also note that this is a callback from the main loop. As long as the handler is executed, no other event (dim or command interface) will be processed. If an interrupt was triggered by dimctrl (so not from within the script) and a number between 10 and 255 is returned, the state machine will change its state accordingly. Other returned ojects or returned values outside of this range are ignored.

    function handleIrq(irq, args, time, user)
    {
        console.out("IRQ received:   "+irq);
        console.out("Interrupt time: "+time);
        console.out("Issuing user:   "+user);
        console.out("Arguments:");
        for (var key in args)
            console.out(" args["+key+"="+args[key]);

        var newState = 10;
        return newState;
    }
    dimctrl.setInterruptHandler(handleIrq);

Parameters:
{Function} func Optional: Function to be called when an interrupt is received. Null, undefined or no argument to remove the handler.

Throws:
: if number of type of arguments is wrong

<static> {Boolean} dimctrl.setState(state)

Change the internal state.

    dim.setState(10);
    dim.setState("StateTen");

Parameters:
{Integer|String} state: Either the name of the state to set or its index can be supplied.

Throws:
: if something is wrong with the supplied arguments (type, number)
if a String is given and it is not found in the list of names

Returns:: {Boolean} A boolean is returned whether setting the state wa sucessfull or not. If the function is not called at unexpected time, i.e. before the execution of the JavaScript has been started or after it has already be terminated, true should be returned always.

<static> dimctrl.triggerInterrupt(argument)

You can also issue an interrupt from anywhere in your code.

    dimctrl.triggerInterrupt();
    dimctrl.triggerInterrupt("my_command");
    dimctrl.triggerInterrupt("my_command arg1 arg2=x arg3");
    dimctrl.triggerInterrupt("arg1=x arg2 arg3");

Parameters:
argument: Any kind of argument can be given. If it is not a String, it is converted using the toString() member function. The result must not contain any line break.
. . . Optional: Any number of additional arguments. Each argument will appear in a new line.

Throws:
: if an argument contains a line break

Returns:: the return of the interrupt handler which is called is returned

Classes

Namespace dimctrl