Revision: 3597
http://vexi.svn.sourceforge.net/vexi/?rev=3597&view=rev
Author: mkpg2
Date: 2009-08-11 02:35:50 +0000 (Tue, 11 Aug 2009)
Log Message:
-----------
JSDoc documentation
Modified Paths:
--------------
trunk/core/org.ibex.js/src/org/ibex/js/JS.jpp
trunk/core/org.ibex.js/src/org/ibex/js/JSNumber.java
trunk/core/org.ibex.js/src/org/vexi/js/VexiJS.jpp
trunk/core/org.vexi.core/src/org/vexi/core/Vexi.jpp
Modified: trunk/core/org.ibex.js/src/org/ibex/js/JS.jpp
===================================================================
--- trunk/core/org.ibex.js/src/org/ibex/js/JS.jpp 2009-08-11 02:33:39 UTC
(rev 3596)
+++ trunk/core/org.ibex.js/src/org/ibex/js/JS.jpp 2009-08-11 02:35:50 UTC
(rev 3597)
@@ -440,16 +440,26 @@
//#noswitch - leave, needed for jsdoc
/*...@page(varname=Proxy,humanname=Proxy Object)
*
- * <p>The proxy object is an alternative map object to the
- * standard js object, which supports a 'range trap' 'Properties'
to
- * trap on the accessingadding/removing of properties</p>
- *
- * <code>
- * proxylist.Properties ++= function(){} // a (range) read trap
<br/>
- * proxylist.Properties ++= function(v){} // a (range) write trap
- * </code>
+ * <p>The proxy object is an alternative map object to the
standard js object, which
+ * supports a 'range trap' <code>Properties</code> to trap on the
+ * accessingadding/removing of properties.</p>
*
* */
+ /* <p>The <code>Properties</code> property is a
<em>meta-property</em>
+ * representing a gateway for accessing the properties of the
proxy object.</p>
+ *
+ * <p>Placing a trap on this allows the interception of all read
and writes to this
+ * proxy object</p>
+ *
+ * <pre>
+ * proxy.Properties ++= function(){} // a (range) read trap
+ * proxy.Properties ++= function(v){} // a (range) write trap
+ * </pre>
+ *
+ * @initial_value(N/A,code=false)
+ * @type(<i>N/A</i>)
+ * */
+ //also "Properties":
//#end
Trap rangeTrap =
propertiesTrap==null?null:propertiesTrap.findRead();
@@ -562,10 +572,11 @@
* standard js array, which supports a 'range trap' 'Elements'
to
* trap on the accessingadding/removing of elements</p>
*
- * <code>
- * proxylist.Elements ++= function(){} // a (range) read
trap <br/>
- * proxylist.Elements ++= function(v){} // a (range) write
trap
- * </code>
+ * <p>Whereas the Proxy is very similar to the standard Object
the ProxyList is not
+ * similar to an array and so cannot be used as a drop in
replacement. Notably
+ * it does not support most of the methods that arrays have,
and it is not sparse
+ * and cannot contain nulls. Putting null to a proxy list will
remove the object
+ * at the index. </p>
*
* */
/* The length of the ProxyList @type(Number) */
@@ -579,6 +590,21 @@
* @return(Number)
* */
case "indexOf": return METHOD;
+ /* <p>The <code>Elements</code> property is a
<em>meta-property</em>
+ * representing a gateway for accessing the properties of the
proxylist object.</p>
+ *
+ * <p>Placing a trap on this allows the interception of all
read and writes to this
+ * proxylist object</p>
+ *
+ * <pre>
+ * proxylist.Elements ++= function(){} // a (range) read
trap
+ * proxylist.Elements ++= function(v){} // a (range) write
trap
+ * </pre>
+ *
+ * @initial_value(N/A,code=false)
+ * @type(<i>N/A</i>)
+ * */
+ //also "Elements":
//#end
throw new JSExn("Attempt to get unrecognized string key
'"+key+"' from a ProxyList");
}
Modified: trunk/core/org.ibex.js/src/org/ibex/js/JSNumber.java
===================================================================
--- trunk/core/org.ibex.js/src/org/ibex/js/JSNumber.java 2009-08-11
02:33:39 UTC (rev 3596)
+++ trunk/core/org.ibex.js/src/org/ibex/js/JSNumber.java 2009-08-11
02:35:50 UTC (rev 3597)
@@ -58,12 +58,14 @@
public String coerceToString() { return d == (long) d ?
Long.toString((long)d) : Double.toString(d); }
}
- final static class B extends JSNumber {
+ final static public class B extends JSNumber {
+ static public JS Constructor = new JS.Constructor("Boolean");
private final boolean b;
B(boolean b) { this.b = b; }
int toInt() { return b ? 1 : 0; }
public String coerceToString() { return b ? "true" : "false"; }
public JS type() { return SC_boolean;}
+ public boolean instanceOf(JS constructor){ return
constructor==Constructor; }
}
public JS type() { return SC_number;}
public boolean instanceOf(JS constructor){ return
constructor==Constructor; }
Modified: trunk/core/org.ibex.js/src/org/vexi/js/VexiJS.jpp
===================================================================
--- trunk/core/org.ibex.js/src/org/vexi/js/VexiJS.jpp 2009-08-11 02:33:39 UTC
(rev 3596)
+++ trunk/core/org.ibex.js/src/org/vexi/js/VexiJS.jpp 2009-08-11 02:35:50 UTC
(rev 3597)
@@ -367,8 +367,10 @@
*
* @param(name=size,optional=true)*/
case "Array": return org.ibex.js.JSArray.Constructor;
+ case "Boolean": return org.ibex.js.JSNumber.B.Constructor;
case "Exception": return org.ibex.js.JSExn.Constructor;
case "Object": return org.ibex.js.JS.Obj.Constructor;
+ case "Number": return org.ibex.js.JSNumber.Constructor;
case "Proxy": return org.ibex.js.JS.Proxy.Constructor;
case "ProxyList": return org.ibex.js.JS.ProxyList.Constructor;
/* @jpp(org.ibex.js.JSPrimitive) */
Modified: trunk/core/org.vexi.core/src/org/vexi/core/Vexi.jpp
===================================================================
--- trunk/core/org.vexi.core/src/org/vexi/core/Vexi.jpp 2009-08-11 02:33:39 UTC
(rev 3596)
+++ trunk/core/org.vexi.core/src/org/vexi/core/Vexi.jpp 2009-08-11 02:35:50 UTC
(rev 3597)
@@ -25,40 +25,87 @@
/*...@page(concept=Overview)
* <p><b>Table of Contents</b></p>
* <dl>
- * <dt><a href="#Definitions">Definitions</a></dt>
- * <dt><a href="#Boxes">Boxes</a></dt>
- * <dt><a href="#Surfaces">Surfaces</a></dt>
- * <dt><a href="#Templates">Templates</a></dt>
+ * <dt><a href="#Preface">Preface</a></dt>
+ * <dt><a href="#Anatomy">Anatomy of an Application</a></dt>
+ * <dt><a href="#Glossary">Glossary</a></dt>
+ * <dt><a href="#Acknowledgements">Acknowledgements</a></dt>
* </dl>
*
- * <h3><a name="Definitions"></a>Definitions</h3>
+ * <h3><a name="Preface"/>Preface</h3>
+ * <p>A complete documentation of all system objects that are to be used in
creating Vexi
+ * applications. This is reference material only and contains no examples or
+ * explanations beyond descriptions of specific properties and concepts.</p>
+ *
+ * <p>If there are any discrepancies between this reference and the
implementation then please
+ * log it at the <a href="http://sourceforge.net/projects/vexi";
target="_blank">project website</a> on
+ * Sourceforge.</p>
+ *
+ * <h3><a name="Anatomy"/>Anatomy of an Application</h3>
+ *
+ * // TODO
+ *
+ *
+ *
+ * <h3><a name="Glossary"/>Glossary</h3>
* <dl>
- * <dt>Core</dt>
- * <dd><p>Vexi itself; the native code (or Java bytecode) that runs on the
client. This term
- * does not include the launcher or the UI.</p></dd>
* <dt>UI / Application</dt>
- * <dd><p>A set of files (mostly XML, JavaScript, and PNG images) bundled up
in a zip archive,
- * ending with the ".vexi" extension. Together, these files specify the
appearance and
- * behavior of the application's user interface.</p></dd>
- * <dt>Server</dt>
- * <dd><p>In this document, the term "server" refers to any other computer
which the client
- * makes XML-RPC or SOAP calls to. Note that it is possible for the
client and server to be
- * the same machine. </p></dd>
+ * <dd><p>A Vexi UI is defined by a set of files (template files, and
resources) all accessible
+ * on the <em>Vexi Path</em>. Together, these files specify the
appearance and behavior of
+ * a user interface. The term UI is prefered to Application as typically
the Vexi code is
+ * just the client part of an application. </p></dd>
+ *
+ * <dt>Archive</dt>
+ * <dd><p>A Vexi Archive or is a zip archive of template files and resources
with the ".vexi"
+ * extension.</p></dd>
+ *
+ * <dt>Box</dt>
+ * <dd><p>The box is the fundamental building block of a Vexi user
interface. All graphical
+ * components are created using combinations of box layout and widgets
created using box layout.
+ * </p></dd>
+ *
+ * <dt><a name="Core"/>Core</dt>
+ * <dd><p>The Core, or Vexi Core refers to the program that will execute a
Vexi application. The
+ * reference implementation of the core is implemented in Java and
hosted on sourceforge.
+ * </p></dd>
+ *
* <dt>Launcher</dt>
* <dd><p>This is a small component that is downloaded the first time a
client visits a Vexi
* application. It downloads the Vexi Core, and launches it with the
appropriate parameters
* indicating where to find the initial UI. The launcher is outside the
scope of this
* document. Note that the launcher is specific to each server it runs
from in order to
* prevent misuse.</p></dd>
+ *
+ * <dt>Path</dt>
+ * <dd><p>The Path, or Vexi Path is the list of locations from which
templates are loaded.
+ * A location is a either a .vexi archive or a directory, and may either
be local or a http://
+ * path. </p></dd>
+ *
+ * <dt>RPC</dt>
+ * <dd><p>Remote Procedure Call. Usually in Vexi it refers to one of the
inbuilt protocols,
+ * XMLRPC or JSON. Though implementing other protocols is possible over
using the lower
+ * level HTTP api in Vexi</p></dd>
+ *
+ * <dt>Server</dt>
+ * <dd><p>In this document, the term "server" refers to any other computer
which the client
+ * makes RPCs to (XMLRPC, JSON or other HTTP). Note that it is possible
for the client
+ * and server to be the same machine. </p></dd>
+ *
+ * <dt>Template File</dt>
+ * <dd><p>A Vexi Template File or .t is a Vexi sourcecode file. It is
XML+VexiScript. The XML
+ * describes the initial structure (of boxes or other js) that will be
created when the
+ * template is instantiated and the VexiScript defines the
behaviour.</p></dd>
+ *
* <dt>To put/write</dt>
* <dd><p>In ECMAscript, when you change the value of a property on an
object, you are putting
* to that property, or writing to it. For example, the ECMAscript
expression "foo.bar = 5"
* puts the value 5 to the bar property on object foo.</p></dd>
+ *
* <dt>To get/read</dt>
* <dd><p>In ECMAscript, when you access the value of a property on an
object, you are getting
* that property, or reading from it. For example, the ECMAscript
expression
* <code>return (3 + foo.bar)</code> gets the value of bar property on
object foo and then
* adds 3 to it before returning the result. </p></dd>
+ *
* <dt>VexiScript</dt>
* <dd><p>This is the interpreted language which defines the behaviour of
Vexi applications.
* It is essentially ECMAScript 1.5 (more commonly known as JavaScript)
with enhancements
@@ -66,13 +113,70 @@
* ECMAScript-compliant, therein this document will only use the term
VexiScript.</p></dd>
* </dl>
*
- * <h3><a name="Boxes"></a>Boxes</h3>
- * <p>The box is the fundamental building block of a Vexi user interface.
All graphical components
- * are created using combinations of box layout and widgets created using
box layout.</p>
- *
- * <h3><a name="Surfaces"></a>Surfaces</h3>
+ * <h3><a name="Acknowledgements"/>Acknowledgements</h3>
+ * <h4>Charles Goodwin</h4>
+ * <a href="http://www.webenableit.com/"; target="_top">Web Enable IT Ltd</a>
+ * <br><<a
href="mailto:[email protected]";>[email protected]</a>></code>
+ * <h4>Adam Megacz</h4>
+ * <p>Inspired by and contains modified portions of the XWT Reference
authored by Adam Megacz.</p>
+ * <h4>Adam Andrews</h4>
+ * <p>Contains modified portions of the Vexi 1.0 Function Reference
authored by Adam Andrews.</p>
+ * <a href="http://www.rocketlogic.com/"; target="_top">Rocket Logic Inc</a>
+ *
+ * <br><br><p>Copyright \xA9 2009 The Vexi Project</p>
*
- * <h3><a name="Templates"></a>Templates</h3>
+ * */
+
+
+/*...@page(concept=Biscuits)
+ *
+ * <p>Biscuits are analgous to the browser concept of cookies, but only exist
on the client side of
+ * a Vexi application by default (whereas cookies are transmitted over http).
Using the
+ * <code>vexi.biscuits</code> object, you can store an arbitrary set of
information e.g. in XML or
+ * JSON format. The important aspect of biscuits is that they are stored
against the URL of the
+ * application launcher. A biscuit is a stream, ...</p>
+ *
+ */
+
+/*...@page(concept=Streams)
+ *
+ * <h4>Objects may have an associated stream...</h4>
+ *
+ * <p>Each objects may have a <i>stream</i> associated with it. A stream is a
sequence of bytes
+ * that can be read or written to. </p>
+ *
+ * <h4>...but streams are not objects</h4>
+ *
+ * <p>You cannot actually reference a stream, since it is not an object.
Instead, you simply
+ * reference the object it belongs to. If you are familiar with Java, this is
similar to how
+ * every Java object has a monitor associated with it, but you cannot directly
manipulate the
+ * monitor (you can't pass around a reference to just the monitor).</p>
+ *
+ * */
+
+/*...@page(concept=Surfaces)
+ *
+ * <p>Each top-level window in a Vexi UI is called a <i>surface</i>. There are
two kinds of
+ * surfaces: <i>frames</i>, which usually have a platform-specific titlebar
and border, and
+ * <i>windows</i>, which never have any additional platform-specific
decorations. </p>
+ *
+ * <p>Whenever we refer to the size or position of a surface, we are referring
to the size or
+ * position of the UI-accessible portion of the surface; this does not include
any
+ * platform-specific decorations. This means that if you set the position of a
frame to (0,0), the
+ * platform-specific titlebar will actually be off the screen on most
platforms (it will be above
+ * and to the left of the top-left corner of the screen).</p>
+ *
+ * <p>Surfaces are not actual JavaScript objects; you cannot obtain a
reference to a surface.
+ * However, each surface is uniquely identified by its <i>root box</i>.</p>
+ *
+ */
+
+
+
+
+
+/*...@page(concept=Templates)
+ *
* <p>Reusable widgets can be created in Vexi by defining them in templates.
Templates are plain
* text files with a '.t' extension and are XML compliant.</p>
* <p>A Vexi template has a root XML node <code><vexi /></code> whose
parameters are the
@@ -105,7 +209,9 @@
* </vexi>
* </pre>
*
- * */
+ *
+ */
+
/*...@page(concept=Threading)
*
* <p>All vexiscript threads execute synchronously. This is to say that at any
one time only ever
@@ -325,7 +431,9 @@
/* Maximum dimension for a box. @type(Number) */
case "ui.maxdim": return JSU.N(Box.MAX_DIMENSION);
case "ui.screen": return getSub(name);
+ /* Current screen height in pixels. @type(Number) */
case "ui.screen.width": return JSU.N(Platform.getScreenBounds().width);
+ /* Current screen width in pixels. @type(Number) */
case "ui.screen.height": return
JSU.N(Platform.getScreenBounds().height);
case "unclone": return METHOD;
/* @skip */
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Vexi-svn mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/vexi-svn
