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