Add docs for outlines and grouping.

Issue #30

dev/release/fix_example_docs.pl

@@ -32,6 +32,8 @@ my @examples = (
     [ 'images.c',               'Example of adding images to a worksheet.' ],
     [ 'headers_footers.c',      'Example of adding worksheet headers/footers' ],
     [ 'defined_name.c',         'Example of how to create defined names' ],
+    [ 'outline.c',              'Example of grouping and outlines' ],
+    [ 'outline_collapsed.c',    'Example of grouping and collapsed outlines' ],
     [ 'tab_colors.c',           'Example of how to set worksheet tab colors' ],
     [ 'hide_sheet.c',           'Example of hiding a worksheet' ],
     [ 'doc_properties.c',       'Example of setting workbook doc properties' ],

docs/Doxyfile

@@ -771,6 +771,7 @@ INPUT                  = src/mainpage.dox                     \
                          src/working_with_dates.dox           \
                          src/working_with_charts.dox          \
                          src/working_with_data_validation.dox \
+                         src/working_with_outlines.dox        \
                          src/working_with_memory.dox          \
                          src/examples.dox                     \
                          src/running_the_tests.dox            \

docs/src/examples.dox

@@ -334,7 +334,7 @@ Example of adding worksheet headers and footers to worksheets.
 <table  width="600">
 <tr>
   <td>@ref headers_footers.c "&lt;&lt; headers_footers.c"</td>
-  <td align="right">@ref tab_colors.c "tab_colors.c &gt;&gt;"</td>
+  <td align="right">@ref outline.c "outline.c &gt;&gt;"</td>
 </tr>
 </table>
 
@@ -348,11 +348,44 @@ single cell or a range of cells in a workbook or worksheet.
 
 
 
-@example tab_colors.c
+@example outline.c
 
 <table  width="600">
 <tr>
   <td>@ref defined_name.c "&lt;&lt; defined_name.c"</td>
+  <td align="right">@ref outline_collapsed.c "outline_collapsed.c &gt;&gt;"</td>
+</tr>
+</table>
+
+Example of how to generate Excel outlines and grouping.
+
+@image html outline1.png
+
+
+
+
+@example outline_collapsed.c
+
+<table  width="600">
+<tr>
+  <td>@ref outline.c "&lt;&lt; outline.c"</td>
+  <td align="right">@ref tab_colors.c "tab_colors.c &gt;&gt;"</td>
+</tr>
+</table>
+
+Example of how to generate Excel outlines and grouping. These examples focus
+mainly on collapsed outlines.
+
+@image html outline2.png
+
+
+
+
+@example tab_colors.c
+
+<table  width="600">
+<tr>
+  <td>@ref outline_collapsed.c "&lt;&lt; outline_collapsed.c"</td>
   <td align="right">@ref hide_sheet.c "hide_sheet.c &gt;&gt;"</td>
 </tr>
 </table>

docs/src/examples.txt

@@ -156,6 +156,21 @@ single cell or a range of cells in a workbook or worksheet.
 
 @image html defined_name.png
 
+##############################################################
+@example outline.c
+
+Example of how to generate Excel outlines and grouping.
+
+@image html outline1.png
+
+##############################################################
+@example outline_collapsed.c
+
+Example of how to generate Excel outlines and grouping. These examples focus
+mainly on collapsed outlines.
+
+@image html outline2.png
+
 ##############################################################
 @example tab_colors.c
 

docs/src/mainpage.dox

@@ -51,6 +51,7 @@ following sections for more information:
 - @ref working_with_dates
 - @ref working_with_charts
 - @ref working_with_data_validation
+- @ref working_with_outlines
 - @ref working_with_memory
 
 - @ref examples

docs/src/working_with_charts.dox

@@ -1030,6 +1030,6 @@ If required these features are all available in the Perl and Python versions
 of this library.
 
 
-Next: @ref working_with_memory
+Next: @ref working_with_data_validation
 
 */

docs/src/working_with_data_validation.dox

@@ -498,4 +498,6 @@ set using `error_message`. It is on by default.
 
 For a full example see @ref data_validate.c.
 
+Next: @ref working_with_outlines
+
 */

docs/src/working_with_outlines.dox

@@ -0,0 +1,130 @@
+/**
+@page working_with_outlines Working with Outlines and Grouping
+
+Excel allows you to group rows or columns so that they can be hidden or
+displayed with a single mouse click. This feature is referred to as Outlines
+and Grouping.
+
+Outlines can reduce complex data down to a few salient sub-totals or
+summaries. For example the following is a worksheet with three outlines.
+
+@image html outline1.png
+
+Rows 2 to 11 are grouped at level 1 and rows 2 to 5 and 7 to 10 are grouped at
+level 2. The lines at the left hand side are called "outline level" bars and
+the level is shown by the small numeral above the outline.
+
+Clicking the minus sign on each of the level 2 outlines will collapse and hide
+the data as shown below.
+
+@image html outline5.png
+
+The minus sign changes to a plus sign to indicate that the data in the outline
+is hidden. This shows the usefulness of outlines: with 2 mouse clicks we have
+reduced the amount of visual data down to 2 sub-totals and a master total.
+
+Finally, clicking on the minus sign on the level 1 outline will collapse the
+remaining rows as follows:
+
+@image html outline6.png
+
+
+@section ww_outlines_grouping Outlines and Grouping in libxlsxwriter
+
+Grouping in `libxlsxwriter` is achieved by setting the outline level via the
+`worksheet_set_row_opt()` and `worksheet_set_column_opt()` worksheet
+functions:
+
+Adjacent row or columns with the same outline level are grouped together into a
+single outline.
+
+The `options` parameter is a #lxw_row_col_options struct. It has the following
+members:
+
+- `'hidden'`
+- `'level'`
+- `'collapsed'`
+
+Options can be set as follows, for example to set up an outline for rows:
+
+@code
+    // The option structs with the outline level set.
+    lxw_row_col_options options1 = {.hidden = 0, .level = 2, .collapsed = 0};
+    lxw_row_col_options options2 = {.hidden = 0, .level = 1, .collapsed = 0};
+
+
+    // Set the row options with the outline level.
+    worksheet_set_row_opt(worksheet, 1,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 2,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 3,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 4,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 5,  LXW_DEF_ROW_HEIGHT, NULL, &options2);
+
+    worksheet_set_row_opt(worksheet, 6,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 7,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 8,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 9,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 10, LXW_DEF_ROW_HEIGHT, NULL, &options2);
+@endcode
+
+@image html outline1.png
+
+Or an outline for columns:
+
+@code
+    lxw_row_col_options options1 = {.hidden = 0, .level = 1, .collapsed = 0};
+
+    worksheet_set_column_opt(worksheet, COLS("B:G"),  5, NULL, &options1);
+@endcode
+
+@image html outline8.png
+
+
+The following example sets an outline level of 1 for rows 1 to 4
+(zero-indexed) and columns B to G. The parameters `height`, `width` and
+`cell_format` are assigned default values:
+
+@code
+    lxw_row_col_options options1 = {.hidden = 0, .level = 1, .collapsed = 0};
+
+    worksheet_set_row_opt(worksheet, 1,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 2,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 3,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 4,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+
+    worksheet_set_column_opt(worksheet, COLS("B:G"),  LXW_DEF_COL_WIDTH, NULL, &options);
+@endcode
+
+@image html outline3.png
+
+Rows and columns can be collapsed by setting the `hidden` member for the
+hidden rows/columns and setting the `collapsed` member for the row/column that
+has the collapsed `'+'` symbol:
+
+@code
+    lxw_row_col_options options1 = {.hidden = 1, .level = 1, .collapsed = 0};
+    lxw_row_col_options options2 = {.hidden = 0, .level = 0, .collapsed = 1};
+
+    worksheet_set_row_opt(worksheet, 1,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 2,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 3,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 4,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+    worksheet_set_row_opt(worksheet, 5,  LXW_DEF_ROW_HEIGHT, NULL, &options2);
+
+    worksheet_set_column_opt(worksheet, COLS("B:G"),  LXW_DEF_COL_WIDTH, NULL, &options1);
+    worksheet_set_column_opt(worksheet, COLS("H:H"),  LXW_DEF_COL_WIDTH, NULL, &options2);
+@endcode
+
+@image html outline7.png
+
+Excel allows up to 7 outline levels. Therefore the `level` parameter should
+be in the range `0 <= level <= 7`.
+
+@image html outline4.png
+
+Some additional outline properties can be set via the
+`worksheet_outline_settings()` worksheet function.
+
+Next: @ref working_with_memory
+
+*/

examples/hide_row_col.c

@@ -3,7 +3,9 @@
  * library.
  *
  * In order to hide rows without setting each one, (of approximately 1 million
- * rows), Excel uses an optimization to hide all rows that don't have data.
+ * rows), Excel uses an optimization to hide all rows that don't have data. In
+ * Libxlsxwriter we replicate that using the worksheet_set_default_row()
+ * function.
  *
  * Copyright 2014-2017, John McNamara, jmcnamara@cpan.org
  *
