Index: /trunk/FACT++/scripts/doc/Database.js =================================================================== --- /trunk/FACT++/scripts/doc/Database.js (revision 14644) +++ /trunk/FACT++/scripts/doc/Database.js (revision 14644) @@ -0,0 +1,96 @@ +/** + * @fileOverview + * Documentation of Database connection object + */ + +/** + * @class + * + * Returns a connection to a MySQL server or a specific database. + * + * For connection the MySQL++ library is used. MySQL++ throws exceptions + * in case of errors, e.g. connection timeout.

+ * + * Note that although the object is created with 'new' and there + * is a 'delete' is JavaScript, it will not call any kind of + * destructor. To close a Subscription you have to explicitly call + * the close() member function. 'delete' in JavaScript is only + * to remove a property from an Object. + * + * @param {String} database + * The databse argument is of this form (optional parts ar given in brackets):
+ * user:password@server.domain.com[:port]/database + * + * @throws + *

  • If number or type of arguments is wrong + *
  • If no connection could be opened, an exception with the reason is + * thrown. + * + * @example + * var db = new Database("thomas@sql.at-home.com/database"); + */ +function Database() +{ + /** + * User connected to the database + * @constant + */ + this.user = user; + + /** + * Server which is connected + * @constant + */ + this.server = server; + + /** + * Database which is connected + * @constant + */ + this.database = database; + + /** + * Port connected (if no port was given 'undefined') + * @constant + */ + this.port = port; + + /** + * Returns the result of an sql query sent to the database. + * + * @param arguments + * The arguments specify the query to be sent + * + * @throws + * If no connection could be opened, an exception with the reason is + * thrown. + * + * @returns + * An array is returned. Each entry in the array corresponds to one + * row of the table and is expressed an an associative array (object). + * The names of the entries (columns) in each row are stored in + * a property cols which is an array itself. For convenience, + * table and query are stored in identically names properties. + * + * @example + * var table = db.query("SELECT * FROM table WHERE value BETWEEN", 5, "AND 20"); + * for (var row=0; row<table.length; row++) + * for (var col in table.cols) + * dim.out("table["+row+"]['"+col+"']="+table[row][col]); + * + */ + this.query = function() { /* [native code] */ } + + /** + * + * Close the connection to the database. + * + * The connection is automaically closed at cript termination. + * + * @returns {Boolean} + * If the connection was successfully closed, i.e. it + * was still open, true is returned, false otherwise. + * + */ + this.close = function() { /* [native code] */ } +}; Index: /trunk/FACT++/scripts/doc/Event.js =================================================================== --- /trunk/FACT++/scripts/doc/Event.js (revision 14644) +++ /trunk/FACT++/scripts/doc/Event.js (revision 14644) @@ -0,0 +1,118 @@ +/** + * @fileOverview + * Documentation of the Event object returned by Subscription.get() + */ + +/** + * @class + * + * The object returned by Subscription.get(). It contains + * all data received with the event. + * + */ +function Event() +{ + /** + * The name of the Subscription this event belongs to. + * + * @type String + * @constant + */ + this.name = name; + + /** + * The format string corresponding to this event. + * + * @see DIM for more details + * @type String + * @constant + */ + this.format = format; + + /** + * The Quality-of-Service transmitted by this event. + * + * @type Integer + * @constant + */ + this.qos = qos; + + /** + * The size in bytes of the event received + * + * @type Integer + * @constant + */ + this.size = size; + + /** + * An counter of events received since the Subscription has + * been created. The first event received is 1. 0 corresponds + * to no event received yet. + * + * @type Integer + * @constant + */ + this.counter = counter; + + /** + * The time transmitted with this event, if transmitted. If nonw + * was transmitted, this might just be the time the event was + * received. + * + * @type Date + * @constant + */ + this.time = time; + + /** + * Array with the data received. + * + * The contents of the array are sorted in the order of the event format + * string. The contents of the array can be all kind of objects + * defined by the format string. If a format described several entries + * (e.g. I:5) and array will be added.

    + * + * In the special case that the format string contains only a single + * format, e.g. "I", "F:5" or "C", data will not be an array, + * but contain the object data (or the array) directly. + * + * If valid data was received, but the size was zero, then + * null is returned as data + * + *

  • data===undefined: no data received (no connection) + *
  • data===null: an event was received, but it was empty + *
  • data.length>0: an event was received and it contains data + * + * @type Array + * @constant + * + */ + this.data = [ ]; + + /** + * Object with the data received. + * + * The object contains essentially the same information than the + * data memeber, but the received data are added as properties + * instead of enumerable lements. This allows to access + * the received data by names as specified by the SERVICE_DESC + * service.

    + * + * If an empty event was received, but names are available, + * the object will be empty. Otherwise 'obj' will be undefined. + * + *

  • obj===undefined: no names are available + *
  • obj!==undefined, length==0: names are available, but no data (no connection) + *
  • obj!==undefined, length>0: names are available, data has been received + * + *

    + * Note that to get the number of properties (length) you have to call + * Object.keys(obj).length; + * + * @type Object + * @constant + * + */ + this.obj = { }; +} Index: /trunk/FACT++/scripts/doc/Local.js =================================================================== --- /trunk/FACT++/scripts/doc/Local.js (revision 14644) +++ /trunk/FACT++/scripts/doc/Local.js (revision 14644) @@ -0,0 +1,97 @@ +/** + * @fileOverview + * Documentation of Local class built into dimctrl. + */ + +/** + * @class + * + * A set of coordinates on the celestial sphere. + * + * The class stores a set of coordinates on the celestial, i.e. local, + * sky. If the data was the result of a coordinate transformation, the + * corresponding time is stored in addition. Functions to convert to sky + * coordinates and to measure distances on th sky are included. + * + * @param {Number} zenithDistance + * Zenith angle in degree (Zenith=0deg) + * + * @param {Number} azimuth + * Azimuth angle in degree (North=0deg, East=90deg) + * + * @example + * var local = new Local(12, 45); + * var sky = local.toSky(); + * + * @author Thomas Bretz + * + */ +function Local(zenithDistance, azimuth) +{ + /** + * Zenith distance in degree (Zenith=0deg) + * + * @constant + * + * @type Number + */ + this.zd = zenithDistance; + + /** + * Azimuth in degree (North=0deg, East=90deg) + * + * @constant + * + * @type Number + */ + this.az = azimuth; + + /** + * Time corresponding to ra and dec if they are the result of + * a conversion. + * + * @constant + * @default undefined + * + * @type Date + */ + this.time = undefined; + + + /** + * Convert celestial coordinats to sky coordinates. + * As observatory location the FACT telescope is assumed. + * The conversion is done using libnova's ln_get_equ_from_hrz. + * + * @constant + * + * @param {Date} [time=new Date()] + * Reference time for the conversion + * + * @returns {Sky} + * A Sky object with the converted coordinates and + * the corresponding time. + */ + this.toSky = function() { /* [native code] */ } + + /** + * Calculate the distance between two celestial sky positions. + * + * The distance between this object and the provided celestial + * position on the sky is calculated. The returned value + * is an absolute distance (angle) between the two positions. + * + * @constant + * + * @param {Local} local + * Celestial coordinates to which the distance on the sky + * should be calculated. In principle every object with + * the properties 'zd' and 'az' can be provided. + * @param {Number} local.zd Zenith distance of the object + * @param {Number} local.az Azimuth of the object + * + * @returns {Number} + * Absolute distance between both positions on the sky in degrees. + */ + this.dist = function() { /* [native code] */} +} Index: /trunk/FACT++/scripts/doc/Moon.js =================================================================== --- /trunk/FACT++/scripts/doc/Moon.js (revision 14644) +++ /trunk/FACT++/scripts/doc/Moon.js (revision 14644) @@ -0,0 +1,85 @@ +/** + * @fileOverview + * Documentation of Moon class built into dimctrl. + */ + +/** + * @class + * + * Calculates the moon's sky position at a given time. + * + * When instantiated, the class members are set to the sky position + * of the moon at the given time. The calculation is done using + * libnova's ln_get_lunar_equ_coords. A different time can be provided + * by the user. The sky coordinates are stored together with the time. + * A function is provided to convert the moon's position to celestial + * coordinates. A function to calculate the illuminated fraction of + * the moon's disk. + * + * @param {Date} [time=new Date()] + * Reference time for the calculation of the moon's position. + * + * @example + * var moon = new Moon(); + * var local = moon.toLocal(); + * + * @author Thomas Bretz + */ +function Moon(time) +{ + /** + * Right ascension of the moon in hours. + * + * @type Number + * @constant + * + */ + this.ra = 0; + + /** + * Declination of the moon in degrees. + * + * @type Number + * @constant + * + */ + this.dec = 0; + + /** + * Time corresponding to the calculated sky coordinates of the moon. + * + * @type Date + * @constant + */ + this.time = time; + + /** + * Converts the moon's sky coordinates to celestial coordinates. + * As observatory location the FACT telescope is assumed. For the + * time, the time corresponding to the stored sky coordinates is used. + * The conversion is done using libnova's ln_get_hrz_from_equ. + * + * @returns {Local} + * A Local object with the converted coordinates and + * the corresponding time. + */ + this.toLocal = function() { /* [native code] */ } +} + +/** + * Calculates the illuminated fraction of the moon's disk for the + * provided time. If no time is provided, the current system time + * is used. The calculation is done using libnova's ln_get_lunar_disk. + * + * @param {Date} [time=new Date()] + * Time for which the moon disk should be calculated. If no time is + * given, the current time is used. + * + * @type Number + * + * @returns + * The illuminated fraction of the moon's disk corresponding + * to the time argument + * + */ +Moon.disk = function() { /* [native code] */ } Index: /trunk/FACT++/scripts/doc/Sky.js =================================================================== --- /trunk/FACT++/scripts/doc/Sky.js (revision 14644) +++ /trunk/FACT++/scripts/doc/Sky.js (revision 14644) @@ -0,0 +1,73 @@ +/** + * @fileOverview + * Documentation of Sky class built into dimctrl. + */ + + +/** + * @class + * + * This class represents a set of sky coordinates. + * + * If the data was the result of a coordinate transformation, the + * corresponding time is stored in addition. A function to convert + * to local coordinates is included. + * + * @param {Number} rightAscension + * Right ascension in hours + * + * @param {Number} declination + * Declination in degree + * + * @example + * var sky = new Sky(12, 45); + * var local = sky.toLocal(); + * + * @author Thomas Bretz + * + */ +function Sky() +{ + + /** + * Right ascension in hours + * + * @constant + * @type Number + */ + this.ra = rightAscension + + /** + * Declination in degrees + * + * @constant + * @type Number + */ + this.dec = declination; + + /** + * Time corresponding to ra and dec if they are the result of + * a conversion. + * + * @constant + * @type Date + */ + this.time = undefined; + + /** + * Convert sky coordinates to celestial coordinates. + * As observatory location the FACT telescope is assumed. + * The conversion is done using libnova's ln_get_hrz_from_equ. + * + * @param {Date} [time=new Date()] + * Reference time for the converstion. + * + * @type Local + * + * @returns + * A Local object with the converted coordinates and + * the conversion time. + */ + this.toLocal = function() { /* [native code] */ } +} + Index: /trunk/FACT++/scripts/doc/String.js =================================================================== --- /trunk/FACT++/scripts/doc/String.js (revision 14644) +++ /trunk/FACT++/scripts/doc/String.js (revision 14644) @@ -0,0 +1,100 @@ +/** + * @fileOverview + * Documentation of the extension of the String class + * built into dimctrl. + */ + +/** + * Format a string (similar to printf in C). + * + * This function replaces modifiers (very similar to printf) with + * a formated version of the argument. Since JavaScript does implicit + * format conversion already, this is actually a very powerful tool, + * because the type of th arguments to be formated is of no importance. + * Implicit conversion means that also arrays and objects can be given + * as arguments. A shortcut is available as $-extension of the native + * String class.

    + * + * Note that this function is completely written in JavaScript. It + * can be found in InterpreterV8.cc.

    + * + * The following modifiers are available (optional parts are put in + * brackets:
    + * + *

  • c: %[[-][0]N]c
    + *
    Extracts the first element from an array. In case of a String this + * is the first character.

    + * + *

  • s: %[[-][0]N]s
    + *
    Converts the argument to a string using toString()

    + * + *

  • f: %[[-][0]N[.n]]f
    + *
    Converts to a Number value with n internal decimal places

    + * + *

  • p: %[[-][0]N[.n]]p
    + *
    Converts to a Number value with a precision of n decimal places

    + * + *

  • e: %[[-][0]N]e
    + *
    Converts to an exponential with a precision of n decimal places

    + * + *

  • x: %[[-][0]N[#b]x
    + *
    Converts to an integer value using the basis b for conversion + * (default is 16 for hexadecimal)

    + * + *

  • d: %[[-][0]N[.n][#b]]d
    + *
    Converts from a value using the basis b for conversion (default + * is 10 for decimal). The integer can be rounded to the given precision n. + *

    + * + * The output string will have at least a length of N. If 0 is given, + * it is filled with 0's instead of white spaces. If prefixed by a minus + * the contents will be left aligned. + * + * @param {String} format + * The format string defining how the given argument elements are + * formated + * + * @param {Array} elements + * An array with the elements to be formated + * + * @returns {String} + * The formated string is returned. + * + * @see + * String.$ + * + * @example + * var result; + * result = String.form("%5d %3d", [ 5, "2" ]); + * result = String.form("%5x", [ 12 ]); + * result = String.form("%#16d", [ "b" ]); + * result = String.form("%s", [ [ 1, 2, 3, ] ]); + * result = String.form("%s", [ { a:1, b:2, c:3, } ]); + * var abbrev = "%03d".$(42); + * + */ +String.form = function() { /* [native code] */ } + + +/** + * An abbreviation for String.form. + * + * Converts all arguments provided by the user into an array + * which is passed to String.form. The contents of the String itself + * is passed as format string. This allows a very compact syntax to + * format any kind of object, array or number. + * For details see String.form. + * + * @param arg An argument to be formated. + * @param [. . .] An undefined number of additional optional arguments. + * + * @returns {String} see String.form + * @throws see String.form + * @see String.form + * + * @example + * var result = "%5d = %12s".$(5, "five"); + * + * @author Thomas Bretz + */ +String.prototype.$ = function() { /* [native code] */ }; Index: /trunk/FACT++/scripts/doc/Subscription.js =================================================================== --- /trunk/FACT++/scripts/doc/Subscription.js (revision 14644) +++ /trunk/FACT++/scripts/doc/Subscription.js (revision 14644) @@ -0,0 +1,121 @@ +/** + * @fileOverview + * Documentation of a DIM service Subscription + */ + +/** + * @class + * + * Creates a handle to a new thread. The handle can be used to + * kill the thread or be ignored. The function provided is + * executed after an initial timeout. Note that although this + * looks similar to the setTimeout in web-browsers, after started, + * the thread will not run until completion but run in parallel to + * the executed script.

    + * + * Note that although the object is created with 'new' and there + * is a 'delete' is JavaScript, it will not call any kind of + * destructor. To close a Subscription you have to explicitly call + * the close() member function. 'delete' in JavaScript is only + * to remove a property from an Object. + * + * @param {Integer} timeout + * A positive integer given the initial delay in milliseconds before + * the thread is executed. + * + * @param {Function} function + * A function which is executed aftr the initial timeout. + * + * @throws + *

  • If number or type of arguments is wrong + * + * @example + * var handle = new Thread(100, function() { dim.out("Hello world!"); }); + * handle.kill(); + */ +function Subscription(service) +{ + /** + * + * The name of the service subscribed to. + * + * @constant + * @type String + * + */ + this.name = service; + + /** + * + * Boolean value which is set to false if the Subscription was closed. + * + * @type Boolean + * + */ + this.isOpen = false; + + /** + * + * Callback in case of event reception. + * + * To install a callback in case a new event of this Subscription + * was received, set this property to a function. The argument + * provided to the function is identical with the object returned + * by Subscription.get(). For the code executed, the same rules apply + * than for a thread created with Thread. + * + * @type Function + * + * @example + * subscription.onchange = function(event) { dim.out(JSON.stringify(event); }; + * + */ + this.onchange = func; + + /** + * + * Returns the last received event of this subscription. + * + * @param {Integer} [timeout=0] + * A timeout in millisecond to wait for an event to arrive. + * This timeout only applied if no event has been received yet + * after a new Subscription has been created. If an event + * is already available, the event is received. If the timeout + * is 'null', waiting will nevr timeout until an event was received. + * If the timeout is less than zero, no exception will be thrown, + * but 'undefined' returned in case of timeout. The corresponding + * timeout is then Math.abs(timeout). + * + * @param {Boolean} [requireNamed=true] + * Usually an event is only considered complete, if also the + * corresponding decription is available distcibuted through + * the service SERVER/SERVICE_DESC. If an event has no + * subscription or it is not important, requireNamed can + * be set to false. + * + * @throws + *
  • If number or type of arguments is wrong + *
  • After a timeout, if the timeout value was greater or equal zero + *
  • If conversion of th received data to an event object has failed + * + * @returns {Event} + * If the thread was still known, true is returned, false + * otherwise. If the thread terminated already, false is + * returned. + * + */ + this.get = function() { /* [native code] */ } + + /** + * + * Unsubscribe from an existing subscription. Note that all open + * subscription produce network traffic and should be omitted if + * not needed. + * + * @returns {Boolean} + * true if the subscription was still open, false if it was + * already closed. + * + */ + this.close() = function() { /* [native code] */ } +} Index: /trunk/FACT++/scripts/doc/Thread.js =================================================================== --- /trunk/FACT++/scripts/doc/Thread.js (revision 14644) +++ /trunk/FACT++/scripts/doc/Thread.js (revision 14644) @@ -0,0 +1,50 @@ +/** + * @fileOverview + * Documentation of the Thread object + */ + +/** + * @class + * + * Creates a handle to a new thread. + * + * The handle can be used to + * kill the thread or be ignored. The function provided is + * executed after an initial timeout. Note that although this + * looks similar to the setTimeout in web-browsers, after started, + * the thread will not run until completion but run in parallel to + * the executed script.

    + * + * To stop the script from within a thread, use exit(). To stop only + * execution of the thread (silently) throw a null exception + * ("throw null;"). To terminate the script with an exception + * throw a normal exception ("throw new Error("my error");"). + * + * @param {Integer} timeout + * A positive integer given the initial delay in milliseconds before + * the thread is executed. + * + * @param {Function} function + * A function which is executed aftr the initial timeout. + * + * @throws + *

  • If number or type of arguments is wrong + * + * @example + * var handle = new Thread(100, function() { dim.out("Hello world!"); }); + * handle.kill(); + */ +function Thread(timeout, function) +{ + /** + * + * Kills a running thread + * + * @returns {Boolean} + * If the thread was still known, true is returned, false + * otherwise. If the thread terminated already, false is + * returned. + * + */ + this.kill = function() { /* [native code] */ } +}; Index: /trunk/FACT++/scripts/doc/_global_.js =================================================================== --- /trunk/FACT++/scripts/doc/_global_.js (revision 14644) +++ /trunk/FACT++/scripts/doc/_global_.js (revision 14644) @@ -0,0 +1,123 @@ +/***************************************************************************/ +/*** ***/ +/*** JsDoc: http://code.google.com/p/jsdoc-toolkit/w/list ***/ +/*** ***/ +/*** jsdoc -d=html/dimctrl scripts/doc/ ***/ +/*** ***/ +/***************************************************************************/ +/** + * @fileOverview + * Documentation of the native functions built into dimctrl's + * global namespace. + */ + +/** + * An associative array containing the user supplied arguments identical to arg. + * + * @static + * @type Array + * + * @example + * var value = $['name']; + * + */ +_global_.$ = []; + +/** + * An associative array containing the user supplied arguments identical to $. + * + * @static + * @type Array + * + * @example + * for (var key in args) + * dim.out("args["+key+"]="+args[key]); + */ +_global_.arg = []; + + +/** + * Includes another java script. + * + * Note that it is literally included, + * i.e. its code is executed as if it were at included at this + * place of the current file. + * + * @param {String} [name="test"] + * Name of the file to be included. The base directory is + * the directory in which dimctrl was started. + * + * @param {String} [. . . ] + * More files to be included + * + * @type Array + * + * @static + * + */ +_global_.include = function() { /* [native code] */ } + +/** + * Forecefully exit the current script. This function can be called + * from anywhere and will terminate the current script. + * + * The effect is the same than throwing a null expecption ("throw null;") + * in the main thread. In every other thread or callback, the whole script + * will terminate which is different from the behaviour of a null exception + * which only terminates the corresponding thread. + * + * @static + * + */ +_global_.exit = function() { /* [native code] */ } + +/** + * + * @returns {String} + * A string with the JavaScript V8 version is returned. + * + * @static + * + */ +_global_.version = function() { /* [native code] */ } + +/** + * Reads a file as a whole. + * + * Files can be split into an array when reading the file. It is + * important to note that no size check is done. So trying to read + * a file larger than the available memory will most probably crash + * the program. Strictly speaking only reading ascii fils make sense. + * Also gzip'ed files are supported. + * + * Note that this is only meant for debugging purpose and should + * not be usd in a production environment. Scripts should not + * access any files by defaults. If external values have to be + * provided arguments should be given to the script. + * + * @static + * + * @param {String} name + * Name of the file to read. The base directory is the current + * working directory + * + * @param {String} [delim=undefined] + * A delimiter used to split the file into an array. If provided + * it must be a String of length 1. + * + * @returns {String,Array[String]} + * If no delimiter is given, a StringObject with the file (read + * until \0) is returned. If a delimiter is given, an array + * of Strings is returned, one for each chunk. Both objects + * contain the property 'name' with the file name and the array + * contains the property 'delim' with the used delimiter. + * + * @throws + *
  • If number or type of arguments is wrong + *
  • If there was an error reading the file, the system error is thrown + * + * @example + * var string = File("fact++.rc"); + * var array = File("fact++.rc", "\n"); + */ +_global_.File = function() { /* [native code] */ } Index: /trunk/FACT++/scripts/doc/dim.js =================================================================== --- /trunk/FACT++/scripts/doc/dim.js (revision 14644) +++ /trunk/FACT++/scripts/doc/dim.js (revision 14644) @@ -0,0 +1,190 @@ +/** + * @fileOverview + * Documentation of dim namespace. + */ + +/** + * @namespace + * + * Namespace for extension functions dealing with the DIM network. + * + * @author Thomas Bretz + */ +var dim = { }; + +/** + * Sleep for a while. This can be used to just wait or give time + * back to the operating system to produce less CPU load if the + * main purpose of a loop is, e.g., to wait for something to happen. + * + * @param {Integer} [milliseconds=0] + * Number of millliseconds to sleep. Note that even 0 will always + * sleep at least one millisecond. + * + */ +dim.sleep = function() { /* [native code] */ } + +/** + * + * Post a message into the dim log stream. + * + * It will be logged by the datalogger, displayed on the console + * and in the smartfact web-gui. + * + * @param argument + * Any kind of argument can be given. If it is not a String, it + * is converted using the toString() member function. + * + * @param [. . .] + * Any number of additional arguments. Each argument will appear in + * a new line. + * + * @example + * dim.print("Five="+5, "--- new line ---"); + * + */ +dim.print = function() { /* [native code] */ } + +/** + * + * Posts a message to the dim network with alarm severity. + * + * Similar to dim.print, but the message is posted to the network + * with alarm severity. This means that it is displayed in red + * and the smartfact web-gui will play an alarm sound. + * The alarm state will stay valid (displayed in the web-gui) until it + * is reset. + * + * @param argument + * Any kind of argument can be given. If it is not a String, it + * is converted using the toString() member function. + * + * @param [. . .] + * Any number of additional arguments. Each argument will appear as + * individual alarm. + * + * @example + * dim.alarm("Alarm for 30 seconds!"); + * dim.sleep(30000); + * dim.alarm(); + */ +dim.alarm = function() { /* [native code] */ } + +/** + * + * Displays a message on the local console (only). + * + * @param argument + * Any kind of argument can be given. If it is not a String, it + * is converted using the toString() member function. + * + * @param [. . .] + * Any number of additional arguments. Each argument will appear in + * a new line. + * + * @example + * dim.out("Five="+5, "--- new line ---"); + * + */ +dim.out = function() { /* [native code] */ } + +/** + * + * Send a dim command to a dim client. + * + * @param {String} commandId + * The command id is a string and usually compiles like + * 'SERVER/COMMAND' + * + * @param argument + * Any kind of argument can be given. Arguments are internally + * converted into strings using toString() and processed as + * if they were typed on th console. + * + * @param [. . .] + * Any number of additional arguments. + * + * @example + * dim.send('DRIVE_CONTROL/TRACK_SOURCE 0.5 180 "Mrk 421"'); + * dim.send('DRIVE_CONTROL/TRACK_SOURCE', 0.5, 180, 'Mrk 421'); + * + * @returns + * A boolean value is returned whether the command was succesfully + * posted into the network or not. Note that true does by no means + * mean that the command was sucessfully received or even processed. + */ +dim.send = function() { /* [native code] */ } + +/** + * Returns the state of the given server. + * + * @param {String} name + * The name of the server of which you want to get the state. + * + * @throws + * If number or type of arguments is wrong + * + * @returns {Object} + * An object with the properties 'index' {Integer} and 'name' {String} + * is returned if a connection to the server is established and + * state information have been received, 'undefined' otherwise. If + * the time of the last state change is available it is stored + * in the 'property'. If a server disconnected, a valid object will + * be returned, but without any properties. + */ +dim.state = function(server, timeout) { /* [native code] */ } + +/** + * Wait for the given state of a server. + * + * @param {String} name + * The name of the server of which you want to wait for a state. + * The name must not contain quotation marks. + * + * @param {String,Integer} state + * The state you want to wait for. It can either be given as an Integer + * or as the corresponding short name. If given as String it must + * not contain quotation marks. + * + * @param {Integer} [timeout] + * An optional timeout. If no timeout is given, waiting will not stop + * until the condition is fulfilled. A timeout of 0 is allowed and + * will essentially just check if the server is in this state or not. + * + * @throws + *
  • If number or type of arguments is wrong + *
  • If no connection to the server is established or no state + * has been received yet. This is identical to dim.state() + * returning 'undefined'. + * + * @returns {Boolean} + * true if the state was achived within the timeout, false otherwise. + */ +dim.wait = function() { /* [native code] */ } + +/** + * + * Callback in case of state changes. + * + * To install a callback in case the state of a server changes. set + * the corresponding property of this array to a function. The argument + * provided to the function is identical with the object returned + * by dim.state(). In addition the name of the server is added + * as the 'name' property and the comment sent with the state change + * as 'comment' property. For the code executed, the same rules apply + * than for a thread created with Thread.

    + * + * If a state change is defined for a server for which no callback + * has been set, the special entry '*' is checked. + * + * + * @type Array[Function] + * + * @example + * dim.onchange['*'] = function(state) { dim.out("State change from "+state.name+" received"); } + * dim.onchange['DIM_CONTROL'] = function(state) { dim.out(JSON.stringify(state); } + * ... + * delete dim.onchange['DIM_CONTROL']; // to remove the callback + * + */ +dim.onchange = []; Index: /trunk/FACT++/scripts/doc/dimctrl.js =================================================================== --- /trunk/FACT++/scripts/doc/dimctrl.js (revision 14644) +++ /trunk/FACT++/scripts/doc/dimctrl.js (revision 14644) @@ -0,0 +1,91 @@ +/** + * @fileOverview + * Documentation of the dimctrl namespace + */ + +/** + * @namespace + * + * Global namespace for functions dealing with the dimctrl state + * + * @author Thomas Bretz + */ +var dimctrl = { }; + +/** + * Define a new internal state. + * + * States should be defined when a script is started. + * + * @param {Integer} index + * The intgeger number assigned to the new state. Only numbers + * in the range [10, 255] are allowed. + * + * @param {String} [name] + * 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' + * + * @param {String} [decription] + * 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). + * + * @example + * dim.newState(10, "StateTen", "This is state number ten"); + */ +dimctrl.newState = function() { /* [native code] */ } + +/** + * Change the internal state. + * + * @param {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. + * + * @example + * dim.setState(10); + * dim.setState("StateTen"); + */ +dimctrl.setState = function() { /* [native code] */ } + +/** + * Get the current internal 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. + * + * @example + * var state = dim.getState(); + * dim.out(JSON.stringify(state)); + */ +dimctrl.getState = function() { /* [native code] */ }