grouping: add documentation and examples

CHANGELOG.md

@@ -10,6 +10,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Added support for worksheet outline groupings.
+
+  In Excel an outline is a group of rows or columns that can be collapsed or
+  expanded to simplify hierarchical data. It is often used with the
+  `SUBTOTAL()` function. For example:
+
+  <img src="https://rustxlsxwriter.github.io/images/worksheet_group_rows2.png">
+
+  See [Grouping and outlining data].
+
+  [Grouping and outlining data]: https://docs.rs/rust_xlsxwriter/latest/rust_xlsxwriter/worksheet/index.html#grouping-and-outlining-data
+
+
 - Added support for ignoring Excel worksheet cell errors.
 
   Excel flags a number of data errors and inconsistencies with a a small

README.md

@@ -92,6 +92,7 @@ currently supported features are:
 - Sparklines.
 - Worksheet PNG/JPEG/GIF/BMP images.
 - Rich multi-format strings.
+- Outline groupings.
 - Defined names.
 - Autofilters.
 - Worksheet Tables.
@@ -143,6 +144,7 @@ frequently.
 
 Recent changes:
 
+- Added worksheet outline groupings.
 - Added support for Worksheet checkboxes.
 - Added `constant_memory` mode.
 

examples/Readme.md

@@ -150,6 +150,16 @@ documentation and generally show how an individual function works.
   worksheets that correspond to the sections of the Excel "Format Cells"
   dialog.
 
+* `app_grouped_columns.rs` - An example of how to group columns into
+  outlines with the `rust_xlsxwriter` library. In Excel an outline is a
+  group of rows or columns that can be collapsed or expanded to simplify
+  hierarchical data. It is often used with the `SUBTOTAL()` function.
+
+* `app_grouped_rows.rs` - An example of how to group rows into outlines
+  with the `rust_xlsxwriter` library. In Excel an outline is a group of
+  rows or columns that can be collapsed or expanded to simplify
+  hierarchical data. It is often used with the `SUBTOTAL()` function.
+
 * `app_headers_footers.rs` - An example of setting headers and footers in
   worksheets using the rust_xlsxwriter library.
 
@@ -1330,6 +1340,54 @@ documentation and generally show how an individual function works.
   filter. Excel uses both of these methods depending on the data being
   filtered.
 
+* `doc_worksheet_group_columns1.rs` - An example of how to group worksheet
+  columns into outlines.
+
+* `doc_worksheet_group_columns2.rs` - An example of how to group worksheet
+  columns into outlines. This example shows hows to add secondary groups
+  within a primary grouping. Excel requires at least one column between
+  each outline grouping at the same level.
+
+* `doc_worksheet_group_columns_collapsed1.rs` - An example of how to group
+  worksheet columns into outlines with collapsed/hidden rows.
+
+* `doc_worksheet_group_columns_collapsed2.rs` - An example of how to group
+  worksheet columns into outlines with collapsed/hidden rows. This example
+  shows hows to add secondary groups within a primary grouping. Excel
+  requires at least one column between each outline grouping at the same
+  level.
+
+* `doc_worksheet_group_rows1.rs` - An example of how to group worksheet
+  rows into outlines.
+
+* `doc_worksheet_group_rows2.rs` - An example of how to group worksheet
+  rows into outlines. This example shows hows to add secondary groups
+  within a primary grouping. Excel requires at least one row between each
+  outline grouping at the same level.
+
+* `doc_worksheet_group_rows_collapsed1.rs` - An example of how to group
+  worksheet rows into outlines with collapsed/hidden rows.
+
+* `doc_worksheet_group_rows_collapsed2.rs` - An example of how to group
+  worksheet rows into outlines with collapsed/hidden rows. This example
+  shows hows to add secondary groups within a primary grouping. Excel
+  requires at least one row between each outline grouping at the same
+  level.
+
+* `doc_worksheet_group_rows_intro1.rs` - An example of how to group
+  worksheet rows into outlines.
+
+* `doc_worksheet_group_rows_intro2.rs` - An example of how to group
+  worksheet rows into outlines.
+
+* `doc_worksheet_group_symbols_above.rs` - An example of how to group
+  worksheet rows into outlines. This example puts the expand/collapse
+  symbol above the range for all row groups in the worksheet.
+
+* `doc_worksheet_group_symbols_to_left.rs` - An example of how to group
+  worksheet columns into outlines. This example puts the expand/collapse
+  symbol to the left of the range for all row groups in the worksheet.
+
 * `doc_worksheet_hide_unused_rows.rs` - Demonstrates efficiently hiding the
   unused rows in a worksheet.
 

