<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="mal_block_tree">

<info>
  <revision version="0.1" date="2009-05-25" status="review"/>

  <credit type="author">
    <name>Shaun McCance</name>
    <email>shaunm@gnome.org</email>
  </credit>
  <copyright>
    <year>2008-2009</year>
    <name>Shaun McCance</name>
  </copyright>

  <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />

  <desc>Create simple trees to show heirarchical structures.</desc>
</info>

<title>Tree Lists</title>

<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block_tree = element tree {
  attribute style { xsd:NMTOKENS } ?,
  attribute * - (mal:* | local:*) { text } *,

  <link xref="mal_block_title">mal_block_title</link> ?,
  mal_tree_item +
}
mal_tree_item = element item {
  attribute style { xsd:NMTOKENS } ?,
  attribute * - (mal:* | local:*) { text } *,

  <link xref="mal_inline">mal_inline</link>,
  mal_tree_item *
}
</code></synopsis>

<p>Use the <code>tree</code> element to create a heirarchical tree.  While
conceptually similar to nested <code xref="mal_block_list">list</code>
elements, trees offer a simple way to display common heirarchies such as
class inheritance or directory layouts.</p>


<!-- BEGIN notes -->
<section id="notes">
  <title>Notes</title>
  <list>
    <item><p>The <code>tree</code> element can contain an optional
    <code xref="mal_block_title">title</code> element followed by one or more
    <code>item</code> elements.  Each child <code>item</code> element can
    contain a mixture of text and any
    <link xref="mal_inline">general inline elements</link>, followed by
    zero or more nested <code>item</code> elements.</p></item>

    <item><p>The <code>tree</code> element can occur in any
    general block context, including inside
    <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
    and certain <link xref="mal_block">block elements</link>.</p></item>

    <item><p>The <code>style</code> attribute takes a space-separated list of
    style hints.  Processing tools should adjust their behavior according to
    those style hints they understand.</p></item>

    <item>
      <p>The following style hints are recommended:</p>
      <table rules="rows">
        <tr>
          <td><p><code>lines</code></p></td>
          <td><p>draw lines to show the hierarchy</p></td>
        </tr>
      </table>
    </item>

    <item><p>The <code>tree</code> element can have attributes from external
    namespaces.  See <link xref="mal_external"/> for more information
    on external-namespace attributes.</p></item>
  </list>
</section>
<!-- END notes -->


<!-- BEGIN examples -->
<section id="examples">
  <title>Examples</title>

  <p>Use a tree to outline a class heirarchy inside a
  <code xref="mal_block_synopsis">>synopsis</code> element:</p>

  <example>
    <code><![CDATA[
<synopsis>
  <tree>
    <item>
      <code>GtkBin</code>
      <item>
        <code>GtkButton</code>
        <item><code>GtkToggleButton</code></item>
        <item><code>GtkColorButton</code></item>
        <item><code>GtkFontButton</code></item>
        <item><code>GtkLinkButton</code></item>
        <item><code>GtkOptionMenu</code></item>
        <item><code>GtkScaleButton</code></item>
      </item>
    </item>
  </tree>
</synopsis>]]></code>
    <synopsis>
      <tree>
        <item>
          <code>GtkBin</code>
          <item>
            <code>GtkButton</code>
            <item><code>GtkToggleButton</code></item>
            <item><code>GtkColorButton</code></item>
            <item><code>GtkFontButton</code></item>
            <item><code>GtkLinkButton</code></item>
            <item><code>GtkOptionMenu</code></item>
            <item><code>GtkScaleButton</code></item>
          </item>
        </item>
      </tree>
    </synopsis>
  </example>

  <p>Use the <code>lines</code> style hint to visually show the tree structure:</p>

  <example>
    <code><![CDATA[
<tree style="lines">
  <item>
    Anatinae (dabbling ducks)
    <item>
      Anas
      <item>Baikal Teal</item>
      <item>Wigeons</item>
      <item>Mallard</item>
    </item>
    <item>Lophonetta</item>
    <item>Speculanas</item>
  </item>
  <item>
    Anthyinae (diving ducks)
    <item>Aythya</item>
    <item>Netta</item>
  </item>
  <item>Dendrocygninae (whistling ducks)</item>
</tree>]]></code>
    <tree style="lines">
      <item>
        Anatinae (dabbling ducks)
        <item>
          Anas
          <item>Baikal Teal</item>
          <item>Wigeons</item>
          <item>Mallard</item>
        </item>
        <item>Lophonetta</item>
        <item>Speculanas</item>
      </item>
      <item>
        Anthyinae (diving ducks)
        <item>Aythya</item>
        <item>Netta</item>
      </item>
      <item>Dendrocygninae (whistling ducks)</item>
    </tree>
  </example>
</section>
<!-- END examples -->


<!-- BEGIN processing -->
<section id="processing">
  <title>Processing Expectations</title>

  <p>Tree lists are display as block elements.  Each child <code>item</code>
  has its leading inline content displayed in a single block and any nested
  <code>item</code> elements displayed as blocks in turn.  Successive levels
  of nesting should yield more indentation, though this may vary based on
  style hints or other factors.  By default, there should be little vertical
  spacing between items; trees are compact.  No bullets, icons, or other marks
  are expected to precede items, although they may be used for certain style
  hints.</p>
</section>
<!-- END processing -->

</page>
