Added docs for diagonal cell borders.

Issue #304

dev/release/fix_example_docs.pl

@@ -40,6 +40,7 @@ my @examples = (
     [ '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' ],
+    [ 'diagonal_border.c',      'Example of how to set a worksheet cell diagonal border.' ],
     [ 'hide_sheet.c',           'Example of hiding a worksheet' ],
     [ 'doc_properties.c',       'Example of setting workbook doc properties' ],
     [ 'doc_custom_properties.c','Example of setting custom doc properties' ],

docs/src/examples.dox

@@ -339,7 +339,7 @@ Example of adding data validations to a worksheet.
 </tr>
 </table>
 
-A simple example of how to add a conditional format a 
+A simple example of how to add a conditional format a
 libxlsxwriter file. Conditional formatting allows you to apply
 a format to a cell or a range of cells based on certain criteria.
 
@@ -473,7 +473,7 @@ mainly on collapsed outlines.
 <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>
+  <td align="right">@ref diagonal_border.c "diagonal_border.c &gt;&gt;"</td>
 </tr>
 </table>
 
@@ -484,11 +484,27 @@ Example of how to set Excel worksheet tab colors.
 
 
 
-@example hide_sheet.c
+@example diagonal_border.c
 
 <table  width="600">
 <tr>
   <td>@ref tab_colors.c "&lt;&lt; tab_colors.c"</td>
+  <td align="right">@ref hide_sheet.c "hide_sheet.c &gt;&gt;"</td>
+</tr>
+</table>
+
+Example of how to set a worksheet cell diagonal border.
+
+@image html diagonal_border.png
+
+
+
+
+@example hide_sheet.c
+
+<table  width="600">
+<tr>
+  <td>@ref diagonal_border.c "&lt;&lt; diagonal_border.c"</td>
   <td align="right">@ref doc_properties.c "doc_properties.c &gt;&gt;"</td>
 </tr>
 </table>

docs/src/examples.txt

@@ -150,7 +150,7 @@ Example of adding data validations to a worksheet.
 ##############################################################
 @example conditional_format1.c
 
-A simple example of how to add a conditional format a 
+A simple example of how to add a conditional format a
 libxlsxwriter file. Conditional formatting allows you to apply
 a format to a cell or a range of cells based on certain criteria.
 
@@ -220,6 +220,13 @@ Example of how to set Excel worksheet tab colors.
 
 @image html tab_colors.png
 
+##############################################################
+@example diagonal_border.c
+
+Example of how to set a worksheet cell diagonal border.
+
+@image html diagonal_border.png
+
 ##############################################################
 @example hide_sheet.c
 

examples/diagonal_border.c

@@ -0,0 +1,40 @@
+/*
+ * A simple formatting example that demonstrates how to add diagonal
+ * cell borders using the libxlsxwriter library.
+ *
+ * Copyright 2014-2020, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    /* Create a new workbook and add a worksheet. */
+    lxw_workbook  *workbook  = workbook_new("diagonal_border.xlsx");
+    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
+
+    /* Add some diagonal border formats. */
+    lxw_format *format1 = workbook_add_format(workbook);
+    format_set_diag_type(  format1, LXW_DIAGONAL_BORDER_UP);
+
+    lxw_format *format2 = workbook_add_format(workbook);
+    format_set_diag_type(  format2, LXW_DIAGONAL_BORDER_DOWN);
+
+    lxw_format *format3 = workbook_add_format(workbook);
+    format_set_diag_type(  format3, LXW_DIAGONAL_BORDER_UP_DOWN);
+
+    lxw_format *format4 = workbook_add_format(workbook);
+    format_set_diag_type(  format4, LXW_DIAGONAL_BORDER_UP_DOWN);
+    format_set_diag_border(format4, LXW_BORDER_HAIR);
+    format_set_diag_color( format4, LXW_COLOR_RED);
+
+    worksheet_write_string(worksheet, CELL("B3"),  "Text", format1);
+    worksheet_write_string(worksheet, CELL("B6"),  "Text", format2);
+    worksheet_write_string(worksheet, CELL("B9"),  "Text", format3);
+    worksheet_write_string(worksheet, CELL("B12"), "Text", format4);
+
+    workbook_close(workbook);
+
+    return 0;
+}

include/xlsxwriter/format.h

@@ -159,9 +159,19 @@ enum lxw_format_alignments {
     LXW_ALIGN_VERTICAL_DISTRIBUTED
 };
 
