Add docs for data validation

Readme.md

@@ -20,6 +20,7 @@ It supports features such as:
 - Defined names.
 - Autofilters.
 - Charts.
+- Data validation and drop down lists.
 - Worksheet PNG/JPEG images.
 - Memory optimization mode for writing large files.
 - Source code available on [GitHub](https://github.com/jmcnamara/libxlsxwriter).

dev/release/fix_example_docs.pl

@@ -28,6 +28,7 @@ my @examples = (
     [ 'constant_memory.c',      'Write a large file with constant memory usage' ],
     [ 'merge_range.c',          'Create a merged range of cells' ],
     [ 'autofilter.c',           'An example of a worksheet autofilter' ],
+    [ 'data_validate.c',        'Examples of worksheet data validation and drop down lists' ],
     [ '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' ],

docs/Doxyfile

@@ -754,29 +754,30 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = src/mainpage.dox                  \
+INPUT                  = src/mainpage.dox                     \
-                         src/introduction.dox              \
+                         src/introduction.dox                 \
-                         src/getting_started.dox           \
+                         src/getting_started.dox              \
-                         src/tutorial01.dox                \
+                         src/tutorial01.dox                   \
-                         src/tutorial02.dox                \
+                         src/tutorial02.dox                   \
-                         src/tutorial03.dox                \
+                         src/tutorial03.dox                   \
-                         ../include/xlsxwriter/workbook.h  \
+                         ../include/xlsxwriter/workbook.h     \
-                         ../include/xlsxwriter/worksheet.h \
+                         ../include/xlsxwriter/worksheet.h    \
-                         ../include/xlsxwriter/format.h    \
+                         ../include/xlsxwriter/format.h       \
-                         ../include/xlsxwriter/chart.h     \
+                         ../include/xlsxwriter/chart.h        \
-                         ../include/xlsxwriter/utility.h   \
+                         ../include/xlsxwriter/utility.h      \
-                         ../include/xlsxwriter/common.h    \
+                         ../include/xlsxwriter/common.h       \
-                         src/working_with_formats.dox      \
+                         src/working_with_formats.dox         \
-                         src/working_with_colors.dox       \
+                         src/working_with_colors.dox          \
-                         src/working_with_dates.dox        \
+                         src/working_with_dates.dox           \
-                         src/working_with_charts.dox       \
+                         src/working_with_charts.dox          \
-                         src/working_with_memory.dox       \
+                         src/working_with_data_validation.dox \
-                         src/examples.dox                  \
+                         src/working_with_memory.dox          \
-                         src/running_the_tests.dox         \
+                         src/examples.dox                     \
-                         src/faq.dox                       \
+                         src/running_the_tests.dox            \
-                         src/bugs.dox                      \
+                         src/faq.dox                          \
-                         src/author.dox                    \
+                         src/bugs.dox                         \
-                         ../License.txt                    \
+                         src/author.dox                       \
+                         ../License.txt                       \
                          ../Changes.txt
 
 # This tag can be used to specify the character encoding of the source files

docs/src/examples.dox

@@ -270,7 +270,7 @@ Example of merging cells in a worksheet.
 <table  width="600">
 <tr>
   <td>@ref merge_range.c "&lt;&lt; merge_range.c"</td>
-  <td align="right">@ref images.c "images.c &gt;&gt;"</td>
+  <td align="right">@ref data_validate.c "data_validate.c &gt;&gt;"</td>
 </tr>
 </table>
 
@@ -281,11 +281,27 @@ Example of adding an autofilter to a worksheet.
 
 
 
-@example images.c
+@example data_validate.c
 
 <table  width="600">
 <tr>
   <td>@ref autofilter.c "&lt;&lt; autofilter.c"</td>
+  <td align="right">@ref images.c "images.c &gt;&gt;"</td>
+</tr>
+</table>
+
+Example of adding data validations to a worksheet.
+
+@image html data_validate4.png
+
+
+
+
+@example images.c
+
+<table  width="600">
+<tr>
+  <td>@ref data_validate.c "&lt;&lt; data_validate.c"</td>
   <td align="right">@ref headers_footers.c "headers_footers.c &gt;&gt;"</td>
 </tr>
 </table>

docs/src/examples.txt

@@ -125,6 +125,13 @@ Example of adding an autofilter to a worksheet.
 
 @image html autofilter.png
 
+##############################################################
+@example data_validate.c
+
+Example of adding data validations to a worksheet.
+
+@image html data_validate4.png
+
 ##############################################################
 @example images.c
 

docs/src/mainpage.dox

@@ -19,6 +19,7 @@ features such as:
 - Defined names.
 - Autofilters.
 - Charts.
+- Data validation and drop down lists.
 - Worksheet PNG/JPEG images.
 - Memory optimization mode for writing large files.
 - Source code available on [GitHub](https://github.com/jmcnamara/libxlsxwriter).
@@ -49,6 +50,7 @@ following sections for more information:
 - @ref working_with_colors
 - @ref working_with_dates
 - @ref working_with_charts
+- @ref working_with_data_validation
 - @ref working_with_memory
 
 - @ref examples

docs/src/working_with_data_validation.dox

@@ -0,0 +1,501 @@
+/**
+@page working_with_data_validation Working with Data Validation
+
+@tableofcontents
+
+
+Data validation is a feature of Excel which allows restrictions to be placed
+on the data that a user enters in a cell and to display associated help and
+warning messages. It can also be used to restrict input to values in a drop
+down list.
+
+A typical use case might be to restrict data in a cell to integer values in a
+certain range, to provide a help message to indicate the required value and to
+issue a warning if the input data doesn't meet the stated criteria. In
+`libxlsxwriter` this can be done as follows:
+
+@code
+
+   lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
+
+   data_validation->validate       = LXW_VALIDATION_TYPE_INTEGER;
+   data_validation->criteria       = LXW_VALIDATION_CRITERIA_BETWEEN;
+   data_validation->minimum_number = 1;
+   data_validation->maximum_number = 10;
+
+   worksheet_data_validation_cell(worksheet, CELL("B3"), data_validation);
+
+@endcode
+
+@image html data_validate1.png
+
+If the user inputs a value that doesn't match the specified criteria an error
+message is displayed:
+
+@image html data_validate4.png
+
+
+For more information on data validation see the Microsoft support article
+[Description and examples of data validation in Excel](http://support.microsoft.com/kb/211485).
+
+The following sections describe how to use the
+`worksheet_data_validation_cell()` and `worksheet_data_validation_range()`
+functions and the various options of #lxw_data_validation.
+
+
+@section ww_data_validate_functions The data validation functions
+
+
+The `worksheet_data_validation_cell()` and `worksheet_data_validation_range()`
+functions are used to construct an Excel data validation.
+
+The data validation can be applied to a single cell or a range of cells:
+
+@code
+   worksheet_data_validation_cell( worksheet, 2, 1,       data_validation);
+   worksheet_data_validation_range(worksheet, 2, 1, 4, 1, data_validation);
+
+   // Same as above using the CELL() and RANGE() macros.
+   worksheet_data_validation_cell( worksheet, CELL("B3"),     data_validation);
+   worksheet_data_validation_range(worksheet, RANGE("B3:B5"), data_validation);
+
+@endcode
+
+The lxw_data_validation struct used in these functions is explained below.
+
+
+@section ww_data_validate_struct The lxw_data_validation struct
+
+The lxw_data_validation struct is used to set the properties of a data
+validation. A typical usage would look something like this:
+
+@code
+    lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
+    data_validation->validate     = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria     = LXW_VALIDATION_CRITERIA_GREATER_THAN;
+    data_validation->value_number = 10;
+    data_validation->show_input   = LXW_VALIDATION_OFF;
+@endcode
+
+This example shows the main properties of lxw_data_validation and Excel data
+validations:
+
+- `validate`: The type of data to restrict the validation to. In this case it
+  is whole numbers.
+
+- `criteria`: The criteria by which the data will be evaluated. In this case
+  whether the input is greater than a value.
+
+- `value`: The value that the criteria applies to. This has several different
+  versions for different types of data. This could also be a `minimum` and
+  `maximum` value if the criteria used is a "BETWEEN" criteria. This is
+  explained in the @ref ww_data_validate_value section below.
+
+- Other options such as `show_input` or `input_message`. These parameters are
+  explained in the @ref ww_data_validate_options section.
+
+Note, in the examples in this document the `data_validation` variable is shown
+as dynamically allocated, however an address of a static or automatic variable
+could also be used. In these cases make sure that the struct members are
+initialized to zero before setting other parameters.
+
+@subsection ww_data_validate_validate validate
+
+The `validate` parameter is used to set the type of data that you wish to
+validate:
+
+@code
+    data_validation->validate = LXW_VALIDATION_TYPE_INTEGER;
+@endcode
+
+It is always required and it has no default value. In Excel the validate
+parameters are:
+
+- Whole
+- Decimal
+- List
+- Date
+- Time
+- Text Length
+- Custom
+- Any
+
+The equivalent parameters in libxlsxwriter are defined in
+#lxw_validation_types:
+
+ - #LXW_VALIDATION_TYPE_INTEGER: Restrict cell input to whole/integer numbers
+   only.
+
+ - #LXW_VALIDATION_TYPE_INTEGER_FORMULA: Restrict cell input to whole/integer
+   numbers only, using a cell reference.
+
+ - #LXW_VALIDATION_TYPE_DECIMAL: Restrict cell input to decimal numbers only.
+
+ - #LXW_VALIDATION_TYPE_DECIMAL_FORMULA: Restrict cell input to decimal
+   numbers only, using a cell reference.
+
+ - #LXW_VALIDATION_TYPE_LIST: Restrict cell input to a list of strings in a
+   dropdown.
+
+ - #LXW_VALIDATION_TYPE_LIST_FORMULA: Restrict cell input to a list of strings
+   in a dropdown, using a cell range.
+
+ - #LXW_VALIDATION_TYPE_DATE: Restrict cell input to date values only, using a
+   lxw_datetime type.
+
+ - #LXW_VALIDATION_TYPE_DATE_FORMULA: Restrict cell input to date values only,
+   using a cell reference.
+
+ - #LXW_VALIDATION_TYPE_TIME: Restrict cell input to time values only, using a
+   lxw_datetime type.
+
+ - #LXW_VALIDATION_TYPE_TIME_FORMULA: Restrict cell input to time values only,
+   using a cell reference.
+
+ - #LXW_VALIDATION_TYPE_LENGTH: Restrict cell input to strings of defined
+   length, using a cell reference.
+
+ - #LXW_VALIDATION_TYPE_LENGTH_FORMULA: Restrict cell input to strings of
+   defined length, using a cell reference.
+
+ - #LXW_VALIDATION_TYPE_CUSTOM_FORMULA: Restrict cell to input controlled by a
+   custom formula that returns `TRUE/FALSE`.
+
+ - #LXW_VALIDATION_TYPE_ANY: Allow any type of input. Mainly only useful for
+   pop-up messages.
+
+
+
+@subsection ww_data_validate_criteria criteria
+
+The `criteria` parameter is used to set the criteria by which the data in the
+cell is validated. It is almost always required except for the `list`,
+`custom` and `any` validate options. It has no default value:
+
+@code
+    data_validation->criteria = LXW_VALIDATION_CRITERIA_GREATER_THAN;
+@endcode
+
+
+Allowable values are defined in #lxw_validation_criteria:
+
+- #LXW_VALIDATION_CRITERIA_BETWEEN: Select data between two values.
+
+- #LXW_VALIDATION_CRITERIA_NOT_BETWEEN: Select data that is not between two values.
+
+- #LXW_VALIDATION_CRITERIA_EQUAL_TO: Select data equal to a value.
+
+- #LXW_VALIDATION_CRITERIA_NOT_EQUAL_TO: Select data not equal to a value.
+
+- #LXW_VALIDATION_CRITERIA_GREATER_THAN: Select data greater than a value.
+
+- #LXW_VALIDATION_CRITERIA_LESS_THAN: Select data less than a value.
+
+- #LXW_VALIDATION_CRITERIA_GREATER_THAN_OR_EQUAL_TO: Select data greater than or equal to a value.
+
+- #LXW_VALIDATION_CRITERIA_LESS_THAN_OR_EQUAL_TO: Select data less than or equal to a value.
+
+
+The `list`, `custom` and `any` validate options don't require a
+`criteria`. If you specify one it will be ignored.
+
+
+@subsection ww_data_validate_value value, minimum, maximum
+
+The `value` parameters are used to set the limiting value to which the
+`criteria` is applied. It is always required and it has no default
+value. There are different types of `value` parameter associated with
+different types of data. They are:
+
+`value_number`:
+
+The `value_number` parameter is used to set the limiting value
+to which the criteria is applied using a whole or decimal number. It is
+typically used with #LXW_VALIDATION_TYPE_INTEGER and
+#LXW_VALIDATION_TYPE_DECIMAL and #LXW_VALIDATION_TYPE_LENGTH.
+
+@code
+    data_validation->validate     = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria     = LXW_VALIDATION_CRITERIA_GREATER_THAN;
+    data_validation->value_number = 0;
+
+    data_validation->validate     = LXW_VALIDATION_TYPE_DECIMAL;
+    data_validation->criteria     = LXW_VALIDATION_CRITERIA_GREATER_THAN;
+    data_validation->value_number = 10.5;
+
+    data_validation->validate     = LXW_VALIDATION_TYPE_LENGTH;
+    data_validation->criteria     = LXW_VALIDATION_CRITERIA_GREATER_THAN;
+    data_validation->value_number = 3;
+@endcode
+
+
+`value_formula`:
+
+The `value_formula` parameter is used to set the limiting value to which the
+criteria is applied using a cell reference. It is valid for any of the
+#lxw_validation_types types that end in `_FORMULA`:
+
+@code
+    data_validation->validate      = LXW_VALIDATION_TYPE_INTEGER_FORMULA;
+    data_validation->criteria      = LXW_VALIDATION_CRITERIA_GREATER_THAN;
+    data_validation->value_formula = "=E3";
+
+    data_validation->validate      = LXW_VALIDATION_TYPE_TIME_FORMULA;
+    data_validation->criteria      = LXW_VALIDATION_CRITERIA_EQUAL;
+    data_validation->value_formula = "=H1";
+
+    data_validation->validate      = LXW_VALIDATION_TYPE_LIST_FORMULA;
+    data_validation->value_formula = "=$E$4:$G$4";
+@endcode
+
+`value_list`:
+
+The `value_list` parameter is used to set a list of strings for a drop down
+list.  The list should be a `NULL` terminated array of char* strings:
+
+@code
+    char *list[] = {"open", "high", "close", NULL};
+
+    data_validation->validate   = LXW_VALIDATION_TYPE_LIST;
+    data_validation->value_list = list;
+@endcode
+
+Note, when using the #LXW_VALIDATION_TYPE_LIST validation with a list of
+strings, like in the last example above, Excel stores the strings internally
+as a Comma Separated Variable string. The total length for this string,
+including commas, cannot exceed the Excel limit of 255 characters. For longer
+sets of data you should use a range reference like the previous example above.
+
+`value_datetime`:
+
+The `value_datetime` parameter is used to set the limiting value to which the
+#LXW_VALIDATION_TYPE_DATE or #LXW_VALIDATION_TYPE_TIME criteria is applied
+using a #lxw_datetime struct:
+
+@code
+    lxw_datetime datetime1          = {2017,  9,  24,  0,  0, 0};
+    lxw_datetime datetime2          = {   0,  0,   0, 12, 30, 0};
+
+    data_validation->validate       = LXW_VALIDATION_TYPE_DATE;
+    data_validation->criteria       = LXW_VALIDATION_CRITERIA_EQUAL;
+    data_validation->value_datetime = datetime1;
+
+    data_validation->validate       = LXW_VALIDATION_TYPE_TIME;
+    data_validation->criteria       = LXW_VALIDATION_CRITERIA_EQUAL;
+    data_validation->value_datetime = datetime2;
+@endcode
+
+The `minimum` and `maximum` parameters are used to set the lower and upper
+limiting values when the `criteria` is either #LXW_VALIDATION_CRITERIA_BETWEEN
+or #LXW_VALIDATION_CRITERIA_NOT_BETWEEN. The parameters are:
+
+- `minimum_number`
+- `minimum_formula`
+- `minimum_datetime`
+- `maximum_number`
+- `maximum_formula`
+- `maximum_datetime`
+
+They are similar to the `value` parameters described above. For example:
+
+@code
+    data_validation->validate         = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria         = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_number   = 1;
+    data_validation->maximum_number   = 10;
+
+    data_validation->validate         = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria         = LXW_VALIDATION_CRITERIA_NOT_BETWEEN;
+    data_validation->minimum_formula  = "=E3";
+    data_validation->maximum_formula  = "=F3";
+
+    data_validation->validate         = LXW_VALIDATION_TYPE_DATE;
+    data_validation->criteria         = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_datetime = datetime1;
+    data_validation->maximum_datetime = datetime2;
+@endcode
+
+@section ww_data_validate_options Data validation options
+
+
+@subsection ww_data_validate_ignore_blank ignore_blank
+
+
+The `ignore_blank` parameter is used to toggle on and off the 'Ignore blank'
+option in the Excel data validation dialog. When the option is on the data
+validation is not applied to blank data in the cell. It is on by default:
+
+@code
+    data_validation->validate       = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria       = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_number = 1;
+    data_validation->maximum_number = 10;
+    data_validation->ignore_blank   = LXW_VALIDATION_OFF;
+@endcode
+
+
+@subsection ww_data_validate_dropdown dropdown
+
+The `dropdown` parameter is used to toggle on and off the 'In-cell dropdown'
+option in the Excel data validation dialog. When the option is on a dropdown
+list will be shown for `list` validations. It is on by default.
+
+@code
+    data_validation->validate   = LXW_VALIDATION_TYPE_LIST;
+    data_validation->value_list = list;
+    data_validation->dropdown   = LXW_VALIDATION_OFF;
+@endcode
+
+
+@subsection ww_data_validate_input_title input_title
+
+The `input_title` parameter is used to set the title of the input message that
+is displayed when a cell is entered. It has no default value and is only
+displayed if the input message is also displayed. See the `input_message`
+parameter below.
+
+The maximum title length is 32 characters.
+
+
+@subsection ww_data_validate_input_message input_message
+
+The `input_message` parameter is used to set the input message that is
+displayed when a cell is entered. It has no default value:
+
+@code
+    data_validation->validate       = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria       = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_number = 1;
+    data_validation->maximum_number = 100;
+    data_validation->input_title    = "Enter an integer:";
+    data_validation->input_message  = "between 1 and 100";
+@endcode
+
+The input message generated from the above example is:
+
+@image html data_validate3.png
+
+The message can be split over several lines using newlines. The maximum message
+length is 255 characters.
+
+
+@subsection ww_data_validate_show_input show_input
+
+The `show_input` parameter is used to toggle on and off the 'Show input
+message when cell is selected' option in the Excel data validation dialog.
+When the option is off an input message is not displayed even if it has been
+set using `input_message`. It is on by default.
+
+
+@subsection ww_data_validate_error_title error_title
+
+The `error_title` parameter is used to set the title of the error message
+that is displayed when the data validation criteria is not met. The default
+error title is 'Microsoft Excel'. The maximum title length is 32 characters.
+
+
+@subsection ww_data_validate_error_message error_message
+
+The `error_message` parameter is used to set the error message that is
+displayed when a cell is entered. The default error message is "The value you
+entered is not valid. A user has restricted values that can be entered into
+the cell". A non-default error message can be displayed as follows:
+
+@code
+    data_validation->validate       = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria       = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_number = 1;
+    data_validation->maximum_number = 100;
+    data_validation->input_title    = "Enter an integer:";
+    data_validation->input_message  = "between 1 and 100";
+    data_validation->error_title    = "Input value is not valid!";
+    data_validation->error_message  = "It should be an integer between 1 and 100";
+@endcode
+
+Which give the following message:
+
+@image html data_validate2.png
+
+The message can be split over several lines using newlines. The maximum message
+length is 255 characters.
+
+
+@subsection ww_data_validate_error_type error_type
+
+The `error_type` parameter is used to specify the type of error dialog that is
+displayed. There are 3 #lxw_validation_error_types options:
+
+- #LXW_VALIDATION_ERROR_TYPE_STOP, the default.
+- #LXW_VALIDATION_ERROR_TYPE_WARNING
+- #LXW_VALIDATION_ERROR_TYPE_INFORMATION
+
+@subsection ww_data_validate_show_error show_error
+
+The `show_error` parameter is used to toggle on and off the 'Show error alert
+after invalid data is entered' option in the Excel data validation dialog.
+When the option is off an error message is not displayed even if it has been
+set using `error_message`. It is on by default.
+
+@section ww_data_validate_examples Examples
+
+@code
+    // Restrict input to an integer between 1 and 10.
+    data_validation->validate         = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria         = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_number   = 1;
+    data_validation->maximum_number   = 10;
+
+    // Restrict input to an integer not between 1 and 10 (using cell references).
+    data_validation->validate         = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria         = LXW_VALIDATION_CRITERIA_NOT_BETWEEN;
+    data_validation->minimum_formula  = "=E3";
+    data_validation->maximum_formula  = "=F3";
+
+    // Restrict input to a decimal between 0.1 and 0.5.
+    data_validation->validate         = LXW_VALIDATION_TYPE_DECIMAL;
+    data_validation->criteria         = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_number   = 0.1;
+    data_validation->maximum_number   = 0.5;
+
+    // Select a value from a drop down list.
+    char *list[]                      = {"open", "high", "close", NULL};
+
+    data_validation->validate         = LXW_VALIDATION_TYPE_LIST;
+    data_validation->value_list       = list;
+
+    // Select a value from a drop down list (using a cell range).
+    data_validation->validate         = LXW_VALIDATION_TYPE_LIST;
+    data_validation->value_formula    = "=$E$4:$G$4";
+
+    // Restrict input to a date between 1/1/2008 and 12/12/2008.
+    lxw_datetime datetime1            = {2008,  1,  1, 0, 0, 0};
+    lxw_datetime datetime2            = {2008, 12, 12, 0, 0, 0};
+
+    data_validation->validate         = LXW_VALIDATION_TYPE_DATE;
+    data_validation->criteria         = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_datetime = datetime1;
+    data_validation->maximum_datetime = datetime2;
+
+    // Restrict input to a string longer than 3 characters.
+    data_validation->validate         = LXW_VALIDATION_TYPE_LENGTH;
+    data_validation->criteria         = LXW_VALIDATION_CRITERIA_GREATER_THAN;
+    data_validation->value_number     = 3;
+
+    // Restrict input to a value if a formula is true.
+    data_validation->validate         = LXW_VALIDATION_TYPE_CUSTOM_FORMULA;
+    data_validation->value_formula    = "=AND(F5=50,G5=60)";
+
+    // Display a custom info message when integer isn't between 1 and 100.
+    data_validation->validate         = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria         = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_number   = 1;
+    data_validation->maximum_number   = 100;
+    data_validation->input_title      = "Enter an integer:";
+    data_validation->input_message    = "between 1 and 100";
+    data_validation->error_title      = "Input value is not valid!";
+    data_validation->error_message    = "It should be an integer between 1 and 100";
+@endcode
+
+For a full example see @ref data_validate.c.
+
+*/

examples/data_validate.c

@@ -0,0 +1,310 @@
+/*
+ * Examples of how to add data validation and dropdown lists using the
+ * libxlsxwriter library.
+ *
+ * Data validation is a feature of Excel which allows you to restrict the data
+ * that a user enters in a cell and to display help and warning messages. It
+ * also allows you to restrict input to values in a drop down list.
+ *
+ * Copyright 2014-2017, John McNamara, jmcnamara@cpan.org
+ */
+
+
+#include "xlsxwriter.h"
+
+/*
+ * Write some data to the worksheet.
+ */
+void write_worksheet_data(lxw_worksheet *worksheet, lxw_format *format) {
+
+
+    worksheet_write_string(worksheet, CELL("A1"),
+                           "Some examples of data validation in libxlsxwriter",
+                           format);
+    worksheet_write_string(worksheet, CELL("B1"), "Enter values in this column", format);
+    worksheet_write_string(worksheet, CELL("D1"), "Sample Data", format);
+
+    worksheet_write_string(worksheet, CELL("D3"), "Integers", NULL);
+    worksheet_write_number(worksheet, CELL("E3"), 1, NULL);
+    worksheet_write_number(worksheet, CELL("F3"), 10, NULL);
+
+    worksheet_write_string(worksheet, CELL("D4"), "List Data", NULL);
+    worksheet_write_string(worksheet, CELL("E4"), "open", NULL);
+    worksheet_write_string(worksheet, CELL("F4"), "high", NULL);
+    worksheet_write_string(worksheet, CELL("G4"), "close", NULL);
+
+    worksheet_write_string(worksheet,  CELL("D5"), "Formula", NULL);
+    worksheet_write_formula(worksheet, CELL("E5"), "=AND(F5=50,G5=60)", NULL);
+    worksheet_write_number(worksheet,  CELL("F5"), 50, NULL);
+    worksheet_write_number(worksheet,  CELL("G5"), 60, NULL);
+
+}
+
+/*
+ * Create a worksheet with data validations.
+ */
+int main() {
+
+    lxw_workbook        *workbook  = new_workbook("data_validate1.xlsx");
+    lxw_worksheet       *worksheet = workbook_add_worksheet(workbook, NULL);
+    lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
+
+    /* Add a format to use to highlight the header cells. */
+    lxw_format *format = workbook_add_format(workbook);
+    format_set_border(format, LXW_BORDER_THIN);
+    format_set_fg_color(format, 0xC6EFCE);
+    format_set_bold(format);
+    format_set_text_wrap(format);
+    format_set_align(format, LXW_ALIGN_VERTICAL_CENTER);
+    format_set_indent(format, 1);
+
+    /* Write some data for the validations. */
+    write_worksheet_data(worksheet, format);
+
+    /* Set up layout of the worksheet. */
+    worksheet_set_column(worksheet, 0, 0, 55, NULL);
+    worksheet_set_column(worksheet, 1, 1, 15, NULL);
+    worksheet_set_column(worksheet, 3, 3, 15, NULL);
+    worksheet_set_row(worksheet, 0, 36, NULL);
+
+
+    /*
+     * Example 1. Limiting input to an integer in a fixed range.
+     */
+    worksheet_write_string(worksheet,
+                           CELL("A3"),
+                           "Enter an integer between 1 and 10",
+                           NULL);
+
+    data_validation->validate       = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria       = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_number = 1;
+    data_validation->maximum_number = 10;
+
+    worksheet_data_validation_cell(worksheet, CELL("B3"), data_validation);
+
+
+    /*
+     * Example 2. Limiting input to an integer outside a fixed range.
+     */
+    worksheet_write_string(worksheet,
+                           CELL("A5"),
+                           "Enter an integer not between 1 and 10 (using cell references)",
+                           NULL);
+
+    data_validation->validate        = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria        = LXW_VALIDATION_CRITERIA_NOT_BETWEEN;
+    data_validation->minimum_formula = "=E3";
+    data_validation->maximum_formula = "=F3";
+
+    worksheet_data_validation_cell(worksheet, CELL("B5"), data_validation);
+
+
+    /*
+     * Example 3. Limiting input to an integer greater than a fixed value.
+     */
+    worksheet_write_string(worksheet,
+                           CELL("A7"),
+                           "Enter an integer greater than 0",
+                           NULL);
+
+    data_validation->validate     = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria     = LXW_VALIDATION_CRITERIA_GREATER_THAN;
+    data_validation->value_number = 0;
+
+    worksheet_data_validation_cell(worksheet, CELL("B7"), data_validation);
+
+
+    /*
+     * Example 4. Limiting input to an integer less than a fixed value.
+     */
+    worksheet_write_string(worksheet,
+                           CELL("A9"),
+                           "Enter an integer less than 10",
+                           NULL);
+
+    data_validation->validate     = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria     = LXW_VALIDATION_CRITERIA_LESS_THAN;
+    data_validation->value_number = 10;
+
+    worksheet_data_validation_cell(worksheet, CELL("B9"), data_validation);
+
+
+    /*
+     * Example 5. Limiting input to a decimal in a fixed range.
+     */
+    worksheet_write_string(worksheet,
+                           CELL("A11"),
+                           "Enter a decimal between 0.1 and 0.5",
+                           NULL);
+
+    data_validation->validate       = LXW_VALIDATION_TYPE_DECIMAL;
+    data_validation->criteria       = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_number = 0.1;
+    data_validation->maximum_number = 0.5;
+
+    worksheet_data_validation_cell(worksheet, CELL("B11"), data_validation);
+
+
+    /*
+     * Example 6. Limiting input to a value in a dropdown list.
+     */
+    worksheet_write_string(worksheet,
+                           CELL("A13"),
+                           "Select a value from a drop down list",
+                           NULL);
+
+    char *list[] = {"open", "high", "close", NULL};
+
+    data_validation->validate   = LXW_VALIDATION_TYPE_LIST;
+    data_validation->value_list = list;
+
+    worksheet_data_validation_cell(worksheet, CELL("B13"), data_validation);
+
+
+    /*
+     * Example 7. Limiting input to a value in a dropdown list.
+     */
+    worksheet_write_string(worksheet,
+                           CELL("A15"),
+                           "Select a value from a drop down list (using a cell range)",
+                           NULL);
+
+    data_validation->validate      = LXW_VALIDATION_TYPE_LIST;
+    data_validation->value_formula = "=$E$4:$G$4";
+
+    worksheet_data_validation_cell(worksheet, CELL("B15"), data_validation);
+
+
+    /*
+     * Example 8. Limiting input to a date in a fixed range.
+     */
+    worksheet_write_string(worksheet,
+                           CELL("A17"),
+                           "Enter a date between 1/1/2008 and 12/12/2008",
+                           NULL);
+
+    lxw_datetime datetime1 = {2008,  1,  1, 0, 0, 0};
+    lxw_datetime datetime2 = {2008, 12, 12, 0, 0, 0};
+
+    data_validation->validate         = LXW_VALIDATION_TYPE_DATE;
+    data_validation->criteria         = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_datetime = datetime1;
+    data_validation->maximum_datetime = datetime2;
+
+    worksheet_data_validation_cell(worksheet, CELL("B17"), data_validation);
+
+
+    /*
+     * Example 9. Limiting input to a time in a fixed range.
+     */
+    worksheet_write_string(worksheet,
+                           CELL("A19"),
+                           "Enter a time between 6:00 and 12:00",
+                           NULL);
+
+    lxw_datetime datetime3 = {0, 0, 0,  6, 0, 0};
+    lxw_datetime datetime4 = {0, 0, 0, 12, 0, 0};
+
+    data_validation->validate         = LXW_VALIDATION_TYPE_DATE;
+    data_validation->criteria         = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_datetime = datetime3;
+    data_validation->maximum_datetime = datetime4;
+
+    worksheet_data_validation_cell(worksheet, CELL("B19"), data_validation);
+
+
+    /*
+     * Example 10. Limiting input to a string greater than a fixed length.
+     */
+    worksheet_write_string(worksheet,
+                           CELL("A21"),
+                           "Enter a string longer than 3 characters",
+                           NULL);
+
+    data_validation->validate     = LXW_VALIDATION_TYPE_LENGTH;
+    data_validation->criteria     = LXW_VALIDATION_CRITERIA_GREATER_THAN;
+    data_validation->value_number = 3;
+
+    worksheet_data_validation_cell(worksheet, CELL("B21"), data_validation);
+
+
+    /*
+     * Example 11. Limiting input based on a formula.
+     */
+    worksheet_write_string(worksheet,
+                           CELL("A23"),
+                           "Enter a value if the following is true \"=AND(F5=50,G5=60)\"",
+
+                           NULL);
+
+    data_validation->validate      = LXW_VALIDATION_TYPE_CUSTOM_FORMULA;
+    data_validation->value_formula = "=AND(F5=50,G5=60)";
+
+    worksheet_data_validation_cell(worksheet, CELL("B23"), data_validation);
+
+
+    /*
+     * Example 12. Displaying and modifying data validation messages.
+     */
+    worksheet_write_string(worksheet,
+                           CELL("A25"),
+                           "Displays a message when you select the cell",
+                           NULL);
+
+    data_validation->validate       = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria       = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_number = 1;
+    data_validation->maximum_number = 100;
+    data_validation->input_title    = "Enter an integer:";
+    data_validation->input_message  = "between 1 and 100";
+
+    worksheet_data_validation_cell(worksheet, CELL("B25"), data_validation);
+
+
+    /*
+     * Example 13. Displaying and modifying data validation messages.
+     */
+    worksheet_write_string(worksheet,
+                           CELL("A27"),
+                           "Display a custom error message when integer isn't between 1 and 100",
+                           NULL);
+
+    data_validation->validate       = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria       = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_number = 1;
+    data_validation->maximum_number = 100;
+    data_validation->input_title    = "Enter an integer:";
+    data_validation->input_message  = "between 1 and 100";
+    data_validation->error_title    = "Input value is not valid!";
+    data_validation->error_message  = "It should be an integer between 1 and 100";
+
+    worksheet_data_validation_cell(worksheet, CELL("B27"), data_validation);
+
+
+    /*
+     * Example 14. Displaying and modifying data validation messages.
+     */
+    worksheet_write_string(worksheet,
+                           CELL("A29"),
+                           "Display a custom info message when integer isn't between 1 and 100",
+                           NULL);
+
+    data_validation->validate       = LXW_VALIDATION_TYPE_INTEGER;
+    data_validation->criteria       = LXW_VALIDATION_CRITERIA_BETWEEN;
+    data_validation->minimum_number = 1;
+    data_validation->maximum_number = 100;
+    data_validation->input_title    = "Enter an integer:";
+    data_validation->input_message  = "between 1 and 100";
+    data_validation->error_title    = "Input value is not valid!";
+    data_validation->error_message  = "It should be an integer between 1 and 100";
+    data_validation->error_type     = LXW_VALIDATION_ERROR_TYPE_INFORMATION;
+
+    worksheet_data_validation_cell(worksheet, CELL("B29"), data_validation);
+
+
+    /* Cleanup. */
+    free(data_validation);
+
+    return workbook_close(workbook);
+}

include/xlsxwriter/worksheet.h

@@ -99,42 +99,105 @@ enum lxw_validation_boolean {
     LXW_VALIDATION_ON
 };
 
+/** Data validation types. */
 enum lxw_validation_types {
     LXW_VALIDATION_TYPE_NONE,
+
+    /** Restrict cell input to whole/integer numbers only. */
     LXW_VALIDATION_TYPE_INTEGER,
+
+    /** Restrict cell input to whole/integer numbers only, using a cell
+     *  reference. */
     LXW_VALIDATION_TYPE_INTEGER_FORMULA,
+
+    /** Restrict cell input to decimal numbers only. */
     LXW_VALIDATION_TYPE_DECIMAL,
+
+    /** Restrict cell input to decimal numbers only, using a cell
+     * reference. */
     LXW_VALIDATION_TYPE_DECIMAL_FORMULA,
+
+    /** Restrict cell input to a list of strings in a dropdown. */
     LXW_VALIDATION_TYPE_LIST,
+
+    /** Restrict cell input to a list of strings in a dropdown, using a
+     * cell range. */
     LXW_VALIDATION_TYPE_LIST_FORMULA,
+
+    /** Restrict cell input to date values only, using a lxw_datetime type. */
     LXW_VALIDATION_TYPE_DATE,
+
+    /** Restrict cell input to date values only, using a cell reference. */
     LXW_VALIDATION_TYPE_DATE_FORMULA,
+
+    /* Restrict cell input to date values only, as a serial number.
+     * Undocumented. */
     LXW_VALIDATION_TYPE_DATE_NUMBER,
+
+    /** Restrict cell input to time values only, using a lxw_datetime type. */
     LXW_VALIDATION_TYPE_TIME,
+
+    /** Restrict cell input to time values only, using a cell reference. */
     LXW_VALIDATION_TYPE_TIME_FORMULA,
+
+    /* Restrict cell input to time values only, as a serial number.
+     * Undocumented. */
     LXW_VALIDATION_TYPE_TIME_NUMBER,
+
+    /** Restrict cell input to strings of defined length, using a cell
+     * reference. */
     LXW_VALIDATION_TYPE_LENGTH,
+
+    /** Restrict cell input to strings of defined length, using a cell
+     * reference. */
     LXW_VALIDATION_TYPE_LENGTH_FORMULA,
+
+    /** Restrict cell to input controlled by a custom formula that returns
+     * `TRUE/FALSE`. */
     LXW_VALIDATION_TYPE_CUSTOM_FORMULA,
+
+    /** Allow any type of input. Mainly only useful for pop-up messages. */
     LXW_VALIDATION_TYPE_ANY
 };
 
+/** Data validation criteria uses to control the selection of data. */
 enum lxw_validation_criteria {
     LXW_VALIDATION_CRITERIA_NONE,
-    LXW_VALIDATION_CRITERIA_EQUAL,
+
-    LXW_VALIDATION_CRITERIA_NOT_EQUAL,
+    /** Select data between two values. */
-    LXW_VALIDATION_CRITERIA_LESS_THAN,
-    LXW_VALIDATION_CRITERIA_LESS_THAN_OR_EQUAL,
-    LXW_VALIDATION_CRITERIA_GREATER_THAN,
-    LXW_VALIDATION_CRITERIA_GREATER_THAN_OR_EQUAL,
     LXW_VALIDATION_CRITERIA_BETWEEN,
-    LXW_VALIDATION_CRITERIA_NOT_BETWEEN
+
+    /** Select data that is not between two values. */
+    LXW_VALIDATION_CRITERIA_NOT_BETWEEN,
+
+    /** Select data equal to a value. */
+    LXW_VALIDATION_CRITERIA_EQUAL_TO,
+
+    /** Select data not equal to a value. */
+    LXW_VALIDATION_CRITERIA_NOT_EQUAL_TO,
+
+    /** Select data greater than a value. */
+    LXW_VALIDATION_CRITERIA_GREATER_THAN,
+
+    /** Select data less than a value. */
+    LXW_VALIDATION_CRITERIA_LESS_THAN,
+
+    /** Select data greater than or equal to a value. */
+    LXW_VALIDATION_CRITERIA_GREATER_THAN_OR_EQUAL_TO,
+
+    /** Select data less than or equal to a value. */
+    LXW_VALIDATION_CRITERIA_LESS_THAN_OR_EQUAL_TO
 };
 
+/** Data validation error types for pop-up messages. */
 enum lxw_validation_error_types {
-    LXW_VALIDATION_ERROR_TYPE_DEFAULT,
+    /** Show a "Stop" data validation pop-up message. This is the default. */
     LXW_VALIDATION_ERROR_TYPE_STOP,
+
+    /** Show an "Error" data validation pop-up message. */
     LXW_VALIDATION_ERROR_TYPE_WARNING,
+
+    /** Show an "Information" data validation pop-up message. */
     LXW_VALIDATION_ERROR_TYPE_INFORMATION
 };
 
@@ -284,33 +347,172 @@ typedef struct lxw_selection {
 
 } lxw_selection;
 
+/**
+ * @brief Worksheet data validation options.
+ */
 typedef struct lxw_data_validation {
 
+    /**
+     * Set the validation type. Should be a #lxw_validation_types value.
+     */
     uint8_t validate;
+
+    /**
+     * Set the validation criteria type to select the data. Should be a
+     * #lxw_validation_criteria value.
+     */
     uint8_t criteria;
+
+    /** Controls whether a data validation is not applied to blank data in the
+     * cell. Should be a #lxw_validation_boolean value. It is on by
+     * default.
+     */
     uint8_t ignore_blank;
+
+    /**
+     * This parameter is used to toggle on and off the 'Show input message
+     * when cell is selected' option in the Excel data validation dialog. When
+     * the option is off an input message is not displayed even if it has been
+     * set using input_message. Should be a #lxw_validation_boolean value. It
+     * is on by default.
+     */
     uint8_t show_input;
+
+    /**
+     * This parameter is used to toggle on and off the 'Show error alert
+     * after invalid data is entered' option in the Excel data validation
+     * dialog. When the option is off an error message is not displayed even
+     * if it has been set using error_message. Should be a
+     * #lxw_validation_boolean value. It is on by default.
+     */
     uint8_t show_error;
+
+    /**
+     * This parameter is used to specify the type of error dialog that is
+     * displayed. Should be a #lxw_validation_error_types value.
+     */
     uint8_t error_type;
+
+    /**
+     * This parameter is used to toggle on and off the 'In-cell dropdown'
+     * option in the Excel data validation dialog. When the option is on a
+     * dropdown list will be shown for list validations. Should be a
+     * #lxw_validation_boolean value. It is on by default.
+     */
     uint8_t dropdown;
+
     uint8_t is_between;
 
+    /**
+     * This parameter is used to set the limiting value to which the criteria
+     * is applied using a whole or decimal number.
+     */
     double value_number;
+
+    /**
+     * This parameter is used to set the limiting value to which the criteria
+     * is applied using a cell reference. It is valid for any of the
+     * `_FORMULA` validation types.
+     */
     char *value_formula;
+
+    /**
+     * This parameter is used to set a list of strings for a drop down list.
+     * The list should be a `NULL` terminated array of char* strings:
+     *
+     * @code
+     *    char *list[] = {"open", "high", "close", NULL};
+     *
+     *    data_validation->validate   = LXW_VALIDATION_TYPE_LIST;
+     *    data_validation->value_list = list;
+     * @endcode
+     *
+     * The `value_formula` parameter can also be used to specify a list from
+     * an Excel cell range.
+     *
+     * Note, the string list is restricted by Excel to 255 characters,
+     * including comma separators.
+     */
     char **value_list;
+
+    /**
+     * This parameter is used to set the limiting value to which the date or
+     * time criteria is applied using a #lxw_datetime struct.
+     */
     lxw_datetime value_datetime;
 
+    /**
+     * This parameter is the same as `value_number` but for the minimum value
+     * when a `BETWEEN` criteria is used.
+     */
     double minimum_number;
+
+    /**
+     * This parameter is the same as `value_formula` but for the minimum value
+     * when a `BETWEEN` criteria is used.
+     */
     char *minimum_formula;
+
+    /**
+     * This parameter is the same as `value_datetime` but for the minimum value
+     * when a `BETWEEN` criteria is used.
+     */
     lxw_datetime minimum_datetime;
 
+    /**
+     * This parameter is the same as `value_number` but for the maximum value
+     * when a `BETWEEN` criteria is used.
+     */
     double maximum_number;
+
+    /**
+     * This parameter is the same as `value_formula` but for the maximum value
+     * when a `BETWEEN` criteria is used.
+     */
     char *maximum_formula;
+
+    /**
+     * This parameter is the same as `value_datetime` but for the maximum value
+     * when a `BETWEEN` criteria is used.
+     */
     lxw_datetime maximum_datetime;
 
+    /**
+     * The input_title parameter is used to set the title of the input message
+     * that is displayed when a cell is entered. It has no default value and
+     * is only displayed if the input message is displayed. See the
+     * `input_message` parameter below.
+     *
+     * The maximum title length is 32 characters.
+     */
     char *input_title;
+
+    /**
+     * The input_message parameter is used to set the input message that is
+     * displayed when a cell is entered. It has no default value.
+     *
+     * The message can be split over several lines using newlines. The maximum
+     * message length is 255 characters.
+     */
     char *input_message;
+
+    /**
+     * The error_title parameter is used to set the title of the error message
+     * that is displayed when the data validation criteria is not met. The
+     * default error title is 'Microsoft Excel'. The maximum title length is
+     * 32 characters.
+     */
     char *error_title;
+
+    /**
+     * The error_message parameter is used to set the error message that is
+     * displayed when a cell is entered. The default error message is "The
+     * value you entered is not valid. A user has restricted values that can
+     * be entered into the cell".
+     *
+     * The message can be split over several lines using newlines. The maximum
+     * message length is 255 characters.
+     */
     char *error_message;
 
     char sqref[LXW_MAX_CELL_RANGE_LENGTH];
@@ -1566,10 +1768,80 @@ lxw_error worksheet_autofilter(lxw_worksheet *worksheet, lxw_row_t first_row,
                                lxw_col_t first_col, lxw_row_t last_row,
                                lxw_col_t last_col);
 
+/**
+ * @brief Add a data validation to a cell.
+ *
+ * @param worksheet  Pointer to a lxw_worksheet instance to be updated.
+ * @param row        The zero indexed row number.
+ * @param col        The zero indexed column number.
+ * @param validation A #lxw_data_validation object to control the validation.
+ *
+ * @return A #lxw_error code.
+ *
+ * The `%worksheet_data_validation_cell()` function is used to construct an
+ * Excel data validation or to limit the user input to a dropdown list of
+ * values:
+ *
+ * @code
+ *
+ *    lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
+ *
+ *    data_validation->validate       = LXW_VALIDATION_TYPE_INTEGER;
+ *    data_validation->criteria       = LXW_VALIDATION_CRITERIA_BETWEEN;
+ *    data_validation->minimum_number = 1;
+ *    data_validation->maximum_number = 10;
+ *
+ *    worksheet_data_validation_cell(worksheet, 2, 1, data_validation);
+ *
+ *    // Same as above with the CELL() macro.
+ *    worksheet_data_validation_cell(worksheet, CELL("B3"), data_validation);
+ *
+ * @endcode
+ *
+ * @image html data_validate4.png
+ *
+ * Data validation and the various options of #lxw_data_validation are
+ * described in more detail in @ref working_with_data_validation.
+ */
 lxw_error worksheet_data_validation_cell(lxw_worksheet *worksheet,
-                                         lxw_row_t row_num, lxw_col_t col_num,
+                                         lxw_row_t row, lxw_col_t col,
-                                         lxw_data_validation *user_options);
+                                         lxw_data_validation *validation);
 
+/**
+ * @brief Add a data validation to a range cell.
+ *
+ * @param worksheet  Pointer to a lxw_worksheet instance to be updated.
+ * @param first_row  The first row of the range. (All zero indexed.)
+ * @param first_col  The first column of the range.
+ * @param last_row   The last row of the range.
+ * @param last_col   The last col of the range.
+ * @param validation A #lxw_data_validation object to control the validation.
+ *
+ * @return A #lxw_error code.
+ *
+ * The `%worksheet_data_validation_range()` function is the same as the
+ * `%worksheet_data_validation_cell()`, see above,  except the data validation
+ * is applied to a range of cells:
+ *
+ * @code
+ *
+ *    lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
+ *
+ *    data_validation->validate       = LXW_VALIDATION_TYPE_INTEGER;
+ *    data_validation->criteria       = LXW_VALIDATION_CRITERIA_BETWEEN;
+ *    data_validation->minimum_number = 1;
+ *    data_validation->maximum_number = 10;
+ *
+ *    worksheet_data_validation_range(worksheet, 2, 1, 4, 1, data_validation);
+ *
+ *    // Same as above with the RANGE() macro.
+ *    worksheet_data_validation_range(worksheet, RANGE("B3:B5"), data_validation);
+ *
+ * @endcode
+ *
+ * Data validation and the various options of #lxw_data_validation are
+ * described in more detail in @ref working_with_data_validation.
+ */
 lxw_error worksheet_data_validation_range(lxw_worksheet *worksheet,
                                           lxw_row_t first_row,
                                           lxw_col_t first_col,

libxlsxwriter.podspec

@@ -16,6 +16,7 @@ Pod::Spec.new do |s|
                             * Defined names.
                             * Autofilters.
                             * Charts.
+                            * Data validation and drop down lists.
                             * Worksheet PNG/JPEG images.
                             * Memory optimisation mode for writing large files.
                             * Source code available on [GitHub](https://github.com/jmcnamara/libxlsxwriter).

src/worksheet.c

@@ -3494,22 +3494,22 @@ _worksheet_write_data_validation(lxw_worksheet *self,
     }
 
     switch (validation->criteria) {
-        case LXW_VALIDATION_CRITERIA_EQUAL:
+        case LXW_VALIDATION_CRITERIA_EQUAL_TO:
             LXW_PUSH_ATTRIBUTES_STR("operator", "equal");
             break;
-        case LXW_VALIDATION_CRITERIA_NOT_EQUAL:
+        case LXW_VALIDATION_CRITERIA_NOT_EQUAL_TO:
             LXW_PUSH_ATTRIBUTES_STR("operator", "notEqual");
             break;
         case LXW_VALIDATION_CRITERIA_LESS_THAN:
             LXW_PUSH_ATTRIBUTES_STR("operator", "lessThan");
             break;
-        case LXW_VALIDATION_CRITERIA_LESS_THAN_OR_EQUAL:
+        case LXW_VALIDATION_CRITERIA_LESS_THAN_OR_EQUAL_TO:
             LXW_PUSH_ATTRIBUTES_STR("operator", "lessThanOrEqual");
             break;
         case LXW_VALIDATION_CRITERIA_GREATER_THAN:
             LXW_PUSH_ATTRIBUTES_STR("operator", "greaterThan");
             break;
-        case LXW_VALIDATION_CRITERIA_GREATER_THAN_OR_EQUAL:
+        case LXW_VALIDATION_CRITERIA_GREATER_THAN_OR_EQUAL_TO:
             LXW_PUSH_ATTRIBUTES_STR("operator", "greaterThanOrEqual");
             break;
         case LXW_VALIDATION_CRITERIA_BETWEEN:
@@ -5614,11 +5614,9 @@ mem_error:
  * Add a data validation to a worksheet, for a cell.
  */
 lxw_error
-worksheet_data_validation_cell(lxw_worksheet *self, lxw_row_t row_num,
+worksheet_data_validation_cell(lxw_worksheet *self, lxw_row_t row,
-                               lxw_col_t col_num,
+                               lxw_col_t col, lxw_data_validation *validation)
-                               lxw_data_validation *validation)
 {
-    return worksheet_data_validation_range(self,
+    return worksheet_data_validation_range(self, row, col,
-                                           row_num, col_num,
+                                           row, col, validation);
-                                           row_num, col_num, validation);
 }

test/unit/worksheet/test_worksheet_write_data_validation2.c

@@ -68,7 +68,7 @@ CTEST(worksheet, test_write_data_validations_203) {
 
     lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
     data_validation->validate = LXW_VALIDATION_TYPE_INTEGER;
-    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL;
+    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL_TO;
     data_validation->value_number = 1;
 
     lxw_worksheet *worksheet = lxw_worksheet_new(NULL);
@@ -91,7 +91,7 @@ CTEST(worksheet, test_write_data_validations_204) {
 
     lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
     data_validation->validate = LXW_VALIDATION_TYPE_INTEGER;
-    data_validation->criteria = LXW_VALIDATION_CRITERIA_NOT_EQUAL;
+    data_validation->criteria = LXW_VALIDATION_CRITERIA_NOT_EQUAL_TO;
     data_validation->value_number = 1;
 
     lxw_worksheet *worksheet = lxw_worksheet_new(NULL);
@@ -160,7 +160,7 @@ CTEST(worksheet, test_write_data_validations_207) {
 
     lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
     data_validation->validate = LXW_VALIDATION_TYPE_INTEGER;
-    data_validation->criteria = LXW_VALIDATION_CRITERIA_GREATER_THAN_OR_EQUAL;
+    data_validation->criteria = LXW_VALIDATION_CRITERIA_GREATER_THAN_OR_EQUAL_TO;
     data_validation->value_number = 1;
 
     lxw_worksheet *worksheet = lxw_worksheet_new(NULL);
@@ -183,7 +183,7 @@ CTEST(worksheet, test_write_data_validations_208) {
 
     lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
     data_validation->validate = LXW_VALIDATION_TYPE_INTEGER;
-    data_validation->criteria = LXW_VALIDATION_CRITERIA_LESS_THAN_OR_EQUAL;
+    data_validation->criteria = LXW_VALIDATION_CRITERIA_LESS_THAN_OR_EQUAL_TO;
     data_validation->value_number = 1;
 
     lxw_worksheet *worksheet = lxw_worksheet_new(NULL);
@@ -466,7 +466,7 @@ CTEST(worksheet, test_write_data_validations_219) {
 
     lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
     data_validation->validate = LXW_VALIDATION_TYPE_DECIMAL;
-    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL;
+    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL_TO;
     data_validation->value_number = 1.2345;
 
     lxw_worksheet *worksheet = lxw_worksheet_new(NULL);
@@ -558,7 +558,7 @@ CTEST(worksheet, test_write_data_validations_223) {
 
     lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
     data_validation->validate = LXW_VALIDATION_TYPE_DATE_NUMBER;
-    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL;
+    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL_TO;
     data_validation->value_number = 39653;
 
     lxw_worksheet *worksheet = lxw_worksheet_new(NULL);
@@ -582,7 +582,7 @@ CTEST(worksheet, test_write_data_validations_224) {
 
     lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
     data_validation->validate = LXW_VALIDATION_TYPE_DATE;
-    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL;
+    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL_TO;
     data_validation->value_datetime = datetime1;
 
     lxw_worksheet *worksheet = lxw_worksheet_new(NULL);
@@ -631,7 +631,7 @@ CTEST(worksheet, test_write_data_validations_226) {
 
     lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
     data_validation->validate = LXW_VALIDATION_TYPE_TIME_NUMBER;
-    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL;
+    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL_TO;
     data_validation->value_number = 0.5;
 
     lxw_worksheet *worksheet = lxw_worksheet_new(NULL);
@@ -655,7 +655,7 @@ CTEST(worksheet, test_write_data_validations_227) {
 
     lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
     data_validation->validate = LXW_VALIDATION_TYPE_TIME;
-    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL;
+    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL_TO;
     data_validation->value_datetime = datetime1;
 
     lxw_worksheet *worksheet = lxw_worksheet_new(NULL);
@@ -849,7 +849,7 @@ CTEST(worksheet, test_write_data_validations_235) {
 
     lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
     data_validation->validate = LXW_VALIDATION_TYPE_DATE_FORMULA;
-    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL;
+    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL_TO;
     data_validation->value_formula = "=H1";
 
     lxw_worksheet *worksheet = lxw_worksheet_new(NULL);
@@ -922,7 +922,7 @@ CTEST(worksheet, test_write_data_validations_238) {
 
     lxw_data_validation *data_validation = calloc(1, sizeof(lxw_data_validation));
     data_validation->validate = LXW_VALIDATION_TYPE_TIME_FORMULA;
-    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL;
+    data_validation->criteria = LXW_VALIDATION_CRITERIA_EQUAL_TO;
     data_validation->value_formula = "=H1";
 
     lxw_worksheet *worksheet = lxw_worksheet_new(NULL);