aboutsummaryrefslogtreecommitdiffstats
path: root/doc/white-papers/widgets/e-table.sgml
blob: 0a52ecbb51c3eb8beb1b13f5fd2c3c3795e3b8f5 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
<!doctype article PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!entity Evolution "<application>Evolution</application>">
<!entity ETable "<classname>ETable</classname>">
<!entity ETableModel "<classname>ETableModel</classname>">
<!entity ETableSimple "<classname>ETableSimple</classname>">
<!entity ETableHeader "<classname>ETableHeader</classname>">
<!entity ETableSpecification "<classname>ETableSpecification</classname>">
]>

<article class="whitepaper" id="e-table">

  <artheader>
    <title>The ETable Widget</title>

    <authorgroup>
      <author>
    <firstname>Chris</firstname>
    <surname>Lahey</surname>
    <affiliation>
      <address>
        <email>clahey@helixcode.com</email>
      </address>
    </affiliation>
      </author>
    </authorgroup>

    <copyright>
      <year>2000</year>
      <holder>Helix Code, Inc.</holder>
    </copyright>

  </artheader>

  <sect1 id="introduction">
    <title>Introduction</title>

    <para>
      &ETable; is a table widget on steroids. It is intended to provide
      all the table functionality needed throughout &Evolution;, and
      hopefully be general purpose enough to be used in other projects.
    </para>

    <para>
      &ETable; provides a lot of interactive control over the data in the
      table.  Without any work from the programmer, &ETable; provides
      rearrangeable columns and editable data.  When finished, &ETable; will
      also provide, again with no programmer intervention, easy interactive
      sorting and grouping.
    </para>

    <para>
      &ETable; gives you a great deal of functionality, flexibility, and
      power. Most of this power is internal to the widget, but some of
      the flexibility requires a bit of work by the programmer.
      However, once you learn it, &ETable; is not very hard at all to
      use.
    </para>
  </sect1>

  <sect1 id="model">
    <title>ETableModel</title>

    <para>
      The back end of &ETable; is an &ETableModel;. To use &ETable;
      you have to create a subclass of &ETableModel;. However, to save
      you the work of defining a new <classname>GtkClass</classname>,
      there is a predefined subclass of &ETableModel; called
      &ETableSimple; which simply takes a list of callbacks to perform
      the various operations.
    </para>
  </sect1>
    
  <sect1 id="columns">
    <title>Columns</title>

    <para>
      There are two different meanings to the word "column". The first
      is the model column. A model column corresponds to a specific
      type of data. This is very much like the usage in a database
      table where a column is a field in the database.
    </para>

    <para>
      The second type of column is a view column. A view column
      corresponds to a visually-displayed column. Each view column
      corresponds to a specific model column, though a model column
      may have any number of view columns associated with it
      (including zero).
    </para>

    <para>
      The view column does not necessarily depend on only one model
      column. In some cases, the view column renderer can be given a
      reference to another model column to get extra information about
      its display. For example, to display deleted messages with a
      line through them, you would create a model column with no view
      column corresponding to whether the message is deleted, and then
      you would tell the text column to strikethrough the display if
      that column had a value corresponding to deleted.
    </para>

    <para>
      The view column also specifies a few other pieces of
      information. One piece of information is the renderer. &ETable;
      provides a number of renderers to choose from, or you can write
      your own. Currently, there are renderers for text, image sets,
      and checkboxes.
    </para>

    <para>
      The view column also includes information about the header.
      There are two types of headers: text, and pixbuf. The first
      allows you to specify a string which is rendered in the header.
      The second allows you to specify an image to copy into the
      header.
    </para>
  </sect1>

  <sect1 id="header">
    <title>Header</title>

    <para>
      The &ETableHeader; represents the header information for the
      table. The &ETableHeader; is used in two different ways. The
      first is the in the <structfield>full_header</structfield>
      element of an &ETable;. This is the list of possible columns in
      the view. You add each of your columns to this &ETableHeader;
      and then pass it into the &ETable;.
    </para>

    <para>
      The second use is completely internal. &ETable; uses another
      &ETableHeader; to store the actual displayed columns. Many of
      the &ETableHeader; functions are for this purpose. The only
      functions that users of the library should need to use are
      <function>e_table_header_new</function> and
      <function>e_table_header_add_col</function>.
    </para>
  </sect1>

  <sect1 id="layout">
    <title>Layout Specification</title>

    <para>
      &ETable; uses an &ETableSpecification; to layout the columns of
      the widget. The &ETableSpecification; is specified as XML data
      passed into the &ETable; as a string.
    </para>

    <para>
      The most powerful part of the &ETableSpecification; is that when
      finished, &ETable; will allow you to get a copy of an
      &ETableSpecification; that describes the current view of the
      tree. This allows the developer to save the current view so that
      next time the user opens this table, they find it in exactly the
      state that they left it.
    </para>

    <para>
      The XML specification allows for a number of things. First, it
      allows you to pick a set of default columns to be shown. Thus,
      even if you had hundreds of pieces of data, you could choose to
      only display a few that fit on the screen by default.
    </para>

    <para>
      The second major thing that the &ETableSpecification; allows you
      to specify is the column grouping and sorting. &ETable; has a
      powerful mechanism for allowing the user to choose columns to
      group by, thus allowing multiple columns of sorting, as well as
      visual grouping of similar elements and interactive selection of
      what data to display.
    </para>

    <para>
      The grouping in &ETableSpecification; is specified as a
      hierarchy of columns to group by. Each level of the hierarchy
      lets you sort by a particular column, either ascending or
      descending. All levels except the last cause the canvas to group
      by the given column.
    </para>

    <para>
      An example &ETableSpecification; follows.
    </para>

    <programlisting>
      &lt;ETableSpecification&gt;
        &lt;columns-shown frozen_columns="2"&gt;
      &lt;column&gt; 0 &lt;/column&gt;
      &lt;column&gt; 1 &lt;/column&gt;
      &lt;column&gt; 2 &lt;/column&gt;
      &lt;column&gt; 3 &lt;/column&gt;
      &lt;column&gt; 4 &lt;/column&gt;
    &lt;/columns-shown&gt;
    &lt;grouping&gt;
      &lt;group column="3" ascending="1"&gt;
        &lt;group column="4" ascending="0"&gt;
          &lt;leaf column="2" ascending="1"/&gt;
        &lt;/group&gt;
      &lt;/group&gt;
    &lt;/grouping&gt;
      &lt;/ETableSpecification&gt;
    </programlisting>

    <para>
      This example has 5 columns which are initially in order. It has
      2 levels of grouping. The first is grouped by the 4th column
      (all indexes are 0 based) and sorts those groups in ascending
      order. Inside those groups, the data is grouped by the fifth
      column and sorted in descending order of the fifth column.
      Finally, the data in those groups is sorted by the third column
      in ascending order. Due to the "frozen_columns" attribute on the
      columns-shown element, the user will not be
      able to rearrange the first two columns. They will always be the
      first two.
    </para>
  </sect1>

  <sect1 id="conclusion">
    <title>Conclusion</title>

    <para>
      All in all, &ETable; is a very powerful widget. Once you learn
      to use it, you have access to a vast amount of power requiring a
      comparatively small amount of work.
    </para>
  </sect1>
</article>