source: branches/testFACT++branch/scripts/doc/dimctrl.js@ 18788

Last change on this file since 18788 was 16829, checked in by tbretz, 11 years ago
Updated.
File size: 5.0 KB
Line 
1throw 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 */
14var 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 */
52dimctrl.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 */
75dimctrl.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 */
92dimctrl.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 */
130dimctrl.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 */
157dimctrl.triggerInterrupt = function() { /* [native code] */ }
Note: See TracBrowser for help on using the repository browser.