| 1 | /**
|
|---|
| 2 | * @fileOverview
|
|---|
| 3 | * Documentation of the dimctrl namespace
|
|---|
| 4 | */
|
|---|
| 5 |
|
|---|
| 6 | /**
|
|---|
| 7 | * @namespace
|
|---|
| 8 | *
|
|---|
| 9 | * Global namespace for functions dealing with the dimctrl state
|
|---|
| 10 | *
|
|---|
| 11 | * @author <a href="mailto:thomas.bretz@epfl.ch">Thomas Bretz</a>
|
|---|
| 12 | */
|
|---|
| 13 | var dimctrl = { };
|
|---|
| 14 |
|
|---|
| 15 | /**
|
|---|
| 16 | * Define a new internal state.
|
|---|
| 17 | *
|
|---|
| 18 | * States should be defined when a script is started.
|
|---|
| 19 | *
|
|---|
| 20 | * @param {Integer} index
|
|---|
| 21 | * The intgeger number assigned to the new state. Only numbers
|
|---|
| 22 | * in the range [10, 255] are allowed.
|
|---|
| 23 | *
|
|---|
| 24 | * @param {String} [name]
|
|---|
| 25 | * A short name describing the state. According the the convention
|
|---|
| 26 | * used throughout FACT++, it it must not contain whitespaces or
|
|---|
| 27 | * underscores. Ever word should start with a capital letter,
|
|---|
| 28 | * e.g. 'TriggerOn'
|
|---|
| 29 | *
|
|---|
| 30 | * @param {String} [decription]
|
|---|
| 31 | * A user defined string which gives a more conscise explanation
|
|---|
| 32 | * of the meaning of the state and can also be displayed in the GUI
|
|---|
| 33 | * or anywhere else automatically,
|
|---|
| 34 | * e.g. "System setup and trigger switched on"
|
|---|
| 35 | *
|
|---|
| 36 | * @throws
|
|---|
| 37 | * <li> if something is wrong with the supplied arguments (type, number)
|
|---|
| 38 | * <li> when the index is out of range [10,255]
|
|---|
| 39 | * <li> the given state name is empty
|
|---|
| 40 | * <li> the given state name contains a colon or an equal sign
|
|---|
| 41 | * <li> when a state with the same name or index was already
|
|---|
| 42 | * <li> set since the script was started.
|
|---|
| 43 | *
|
|---|
| 44 | * @returns {Boolean}
|
|---|
| 45 | * A boolean whether the state was newly added (true) or an existing
|
|---|
| 46 | * one overwritten (false).
|
|---|
| 47 | *
|
|---|
| 48 | * @example
|
|---|
| 49 | * dim.newState(10, "StateTen", "This is state number ten");
|
|---|
| 50 | */
|
|---|
| 51 | dimctrl.newState = function() { /* [native code] */ }
|
|---|
| 52 |
|
|---|
| 53 | /**
|
|---|
| 54 | * Change the internal state.
|
|---|
| 55 | *
|
|---|
| 56 | * @param {Integer,String} state
|
|---|
| 57 | * Either the name of the state to set or its index can be supplied.
|
|---|
| 58 | *
|
|---|
| 59 | * @throws
|
|---|
| 60 | * <li> if something is wrong with the supplied arguments (type, number)
|
|---|
| 61 | * <li> if a String is given and it is not found in the list of names
|
|---|
| 62 | *
|
|---|
| 63 | * @returns {Boolean}
|
|---|
| 64 | * A boolean is returned whether setting the state wa sucessfull or
|
|---|
| 65 | * not. If the function is not called at unexpected time, i.e.
|
|---|
| 66 | * before the execution of the JavaScript has been started or
|
|---|
| 67 | * after it has already be terminated, true should be returned
|
|---|
| 68 | * always.
|
|---|
| 69 | *
|
|---|
| 70 | * @example
|
|---|
| 71 | * dim.setState(10);
|
|---|
| 72 | * dim.setState("StateTen");
|
|---|
| 73 | */
|
|---|
| 74 | dimctrl.setState = function() { /* [native code] */ }
|
|---|
| 75 |
|
|---|
| 76 | /**
|
|---|
| 77 | * Get the current internal state.
|
|---|
| 78 | *
|
|---|
| 79 | * @throws
|
|---|
| 80 | * if arguments are supplied
|
|---|
| 81 | *
|
|---|
| 82 | * @returns {Object}
|
|---|
| 83 | * An object with the properties index {Number}, name {String} and
|
|---|
| 84 | * description {String}. Note that name and description might be
|
|---|
| 85 | * an empty string.
|
|---|
| 86 | *
|
|---|
| 87 | * @example
|
|---|
| 88 | * var state = dim.getState();
|
|---|
| 89 | * dim.out(JSON.stringify(state));
|
|---|
| 90 | */
|
|---|
| 91 | dimctrl.getState = function() { /* [native code] */ }
|
|---|
