1 throw new Error("Description for built in functions. Must not be included!");
  2 /**
  3  * @fileOverview
  4  *    Documentation of the dimctrl namespace
  5  */
  6 
  7 /**
  8  * @namespace
  9  *
 10  * Global namespace for functions dealing with the dimctrl state
 11  *
 12  * @author <a href="mailto:thomas.bretz@epfl.ch">Thomas Bretz</a>
 13  */
 14 var dimctrl = { };
 15 
 16 /**
 17  * Define a new internal state.
 18  *
 19  * States should be defined when a script is started.
 20  *
 21  * @param {Integer} index
 22  *    The intgeger number assigned to the new state. Only numbers
 23  *    in the range [10, 255] are allowed.
 24  *
 25  * @param {String} [name]
 26  *    A short name describing the state. According the the convention
 27  *    used throughout FACT++, it it must not contain whitespaces or
 28  *    underscores. Ever word should start with a capital letter,
 29  *    e.g. 'TriggerOn'
 30  *
 31  * @param {String} [decription]
 32  *    A user defined string which gives a more conscise explanation
 33  *    of the meaning of the state and can also be displayed in the GUI
 34  *    or anywhere else automatically,
 35  *    e.g. "System setup and trigger switched on"
 36  *
 37  * @throws
 38  *    <li> if something is wrong with the supplied arguments (type, number)
 39  *    <li> when the index is out of range [10,255]
 40  *    <li> the given state name is empty
 41  *    <li> the given state name contains a colon or an equal sign
 42  *    <li> when a state with the same name or index was already
 43  *    <li> set since the script was started.
 44  *
 45  * @returns {Boolean}
 46  *    A boolean whether the state was newly added (true) or an existing
 47  *    one overwritten (false).
 48  *
 49  * @example
 50  *     dim.defineState(10, "StateTen", "This is state number ten");
 51  */
 52 dimctrl.defineState = function() { /* [native code] */ }
 53 
 54 /**
 55  * Change the internal state.
 56  *
 57  * @param {Integer,String} state
 58  *    Either the name of the state to set or its index can be supplied.
 59  *
 60  * @throws
 61  *    <li> if something is wrong with the supplied arguments (type, number)
 62  *    <li> if a String is given and it is not found in the list of names
 63  *
 64  * @returns {Boolean}
 65  *     A boolean is returned whether setting the state wa sucessfull or
 66  *     not. If the function is not called at unexpected time, i.e.
 67  *     before the execution of the JavaScript has been started or
 68  *     after it has already be terminated, true should be returned
 69  *     always.
 70  *
 71  * @example
 72  *     dim.setState(10);
 73  *     dim.setState("StateTen");
 74  */
 75 dimctrl.setState = function() { /* [native code] */ }
 76 
 77 /**
 78  * Get the current internal state.
 79  *
 80  * @throws
 81  *    if arguments are supplied
 82  *
 83  * @returns {Object}
 84  *     An object with the properties index {Number}, name {String} and
 85  *     description {String}. Note that name and description might be
 86  *     an empty string.
 87  *
 88  * @example
 89  *     var state = dim.getState();
 90  *     console.out(JSON.stringify(state));
 91  */
 92 dimctrl.getState = function() { /* [native code] */ }
 93 
 94 /**
 95  * Set an interrupt handler, a function which is called if an
 96  * interrupt is received, e.g. via dim (dimctrl --interrupt).
 97  * Note that the interrupt handler is executed in its own JavaScript
 98  * thread. Thus it interrupts the execution of the script, but does
 99  * not stop its execution. Please also note that this is a callback
100  * from the main loop. As long as the handler is executed, no other
101  * event (dim or command interface) will be processed.
102  *
103  * If an interrupt was triggered by dimctrl (so not from within
104  * the script) and a number between 10 and 255 is returned,
105  * the state machine will change its state accordingly. Other returned
106  * ojects or returned values outside of this range are ignored.
107  *
108  * @param {Function} [func]
109  *    Function to be called when an interrupt is received. Null, undefined
110  *    or no argument to remove the handler.
111  *
112  * @throws
113  *    if number of type of arguments is wrong
114  *
115  * @example
116  *     function handleIrq(irq, args, time, user)
117  *     {
118  *         console.out("IRQ received:   "+irq);
119  *         console.out("Interrupt time: "+time);
120  *         console.out("Issuing user:   "+user);
121  *         console.out("Arguments:");
122  *         for (var key in args)
123  *             console.out(" args["+key+"="+args[key]);
124  *
125  *         var newState = 10;
126  *         return newState;
127  *     }
128  *     dimctrl.setInterruptHandler(handleIrq);
129  */
130 dimctrl.setInterruptHandler = function() { /* [native code] */ }
131 
132 /**
133  * You can also issue an interrupt from anywhere in your code.
134  *
135  * @param argument
136  *     Any kind of argument can be given. If it is not a String, it
137  *     is converted using the toString() member function. The result
138  *     must not contain any line break.
139  *
140  * @param [. . .]
141  *     Any number of additional arguments. Each argument will appear in
142  *     a new line.
143  *
144  * @returns
145  *    the return of the interrupt handler which is called is returned
146  *
147  * @throws
148  *    if an argument contains a line break
149  *
150  * @example
151  *     dimctrl.triggerInterrupt();
152  *     dimctrl.triggerInterrupt("my_command");
153  *     dimctrl.triggerInterrupt("my_command arg1 arg2=x arg3");
154  *     dimctrl.triggerInterrupt("arg1=x arg2 arg3");
155  *
156  */
157 dimctrl.triggerInterrupt = function() { /* [native code] */ }
158