aboutsummaryrefslogtreecommitdiffstats
path: root/doc/white-papers/widgets/e-table.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/white-papers/widgets/e-table.sgml')
-rw-r--r--doc/white-papers/widgets/e-table.sgml229
1 files changed, 229 insertions, 0 deletions
diff --git a/doc/white-papers/widgets/e-table.sgml b/doc/white-papers/widgets/e-table.sgml
new file mode 100644
index 0000000000..0a52ecbb51
--- /dev/null
+++ b/doc/white-papers/widgets/e-table.sgml
@@ -0,0 +1,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>