Added panes documentation and example.

dev/release/fix_example_docs.pl

@@ -30,6 +30,7 @@ my @examples = (
     [ 'autofilter.c',        'An example of a worksheet autofilter' ],
     [ 'headers_footers.c',   'Example of adding worksheet headers/footers' ],
     [ 'defined_name.c',      'Example of how to create defined names' ],
+    [ 'panes.c',             'Example of how to create worksheet panes' ],
 );
 
 # Convert the array refs to a hash for lookups.
@@ -56,7 +57,7 @@ while ( my $line = <> ) {
 
         # Warn if there are any new/unkown items.
         if ( !exists $examples{$example} ) {
-            warn "Unknown example: $example\n";
+            warn "$0 Unknown example: $example\n";
         }
         next;
     }

docs/src/examples.dox

@@ -143,7 +143,15 @@ Example of how to create defined names (named ranges) using libxlsxwriter.
 Defined names are used to define descriptive names to represent a value, a
 single cell or a range of cells in a workbook or worksheet.
 
+Next example: @ref panes.c
 @image html defined_name.png
 
 
+@example panes.c
+An example of how to create panes in a worksheet, both “freeze” panes and “split” panes.
+
+Back to @ref examples
+@image html panes.png
+
+
 */

examples/panes.c

@@ -0,0 +1,129 @@
+/*
+ * A simple example using the libxlsxwriter library to create worksheets with
+ * panes.
+ *
+ * Copyright 2014-2015, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    int row;
+    int col;
+
+    /* Create a new workbook and add some worksheets. */
+    lxw_workbook  *workbook   = new_workbook("panes.xlsx");
+
+    lxw_worksheet *worksheet1 = workbook_add_worksheet(workbook, "Panes 1");
+    lxw_worksheet *worksheet2 = workbook_add_worksheet(workbook, "Panes 2");
+    lxw_worksheet *worksheet3 = workbook_add_worksheet(workbook, "Panes 3");
+    lxw_worksheet *worksheet4 = workbook_add_worksheet(workbook, "Panes 4");
+
+
+    /* Set up some formatting and text to highlight the panes. */
+    lxw_format *header = workbook_add_format(workbook);
+    format_set_align(header, LXW_ALIGN_CENTER);
+    format_set_align(header, LXW_ALIGN_VERTICAL_CENTER);
+    format_set_fg_color(header, 0xD7E4BC);
+    format_set_bold(header);
+    format_set_border(header, LXW_BORDER_THIN);
+
+    lxw_format *center = workbook_add_format(workbook);
+    format_set_align(center, LXW_ALIGN_CENTER);
+
+
+    /*
+     * Example 1. Freeze pane on the top row.
+     */
+    worksheet_freeze_panes(worksheet1, 1, 0);
+
+    /* Some sheet formatting. */
+    worksheet_set_column(worksheet1, 0, 8, 16, NULL, NULL);
+    worksheet_set_row(worksheet1, 0, 20, NULL, NULL);
+
+    /* Some worksheet text to demonstrate scrolling. */
+    for (col = 0; col < 9; col++) {
+        worksheet_write_string(worksheet1, 0, col, "Scroll down", header);
+    }
+
+    for (row = 1; row < 100; row++) {
+        for (col = 0; col < 9; col++) {
+            worksheet_write_number(worksheet1, row, col, row + 1, center);
+        }
+    }
+
+
+    /*
+     * Example 2. Freeze pane on the left column.
+     */
+    worksheet_freeze_panes(worksheet2, 0, 1);
+
+    /* Some sheet formatting. */
+    worksheet_set_column(worksheet2, 0, 0, 16, NULL, NULL);
+
+    /* Some worksheet text to demonstrate scrolling. */
+    for (row = 0; row < 50; row++) {
+        worksheet_write_string(worksheet2, row, 0, "Scroll right", header);
+
+        for (col = 1; col < 26; col++) {
+            worksheet_write_number(worksheet2, row, col, col, center);
+        }
+    }
+
+
+    /*
+     * Example 3. Freeze pane on the top row and left column.
+     */
+    worksheet_freeze_panes(worksheet3, 1, 1);
+
+
+    /* Some sheet formatting. */
+    worksheet_set_column(worksheet3, 0, 25, 16, NULL, NULL);
+    worksheet_set_row(worksheet3, 0, 20, NULL, NULL);
+    worksheet_write_string(worksheet3, 0, 0, "", header);
+
+
+    /* Some worksheet text to demonstrate scrolling. */
+    for (col = 1; col < 26; col++) {
+        worksheet_write_string(worksheet3, 0, col, "Scroll down", header);
+    }
+
+    for (row = 1; row < 50; row++) {
+        worksheet_write_string(worksheet3, row, 0, "Scroll right", header);
+
+        for (col = 1; col < 26; col++) {
+            worksheet_write_number(worksheet3, row, col, col, center);
+        }
+    }
+
+
+    /*
+     * Example 4. Split pane on the top row and left column.
+     *
+     * The divisions must be specified in terms of row and column dimensions.
+     * The default row height is 15 and the default column width is 8.43
+     */
+    worksheet_split_panes(worksheet4, 15, 8.43);
+
+    /* Some sheet formatting. */
+
+    /* Some worksheet text to demonstrate scrolling. */
+    for (col = 1; col < 26; col++) {
+        worksheet_write_string(worksheet4, 0, col, "Scroll", center);
+    }
+
+    for (row = 1; row < 50; row++) {
+        worksheet_write_string(worksheet4, row, 0, "Scroll", center);
+
+        for (col = 1; col < 26; col++) {
+            worksheet_write_number(worksheet4, row, col, col, center);
+        }
+    }
+
+
+    workbook_close(workbook);
+
+    return 0;
+}

