diff options
Diffstat (limited to 'doc/white-papers/widgets/e-table.sgml')
| -rw-r--r-- | doc/white-papers/widgets/e-table.sgml | 229 |
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> + <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> |