+/**
+ * Diagonal border types.
+ *
+ */
 enum lxw_format_diagonal_types {
+
+    /** Cell diagonal border from bottom left to top right. */
     LXW_DIAGONAL_BORDER_UP = 1,
+
+    /** Cell diagonal border from top left to bottom right. */
     LXW_DIAGONAL_BORDER_DOWN,
+
+    /** Cell diagonal border in both directions. */
     LXW_DIAGONAL_BORDER_UP_DOWN
 };
 
@@ -1198,9 +1208,76 @@ void format_set_left_color(lxw_format *format, lxw_color_t color);
  */
 void format_set_right_color(lxw_format *format, lxw_color_t color);
 
-void format_set_diag_type(lxw_format *format, uint8_t value);
+/**
+ * @brief Set the diagonal cell border type.
+ *
+ * @param format Pointer to a Format instance.
+ * @param type   The #lxw_format_diagonal_types diagonal border type.
+ *
+ * Set the diagonal cell border type:
+ *
+ * @code
+ *     lxw_format *format1 = workbook_add_format(workbook);
+ *     format_set_diag_type(  format1, LXW_DIAGONAL_BORDER_UP);
+ *
+ *     lxw_format *format2 = workbook_add_format(workbook);
+ *     format_set_diag_type(  format2, LXW_DIAGONAL_BORDER_DOWN);
+ *
+ *     lxw_format *format3 = workbook_add_format(workbook);
+ *     format_set_diag_type(  format3, LXW_DIAGONAL_BORDER_UP_DOWN);
+ *
+ *     lxw_format *format4 = workbook_add_format(workbook);
+ *     format_set_diag_type(  format4, LXW_DIAGONAL_BORDER_UP_DOWN);
+ *     format_set_diag_border(format4, LXW_BORDER_HAIR);
+ *     format_set_diag_color( format4, LXW_COLOR_RED);
+ *
+ *     worksheet_write_string(worksheet, CELL("B3"),  "Text", format1);
+ *     worksheet_write_string(worksheet, CELL("B6"),  "Text", format2);
+ *     worksheet_write_string(worksheet, CELL("B9"),  "Text", format3);
+ *     worksheet_write_string(worksheet, CELL("B12"), "Text", format4);
+ * @endcode
+ *
+ * @image html diagonal_border.png
+ *
+ * The allowable border types are defined in #lxw_format_diagonal_types:
+ *
+ * - #LXW_DIAGONAL_BORDER_UP: Cell diagonal border from bottom left to top
+ *   right.
+ *
+ * - #LXW_DIAGONAL_BORDER_DOWN: Cell diagonal border from top left to bottom
+ *   right.
+ *
+ * - #LXW_DIAGONAL_BORDER_UP_DOWN: Cell diagonal border from top left to
+ *   bottom right. A combination of the 2 previous types.
+ *
+ * If the border style isn't specified with `format_set_diag_border()` then it
+ * will default to #LXW_BORDER_THIN.
+ */
+void format_set_diag_type(lxw_format *format, uint8_t type);
+
+/**
+ * @brief Set the diagonal cell border style.
+ *
+ * @param format Pointer to a Format instance.
+ * @param style  The #lxw_format_borders style.
+ *
+ * Set the diagonal border style. This should be a #lxw_format_borders value.
+ * See the example above.
+ *
+ */
+void format_set_diag_border(lxw_format *format, uint8_t style);
+
+/**
+ * @brief Set the diagonal cell border color.
+ *
+ * @param format Pointer to a Format instance.
+ * @param color  The cell diagonal border color.
+ *
+ * Set the diagonal border color. The color should be an RGB integer value,
+ * see @ref working_with_colors and the above example.
+ */
 void format_set_diag_color(lxw_format *format, lxw_color_t color);
-void format_set_diag_border(lxw_format *format, uint8_t value);
+
 void format_set_font_outline(lxw_format *format);
 void format_set_font_shadow(lxw_format *format);
 void format_set_font_family(lxw_format *format, uint8_t value);

src/styles.c

@@ -846,7 +846,7 @@ _write_border(lxw_styles *self, lxw_format *format, uint8_t is_dxf)
 
     /* Ensure that a default diag border is set if the diag type is set. */
     if (format->diag_type && !format->diag_border) {
-        format->diag_border = 1;
+        format->diag_border = LXW_BORDER_THIN;
     }
 
     /* Write the start border tag. */