From f073038b91db7859f22c240c82226e4741228a7f Mon Sep 17 00:00:00 2001 From: Christopher James Lahey Date: Fri, 3 Mar 2000 22:10:50 +0000 Subject: New doc for the ETable widget. 2000-03-03 Christopher James Lahey * 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 --- doc/ChangeLog | 47 +++++++ doc/white-papers/calendar/ChangeLog | 13 -- doc/white-papers/mail/ChangeLog | 26 ---- doc/white-papers/widgets/e-table.sgml | 229 +++++++++++++++++++++++++++++++++ help/ChangeLog | 47 +++++++ help/white-papers/calendar/ChangeLog | 13 -- help/white-papers/mail/ChangeLog | 26 ---- help/white-papers/widgets/e-table.sgml | 229 +++++++++++++++++++++++++++++++++ 8 files changed, 552 insertions(+), 78 deletions(-) create mode 100644 doc/ChangeLog delete mode 100644 doc/white-papers/calendar/ChangeLog delete mode 100644 doc/white-papers/mail/ChangeLog create mode 100644 doc/white-papers/widgets/e-table.sgml create mode 100644 help/ChangeLog delete mode 100644 help/white-papers/calendar/ChangeLog delete mode 100644 help/white-papers/mail/ChangeLog create mode 100644 help/white-papers/widgets/e-table.sgml diff --git a/doc/ChangeLog b/doc/ChangeLog new file mode 100644 index 0000000000..afed7cc645 --- /dev/null +++ b/doc/ChangeLog @@ -0,0 +1,47 @@ +2000-03-03 Christopher James Lahey + + * 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. + +2000-03-01 Dan Winship + + * ibex.sgml: Ibex white paper + +2000-02-29 Federico Mena Quintero + + * calendar.sgml: Sections for the calendar user agent and the + calendar client library. + +2000-02-29 Dan Winship + + * camel.sgml: Reorg a bit more, make the 
 section narrower,
+	add more references to graphics (the graphics themselves are
+	still in beta), add a section on CamelStream.
+
+2000-02-28  Federico Mena Quintero  
+
+	* calendar.sgml: Section for the personal calendar server.
+
+2000-02-28  Dan Winship  
+
+	* camel.sgml: add Bertrand to authors, edit his additions
+
+2000-02-28  bertrand  
+
+	* camel.sgml: add a blurb about camel offering
+	uniform interface. needs style and grammar corrections. 
+	Talk about virtual folders.
+	Talk about lightweight messages
+	Talk about IMAP. 
+
+2000-02-28  Dan Winship  
+
+	* camel.sgml: Beginnings of a Camel white paper
+
+2000-02-25  Federico Mena Quintero  
+
+	* calendar.sgml: New file for the Evolution calendaring white paper.
+
diff --git a/doc/white-papers/calendar/ChangeLog b/doc/white-papers/calendar/ChangeLog
deleted file mode 100644
index c631ffa0df..0000000000
--- a/doc/white-papers/calendar/ChangeLog
+++ /dev/null
@@ -1,13 +0,0 @@
-2000-02-29  Federico Mena Quintero  
-
-	* calendar.sgml: Sections for the calendar user agent and the
-	calendar client library.
-
-2000-02-28  Federico Mena Quintero  
-
-	* calendar.sgml: Section for the personal calendar server.
-
-2000-02-25  Federico Mena Quintero  
-
-	* calendar.sgml: New file for the Evolution calendaring white paper.
-
diff --git a/doc/white-papers/mail/ChangeLog b/doc/white-papers/mail/ChangeLog
deleted file mode 100644
index 5933582d40..0000000000
--- a/doc/white-papers/mail/ChangeLog
+++ /dev/null
@@ -1,26 +0,0 @@
-2000-03-01  Dan Winship  
-
-	* ibex.sgml: Ibex white paper
-
-2000-02-29  Dan Winship  
-
-	* camel.sgml: Reorg a bit more, make the 
 section narrower,
-	add more references to graphics (the graphics themselves are
-	still in beta), add a section on CamelStream.
-
-2000-02-28  Dan Winship  
-
-	* camel.sgml: add Bertrand to authors, edit his additions
-
-2000-02-28  bertrand  
-
-	* camel.sgml: add a blurb about camel offering
-	uniform interface. needs style and grammar corrections. 
-	Talk about virtual folders.
-	Talk about lightweight messages
-	Talk about IMAP. 
-
-2000-02-28  Dan Winship  
-
-	* camel.sgml: Beginnings of a Camel white paper
-
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 @@
+Evolution">
+ETable">
+ETableModel">
+ETableSimple">
+ETableHeader">
+ETableSpecification">
+]>
+
+

+
+  
+    The ETable Widget
+
+    
+      
+	Chris
+	Lahey
+	
+	  

