diff options
Diffstat (limited to 'doc/white-papers/widgets/e-table.sgml')
| -rw-r--r-- | doc/white-papers/widgets/e-table.sgml | 279 |
1 files changed, 0 insertions, 279 deletions
diff --git a/doc/white-papers/widgets/e-table.sgml b/doc/white-papers/widgets/e-table.sgml deleted file mode 100644 index 5ff4faf2ae..0000000000 --- a/doc/white-papers/widgets/e-table.sgml +++ /dev/null @@ -1,279 +0,0 @@ -<!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>"> -<!entity ETableCol "<classname>ETableCol</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> - <author> - <firstname>Miguel</firstname> - <surname>de Icaza</surname> - <affiliation> - <address> - <email>miguel@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> - - <para> - &ETable;'s power comes from the fact that it is fully - model/view/controller based. Various models are involved into - the process of rendering the information, and various views are - provided. The programmer has a wide range of options: from the - most finely hand-tuned table to a generic all-encompasing widget - that takes over most of tasks. It is up to the programmer: he - can use the simple to use &ETable; widget that takes care of - everything in a generic way, or he can use the various - components to roll his own tabular display. - </para> - - <para> - &ETable; ships with a standard set of information renderers: - strings, bitmaps, toggle-buttons, check-boxes, and multi-line - strings. But the programmer can write and implement his own - renderer for his information. This means that by default - &ETable; provides the basic display facilities that programmers - required, but they offer the programmer a complete freedom to - incorporate new cell renderers. - </para> - - </sect1> - - <sect1 id="model"> - <title>ETableModel</title> - - <para> - The data back end for the &ETable; is an &ETableModel;. The - &ETableModel is an abstract interface that acts as the - information repository for the various &ETable components. - </para> - - <para> - To use &ETable; you have to create a subclass of the abstract - &ETableModel; class. However, to save you the work of defining - a new <classname>GtkClass</classname> every time you use - &ETable, there is a predefined subclass of &ETableModel; called - &ETableSimple; which simply takes a list of function 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 (defined by the &ETableCol: object). A model - column describes how it maps to the column in the &ETableModel; - as well as containing information about its properties (name, - resizability, resize dimensions, and a renderer for this - specific columns). - </para> - - <para> - &ETable; distinguishes between a model column index, and a view - column index. The former reflects the column in which the data - is stored in the &ETableModel; The later represents the actual - location at which the column is being displayed in the screen. - </para> - - <para> - Each view column index corresponds to a specific model column, - though a model column may have any number of view columns - associated with it (including zero). For example the same - column might be rendered twice, or the data from one column - could be used to display different bits of information - </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> |