tableprinter: update of documentation

[libucw.git] / ucw / doc / table.txt

diff --git a/ucw/doc/table.txt b/ucw/doc/table.txt
index b52bc68837fb42627cf598f23585b68b8d9eeb6c..5185cd63a92a4f3fe75d5590c25dc477b25fe24b 100644 (file)
--- a/ucw/doc/table.txt
+++ b/ucw/doc/table.txt
@@ -39,50 +39,60 @@ string for `printf` used for this column. Moreover, various flags can
 be OR-ed to the width of the column, for example `CELL_ALIGN_LEFT` prescribes
 that the cell should be aligned to the left.
 
-  struct table recording_table = {
+To define the column order, we can create an array of struct table_col_info
+using the following macros: TBL_COL, TBL_COL_FMT, TBL_COL_TYPE. An example
+follows:
+
+  struct table_col_info column_order[] = { TBL_COL(TBL_REC_ID), TBL_COL(TBL_REC_ALBUM_NAME) };
+
+The column order is supplied in the struct table using the TBL_COL_ORDER macro.
+
+  struct table recording_table_template = {
     TBL_COLUMNS {
        [TBL_REC_ID] = TBL_COL_UINT("id", 16),
        [TBL_REC_ALBUM_NAME] = TBL_COL_STR_FMT("album-name", 20 | CELL_ALIGN_LEFT, "%s"),
        [TBL_REC_ARTIST] = TBL_COL_STR("artist", 20),
        [TBL_REC_YEAR] = TBL_COL_UINT("year", 10),
        TBL_COL_END
-    }
+    },
+    TBL_COL_ORDER(column_order)
   };
 
-Each table definition has to be initialized before use by @table_init():
 
-  table_init(&recording_table);
+Each table definition has to be created from a template before use by @table_init():
+
+  struct table *rec_table = table_init(&recording_table_template);
 
 Once it is initialized, we can use it for printing multiple tables.
 At the start of each table, we should obtain a <<fastbuf:,fastbuf>> where the output
 should be sent, store it in the table structure and call @table_start():
 
   struct fastbuf *out = bfdopen_shared(1, 4096);
-  table_start(&recording_table, out);
+  table_start(&rec_table, out);
 
 Then we can fill the rows one after another. Each row is ended by
 @table_end_row():
 
-  table_col_uint(&recording_table, TBL_REC_ID, 0);
-  table_col_str(&recording_table, TBL_REC_ALBUM_NAME, "The Wall");
-  table_col_str(&recording_table, TBL_REC_ARTIST, "Pink Floyd");
-  table_col_uint(&recording_table, TBL_REC_YEAR, 1979);
-  table_end_row(&recording_table);
+  table_col_uint(&rec_table, TBL_REC_ID, 0);
+  table_col_str(&rec_table, TBL_REC_ALBUM_NAME, "The Wall");
+  table_col_str(&rec_table, TBL_REC_ARTIST, "Pink Floyd");
+  table_col_uint(&rec_table, TBL_REC_YEAR, 1979);
+  table_end_row(&rec_table);
 
-  table_col_uint(&recording_table, TBL_REC_ID, 1);
-  table_col_str(&recording_table, TBL_REC_ALBUM_NAME, "Rio Grande Mud");
-  table_col_str(&recording_table, TBL_REC_ARTIST, "ZZ Top");
-  table_col_uint(&recording_table, TBL_REC_YEAR, 1972);
-  table_end_row(&recording_table);
+  table_col_uint(&rec_table, TBL_REC_ID, 1);
+  table_col_str(&rec_table, TBL_REC_ALBUM_NAME, "Rio Grande Mud");
+  table_col_str(&rec_table, TBL_REC_ARTIST, "ZZ Top");
+  table_col_uint(&rec_table, TBL_REC_YEAR, 1972);
+  table_end_row(&rec_table);
 
 Finally, we should close the table by calling @table_end():
 
-  table_end(&recording_table);
+  table_end(&rec_table);
 
 At this moment, the table structure is ready to be used again. When
 you do not need it any longer, you can dispose of it by @table_cleanup():
 
-  table_cleanup(&recording_table);
+  table_cleanup(&rec_table);
 
 ucw/table.h
 -----------