Chris Lahey

clahey@helixcode.com

Miguel de Icaza

miguel@helixcode.com

2000 Helix Code, Inc. &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. &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. &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. 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 GtkClass, there is a predefined subclass of &ETableModel; called &ETableSimple; which simply takes a list of callbacks to perform the various operations. 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. 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). 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". 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. 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. The &ETableHeader; represents the header information for the table. The &ETableHeader; is used in two different ways. The first is the in the full_header 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;. 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 e_table_header_new and e_table_header_add_col. &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. 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. 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. 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. 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. An example &ETableSpecification; follows. <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> 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. 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.