231 lines
8.1 KiB
Plaintext
231 lines
8.1 KiB
Plaintext
<!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, a mail program could display deleted
|
|
messages with a line through them by creating a model column
|
|
with no corresponding view column that told whether or not the
|
|
message is deleted, and then having the text column
|
|
strikethrough the display if the invisible 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>
|
|
<ETableSpecification>
|
|
<columns-shown frozen_columns="2">
|
|
<column> 0 </column>
|
|
<column> 1 </column>
|
|
<column> 2 </column>
|
|
<column> 3 </column>
|
|
<column> 4 </column>
|
|
</columns-shown>
|
|
<grouping>
|
|
<group column="3" ascending="1">
|
|
<group column="4" ascending="0">
|
|
<leaf column="2" ascending="1"/>
|
|
</group>
|
|
</group>
|
|
</grouping>
|
|
</ETableSpecification>
|
|
</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>
|