improve widget docs

config.ld

@@ -6,3 +6,4 @@ format = 'markdown'
 
 new_type('widget', 'Widgets', true)
 new_type('attrib', 'Attributes', false)
+new_type('prop', 'Properties', false)

doc/classes/Event.html

@@ -165,7 +165,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/classes/Layout.html

@@ -402,7 +402,7 @@ found, and focuses that widget.
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/classes/Widget.html

@@ -34,6 +34,8 @@
 <ul>
 <li><a href="#Functions">Functions</a></li>
 <li><a href="#Methods">Methods</a></li>
+<li><a href="#API_Properties">API Properties </a></li>
+<li><a href="#Internal_Properties">Internal Properties </a></li>
 <li><a href="#Constructor">Constructor</a></li>
 </ul>
 
@@ -83,6 +85,10 @@
 </table>
 <h2><a href="#Methods">Methods</a></h2>
 <table class="function_list">
+	<tr>
+	<td class="name" nowrap><a href="#Widget:defineAttribute">Widget:defineAttribute (name, descriptor)</a></td>
+	<td class="summary">Define a custom attribute for this widget.</td>
+	</tr>
 	<tr>
 	<td class="name" nowrap><a href="#Widget:bubbleEvent">Widget:bubbleEvent (eventName[, data])</a></td>
 	<td class="summary">Fire an event on this widget and each ancestor.</td>
@@ -144,10 +150,56 @@
 	<td class="summary">Determine whether a point is within a widget.</td>
 	</tr>
 	<tr>
+	<td class="name" nowrap><a href="#Widget:eachAncestor">Widget:eachAncestor (includeSelf)</a></td>
+	<td class="summary">Iterate widget's ancestors.</td>
+	</tr>
+	<tr>
 	<td class="name" nowrap><a href="#Widget:reshape">Widget:reshape ()</a></td>
 	<td class="summary">Reshape the widget.</td>
 	</tr>
 </table>
+<h2><a href="#API_Properties">API Properties </a></h2>
+<table class="function_list">
+	<tr>
+	<td class="name" nowrap><a href="#Widget.focused">Widget.focused</a></td>
+	<td class="summary">Whether this widget has keyboard focus.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#Widget.hovered">Widget.hovered</a></td>
+	<td class="summary">Whether the pointer is within this widget.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#Widget.pressed">Widget.pressed</a></td>
+	<td class="summary">Whether the pointer was pressed on this widget and not yet released.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#Widget.items">Widget.items</a></td>
+	<td class="summary">Used by some widgets to store unseen children.</td>
+	</tr>
+</table>
+<h2><a href="#Internal_Properties">Internal Properties </a></h2>
+<table class="function_list">
+	<tr>
+	<td class="name" nowrap><a href="#Widget.isWidget">Widget.isWidget</a></td>
+	<td class="summary">Identifies this object as a widget.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#Widget.isReshaping">Widget.isReshaping</a></td>
+	<td class="summary">Whether the widget is currently being reshaped.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#Widget.hasType">Widget.hasType</a></td>
+	<td class="summary">Whether this widget has a type.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#Widget.fontData">Widget.fontData</a></td>
+	<td class="summary">The <code>Font</code> object associated with the widget.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#Widget.textData">Widget.textData</a></td>
+	<td class="summary">The <code>Text</code> object associated with the widget.</td>
+	</tr>
+</table>
 <h2><a href="#Constructor">Constructor</a></h2>
 <table class="function_list">
 	<tr>
@@ -192,6 +244,37 @@
     <h2 class="section-header "><a name="Methods"></a>Methods</h2>
 
     <dl class="function">
+    <dt>
+    <a name = "Widget:defineAttribute"></a>
+    <strong>Widget:defineAttribute (name, descriptor)</strong>
+    </dt>
+    <dd>
+    Define a custom attribute for this widget.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
+        The name of the attribute.
+        </li>
+        <li><span class="parameter">descriptor</span>
+            <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
+        A table, optionally containing <code>get</code> and <code>set</code> functions (see <code>Attribute</code>).
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="../classes/Widget.html#">Widget</a></span>
+        Return this widget for chaining.
+    </ol>
+
+
+
+
+</dd>
     <dt>
     <a name = "Widget:bubbleEvent"></a>
     <strong>Widget:bubbleEvent (eventName[, data])</strong>
@@ -556,6 +639,40 @@ Cycles back around to the last widget in the tree from the layout root.
 
 
 
