[Laszlo-checkins] r10004 - openlaszlo/trunk/docs/src/reference
lou@openlaszlo.org
lou at openlaszlo.org
Wed Jun 25 16:46:59 PDT 2008
Author: lou
Date: 2008-06-25 16:46:20 -0700 (Wed, 25 Jun 2008)
New Revision: 10004
Modified:
openlaszlo/trunk/docs/src/reference/info.xml
Log:
Change 20080625-lou-n by lou at loumac.local on 2008-06-25 19:38:42 AST
in /Users/lou/src/svn/openlaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: reverence incorporate comments for intro to attributes page
Bugs Fixed: LPP-6024
Technical Reviewer: (pending)
QA Reviewer: llundrigan
Doc Reviewer: (pending)
Details: Incorporate Tucker's comments (see "File Attachments:" in the JIRA bug
Tests: visual verify
Modified: openlaszlo/trunk/docs/src/reference/info.xml
===================================================================
--- openlaszlo/trunk/docs/src/reference/info.xml 2008-06-25 23:43:37 UTC (rev 10003)
+++ openlaszlo/trunk/docs/src/reference/info.xml 2008-06-25 23:46:20 UTC (rev 10004)
@@ -14,61 +14,66 @@
<doc>
<tag name="lzxname"><text>An introduction to Attributes</text></tag>
<text>
-<p>Attributes can be an element of a tag or a property of a JavaSctipt
- class. Attributes are declared and set in tags, but they can also
+<p>Attributes can be an element of a tag or a property of a JavaScript
+ class. Attributes are declared and set in tags, but they can also
be set and read in script. Not all attributes can be set in script,
similarly not all attributes can be in tags. Attributes are
- characterized based on this behaviour into five categories. See <a
+ characterized based on this behavior into five categories. See <a
href="#types">below</a> for more information on the various
categories.</p>
<p>An attribute can be declared in a tag header as follows:</p>
-<example title="Setting an attribute value in the tag header"><canvas height="20">
- <view <span class="redText">width="20"</span> height="20" bgcolor="red"/>
-</canvas></example>
+<example title="Setting an attribute value in the tag header">
+ <canvas height="20">
+ <view <span class="redText">width="20"</span> height="20" bgcolor="red"/>
+ </canvas></example>
<p>An alternative (although more verbose) way to set the attribute is
using the <tagname link="true">attribute</tagname> tag as a child of
the tag whose attribute is being set:</p>
-<example title="Using the attribute element to set an attribute value"><canvas height="20">
- <view>
- <span class="redText"><attribute name="width" type="number" value="20"/></span>
- <attribute name="height" type="number" value="20"/>
- <attribute name="bgcolor" type="color" value="red"/>
- </view>
-</canvas></example>
+<example title="Using the attribute element to set an attribute value">
+ <canvas height="20">
+ <view>
+ <attribute name="width" value="20"/>
+ <attribute name="height" value="20"/>
+ <attribute name="bgcolor" value="red"/>
+ </view>
+ </canvas>
+</example>
<p>This second example is actually the same as saying <view width="20" height="20" bgcolor="red"/>. The <tagname>attribute</tagname> tag becomes useful when writing classes as well as when performing complicated constraints of existing attributes.</p>
<p>In script, the values of most attributes are can be retrieved using
dot syntax:</p>
-<example title="Using dot syntax to retrieve an attribute value"><canvas height="20">
- <view name="myView" width="20" height="20" bgcolor="red"/>
+<example title="Using dot syntax to retrieve an attribute value">
+ <canvas height="40" debug="false">
+ <simplelayout />
+ <view name="myView" width="20" height="20" bgcolor="red"/>
+
+ <text oninit="this.format('myView.width = %d', myView.width)" />
+ </canvas>
+</example>
- <script>
- var myAttributeValue = <span class="redText">myView.x</span>;
- // myAttributeValue now has the value 20
- </script>
-</canvas></example>
-
<p>Additionally attributes can be read using the
<method>getAttribute</method> method. This is unnecessary most of the
time, but can be useful for retrieving the value of an arbitrary
-attribute, whose name is represented by a string.</p>
+attribute, whose name you don't know in advance.</p>
-<example title="Using getAttribute to retrieve an attribute value"><canvas height="20">
- <view name="myView" width="20" height="20" bgcolor="red"/>
+<example title="Using getAttribute to retrieve an attribute value">
+ <canvas height="40" debug="false">
+ <simplelayout />
+ <view name="myView" width="20" height="20" bgcolor="red"/>
+ <attribute name="whatAttr" type="string" value="height" />
+ <text
+ oninit="this.format('myView.%s = %d',
+ canvas.whatAttr,
+ myView[canvas.whatAttr])" />
+ </canvas>
+</example>
- <script>
- var myAttributeName = "x";
- var myAttributeValue = <span class="redText">myView.getAttribute(myAttributeName)</span>;
- // myAttributeValue now has the value 20
- </script>
-</canvas></example>
-
<p>All attributes that are settable in script (see below) can be set
using the <method>setAttribute</method> method:</p>
@@ -103,8 +108,8 @@
<simplesect>
<h2><literal>read/write</literal> attributes</h2>
<p><literal>read/write</literal> attributes may be modified at runtime
-and used in constraint expressions. When <method>setAttribute</method>
-is called, the appropriate setter will be called automatically. The
+ and be the target of a constraint expression. When <method>setAttribute</method>
+ is called the value of the attribute will be updated, along with any constraints that depend on the attribute. The
value of an attribute can be retrieved through script using dot
syntax, (for example, myView.opacity). </p>
@@ -115,19 +120,6 @@
</view>
</canvas></example>
-<a name="defaultsetter"></a>
-
-<p>Some attributes use the setter method
-(<method>setAttribute</method>) to set their values at
-run-time. Typically they are custom attributes that have been declared
-in components using the <tagname>attribute</tagname> tag. Therefore they can be
-declared and set in tags too.</p>
-
-<example title="Using SetAttribute to set a window title"><canvas height="50">
- <window width="140" <span class="redText">title="My Window"</span> onclick="this.setAttribute('title', 'Hello World');"/>
-</canvas>
-</example>
-
<para role="rightalign"><ulink>More on attributes</ulink></para>
</simplesect>
@@ -144,6 +136,19 @@
</canvas>
</example>
+<para>
+There is a long-hand version for event-handler attributes, just like normal attributes:
+</para>
+ <example title="Using the long-hand version">
+ <canvas height="40">
+ <text>
+ Click me!
+ <handler name="onclick">
+ this.setAttribute('text', 'Hello World!');
+ </handler>
+ </text>
+ </canvas>
+</example>
<para role="rightalign"><ulink>More on attributes</ulink></para>
</simplesect>
@@ -154,9 +159,14 @@
<h2><literal>initialize-only</literal> attributes</h2>
<p><literal>initialize-only</literal> attributes are declared and set in the tag, but cannot be changed in using script. Good examples of <literal>initialize-only</literal> attributes are name and id. They can be read from script using dot syntax.</p>
<example title="Using initialize-only attributes">
-<canvas height="50">
- <view width="50" height="50" bgcolor="red" <span class="redText">align="center"</span> />
-</canvas>
+ <canvas height="40">
+ <text id="myID">
+ Click me!
+ <handler name="onclick">
+ this.setAttribute('text', this.id);
+ </handler>
+ </text>
+ </canvas>
</example>
<para role="rightalign"><ulink>More on attributes</ulink></para>
</simplesect>
@@ -166,13 +176,19 @@
<a name="readonly"></a>
<simplesect>
<h2><literal>read-only</literal> attributes</h2>
- <p><literal>read-only</literal> attributes, sometimes called "Fields", are only available through
- the element's API. Since they are read-only, they cannot be set in a <tag>.
+ <p><literal>read-only</literal> attributes, sometimes called "Fields", are only accessible using script. Since they are read-only, they cannot be set in a <tag>.
Their values can be retrieved using dot syntax.</p>
- <example title="Using read-only attributes">
-<canvas height="150" debug="true">
- <view width="50" height="50" bgcolor="red" <span class="redText">onclick="Debug.write('subview' + canvas.subviews);"</span> />
-</canvas>
+ <example title="Using read-only attributes">
+ <canvas height="30" debug="true">
+ <!-- need debugging for %w formatter, but don't need debug window -->
+ <debug y="50" />
+ <text id="myID">
+ Click me!
+ <handler name="onclick">
+ this.format("canvas.subviews: %w", canvas.subviews);
+ </handler>
+ </text>
+ </canvas>
</example>
<para role="rightalign"><ulink>More on attributes</ulink></para>
</simplesect>
More information about the Laszlo-checkins
mailing list