New doc for the ETable widget.

2000-03-03  Christopher James Lahey  <clahey@helixcode.com>

        * white-papers/widgets/, white-papers/widgets/e-table.sgml: New
        doc for the ETable widget.

        * ChangeLog: Created a ChangeLog file for the docs file and
        integrated the individual ChangeLogs.

svn path=/trunk/; revision=2029

1 files changed, 229 insertions, 0 deletions

diff --git a/help/white-papers/widgets/e-table.sgml b/help/white-papers/widgets/e-table.sgml
new file mode 100644
index 0000000000..0a52ecbb51
--- /dev/null
+++ b/help/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>