+</dd>
+    <dt>
+    <a name = "Widget:eachAncestor"></a>
+    <strong>Widget:eachAncestor (includeSelf)</strong>
+    </dt>
+    <dd>
+    Iterate widget's ancestors.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">includeSelf</span>
+            <span class="types"><span class="type">boolean</span></span>
+        Whether to include this widget as the first result.
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">function</span></span>
+        Returns an iterator function that returns widgets.
+    </ol>
+
+
+
+    <h3>Usage:</h3>
+    <ul>
+        <pre class="example">
+<span class="keyword">for</span> ancestor <span class="keyword">in</span> myWidget:eachAncestor(<span class="keyword">true</span>) <span class="keyword">do</span>
+    <span class="global">print</span>(widget.<span class="global">type</span> <span class="keyword">or</span> <span class="string">'generic'</span>)
+<span class="keyword">end</span></pre>
+    </ul>
+
 </dd>
     <dt>
     <a name = "Widget:reshape"></a>
@@ -576,6 +693,168 @@ on the parent widget.
 
 
 
+</dd>
+</dl>
+    <h2 class="section-header has-description"><a name="API_Properties"></a>API Properties </h2>
+
+          <div class="section-description">
+          These properties may be useful when creating user interfaces,
+and are a formal part of the API.
+          </div>
+    <dl class="function">
+    <dt>
+    <a name = "Widget.focused"></a>
+    <strong>Widget.focused</strong>
+    </dt>
+    <dd>
+    Whether this widget has keyboard focus. </p>
+
+<p>Can be used by styles and themes. This value is automatically set by
+the <code>Input</code> class, and should generally be treated as read-only.
+
+
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "Widget.hovered"></a>
+    <strong>Widget.hovered</strong>
+    </dt>
+    <dd>
+    Whether the pointer is within this widget. </p>
+
+<p>Can be used by styles and themes. This value is automatically set by
+the <code>Input</code> class, and should generally be treated as read-only.
+
+
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "Widget.pressed"></a>
+    <strong>Widget.pressed</strong>
+    </dt>
+    <dd>
+    Whether the pointer was pressed on this widget and not yet released. </p>
+
+<p>Can be used by styles and themes. This value is automatically set by
+the <code>Input</code> class, and should generally be treated as read-only.
+
+
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "Widget.items"></a>
+    <strong>Widget.items</strong>
+    </dt>
+    <dd>
+    Used by some widgets to store unseen children.
+
+
+
+
+
+
+
+</dd>
+</dl>
+    <h2 class="section-header has-description"><a name="Internal_Properties"></a>Internal Properties </h2>
+
+          <div class="section-description">
+          These properties are used internally, but are not likely to be useful
+when creating user interfaces; they are not a formal part of the API
+and may change at any time.
+          </div>
+    <dl class="function">
+    <dt>
+    <a name = "Widget.isWidget"></a>
+    <strong>Widget.isWidget</strong>
+    </dt>
+    <dd>
+    Identifies this object as a widget. </p>
+
+<p>Can be used to determine whether an unknown object is a widget.
+
+
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "Widget.isReshaping"></a>
+    <strong>Widget.isReshaping</strong>
+    </dt>
+    <dd>
+    Whether the widget is currently being reshaped. </p>
+
+<p>Used internally by <a href="../classes/Widget.html#Widget:reshape">reshape</a> to prevent stack overflows when handling
+<code>Reshape</code> events.
+
+
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "Widget.hasType"></a>
+    <strong>Widget.hasType</strong>
+    </dt>
+    <dd>
+    Whether this widget has a type. </p>
+
+<p>Used by the <a href="../modules/attribute.html#type">type</a> attribute to determine whether to
+run the type initializer when the widget's type is set. After a type
+initializer has run, <a href="../classes/Widget.html#Widget.hasType">hasType</a> becomes <code>true</code> and no other type
+initializers should run on the widget.
+
+
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "Widget.fontData"></a>
+    <strong>Widget.fontData</strong>
+    </dt>
+    <dd>
+    The <code>Font</code> object associated with the widget.
+
+
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "Widget.textData"></a>
+    <strong>Widget.textData</strong>
+    </dt>
+    <dd>
+    The <code>Text</code> object associated with the widget.
+
+
+
+
+
+
+
 </dd>
 </dl>
     <h2 class="section-header "><a name="Constructor"></a>Constructor</h2>
@@ -621,7 +900,7 @@ This table is identical to the constructed widget.
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/index.html

@@ -86,7 +86,7 @@
 	</tr>
 	<tr>
 		<td class="name"  nowrap><a href="widgets/radio.html">radio</a></td>
-		<td class="summary">A radio button.</td>
+		<td class="summary">A radio widget.</td>
 	</tr>
 	<tr>
 		<td class="name"  nowrap><a href="widgets/sash.html">sash</a></td>
