Begin component documentation.

com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-component.xml

@@ -4,22 +4,70 @@
          id="0c480fad-ee66-4532-a0b1-f06ebe582ea8"
          title="Components">
 
-  <Subsection title="Overview">
+  <Subsection title="Description">
     <Paragraph>
-      A component...
+      <Term type="term">Components</Term>
+      are the elements that make up the user interface inside
+      <Link target="cb46abcd-d0b1-41f4-bb95-662186d4aa78">windows</Link>. Concretely, a component is any object that
+      implements the
+      <Term type="class">SyComponentType</Term>
+      interface. The package provides the abstract <Term type="class">SyComponentAbstract</Term> class that provides
+      sensible default implementations of all the required methods.
     </Paragraph>
   </Subsection>
 
-  <Subsection title="Activity" id="1d8361cb-1aa8-408e-820d-4d04c7f3bfab">
+  <Subsection title="Tree">
     <Paragraph>
-      A component may be <Term type="term">active</Term> or <Term type="term">inactive</Term>.
+      Components form a tree structure, with each component having an arbitrary number of child components, and at most
+      one parent component. A component is said to be
+      <Term type="term">detached</Term>
+      if it has no parent component, and it is also not the <Term type="term">root component</Term> for a window. A
+      detached component is not visited during
+      <Link target="88d61172-40fe-4f21-b4e9-776ff4a8f0d7">layout</Link>
+      operations or during
+      <Link target="b097067b-b8d6-4397-bb24-6a48f003e84f">event dispatch</Link>.
     </Paragraph>
   </Subsection>
 
-  <Subsection title="Layout" id="88d61172-40fe-4f21-b4e9-776ff4a8f0d7">
+  <Subsection title="Activity"
+              id="1d8361cb-1aa8-408e-820d-4d04c7f3bfab">
+    <Paragraph>
+      A component may be <Term type="term">active</Term> or <Term type="term">inactive</Term>. A component can be set to
+      active or inactive by setting the value of the component's
+      <Term type="variable">activity</Term>
+      attribute. Inactivity is implicitly inherited; if the parent component <Term type="variable">P</Term> of a
+      component
+      <Term type="variable">C</Term>
+      is inactive, then <Term type="variable">C</Term> is considered to be inactive.
+    </Paragraph>
+    <Paragraph>
+      An inactive component will <Term type="term">not</Term> receive events during
+      <Link target="b097067b-b8d6-4397-bb24-6a48f003e84f">event dispatch</Link>. Additionally,
+      <Link target="6aeefd35-8837-4503-99ee-3ccba984a49e">themes</Link>
+      are encouraged to render inactive components in a greyed-out form. For example, the button labelled "Button 1" in
+      the following image is inactive and so cannot be clicked:
+    </Paragraph>
+    <FormalItem title="Inactive Button">
+      <Image source="buttonInactive.png"
+             width="220"
+             height="120">
+        Multiple buttons, one of which is inactive.
+      </Image>
+    </FormalItem>
+  </Subsection>
+
+  <Subsection title="Layout"
+              id="88d61172-40fe-4f21-b4e9-776ff4a8f0d7">
     <Paragraph>
       Component layout...
     </Paragraph>
   </Subsection>
 
+  <Subsection title="Standard Components">
+    <Paragraph>
+      The <Term type="package">jsycamore</Term> package provides a set of
+      <Link target="43bf8da9-c7dc-44f5-aa88-d592b3f4408c">standard components</Link>.
+    </Paragraph>
+  </Subsection>
+
 </Section>

com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-screen.xml

@@ -100,6 +100,7 @@
                   If the <Link target="7973aa4f-4fd9-40dd-8d96-0aaa3b4d6147">viewport-space</Link> position
                   of the mouse event (the cursor position) falls within the viewport-space bounds of
                   <Term type="variable">w</Term>, then ask <Term type="variable">w</Term> for the
+                  <Link target="1d8361cb-1aa8-408e-820d-4d04c7f3bfab">active</Link>
                   <Link target="0c480fad-ee66-4532-a0b1-f06ebe582ea8">component</Link>
                   <Term type="variable">c</Term> that is overlapped by the cursor. The window implementation
                   is required to return the most specific component for the given position; the component that