diff --git a/dev/release/fix_example_docs.pl b/dev/release/fix_example_docs.pl index 9adb4e8c..7259b37e 100644 --- a/dev/release/fix_example_docs.pl +++ b/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; } diff --git a/docs/images/panes.png b/docs/images/panes.png new file mode 100644 index 00000000..be238340 Binary files /dev/null and b/docs/images/panes.png differ diff --git a/docs/src/examples.dox b/docs/src/examples.dox index de7105e0..835658ea 100644 --- a/docs/src/examples.dox +++ b/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 + + */ diff --git a/examples/panes.c b/examples/panes.c new file mode 100644 index 00000000..e5e1e962 --- /dev/null +++ b/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; +} diff --git a/include/xlsxwriter/worksheet.h b/include/xlsxwriter/worksheet.h index 73e9c1bc..d579906a 100644 --- a/include/xlsxwriter/worksheet.h +++ b/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);