@@ -136,7 +136,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/modules/attribute.html

@@ -599,13 +599,20 @@ associated with the widget.
     <strong>align</strong>
     </dt>
     <dd>
-    Text and icon alignment. </p>
+
+<p>Text and icon alignment. </p>
 
 <p>Should contain a string defining vertical and horizontal alignment.
 Vertical alignment is defined by either 'top', 'middle', or 'bottom',
 and horizontal alignment is defined by either 'left', 'center', or 'right'.</p>
 
-<p>For example, <code>align = &apos;top left&apos;</code>
+<p>For example, <code>align = &apos;top left&apos;</code></p>
+
+<ul>
+    <li>This attribute cascades.</li>
+</ul>
+
+
 
 
 
@@ -619,11 +626,18 @@ and horizontal alignment is defined by either 'left', 'center', or 'right'.</p>
     <strong>wrap</strong>
     </dt>
     <dd>
-    Wrap text onto multiple lines. </p>
+
+<p>Wrap text onto multiple lines. </p>
 
 <p>Should contain <code>true</code> for multiline text, or <code>false</code> or <code>nil</code>
 for a single line. Even text containing line breaks will display
-as a single line when this attribute is not set to <code>true</code>.
+as a single line when this attribute is not set to <code>true</code>.</p>
+
+<ul>
+    <li>This attribute cascades.</li>
+</ul>
+
+
 
 
 
@@ -741,7 +755,7 @@ child widgets appear.
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/widgets/button.html

@@ -99,7 +99,7 @@ layout:show()
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/widgets/check.html

@@ -83,7 +83,7 @@ standard themes, the widget's value should be indicated in some other way.</p>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/widgets/menu.html

@@ -79,7 +79,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/widgets/menu.item.html

@@ -79,7 +79,7 @@ not be explicitly created.</p>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/widgets/progress.html

@@ -78,7 +78,7 @@ between 0 and 1 (inclusive) to change the width of the bar.</p>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/widgets/radio.html

@@ -30,6 +30,10 @@
   <li><a href="../index.html">Index</a></li>
 </ul>
 
+<h2>Contents</h2>
+<ul>
+<li><a href="#Special_Attributes">Special Attributes </a></li>
+</ul>
 
 
 <h2>Widgets</h2>
@@ -62,12 +66,10 @@
 <div id="content">
 
 <h1>Widget <code>radio</code></h1>
-<p>A radio button.</p>
+<p>A radio widget.</p>
-<p>Radio buttons change their <a href="../modules/attribute.html#value">value</a> attribute to
+<p>When pressed, a radio widget's <a href="../modules/attribute.html#value">value</a> changes to
-<code>true</code> when pressed. Radio buttons should also have a <code>group</code>
+<code>true</code>, and the values of other radio widgets in the same <a href="../widgets/radio.html#group">group</a>
-attribute. When a radio button is pressed, other radio buttons
+change to <code>false</code>.</p>
-in the same layout with the same <code>group</code> attribute change their values
-to <code>false</code>.</p>
 
 <p>Changing the value of a radio button causes it to change its appearance to
 indicate its value. The standard themes use the <a href="../modules/attribute.html#icon">icon</a>
@@ -75,18 +77,49 @@ attribute for this purpose. If a custom icon is provided when using the
 standard themes, the widget's value should be indicated in some other way.</p>
 
 
+<h2><a href="#Special_Attributes">Special Attributes </a></h2>
+<table class="function_list">
+	<tr>
+	<td class="name" nowrap><a href="#group">group</a></td>
+	<td class="summary">Widget group.</td>
+	</tr>
+</table>
 
 <br/>
 <br/>
 
 
+    <h2 class="section-header "><a name="Special_Attributes"></a>Special Attributes </h2>
+
+    <dl class="function">
+    <dt>
+    <a name = "group"></a>
+    <strong>group</strong>
+    </dt>
+    <dd>
+    Widget group. </p>
+
+<p>Should contain a string identifying the widget's group.
+If not defined, defaults to the string <code>&apos;default&apos;</code>.</p>
+
+<p>When a radio widget is pressed, the values of other radio widgets
+in the same group change to <code>false</code>.
+
+
+
+
+
+
+
+</dd>
+</dl>
 
 
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/widgets/sash.html

@@ -98,7 +98,7 @@ layout:show()
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/widgets/slider.html

@@ -78,7 +78,7 @@ number between 0 and 1, inclusive.</p>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/widgets/status.html

@@ -96,7 +96,7 @@ layout:show()
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/widgets/stepper.html

@@ -81,7 +81,7 @@ item displayed in the content area.</p>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

doc/widgets/text.html