include/xlsxwriter/worksheet.h

@@ -1181,20 +1181,79 @@ void worksheet_activate(lxw_worksheet *worksheet);
   */
 void worksheet_select(lxw_worksheet *worksheet);
 
-/* TODO */
+/**
+ * @brief Split and freeze a worksheet into panes.
+ *
+ * @param worksheet Pointer to a lxw_worksheet instance to be updated.
+ * @param row       The cell row (zero indexed).
+ * @param col       The cell column (zero indexed).
+ *
+ * The `%worksheet_freeze_panes()` method can be used to divide a worksheet
+ * into horizontal or vertical regions known as panes and to "freeze" these
+ * panes so that the splitter bars are not visible.
+ *
+ * The parameters `row` and `col` are used to specify the location of the
+ * split. It should be noted that the split is specified at the top or left of
+ * a cell and that the method uses zero based indexing. Therefore to freeze
+ * the first row of a worksheet it is necessary to specify the split at row 2
+ * (which is 1 as the zero-based index).
+ *
+ * You can set one of the `row` and `col` parameters as zero if you do not
+ * want either a vertical or horizontal split.
+ *
+ * Examples:
+ *
+ * @code
+ *     worksheet_freeze_panes(worksheet1, 1, 0); // Freeze the first row.
+ *     worksheet_freeze_panes(worksheet2, 0, 1); // Freeze the first column.
+ *     worksheet_freeze_panes(worksheet3, 1, 1); // Freeze first row/column.
+ *
+ * @endcode
+ *
+ */
 void worksheet_freeze_panes(lxw_worksheet *worksheet,
-                            lxw_row_t first_row, lxw_col_t first_col);
-/* TODO */
+                            lxw_row_t row, lxw_col_t col);
+/**
+ * @brief Split a worksheet into panes.
+ *
+ * @param worksheet  Pointer to a lxw_worksheet instance to be updated.
+ * @param vertical   The position for the vertical split.
+ * @param horizontal The position for the horizontal split.
+ *
+ * The `%worksheet_split_panes()` method can be used to divide a worksheet
+ * into horizontal or vertical regions known as panes. This method is
+ * different from the `worksheet_freeze_panes()` method in that the splits
+ * between the panes will be visible to the user and each pane will have its
+ * own scroll bars.
+ *
+ * The parameters `vertical` and `horizontal` are used to specify the vertical
+ * and horizontal position of the split. The units for `vertical` and
+ * `horizontal` are the same as those used by Excel to specify row height and
+ * column width. However, the vertical and horizontal units are different from
+ * each other. Therefore you must specify the `vertical` and `horizontal`
+ * parameters in terms of the row heights and column widths that you have set
+ * or the default values which are 15 for a row and 8.43 for a column.
+ *
+ * Examples:
+ *
+ * @code
+ *     worksheet_split_panes(worksheet1, 15, 0);    // First row.
+ *     worksheet_split_panes(worksheet2, 0,  8.43); // First column.
+ *     worksheet_split_panes(worksheet3, 15, 8.43); // First row and column.
+ *
+ * @endcode
+ *
+ */
 void worksheet_split_panes(lxw_worksheet *worksheet,
                            double vertical, double horizontal);
 
-/* Infrequent options. Undocumented for now. */
+/* worksheet_freeze_panes() with infrequent options. Undocumented for now. */
 void worksheet_freeze_panes_opt(lxw_worksheet *worksheet,
                                 lxw_row_t first_row, lxw_col_t first_col,
                                 lxw_row_t top_row, lxw_col_t left_col,
                                 uint8_t type);
 
-/* Infrequent options. Undocumented for now. */
+/* worksheet_split_panes() with infrequent options. Undocumented for now. */
 void worksheet_split_panes_opt(lxw_worksheet *worksheet,
                                double vertical, double horizontal,
                                lxw_row_t top_row, lxw_col_t left_col);