examples/app_grouped_columns.rs

@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2025, John McNamara, [email protected]
+
+//! An example of how to group columns into outlines with the `rust_xlsxwriter`
+//! library.
+//!
+//! In Excel an outline is a group of rows or columns that can be collapsed or
+//! expanded to simplify hierarchical data. It is often used with the
+//! `SUBTOTAL()` function.
+
+use rust_xlsxwriter::{Format, Workbook, Worksheet, XlsxError};
+
+fn main() -> Result<(), XlsxError> {
+    // Create a new Excel file object.
+    let mut workbook = Workbook::new();
+
+    // Add a format to use in headings.
+    let bold = Format::new().set_bold();
+
+    // -----------------------------------------------------------------------
+    // 1. Add an outline column group with sub-total.
+    // -----------------------------------------------------------------------
+
+    // Add a worksheet with some sample data.
+    let worksheet = workbook.add_worksheet();
+    let description = "Simple outline column grouping.";
+    populate_worksheet_data(worksheet, description, &bold)?;
+
+    // Add grouping for the over the sub-total range.
+    worksheet.group_columns(1, 8)?;
+
+    // -----------------------------------------------------------------------
+    // 2. Add nested outline column groups with sub-totals.
+    // -----------------------------------------------------------------------
+
+    // Add a worksheet with some sample data.
+    let worksheet = workbook.add_worksheet();
+    let description = "Nested outline column grouping.";
+    populate_worksheet_data(worksheet, description, &bold)?;
+
+    // Add grouping for the over the sub-total range.
+    worksheet.group_columns(1, 8)?;
+
+    // Add secondary groups within the first range.
+    worksheet.group_columns(1, 3)?;
+    worksheet.group_columns(5, 7)?;
+
+    // -----------------------------------------------------------------------
+    // 3. Add a collapsed inner outline column groups.
+    // -----------------------------------------------------------------------
+
+    // Add a worksheet with some sample data.
+    let worksheet = workbook.add_worksheet();
+    let description = "Collapsed inner column grouping.";
+    populate_worksheet_data(worksheet, description, &bold)?;
+
+    // Add grouping for the over the sub-total range.
+    worksheet.group_columns(1, 8)?;
+
+    // Add collapsed secondary groups within the first range.
+    worksheet.group_columns_collapsed(1, 3)?;
+    worksheet.group_columns_collapsed(5, 7)?;
+
+    // -----------------------------------------------------------------------
+    // 4. Add a collapsed outer column group.
+    // -----------------------------------------------------------------------
+
+    // Add a worksheet with some sample data.
+    let worksheet = workbook.add_worksheet();
+    let description = "Collapsed outer column grouping.";
+    populate_worksheet_data(worksheet, description, &bold)?;
+
+    // Add collapsed grouping for the over the sub-total range.
+    worksheet.group_columns_collapsed(1, 8)?;
+
+    // Add secondary groups within the first range.
+    worksheet.group_columns(1, 3)?;
+    worksheet.group_columns(5, 7)?;
+
+    // -----------------------------------------------------------------------
+    // 5. Column groups with outline symbols on top.
+    // -----------------------------------------------------------------------
+
+    // Add a worksheet with some sample data.
+    let worksheet = workbook.add_worksheet();
+    let description = "Outline column grouping symbols to the left.";
+    populate_worksheet_data(worksheet, description, &bold)?;
+
+    // Add outline column groups.
+    worksheet.group_columns(1, 3)?;
+    worksheet.group_columns(5, 7)?;
+
+    // Change the worksheet group setting so outline symbols are to the left.
+    worksheet.group_symbols_to_left(true);
+
+    // -----------------------------------------------------------------------
+    // 6. Demonstrate all group levels.
+    // -----------------------------------------------------------------------
+
+    // Add a worksheet with some sample data.
+    let worksheet = workbook.add_worksheet();
+    let description = "Excel outline levels.";
+    let levels = [
+        "Level 1", "Level 2", "Level 3", "Level 4", //
+        "Level 5", "Level 6", "Level 7", "Level 6", //
+        "Level 5", "Level 4", "Level 3", "Level 2", //
+        "Level 1",
+    ];
+    worksheet.write_row(0, 0, levels)?;
+    worksheet.write_with_format(2, 0, description, &bold)?;
+
+    // Add outline column groups from outer to inner.
+    worksheet.group_columns(0, 12)?;
+    worksheet.group_columns(1, 11)?;
+    worksheet.group_columns(2, 10)?;
+    worksheet.group_columns(3, 9)?;
+    worksheet.group_columns(4, 8)?;
+    worksheet.group_columns(5, 7)?;
+    worksheet.group_columns(6, 6)?;
+
+    // Save the file to disk.
+    workbook.save("grouped_columns.xlsx")?;
+
+    Ok(())
+}
+
+// Generate worksheet data.
+pub fn populate_worksheet_data(
+    worksheet: &mut Worksheet,
+    description: &str,
+    bold: &Format,
+) -> Result<(), XlsxError> {
+    worksheet.write_with_format(0, 0, "Region", bold)?;
+    worksheet.write_with_format(1, 0, "North", bold)?;
+    worksheet.write_with_format(2, 0, "South", bold)?;
+    worksheet.write_with_format(3, 0, "East", bold)?;
+    worksheet.write_with_format(4, 0, "West", bold)?;
+
+    worksheet.write_with_format(0, 1, "Jan", bold)?;
+    worksheet.write(1, 1, 50)?;
+    worksheet.write(2, 1, 10)?;
+    worksheet.write(3, 1, 45)?;
+    worksheet.write(4, 1, 15)?;
+
+    worksheet.write_with_format(0, 2, "Feb", bold)?;
+    worksheet.write(1, 2, 20)?;
+    worksheet.write(2, 2, 20)?;
+    worksheet.write(3, 2, 75)?;
+    worksheet.write(4, 2, 15)?;
+
+    worksheet.write_with_format(0, 3, "Mar", bold)?;
+    worksheet.write(1, 3, 15)?;
+    worksheet.write(2, 3, 30)?;
+    worksheet.write(3, 3, 50)?;
+    worksheet.write(4, 3, 35)?;
+
+    worksheet.write_with_format(0, 4, "Q1 Total", bold)?;
+    worksheet.write_formula_with_format(1, 4, "=SUBTOTAL(9,B2:D2)", bold)?;
+    worksheet.write_formula_with_format(2, 4, "=SUBTOTAL(9,B3:D3)", bold)?;
+    worksheet.write_formula_with_format(3, 4, "=SUBTOTAL(9,B4:D4)", bold)?;
+    worksheet.write_formula_with_format(4, 4, "=SUBTOTAL(9,B5:D5)", bold)?;
+
+    worksheet.write_with_format(0, 5, "Apr", bold)?;
+    worksheet.write(1, 5, 25)?;
+    worksheet.write(2, 5, 50)?;
+    worksheet.write(3, 5, 15)?;
+    worksheet.write(4, 5, 35)?;
+
+    worksheet.write_with_format(0, 6, "May", bold)?;
+    worksheet.write(1, 6, 65)?;
+    worksheet.write(2, 6, 50)?;
+    worksheet.write(3, 6, 75)?;
+    worksheet.write(4, 6, 70)?;
+
+    worksheet.write_with_format(0, 7, "Jun", bold)?;
+    worksheet.write(1, 7, 80)?;
+    worksheet.write(2, 7, 50)?;
+    worksheet.write(3, 7, 90)?;
+    worksheet.write(4, 7, 50)?;
+
+    worksheet.write_with_format(0, 8, "Q2 Total", bold)?;
+    worksheet.write_formula_with_format(1, 8, "=SUBTOTAL(9,F2:H2)", bold)?;
+    worksheet.write_formula_with_format(2, 8, "=SUBTOTAL(9,F3:H3)", bold)?;
+    worksheet.write_formula_with_format(3, 8, "=SUBTOTAL(9,F4:H4)", bold)?;
+    worksheet.write_formula_with_format(4, 8, "=SUBTOTAL(9,F5:H5)", bold)?;
+
+    worksheet.write_with_format(0, 9, "H1 Total", bold)?;
+    worksheet.write_formula_with_format(1, 9, "=SUBTOTAL(9,B2:I2)", bold)?;
+    worksheet.write_formula_with_format(2, 9, "=SUBTOTAL(9,B3:I3)", bold)?;
+    worksheet.write_formula_with_format(3, 9, "=SUBTOTAL(9,B4:I4)", bold)?;
+    worksheet.write_formula_with_format(4, 9, "=SUBTOTAL(9,B5:I5)", bold)?;
+
+    // Autofit the columns for clarity.
+    worksheet.autofit();
+
+    worksheet.write_with_format(6, 0, description, bold)?;
+
+    Ok(())
+}