@@ -30,6 +30,10 @@
   <li><a href="../index.html">Index</a></li>
 </ul>
 
+<h2>Contents</h2>
+<ul>
+<li><a href="#Special_Attributes">Special Attributes </a></li>
+</ul>
 
 
 <h2>Widgets</h2>
@@ -68,18 +72,47 @@
 </p>
 
 
+<h2><a href="#Special_Attributes">Special Attributes </a></h2>
+<table class="function_list">
+	<tr>
+	<td class="name" nowrap><a href="#highlight">highlight</a></td>
+	<td class="summary">Highlight color.</td>
+	</tr>
+</table>
 
 <br/>
 <br/>
 
 
+    <h2 class="section-header "><a name="Special_Attributes"></a>Special Attributes </h2>
+
+    <dl class="function">
+    <dt>
+    <a name = "highlight"></a>
+    <strong>highlight</strong>
+    </dt>
+    <dd>
+    Highlight color. </p>
+
+<p>Should contain an array with 3 or 4 values (RGB or RGBA) from 0 to 255.</p>
+
+<p>This color is used to indicate the selected range of text.
+
+
+
+
+
+
+
+</dd>
+</dl>
 
 
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
-<i style="float:right;">Last updated 2015-12-07 05:47:24 </i>
+<i style="float:right;">Last updated 2015-12-15 13:53:58 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

luigi/widget.lua

@@ -4,6 +4,7 @@ Widget class.
 @classmod Widget
 --]]--
 
+local STRICT = false
 local ROOT = (...):gsub('[^.]*$', '')
 
 local Backend = require(ROOT .. 'backend')
@@ -15,8 +16,96 @@ local Widget = {}
 
 Event.injectBinders(Widget)
 
+--[[--
+API Properties
+
+These properties may be useful when creating user interfaces,
+and are a formal part of the API.
+
+@section api
+--]]--
+
+--[[--
+Whether this widget has keyboard focus.
+
+Can be used by styles and themes. This value is automatically set by
+the `Input` class, and should generally be treated as read-only.
+--]]--
+Widget.focused = false
+
+--[[--
+Whether the pointer is within this widget.
+
+Can be used by styles and themes. This value is automatically set by
+the `Input` class, and should generally be treated as read-only.
+--]]--
+Widget.hovered = false
+
+--[[--
+Whether the pointer was pressed on this widget and not yet released.
+
+Can be used by styles and themes. This value is automatically set by
+the `Input` class, and should generally be treated as read-only.
+--]]--
+Widget.pressed = false
+
+--[[--
+Used by some widgets to store unseen children.
+--]]--
+Widget.items = false
+-- TODO: make this a custom attribute, or
+-- maybe add a `visibile` attribute instead
+
+--[[--
+Internal Properties
+
+These properties are used internally, but are not likely to be useful
+when creating user interfaces; they are not a formal part of the API
+and may change at any time.
+
+@section internal
+--]]--
+
+--[[--
+Identifies this object as a widget.
+
+Can be used to determine whether an unknown object is a widget.
+--]]--
 Widget.isWidget = true
 
+--[[--
+Whether the widget is currently being reshaped.
+
+Used internally by `reshape` to prevent stack overflows when handling
+`Reshape` events.
+--]]--
+Widget.isReshaping = false
+
+--[[--
+Whether this widget has a type.
+
+Used by the @{attribute.type|type} attribute to determine whether to
+run the type initializer when the widget's type is set. After a type
+initializer has run, `hasType` becomes `true` and no other type
+initializers should run on the widget.
+--]]--
+Widget.hasType = false
+
+--[[--
+The `Font` object associated with the widget.
+--]]--
+Widget.fontData = false
+
+--[[--
+The `Text` object associated with the widget.
+--]]--
+Widget.textData = false
+
+
+--[[--
+@section end
+--]]--
+
 Widget.typeDecorators = {
     button = require(ROOT .. 'widget.button'),
     check = require(ROOT .. 'widget.check'),
@@ -83,10 +172,14 @@ local function metaNewIndex (self, property, value)
         else
             self.attributes[property] = value
         end
+    else
+        if STRICT and Widget[property] == nil then
+            error(property .. ' is not a valid widget property.')
         else
             rawset(self, property, value)
         end
     end
+end
 
 local attributeNames = {}
 
@@ -152,7 +245,7 @@ A table, optionally containing `get` and `set` functions (see `Attribute`).
 Return this widget for chaining.
 --]]--
 function Widget:defineAttribute (name, descriptor)
-    self.attributeDescriptors[name] = descriptor
+    self.attributeDescriptors[name] = descriptor or {}
     local value = rawget(self, name)
     rawset(self, name, nil)
     self[name] = value