@@ -25,7 +27,7 @@ int main() {
     /* Hide all rows without data. */
     worksheet_set_default_row(worksheet, 15, LXW_TRUE);
 
-    /* Set the height of empty rows that we do want to display even if it is */
+    /* Set the height of empty rows that we want to display even if it is */
     /* the default height. */
     for (row = 1; row <= 6; row++)
         worksheet_set_row(worksheet, row, 15, NULL);

include/xlsxwriter/worksheet.h

@@ -267,12 +267,14 @@ STAILQ_HEAD(lxw_chart_data, lxw_image_options);
  * Options struct for the worksheet_set_column() and worksheet_set_row()
  * functions.
  *
- * It has the following members but currently only the `hidden` property is
- * supported:
+ * It has the following members:
  *
  * * `hidden`
  * * `level`
  * * `collapsed`
+ *
+ * The members of this struct are explained in @ref ww_outlines_grouping.
+ *
  */
 typedef struct lxw_row_col_options {
     /** Hide the row/column */
@@ -1369,7 +1371,7 @@ lxw_error worksheet_set_row(lxw_worksheet *worksheet,
  *  `worksheet_set_row()` with an additional `options` parameter.
  *
  * The `options` parameter is a #lxw_row_col_options struct. It has the
- * following members but currently only the `hidden` property is supported:
+ * following members:
  *
  * - `hidden`
  * - `level`
@@ -1379,12 +1381,41 @@ lxw_error worksheet_set_row(lxw_worksheet *worksheet,
  * example, to hide intermediary steps in a complicated calculation:
  *
  * @code
- *     lxw_row_col_options options = {.hidden = 1, .level = 0, .collapsed = 0};
+ *     lxw_row_col_options options1 = {.hidden = 1, .level = 0, .collapsed = 0};
+ *
+ *     // Hide the fourth and fifth (zero indexed) rows.
+ *     worksheet_set_row_opt(worksheet, 3,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+ *     worksheet_set_row_opt(worksheet, 4,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
  *
- *     // Hide the fourth row.
- *     worksheet_set_row_opt(worksheet, 3, 20, NULL, &options);
  * @endcode
  *
+ * @image html hide_row_col2.png
+ *
+ * The `"hidden"`, `"level"`,  and `"collapsed"`, options can also be used to
+ * create Outlines and Grouping. See @ref working_with_outlines.
+ *
+ * @code
+ *     // The option structs with the outline level set.
+ *     lxw_row_col_options options1 = {.hidden = 0, .level = 2, .collapsed = 0};
+ *     lxw_row_col_options options2 = {.hidden = 0, .level = 1, .collapsed = 0};
+ *
+ *
+ *     // Set the row options with the outline level.
+ *     worksheet_set_row_opt(worksheet, 1,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+ *     worksheet_set_row_opt(worksheet, 2,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+ *     worksheet_set_row_opt(worksheet, 3,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+ *     worksheet_set_row_opt(worksheet, 4,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+ *     worksheet_set_row_opt(worksheet, 5,  LXW_DEF_ROW_HEIGHT, NULL, &options2);
+ *
+ *     worksheet_set_row_opt(worksheet, 6,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+ *     worksheet_set_row_opt(worksheet, 7,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+ *     worksheet_set_row_opt(worksheet, 8,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+ *     worksheet_set_row_opt(worksheet, 9,  LXW_DEF_ROW_HEIGHT, NULL, &options1);
+ *     worksheet_set_row_opt(worksheet, 10, LXW_DEF_ROW_HEIGHT, NULL, &options2);
+ * @endcode
+ *
+ * @image html outline1.png
+ *
  */
 lxw_error worksheet_set_row_opt(lxw_worksheet *worksheet,
                                 lxw_row_t row,
@@ -1492,36 +1523,48 @@ lxw_error worksheet_set_column(lxw_worksheet *worksheet,
                                lxw_col_t last_col,
                                double width, lxw_format *format);
 
- /**
-  * @brief Set the properties for one or more columns of cells with options.
-  *
-  * @param worksheet Pointer to a lxw_worksheet instance to be updated.
-  * @param first_col The zero indexed first column.
-  * @param last_col  The zero indexed last column.
-  * @param width     The width of the column(s).
-  * @param format    A pointer to a Format instance or NULL.
-  * @param options   Optional row parameters: hidden, level, collapsed.
-  *
-  * The `%worksheet_set_column_opt()` function  is the same as
-  * `worksheet_set_column()` with an additional `options` parameter.
-  *
-  * The `options` parameter is a #lxw_row_col_options struct. It has the
-  * following members but currently only the `hidden` property is supported:
-  *
-  * - `hidden`
-  * - `level`
-  * - `collapsed`
-  *
-  * The `"hidden"` option is used to hide a column. This can be used, for
-  * example, to hide intermediary steps in a complicated calculation:
-  *
-  * @code
-  *     lxw_row_col_options options = {.hidden = 1, .level = 0, .collapsed = 0};
-  *
-  *     worksheet_set_column_opt(worksheet, COLS("A:A"), 8.43, NULL, &options);
-  * @endcode
-  *
-  */
+/**
+ * @brief Set the properties for one or more columns of cells with options.
+ *
+ * @param worksheet Pointer to a lxw_worksheet instance to be updated.
+ * @param first_col The zero indexed first column.
+ * @param last_col  The zero indexed last column.
+ * @param width     The width of the column(s).
+ * @param format    A pointer to a Format instance or NULL.
+ * @param options   Optional row parameters: hidden, level, collapsed.
+ *
+ * The `%worksheet_set_column_opt()` function  is the same as
+ * `worksheet_set_column()` with an additional `options` parameter.
+ *
+ * The `options` parameter is a #lxw_row_col_options struct. It has the
+ * following members:
+ *
+ * - `hidden`
+ * - `level`
+ * - `collapsed`
+ *
+ * The `"hidden"` option is used to hide a column. This can be used, for
+ * example, to hide intermediary steps in a complicated calculation:
+ *
+ * @code
+ *     lxw_row_col_options options1 = {.hidden = 1, .level = 0, .collapsed = 0};
+ *
+ *     worksheet_set_column_opt(worksheet, COLS("D:E"),  LXW_DEF_COL_WIDTH, NULL, &options1);
+ * @endcode
+ *
+ * @image html hide_row_col3.png
+ *
+ * The `"hidden"`, `"level"`,  and `"collapsed"`, options can also be used to
+ * create Outlines and Grouping. See @ref working_with_outlines.
+ *
+ * @code
+ *     lxw_row_col_options options1 = {.hidden = 0, .level = 1, .collapsed = 0};
+ *
+ *     worksheet_set_column_opt(worksheet, COLS("B:G"),  5, NULL, &options1);
+ * @endcode
+ *
+ * @image html outline8.png
+ */
 lxw_error worksheet_set_column_opt(lxw_worksheet *worksheet,
                                    lxw_col_t first_col,
                                    lxw_col_t last_col,
@@ -2937,6 +2980,50 @@ void worksheet_set_tab_color(lxw_worksheet *worksheet, lxw_color_t color);
 void worksheet_protect(lxw_worksheet *worksheet, const char *password,
                        lxw_protection *options);
 
+/**
+ * @brief Set the Outline and Grouping display properties.
+ *
+ * @param worksheet      Pointer to a lxw_worksheet instance to be updated.
+ * @param visible        Outlines are visible. Optional, defaults to True.
+ * @param symbols_below  Show row outline symbols below the outline bar.
+ * @param symbols_right  Show column outline symbols to the right of outline.
+ * @param auto_style     Use Automatic outline style.
+ *
+ * The `%worksheet_outline_settings()` method is used to control the
+ * appearance of outlines in Excel. Outlines are described the section on 
+ * @ref working_with_outlines.
+ * 
+ * The `visible` parameter is used to control whether or not outlines are
+ * visible. Setting this parameter to False will cause all outlines on the
+ * worksheet to be hidden. They can be un-hidden in Excel by means of the
+ * "Show Outline Symbols" command button. The default Excel setting is True
+ * for visible outlines.
+ *
+ * The `symbols_below` parameter is used to control whether the row outline
+ * symbol will appear above or below the outline level bar. The default Excel
+ * setting is True for symbols to appear below the outline level bar.
+ *
+ * The `symbols_right` parameter is used to control whether the column outline
+ * symbol will appear to the left or the right of the outline level bar. The
+ * default Excel setting is True for symbols to appear to the right of the
+ * outline level bar.
+ *
+ * The `auto_style` parameter is used to control whether the automatic outline
+ * generator in Excel uses automatic styles when creating an outline. This has
+ * no effect on a file generated by XlsxWriter but it does have an effect on
+ * how the worksheet behaves after it is created. The default Excel setting is
+ * False for "Automatic Styles" to be turned off.
+ *
+ * The default settings for all of these parameters in libxlsxwriter
+ * correspond to Excel's default parameters and are shown below:
+ * 
+ * @code
+ *     worksheet_outline_settings(worksheet1, LXW_TRUE, LXW_TRUE, LXW_TRUE, LXW_FALSE);
+ * @endcode
+ *
+ * The worksheet parameters controlled by `worksheet_outline_settings()` are
+ * rarely used.
+ */
 void worksheet_outline_settings(lxw_worksheet *worksheet, uint8_t visible,
                                 uint8_t symbols_below, uint8_t symbols_right,
                                 uint8_t auto_style);