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 behavior into five categories. See below for more information on the various categories.
An attribute can be declared in a tag header as follows:
Example 9. Setting an attribute value in the tag header
<canvas height="20">
<view width="20" height="20" bgcolor="red"/>
</canvas>
An alternative (although more verbose) way to set the attribute is
using the <attribute> tag as a child of
the tag whose attribute is being set:
Example 10. 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>
This second example is actually the same as saying <view width="20" height="20" bgcolor="red"/>. The <attribute> tag becomes useful when writing classes as well as when performing complicated constraints of existing attributes.
In script, the values of most attributes are can be retrieved using dot syntax:
Example 11. 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>
Additionally attributes can be read using the
getAttribute method. This is unnecessary most of the
time, but can be useful for retrieving the value of an arbitrary
attribute, whose name you don't know in advance.
Example 12. 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>
All attributes that are settable in script (see below) can be set
using the setAttribute method:
Example 13. Using setAttribute to set an attribute value
<canvas height="20">
<view width="20" height="20" bgcolor="red" oninit="this.setAttribute('width', 50);"/>
</canvas>
For more infomation see the reference page for Attribute. The Classes tutorial describes how to use attributes to define a class.
There are four kinds of attributes:
read/write attributes may be modified at runtime
and be the target of a constraint expression. When setAttribute
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).
For example:
Example 14. Using setAttribute to update a constraint
<canvas height="20">
<view id="myView" onclick="setAttribute('opacity', 1.5 - this.opacity)" bgcolor="red">
<text text="${'My opacity is ' + myView.opacity + '. Click to change it.'}"/>
</view>
</canvas>
event-handler attributes are instructions for what to perform when a particular event happens. They always contain script, and cannot be
changed at run-time (that is, from script). Their values cannot (and do not need to) be retrieved from script.
Example 15. Using event-handler attributes
<canvas height="150" debug="true">
<view width="50" height="50" bgcolor="red" onclick="Debug.write('Hello, World!');"/>
</canvas>
There is a long-hand version for event-handler attributes, just like normal attributes:
Example 16. Using the long-hand version
<canvas height="40">
<text>
Click me!
<handler name="onclick">
this.setAttribute('text', 'Hello World!');
</handler>
</text>
</canvas>
initialize-only attributes are declared and set in the tag, but cannot be changed in using script. Good examples of initialize-only attributes are name and id. They can be read from script using dot syntax.
Example 17. Using initialize-only attributes
<canvas height="40">
<text id="myID">
Click me!
<handler name="onclick">
this.setAttribute('text', this.id);
</handler>
</text>
</canvas>
read-only 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.
Example 18. 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>