@@ -313,17 +406,7 @@ function Widget:addChild (data)
     return child
 end
 
-local function checkReshape (widget)
-    if widget.needsReshape then
-        widget.position = {}
-        widget.dimensions = {}
-        widget.needsReshape = nil
-    end
-end
-
 function Widget:calculateDimension (name)
-    checkReshape(self)
-
     -- If dimensions are already calculated, return them.
     if self.dimensions[name] then
         return self.dimensions[name]
@@ -423,8 +506,6 @@ local function calculateRootPosition (self, axis)
 end
 
 function Widget:calculatePosition (axis)
-    checkReshape(self)
-
     if self.position[axis] then
         return self.position[axis]
     end
@@ -605,13 +686,25 @@ The point's Y coordinate.
 true if the point is within the widget, else false.
 --]]--
 function Widget:isAt (x, y)
-    checkReshape(self)
-
     local x1, y1, w, h = self:getRectangle()
     local x2, y2 = x1 + w, y1 + h
     return (x1 <= x) and (x2 >= x) and (y1 <= y) and (y2 >= y)
 end
 
+--[[--
+Iterate widget's ancestors.
+
+@tparam boolean includeSelf
+Whether to include this widget as the first result.
+
+@treturn function
+Returns an iterator function that returns widgets.
+
+@usage
+for ancestor in myWidget:eachAncestor(true) do
+    print(widget.type or 'generic')
+end
+--]]--
 function Widget:eachAncestor (includeSelf)
     local instance = includeSelf and self or self.parent
     return function()
@@ -634,11 +727,12 @@ on the parent widget.
 function Widget:reshape ()
     if self.isReshaping then return end
     self.isReshaping = true
-    self.needsReshape = true
+
+    self.position = {}
+    self.dimensions = {}
+
     self.textData = nil
-    Event.Reshape:emit(self, {
+    Event.Reshape:emit(self, { target = self })
-        target = self
-    })
     for i, widget in ipairs(self) do
         if widget.reshape then
             widget:reshape()

luigi/widget/radio.lua

@@ -1,11 +1,9 @@
 --[[--
-A radio button.
+A radio widget.
 
-Radio buttons change their @{attribute.value|value} attribute to
+When pressed, a radio widget's @{attribute.value|value} changes to
-`true` when pressed. Radio buttons should also have a `group`
+`true`, and the values of other radio widgets in the same `group`
-attribute. When a radio button is pressed, other radio buttons
+change to `false`.
-in the same layout with the same `group` attribute change their values
-to `false`.
 
 Changing the value of a radio button causes it to change its appearance to
 indicate its value. The standard themes use the @{attribute.icon|icon}
@@ -44,7 +42,27 @@ local function setGroup (self, value)
 end
 
 return function (self)
+--[[--
+Special Attributes
+
+@section special
+--]]--
+
+--[[--
+Widget group.
+
+Should contain a string identifying the widget's group.
+If not defined, defaults to the string `'default'`.
+
+When a radio widget is pressed, the values of other radio widgets
+in the same group change to `false`.
+
+@attrib group
+--]]--
     self:defineAttribute('group', { set = setGroup })
+--[[--
+@section end
+--]]--
 
     self:onPress(function ()
         for _, widget in ipairs(groups[self.group]) do

luigi/widget/text.lua

@@ -186,6 +186,25 @@ return function (self)
 
     self.text = ''
 
+--[[--
+Special Attributes
+
+@section special
+--]]--
+
+--[[--
+Highlight color.
+
+Should contain an array with 3 or 4 values (RGB or RGBA) from 0 to 255.
+
+This color is used to indicate the selected range of text.
+
+@attrib highlight
+--]]--
+    self:defineAttribute('highlight')
+--[[--
+@section end
+--]]--
     if not self.highlight then
         self.highlight = { 0x80, 0x80, 0x80 }
     end
@@ -266,14 +285,19 @@ return function (self)
         Backend.setScissor(x, y, w, h)
         Backend.setFont(font)
 
-        -- draw highlight
         if self.focused then
+            -- draw highlighted selection
             Backend.setColor(self.highlight)
             Backend.drawRectangle('fill', startX, y, width, height)
+            -- draw cursor selection
             if Backend.getTime() % 2 < 1.75 then
                 Backend.setColor(color)
                 Backend.drawRectangle('fill', endX, y, 1, height)
             end
+        else
+            Backend.setColor { color[1], color[2], color[3],
+                (color[4] or 256) / 8 }
+            Backend.drawRectangle('fill', startX, y, width, height)
         end
 
         -- draw text