+	    clahey@helixcode.com
+	  

+	
+      
+    
+
+    
+      2000
+      Helix Code, Inc.
+    
+
+  
+
+  
+    Introduction
+
+    
+      &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.
+    
+  
+
+  
+    ETableModel
+
+    
+      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.
+    
+  
+    
+  
+    Columns
+
+    
+      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, 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.
+    
+
+    
+      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.
+    
+  
+
+  
+    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.
+    
+  
+
+  
+    Layout Specification
+
+    
+      &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.
+    
+  
+
+  
+    Conclusion
+
+    
+      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.
+    
+  
+

diff --git a/help/ChangeLog b/help/ChangeLog
new file mode 100644
index 0000000000..afed7cc645
--- /dev/null
+++ b/help/ChangeLog
@@ -0,0 +1,47 @@
+2000-03-03  Christopher James Lahey  
+
+	* 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.
+
+2000-03-01  Dan Winship  
+
+	* ibex.sgml: Ibex white paper
+
+2000-02-29  Federico Mena Quintero  
+
+	* calendar.sgml: Sections for the calendar user agent and the
+	calendar client library.
+
+2000-02-29  Dan Winship  
+
+	* camel.sgml: Reorg a bit more, make the 
 section narrower,
+	add more references to graphics (the graphics themselves are
+	still in beta), add a section on CamelStream.
+
+2000-02-28  Federico Mena Quintero  
+
+	* calendar.sgml: Section for the personal calendar server.
+
+2000-02-28  Dan Winship  
+
+	* camel.sgml: add Bertrand to authors, edit his additions
+
+2000-02-28  bertrand  
+
+	* camel.sgml: add a blurb about camel offering
+	uniform interface. needs style and grammar corrections. 
+	Talk about virtual folders.
+	Talk about lightweight messages
+	Talk about IMAP. 
+
+2000-02-28  Dan Winship  
+
+	* camel.sgml: Beginnings of a Camel white paper
+
+2000-02-25  Federico Mena Quintero  
+
+	* calendar.sgml: New file for the Evolution calendaring white paper.
+
diff --git a/help/white-papers/calendar/ChangeLog b/help/white-papers/calendar/ChangeLog
deleted file mode 100644
index c631ffa0df..0000000000
--- a/help/white-papers/calendar/ChangeLog
+++ /dev/null
@@ -1,13 +0,0 @@
-2000-02-29  Federico Mena Quintero  
-
-	* calendar.sgml: Sections for the calendar user agent and the
-	calendar client library.
-
-2000-02-28  Federico Mena Quintero  
-
-	* calendar.sgml: Section for the personal calendar server.
-
-2000-02-25  Federico Mena Quintero  
-
-	* calendar.sgml: New file for the Evolution calendaring white paper.
-
diff --git a/help/white-papers/mail/ChangeLog b/help/white-papers/mail/ChangeLog
deleted file mode 100644
index 5933582d40..0000000000
--- a/help/white-papers/mail/ChangeLog
+++ /dev/null
@@ -1,26 +0,0 @@
-2000-03-01  Dan Winship  
-
-	* ibex.sgml: Ibex white paper
-
-2000-02-29  Dan Winship  
-
-	* camel.sgml: Reorg a bit more, make the 
 section narrower,
-	add more references to graphics (the graphics themselves are
-	still in beta), add a section on CamelStream.
-
-2000-02-28  Dan Winship  
-
-	* camel.sgml: add Bertrand to authors, edit his additions
-
-2000-02-28  bertrand  
-
-	* camel.sgml: add a blurb about camel offering
-	uniform interface. needs style and grammar corrections. 
-	Talk about virtual folders.
-	Talk about lightweight messages
-	Talk about IMAP. 
-
-2000-02-28  Dan Winship  
-
-	* camel.sgml: Beginnings of a Camel white paper
-
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 @@
+Evolution">
+ETable">
+ETableModel">
+ETableSimple">
+ETableHeader">
+ETableSpecification">
+]>
+
+

+
+  
+    The ETable Widget
+
+    
+      
+	Chris
+	Lahey
+	
+	  

+	    clahey@helixcode.com
+	  

+	
+      
+    
+
+    
+      2000
+      Helix Code, Inc.
+    
+
+  
+
+  
+    Introduction
+
+    
+      &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.
+    
+  
+
+  
+    ETableModel
+
+    
+      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.
+    
+  
+    
+  
+    Columns
+
+    
+      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, 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.
+    
+
+    
+      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.
+    
+  
+
+  
+    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.
+    
+  
+
+  
+    Layout Specification
+
+    
+      &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.
+    
+  
+
+  
+    Conclusion
+
+    
+      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.
+    
+  
+

-- 
cgit