1
<page xmlns="http://projectmallard.org/1.0/"
6
<revision version="0.1" date="2009-05-25" status="review"/>
9
<name>Shaun McCance</name>
10
<email>shaunm@gnome.org</email>
13
<year>2008-2009</year>
14
<name>Shaun McCance</name>
17
<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
19
<desc>Create simple trees to show heirarchical structures.</desc>
22
<title>Tree Lists</title>
24
<synopsis><code mime="application/relax-ng-compact-syntax">
25
mal_block_tree = element tree {
26
attribute style { xsd:NMTOKENS } ?,
27
attribute * - (mal:* | local:*) { text } *,
29
<link xref="mal_block_title">mal_block_title</link> ?,
32
mal_tree_item = element item {
33
attribute style { xsd:NMTOKENS } ?,
34
attribute * - (mal:* | local:*) { text } *,
36
<link xref="mal_inline">mal_inline</link>,
41
<p>Use the <code>tree</code> element to create a heirarchical tree. While
42
conceptually similar to nested <code xref="mal_block_list">list</code>
43
elements, trees offer a simple way to display common heirarchies such as
44
class inheritance or directory layouts.</p>
51
<item><p>The <code>tree</code> element can contain an optional
52
<code xref="mal_block_title">title</code> element followed by one or more
53
<code>item</code> elements. Each child <code>item</code> element can
54
contain a mixture of text and any
55
<link xref="mal_inline">general inline elements</link>, followed by
56
zero or more nested <code>item</code> elements.</p></item>
58
<item><p>The <code>tree</code> element can occur in any
59
general block context, including inside
60
<link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
61
and certain <link xref="mal_block">block elements</link>.</p></item>
63
<item><p>The <code>style</code> attribute takes a space-separated list of
64
style hints. Processing tools should adjust their behavior according to
65
those style hints they understand.</p></item>
68
<p>The following style hints are recommended:</p>
71
<td><p><code>lines</code></p></td>
72
<td><p>draw lines to show the hierarchy</p></td>
77
<item><p>The <code>tree</code> element can have attributes from external
78
namespaces. See <link xref="mal_external"/> for more information
79
on external-namespace attributes.</p></item>
85
<!-- BEGIN examples -->
86
<section id="examples">
87
<title>Examples</title>
89
<p>Use a tree to outline a class heirarchy inside a
90
<code xref="mal_block_synopsis">>synopsis</code> element:</p>
99
<code>GtkButton</code>
100
<item><code>GtkToggleButton</code></item>
101
<item><code>GtkColorButton</code></item>
102
<item><code>GtkFontButton</code></item>
103
<item><code>GtkLinkButton</code></item>
104
<item><code>GtkOptionMenu</code></item>
105
<item><code>GtkScaleButton</code></item>
109
</synopsis>]]></code>
115
<code>GtkButton</code>
116
<item><code>GtkToggleButton</code></item>
117
<item><code>GtkColorButton</code></item>
118
<item><code>GtkFontButton</code></item>
119
<item><code>GtkLinkButton</code></item>
120
<item><code>GtkOptionMenu</code></item>
121
<item><code>GtkScaleButton</code></item>
128
<p>Use the <code>lines</code> style hint to visually show the tree structure:</p>
134
Anatinae (dabbling ducks)
137
<item>Baikal Teal</item>
141
<item>Lophonetta</item>
142
<item>Speculanas</item>
145
Anthyinae (diving ducks)
149
<item>Dendrocygninae (whistling ducks)</item>
153
Anatinae (dabbling ducks)
156
<item>Baikal Teal</item>
160
<item>Lophonetta</item>
161
<item>Speculanas</item>
164
Anthyinae (diving ducks)
168
<item>Dendrocygninae (whistling ducks)</item>
172
<!-- END examples -->
175
<!-- BEGIN processing -->
176
<section id="processing">
177
<title>Processing Expectations</title>
179
<p>Tree lists are display as block elements. Each child <code>item</code>
180
has its leading inline content displayed in a single block and any nested
181
<code>item</code> elements displayed as blocks in turn. Successive levels
182
of nesting should yield more indentation, though this may vary based on
183
style hints or other factors. By default, there should be little vertical
184
spacing between items; trees are compact. No bullets, icons, or other marks
185
are expected to precede items, although they may be used for certain style
188
<!-- END processing -->
added
removed
doc/mallard/C/mal_block_tree.page
