diff --git a/.indent.pro b/.indent.pro index 3c26525c..8b87d676 100644 --- a/.indent.pro +++ b/.indent.pro @@ -45,6 +45,7 @@ -T lxw_app -T lxw_border -T lxw_cell +-T lxw_col_options -T lxw_col_t -T lxw_color_t -T lxw_content_types @@ -62,6 +63,7 @@ -T lxw_rel_tuple -T lxw_relationships -T lxw_row +-T lxw_row_col_options -T lxw_row_t -T lxw_sst -T lxw_styles diff --git a/Makefile b/Makefile index c9c0ec68..04152904 100644 --- a/Makefile +++ b/Makefile @@ -19,7 +19,7 @@ all : $(Q)make -C src # Build the example programs. -examples: +examples : $(Q)make -C examples # Clean src and test directories. @@ -55,9 +55,13 @@ test_valgrind : all $(Q)make -C test/functional/src test_valgrind $(Q)make -C examples test_valgrind +# Minimal target for quick compile without creating the libs. +test_compile : + $(Q)make -C src test_compile + # Indent the source files with the .indent.pro settings. indent: - $(Q)gindent src/*.c include/*.h + $(Q)gindent src/*.c include/*.h include/xlsxwriter/*.h tags: $(Q)rm -f TAGS diff --git a/docs/src/cworkbook.dox b/docs/src/cworkbook.dox deleted file mode 100644 index 21f94b34..00000000 --- a/docs/src/cworkbook.dox +++ /dev/null @@ -1,495 +0,0 @@ -/** - * .. _workbook: - * - * The Workbook Class - * ================== - * - * The Workbook class is the main class exposed by the xlsxwriter module and it is - * the only class that you will need to instantiate directly. - * - * The Workbook class represents the entire spreadsheet as you see it in Excel and - * internally it represents the Excel file as it is written on disk. - * - * Constructor - */ - - * -/** - * @brief Create a new xlsxwriter Workbook object. - * - * - * @param self Pointer to lxw_format. - * @param filename The name of the new Excel file to create. - * @param options Optional workbook parameters. See below. - * :rtype: A Workbook object. - * - * - * The ``Workbook:new()`` constructor is used to create a new Excel workbook with a - * given filename: - * - * @code - * import xlsxwriter - * - * workbook = xlsxwriter.Workbook('filename.xlsx'); - * worksheet = workbook:add_worksheet(); - * - * worksheet:write(0, 0, 'Hello Excel'); - * - * @endcode - * - * @image html workbook01.png - * - * The constructor options are: - * - * * **constant_memory**: Reduces the amount of data stored in memory so that - * large files can be written efficiently: - * - * @code - * workbook = xlsxwriter.Workbook(filename, {constant_memory = True}); - * - * Note, in this mode a row of data is written and then discarded when a cell - * in a new row is added via one of the worksheet ``write_()`` methods. - * Therefore, once this mode is active, data should be written in sequential - * row order. - * - * See :ref:`memory_perf` for more details. - * - * @endcode - * - * * **tmpdir**: ``xlsxwriter`` stores worksheet data in a temporary files prior - * to assembling the final XLSX file. The temporary files are created in the - * system's temp directory. If the default temporary directory isn't accessible - * to your application, or doesn't contain enough space, you can specify an - * alternative location using the ``tempdir`` option: - * - * @code - * workbook = xlsxwriter.Workbook(filename, {tmpdir = '/home/user/tmp'}); - * - * The temporary directory must exist and will not be created. - * - * @endcode - * - * * **in_memory**: To avoid the use of temporary files in the assembly of the - * final XLSX file, for example on servers that don't allow temp files such as - * the Google APP Engine, set the ``in_memory`` constructor option to ``True``: - * - * @code - * workbook = xlsxwriter.Workbook(filename, {in_memory = True}); - * - * This option overrides the ``constant_memory`` option. - * @endcode - * - * * **strings_to_numbers**: Enable the - * :ref:`worksheet: `:func:`write()` method to convert strings to - * numbers, where possible, using :func:`float()` in order to avoid an Excel - * warning about "Numbers Stored as Text". The default is ``False``: - * - * @code - * workbook = xlsxwriter.Workbook(filename, {strings_to_numbers = True}); - * - * @endcode - * - * * **strings_to_formulas**: Enable the - * :ref:`worksheet: `:func:`write()` method to convert strings to - * formulas. The default is ``True``: - * - * @code - * workbook = xlsxwriter.Workbook(filename, {strings_to_formulas = False}); - * - * @endcode - * - * * **strings_to_urls**: Enable the - * :ref:`worksheet: `:func:`write()` method to convert strings to - * urls. The default is ``True``: - * - * @code - * workbook = xlsxwriter.Workbook(filename, {strings_to_urls = True}); - * - * @endcode - * - * * **default_date_format**: This option is used to specify a default date - * format string for use with the - * :ref:`worksheet: `:func:`write_datetime()` method when an - * explicit format isn't given. See :ref:`working_with_dates_and_time` for more - * details: - * - * @code - * xlsxwriter.Workbook(filename, {default_date_format = 'dd/mm/yy'}); - * - * @endcode - * - * * **date_1904**: Excel for Windows uses a default epoch of 1900 and Excel for - * Mac uses an epoch of 1904. However, Excel on either platform will convert - * automatically between one system and the other. xlsxwriter stores dates in - * the 1900 format by default. If you wish to change this you can use the - * ``date_1904`` workbook option. This option is mainly for enhanced - * compatibility with Excel and in general isn't required very often: - * - * @code - * workbook = xlsxwriter.Workbook(filename, {date_1904 = True}); - * - * @endcode - * - * When specifying a filename it is recommended that you use an ``.xlsx`` - * extension or Excel will generate a warning when opening the file. - * - * It is possible to write files to in-memory strings using StringIO as follows: - * - * @code - * output = StringIO(); - * workbook = xlsxwriter.Workbook(output); - * worksheet = workbook:add_worksheet(); - * - * worksheet:write('A1', 'Hello'); - * workbook:close(); - * - * xlsx_data = output.getvalue(); - * - * @endcode - * - * To avoid the use of any temporary files and keep the entire file in-memory use - * the ``in_memory`` constructor option shown above. - * - * See also :ref:`ex_http_server`. - * - * - * workbook:add_worksheet() - */ - - * -/** - * @brief Add a new worksheet to a workbook: - * - * - * @param self Pointer to lxw_format. - * @param sheetname Optional worksheet name, defaults to Sheet1, etc. - * :rtype: A :ref:`worksheet ` object. - * - * The ``add_worksheet()`` method adds a new worksheet to a workbook: - * - * At least one worksheet should be added to a new workbook: The - * :ref:`Worksheet ` object is used to write data and configure a - * worksheet in the workbook: - * - * The ``sheetname`` parameter is optional. If it is not specified the default - * Excel convention will be followed, i.e. Sheet1, Sheet2, etc.: - * - * @code - * worksheet1 = workbook:add_worksheet(); // Sheet1 - * worksheet2 = workbook:add_worksheet('Foglio2'); // Foglio2 - * worksheet3 = workbook:add_worksheet('Data'); // Data - * worksheet4 = workbook:add_worksheet(); // Sheet4 - * - * @endcode - * - * @image html workbook02.png - * - * The worksheet name must be a valid Excel worksheet name, i.e. it cannot contain - * any of the characters ``' [ ] : * ? / \ - * '`` and it must be less than 32 characters. - * - * In addition, you cannot use the same, case insensitive, ``sheetname`` for more - * than one worksheet: - * - * workbook:add_format() - */ - - * -/** - * @brief Create a new Format object to formats cells in worksheets. - * - * - * @param self Pointer to lxw_format. - * @paramionary properties An optional dictionary of format properties. - * :rtype: A :ref:`format ` object. - * - * The ``add_format()`` method can be used to create new :ref:`Format ` - * objects which are used to apply formatting to a cell. You can either define - * the properties at creation time via a dictionary of property values or later - * via method calls: - * - * @code - * format1 = workbook:add_format(props); // Set properties at creation. - * format2 = workbook:add_format(); // Set properties later. - * - * @endcode - * - * See the :ref:`format` and :ref:`working_with_formats` sections for more details - * about Format properties and how to set them. - * - * - * workbook:add_chart() - */ - - * -/** - * @brief Create a chart object that can be added to a worksheet: - * - * - * @param self Pointer to lxw_format. - * @paramionary options An dictionary of chart type options. - * :rtype: A :ref:`Chart ` object. - * - * This method is use to create a new chart object that can be inserted into a - * worksheet via the :func:`insert_chart()` Worksheet method: - * - * @code - * chart = workbook:add_chart({type = 'column'}); - * - * @endcode - * - * The properties that can be set are: - * - * @code - * type (required); - * subtype (optional); - * - * @endcode - * - * * ``type`` - * - * This is a required parameter. It defines the type of chart that will be - * created: - * - * @code - * chart = workbook:add_chart({type = 'line'}); - * - * The available types are: - * - * @code - * area - * bar - * column - * line - * pie - * radar - * scatter - * stock - * - * @endcode - * - * * ``subtype`` - * - * Used to define a chart subtype where available: - * - * @code - * workbook:add_chart({type = 'bar', subtype = 'stacked'}); - * - * @endcode - * - * See the :ref:`chart_class` for a list of available chart subtypes. - * - * See also :ref:`working_with_charts` and :ref:`chart_examples`. - * - * workbook:add_chartsheet() - */ - - * -/** - * @brief Add a new add_chartsheet to a workbook: - * - * - * @param self Pointer to lxw_format. - * @param sheetname Optional chartsheet name, defaults to Chart1, etc. - * :rtype: A :ref:`chartsheet ` object. - * - * The ``add_chartsheet()`` method adds a new chartsheet to a workbook: - * - * @image html chartsheet.png - * - * See :ref:`chartsheet` for details. - * - * The ``sheetname`` parameter is optional. If it is not specified the default - * Excel convention will be followed, i.e. Chart1, Chart2, etc. - * - * The chartsheet name must be a valid Excel worksheet name, i.e. it cannot - * contain any of the characters ``' [ ] : * ? / \ - * '`` and it must be less than 32 characters. - * - * In addition, you cannot use the same, case insensitive, ``sheetname`` for more - * than one chartsheet. - * - * - * workbook:close() - */ - - * -/** - * @brief Close the Workbook object and write the XLSX file. - * - * - * In general your Excel file will be closed automatically when your program ends - * or when the Workbook object goes out of scope, however the ``close()`` method - * can be used to explicitly close an Excel file: - * - * @code - * workbook:close(); - * - * @endcode - * - * An explicit ``close()`` is required if the file must be closed prior to - * performing some external action on it such as copying it, reading its size or - * attaching it to an email. - * - * In addition, ``close()`` may occasionally be required to prevent Python's - * garbage collector from disposing of the Workbook, Worksheet and Format objects - * in the wrong order. - * - * - * workbook:set_properties() - */ - - * -/** - * @brief Set the document properties such as Title, Author etc. - * - * - * @param self Pointer to lxw_format. - * @param properties Dictionary of document properties. - * - * The ``set_properties`` method can be used to set the document properties of the - * Excel file created by ``xlsxwriter``. These properties are visible when you - * use the ``Office Button -> Prepare -> Properties`` option in Excel and are - * also available to external applications that read or index windows files. - * - * The properties that can be set are: - * - * * ``title`` - * * ``subject`` - * * ``author`` - * * ``manager`` - * * ``company`` - * * ``category`` - * * ``keywords`` - * * ``comments`` - * * ``status`` - * - * The properties are all optional and should be passed in dictionary format as - * follows: - * - * @code - * workbook:set_properties({ - * title = 'This is an example spreadsheet', - * subject = 'With document properties', - * author = 'John McNamara', - * manager = 'Dr. Heinz Doofenshmirtz', - * company = 'of Wolves', - * category = 'Example spreadsheets', - * keywords = 'Sample, Example, Properties', - * comments = 'Created with Python and xlsxwriter'}); - * - * @endcode - * - * @image html doc_properties.png - * - * See also :ref:`ex_doc_properties`. - * - * workbook:define_name() - */ - - * -/** - * @brief Create a defined name in the workbook to use as a variable. - * - * - * @param self Pointer to lxw_format. - * @param name The defined name. - * @param formula The cell or range that the defined name refers to. - * - * This method is used to defined a name that can be used to represent a value, a - * single cell or a range of cells in a workbook: These defined names can then be - * used in formulas: - * - * @code - * workbook:define_name('Exchange_rate', '=0.96'); - * worksheet:write('B3', '=B2*Exchange_rate'); - * - * @endcode - * - * As in Excel a name defined like this is "global" to the workbook and can be - * referred to from any worksheet: - * - * @code - * // Global workbook name. - * workbook:define_name('Sales', '=Sheet1!$G$1:$H$10'); - * - * @endcode - * - * It is also possible to define a local/worksheet name by prefixing it with the - * sheet name using the syntax ``'sheetname!definedname'``: - * - * @code - * // Local worksheet name. - * workbook:define_name('Sheet2!Sales', '=Sheet2!$G$1:$G$10'); - * - * @endcode - * - * If the sheet name contains spaces or special characters you must follow the - * Excel convention and enclose it in single quotes: - * - * @code - * workbook:define_name("'New Data'!Sales", '=Sheet2!$G$1:$G$10'); - * - * @endcode - * - * See also the ``defined_name.py`` program in the examples directory. - * - * - * workbook:worksheets() - */ - - * -/** - * @brief Return a list of the worksheet objects in the workbook: - * - * - * :rtype: A list of :ref:`worksheet ` objects. - * - * The ``worksheets()`` method returns a list of the worksheets in a workbook: - * This is useful if you want to repeat an operation on each worksheet in a - * workbook: - * - * @code - * for worksheet in workbook:worksheets(): - * worksheet:write('A1', 'Hello'); - * - * @endcode - * - * workbook:set_calc_mode() - */ - - * -/** - * @brief Set the Excel calculation mode for the workbook: - * - * - * @param self Pointer to lxw_format. - * @param mode The calculation mode string - * - * Set the calculation mode for formulas in the workbook: This is mainly of use - * for workbooks with slow formulas where you want to allow the user to calculate - * them manually. - * - * The ``mode`` parameter can be: - * - * * ``auto``: The default. Excel will re-calculate formulas when a formula or a - * value affecting the formula changes. - * - * * ``auto_except_tables``: Excel will automatically re-calculate formulas - * except for tables. - * - * * ``manual``: Only re-calculate formulas when the user requires it. Generally - * by pressing F9. - * - * - * workbook:use_zip64() - */ - - * -/** - * @brief Allow ZIP64 extensions when writing xlsx file zip container. - * - * - * Use ZIP64 extensions when writing the xlsx file zip container and allow files - * greater than 4 GB. - * diff --git a/docs/src/cworksheet.dox b/docs/src/cworksheet.dox deleted file mode 100644 index dc3e0988..00000000 --- a/docs/src/cworksheet.dox +++ /dev/null @@ -1,2247 +0,0 @@ -/** - * .. _worksheet: - * - * The Worksheet Class - * =================== - * - * The worksheet class represents an Excel worksheet. It handles operations such - * as writing data to cells or formatting worksheet layout. - * - * A worksheet object isn't instantiated directly. Instead a new worksheet is - * created by calling the :func:`add_worksheet()` method from a Workbook() - * object: - * - * @code - * workbook = Workbook:new("filename.xlsx"); - * - * worksheet1 = workbook:add_worksheet(); - * worksheet2 = workbook:add_worksheet(); - * - * worksheet1.write(0, 0, 123); - * - * @endcode - * - * @image html worksheet00.png - * - * - * worksheet:write() - */ - - * -/** - * @brief Write generic data to a worksheet cell. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param row The zero indexed row number. - * @param col The zero indexed column number. - * @param args The additional args that are passed to the sub methods - * such as number, string and format. - * - * Excel makes a distinction between data types such as strings, numbers, blanks, - * formulas and hyperlinks. To simplify the process of writing data to an - * xlsxwriter.lua file the `write()` method acts as a general alias for several - * more specific methods: - * - * * :func:`worksheet_write_string()` - * * :func:`worksheet_write_number()` - * * :func:`worksheet_write_blank()` - * * :func:`worksheet_write_formula()` - * * :func:`worksheet_write_datetime()` - * * :func:`worksheet_write_boolean()` - * * :func:`worksheet_write_url()` - * - * The rules for handling data in `write()` are as follows: - * - * * Data types `float`, `int`, `long`, :class:`decimal.Decimal` and - * :class:`fractions.Fraction` are written using :func:`worksheet_write_number()`. - * - * * Data types :class:`datetime.datetime`, :class:`datetime.date` or - * :class:`datetime.time` are written using :func:`worksheet_write_datetime()` . - * - * * `None` and empty strings `""` are written using :func:`worksheet_write_blank()`. - * - * * Data type `bool` is written using :func:`worksheet_write_boolean()`. - * - * Strings are then handled as follows: - * - * * Strings that start with `"="` are take to match a formula and are written - * using :func:`worksheet_write_formula()`. This can be overridden, see below. - * - * * Strings that match supported URL types are written using - * :func:`worksheet_write_url()`. This can be overridden, see below. - * - * * When the Workbook() constructor `strings_to_numbers` option is - * `true` strings that convert to numbers using :func:`float()` are written - * using :func:`worksheet_write_number()` in order to avoid Excel warnings about "Numbers - * Stored as Text". See the note below. - * - * * Strings that don't match any of the above criteria are written using - * :func:`worksheet_write_string()`. - * - * If none of the above types are matched the value is evaluated with `float()` - * to see if it corresponds to a user defined float type. If it does then it is - * written using :func:`worksheet_write_number()`. - * - * If not then it is evaluated with `str()` to see if it corresponds to a user - * defined string type. If it does then it is written using - * :func:`worksheet_write_string()`. - * - * Finally, if none of these rules are matched then a `TypeError` exception is - * raised. - * - * Here are some examples: - * - * @code - * worksheet:write(0, 0, "Hello"); // worksheet_write_string(); - * worksheet:write(1, 0, "World"); // worksheet_write_string(); - * worksheet:write(2, 0, 2); // worksheet_write_number(); - * worksheet:write(3, 0, 3.00001); // worksheet_write_number(); - * worksheet:write(4, 0, "=SIN(PI()/4)"); // worksheet_write_formula(); - * worksheet:write(5, 0, ""); // worksheet_write_blank(); - * worksheet:write(6, 0, None); // worksheet_write_blank(); - * - * @endcode - * - * This creates a worksheet like the following: - * - * @image html worksheet01.png - * - * .. note:: - * - * The Workbook() constructor option takes three optional arguments - * that can be used to override string handling in the `write()` function. - * These options are shown below with their default values: - * - * @code - * Workbook:new(filename, {strings_to_numbers = false, - * strings_to_formulas = true, - * strings_to_urls = true}); - * - * @endcode - * - * The `write()` method supports two forms of notation to designate the position - * of cells: **Row-column** notation and **A1** notation: - * - * @code - * // These are equivalent. - * worksheet:write(0, 0, "Hello"); - * worksheet:write(0, 0, "Hello"); - * - * @endcode - * - * See :ref:`cell_notation` for more details. - * - * The `format` parameter in the sub `write` methods is used to apply - * formatting to the cell. This parameter is optional but when present it should - * be a valid :ref:`Format ` object: - * - * @code - * format = workbook:add_format({bold = true, italic = true}); - * - * worksheet:write(0, 0, "Hello", format); // Cell is bold and italic. - * - * @endcode - * - * worksheet:worksheet_write_string() - */ - - * -/** - * @brief Write a string to a worksheet cell. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param row The zero indexed row number. - * @param col The zero indexed column number. - * @param string String to write to cell. - * @param format Optional Format object. :ref:`Format ` - * - * The `worksheet_write_string()` method writes a string to the cell specified by `row` - * and `column`: - * - * @code - * worksheet:worksheet_write_string(0, 0, "Your text here"); - * worksheet:worksheet_write_string(1, 0, "or here"); - * - * @endcode - * - * Both row-column and A1 style notation are supported. See :ref:`cell_notation` - * for more details. - * - * The `format` parameter is used to apply formatting to the cell. This - * parameter is optional but when present is should be a valid - * :ref:`Format ` object. - * - * Unicode strings are supported in UTF-8 encoding. This generally requires that - * your source file in also UTF-8 encoded: - * - * @code - * // _*_ coding: utf-8 - * - * worksheet:write(0, 0, u"Some UTF-8 text"); - * - * @endcode - * - * @image html worksheet02.png - * - * Alternatively, you can read data from an encoded file, convert it to UTF-8 - * during reading and then write the data to an Excel file. There are several - * sample`unicode_\*.py` programs like this in the `examples` directory of the XlsxWriter source tree. - * - * The maximum string size supported by Excel is 32,767 characters. Strings longer - * than this will be truncated by `worksheet_write_string()`. - * - * .. note:: - * - * Even though Excel allows strings of 32,767 characters it can only - * **display** 1000 in a cell. However, all 32,767 characters are displayed in the - * formula bar. - * - * - * worksheet:worksheet_write_number() - */ - - * -/** - * @brief Write a number to a worksheet cell. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param row The zero indexed row number. - * @param col The zero indexed column number. - * @param number Number to write to cell. - * @param format Optional Format object. :ref:`Format ` - * - * The `worksheet_write_number()` method writes numeric types to the cell specified by - * `row` and `column`: - * - * @code - * worksheet:worksheet_write_number(0, 0, 123456); - * worksheet:worksheet_write_number(1, 0, 2.3451); - * - * @endcode - * - * The numeric types supported are `float`, `int`, `long`, - * :class:`decimal.Decimal` and :class:`fractions.Fraction` or anything that can - * be converted via `float()`. - * - * When written to an Excel file numbers are converted to IEEE-754 64-bit - * double-precision floating point. This means that, in most cases, the maximum - * number of digits that can be stored in Excel without losing precision is 15. - * - * .. note:: - * NAN and INF are not supported and will raise a TypeError exception. - * - * Both row-column and A1 style notation are supported. See :ref:`cell_notation` - * for more details. - * - * The `format` parameter is used to apply formatting to the cell. This - * parameter is optional but when present is should be a valid - * :ref:`Format ` object. - * - * - * worksheet:worksheet_write_formula() - */ - - * -/** - * @brief Write a formula to a worksheet cell. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param row The zero indexed row number. - * @param col The zero indexed column number. - * @param formula Formula to write to cell. - * @param format Optional Format object. :ref:`Format ` - * - * The `worksheet_write_formula()` method writes a formula or function to the cell - * specified by `row` and `column`: - * - * @code - * worksheet:worksheet_write_formula(0, 0, "=B3 + B4"); - * worksheet:worksheet_write_formula(1, 0, "=SIN(PI()/4)"); - * worksheet:worksheet_write_formula(2, 0, "=SUM(B1:B5)"); - * worksheet:worksheet_write_formula(3, 0, "=IF(A3>1,"Yes", "No")"); - * worksheet:worksheet_write_formula("A5", "=AVERAGE(1, 2, 3, 4)"); - * worksheet:worksheet_write_formula("A6", "=DATEVALUE("1-Jan-2013")"); - * - * @endcode - * - * Array formulas are also supported: - * - * @code - * worksheet:worksheet_write_formula("A7", "{=SUM(A1:B1*A2:B2)}"); - * - * @endcode - * - * See also the `worksheet_write_array_formula()` method below. - * - * Both row-column and A1 style notation are supported. See :ref:`cell_notation` - * for more details. - * - * The `format` parameter is used to apply formatting to the cell. This - * parameter is optional but when present is should be a valid - * :ref:`Format ` object. - * - * XlsxWriter doesn't calculate the value of a formula and instead stores the - * value 0 as the formula result. It then sets a global flag in the XLSX file to - * say that all formulas and functions should be recalculated when the file is - * opened. This is the method recommended in the Excel documentation and in - * general it works fine with spreadsheet applications. However, applications - * that don't have a facility to calculate formulas, such as Excel Viewer, or - * some mobile applications will only display the 0 results. - * - * If required, it is also possible to specify the calculated result of the - * formula using the options `value` parameter. This is occasionally necessary - * when working with non-Excel applications that don't calculate the value of the - * formula. The calculated `value` is added at the end of the argument list: - * - * @code - * worksheet:write(0, 0, "=2+2", num_format, 4); - * - * @endcode - * - * Excel stores formulas in US style formatting regardless of the Locale or - * Language of the Excel version. Therefore all formula names written using - * XlsxWriter must be in English (use the following - * `formula translator `_ if necessary). Also, - * formulas must be written with the US style separator/range operator which is a - * comma (not semi-colon). Therefore a formula with multiple values should be - * written as follows: - * - * @code - * worksheet:worksheet_write_formula(0, 0, "=SUM(1, 2, 3)"); // OK - * worksheet:worksheet_write_formula(1, 0, "=SUM(1; 2; 3)"); // NO. Error on load. - * - * @endcode - * - * Excel 2010 and 2013 added functions which weren't defined in the original file - * specification. These functions are referred to as *future* functions. Examples - * of these functions are `ACOT`, `CHISQ.DIST.RT` , `CONFIDENCE.NORM`, - * `STDEV.P`, `STDEV.S` and `WORKDAY.INTL`. The full list is given in the - * `MS XLSX extensions documentation on future functions `_. - * - * When written using `worksheet_write_formula()` these functions need to be fully - * qualified with the `_xlfn.` prefix as they are shown in the MS XLSX - * documentation link above. For example: - * - * @code - * worksheet:worksheet_write_formula(0, 0, "=_xlfn.STDEV.S(B1:B10)"); - * - * - * @endcode - * - * worksheet:worksheet_write_array_formula() - */ - - * -/** - * @brief * - * Write an array formula to a worksheet cell. - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @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 formula Array formula to write to cell. - * @param format Optional Format object. :ref:`Format ` - * - * The `worksheet_write_array_formula()` method write an array formula to a cell range. In - * Excel an array formula is a formula that performs a calculation on a set of - * values. It can return a single value or a range of values. - * - * An array formula is indicated by a pair of braces around the formula: - * `{=SUM(A1:B1*A2:B2)}`. - * - * For array formulas that return a range of values you must specify the range - * that the return values will be written to: - * - * @code - * worksheet:worksheet_write_array_formula("A1:A3", "{=TREND(C1:C3,B1:B3)}"); - * worksheet:worksheet_write_array_formula(0, 0, 2, 0, "{=TREND(C1:C3,B1:B3)}"); - * - * @endcode - * - * If the array formula returns a single value then the `first_` and `last_` - * parameters should be the same: - * - * @code - * worksheet:worksheet_write_array_formula("A1:A1", "{=SUM(B1:C1*B2:C2)}"); - * - * @endcode - * - * It this case however it is easier to just use the `worksheet_write_formula()` or - * `write()` methods: - * - * @code - * // Same as above but more concise. - * worksheet:write(0, 0, "{=SUM(B1:C1*B2:C2)}"); - * worksheet:worksheet_write_formula(0, 0, "{=SUM(B1:C1*B2:C2)}"); - * - * @endcode - * - * As shown above, both row-column and A1 style notation are supported. See - * :ref:`cell_notation` for more details. - * - * The `format` parameter is used to apply formatting to the cell. This - * parameter is optional but when present is should be a valid - * :ref:`Format ` object. - * - * If required, it is also possible to specify the calculated value of the - * formula. This is occasionally necessary when working with non-Excel - * applications that don't calculate the value of the formula. The calculated - * `value` is added at the end of the argument list: - * - * @code - * worksheet:worksheet_write_array_formula("A1:A3", "{=TREND(C1:C3,B1:B3)}", format, 105); - * - * @endcode - * - * See also :ref:`ex_array_formula`. - * - * - * worksheet:worksheet_write_blank() - */ - - * -/** - * @brief Write a blank worksheet cell. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param row The zero indexed row number. - * @param col The zero indexed column number. - * @param blank None or empty string. The value is ignored. - * @param format Optional Format object. :ref:`Format ` - * - * Write a blank cell specified by `row` and `column`: - * - * @code - * worksheet:worksheet_write_blank(0, 0, None, format); - * - * @endcode - * - * This method is used to add formatting to a cell which doesn't contain a string - * or number value. - * - * Excel differentiates between an "Empty" cell and a "Blank" cell. An "Empty" - * cell is a cell which doesn't contain data or formatting whilst a "Blank" cell - * doesn't contain data but does contain formatting. Excel stores "Blank" cells - * but ignores "Empty" cells. - * - * As such, if you write an empty cell without formatting it is ignored: - * - * @code - * worksheet:write(0, 0, None, format); // worksheet_write_blank(); - * worksheet:write(1, 0, None); // Ignored - * - * @endcode - * - * This seemingly uninteresting fact means that you can write arrays of data - * without special treatment for `None` or empty string values. - * - * As shown above, both row-column and A1 style notation are supported. See - * :ref:`cell_notation` for more details. - * - * worksheet:worksheet_write_boolean() - */ - - * -/** - * @brief Write a boolean value to a worksheet cell. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param row The zero indexed row number. - * @param col The zero indexed column number. - * @param boolean Boolean value to write to cell. - * @param format Optional Format object. :ref:`Format ` - * - * The `worksheet_write_boolean()` method writes a boolean value to the cell specified by - * `row` and `column`: - * - * @code - * worksheet:worksheet_write_boolean(0, 0, true); - * worksheet:worksheet_write_boolean(1, 0, false); - * - * @endcode - * - * Both row-column and A1 style notation are supported. See :ref:`cell_notation` - * for more details. - * - * The `format` parameter is used to apply formatting to the cell. This - * parameter is optional but when present is should be a valid - * :ref:`Format ` object. - * - * - * worksheet:worksheet_write_datetime() - */ - - * -/** - * @brief Write a date or time to a worksheet cell. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param row The zero indexed row number. - * @param col The zero indexed column number. - * @param datetime A datetime.datetime, .date or .time object. - * @param format Optional Format object. :ref:`Format ` - * - * The `worksheet_write_datetime()` method can be used to write a date or time to the cell - * specified by `row` and `column`: - * - * @code - * worksheet:worksheet_write_datetime(0, 0, datetime, date_format); - * - * @endcode - * - * The datetime should be a :class:`datetime.datetime`, :class:`datetime.date` or - * :class:`datetime.time` object. The :mod:`datetime` class is part of the - * standard Python libraries. - * - * There are many way to create datetime objects, for example the - * :meth:`datetime.datetime.strptime` method: - * - * @code - * date_time = datetime.datetime.strptime("2013-01-23", "%Y-%m-%d"); - * - * @endcode - * - * See the :mod:`datetime` documentation for other date/time creation methods. - * - * A date/time should have a `format` of type :ref:`Format `, - * otherwise it will appear as a number: - * - * @code - * date_format = workbook:add_format({num_format = "d mmmm yyyy"}); - * - * worksheet:worksheet_write_datetime(0, 0, date_time, date_format); - * - * @endcode - * - * If required, a default date format string can be set using the Workbook() - * constructor `default_date_format` option. - * - * See :ref:`working_with_dates_and_time` for more details. - * - * - * worksheet:worksheet_write_url() - */ - - * -/** - * @brief Write a hyperlink to a worksheet cell. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param row The zero indexed row number. - * @param col The zero indexed column number. - * @param url Hyperlink url. - * @param format Optional Format object. Defaults to blue underline. - * @param string An optional display string for the hyperlink. - * @param tip An optional tooltip. - * - * The `worksheet_write_url()` method is used to write a hyperlink in a worksheet cell. - * The url is comprised of two elements: the displayed string and the - * non-displayed link. The displayed string is the same as the link unless an - * alternative string is specified. - * - * Both row-column and A1 style notation are supported. See :ref:`cell_notation` - * for more details. - * - * The `format` parameter is used to apply formatting to the cell. This - * parameter is optional. Since a hyperlink without a format doesn't look like a - * link the following default :ref:`Format ` is used: - * - * @code - * workbook:add_format({color = "blue", underline = 1}); - * - * @endcode - * - * Therefore the following are equivalent: - * - * @code - * link_format = workbook:add_format({color = "blue", underline = 1}); - * worksheet:worksheet_write_url(0, 0, "ftp://www.python.org/", link_format); - * - * // Same as: - * worksheet:worksheet_write_url(0, 0, "ftp://www.python.org/"); // Default format. - * - * @endcode - * - * Four web style URI's are supported: `http://`, `https://`, `ftp://` and - * `mailto:`: - * - * @code - * worksheet:worksheet_write_url(0, 0, "ftp://www.python.org/"); - * worksheet:worksheet_write_url(1, 0, "http://www.python.org/"); - * worksheet:worksheet_write_url(2, 0, "https://www.python.org/"); - * worksheet:worksheet_write_url(3, 0, "mailto:jmcnamaracpan.org"); - * - * @endcode - * - * All of the these URI types are recognised by the :func:`write()` method, so the - * following are equivalent: - * - * @code - * worksheet:worksheet_write_url(1, 0, "http://www.python.org/"); - * worksheet:write (1, 0, "http://www.python.org/"); // Same. - * - * @endcode - * - * You can display an alternative string using the `string` parameter: - * - * @code - * worksheet:worksheet_write_url(0, 0, "http://www.python.org", link_format, "Python"); - * - * @endcode - * - * .. Note:: - * - * If you wish to have some other cell data such as a number or a formula you - * can overwrite the cell using another call to `worksheet_write_*()`: - * - * @code - * worksheet:worksheet_write_url(0, 0, "http://www.python.org/", link_format); - * - * // Overwrite the URL string with a formula. The cell is still a link. - * worksheet:worksheet_write_formula(0, 0, "=1+1", link_format); - * - * @endcode - * - * There are two local URIs supported: `internal:` and `external:`. These are - * used for hyperlinks to internal worksheet references or external workbook and - * worksheet references: - * - * @code - * worksheet:worksheet_write_url(0, 0, "internal:Sheet2!A1"); - * worksheet:worksheet_write_url(1, 0, "internal:Sheet2!A1"); - * worksheet:worksheet_write_url(2, 0, "internal:Sheet2!A1:B2"); - * worksheet:worksheet_write_url(3, 0, "internal:'Sales Data'!A1"); - * worksheet:worksheet_write_url("A5", r"external:c:\temp\foo.xlsx"); - * worksheet:worksheet_write_url("A6", r"external:c:\foo.xlsx#Sheet2!A1"); - * worksheet:worksheet_write_url("A7", r"external:..\foo.xlsx"); - * worksheet:worksheet_write_url("A8", r"external:..\foo.xlsx#Sheet2!A1"); - * worksheet:worksheet_write_url("A9", r"external:\\NET\share\foo.xlsx"); - * - * @endcode - * - * Worksheet references are typically of the form `Sheet1!A1`. You can also link - * to a worksheet range using the standard Excel notation: `Sheet1!A1:B2`. - * - * In external links the workbook and worksheet name must be separated by the - * `#` character: `external:Workbook:xlsx#Sheet1!A1'`. - * - * You can also link to a named range in the target worksheet: For example say you - * have a named range called `my_name` in the workbook `c:\temp\foo.xlsx` you - * could link to it as follows: - * - * @code - * worksheet:worksheet_write_url("A14", r"external:c:\temp\foo.xlsx#my_name"); - * - * @endcode - * - * Excel requires that worksheet names containing spaces or non alphanumeric - * characters are single quoted as follows `'Sales Data'!A1`. - * - * Links to network files are also supported. Network files normally begin with - * two back slashes as follows `\\NETWORK\etc`. In order to generate this in a - * single or double quoted string you will have to escape the backslashes, - * `'\\\\NETWORK\\etc'` or use a raw string `r'\\NETWORK\etc'`. - * - * Alternatively, you can avoid most of these quoting problems by using forward - * slashes. These are translated internally to backslashes: - * - * @code - * worksheet:worksheet_write_url("A14", "external:c:/temp/foo.xlsx"); - * worksheet:worksheet_write_url("A15", "external://NETWORK/share/foo.xlsx"); - * - * @endcode - * - * See also :ref:`ex_hyperlink`. - * - * .. note:: - * XlsxWriter will escape the following characters in URLs as required - * by Excel: `\s " < > \ [ ] ` ^ { }` unless the URL already contains `%xx` - * style escapes. In which case it is assumed that the URL was escaped - * correctly by the user and will by passed directly to Excel. - * - * - * worksheet:worksheet_write_rich_string() - */ - - * -/** - * @brief Write a "rich" string with multiple formats to a worksheet cell. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param row The zero indexed row number. - * @param col The zero indexed column number. - * @param string_parts String and format pairs. - * @param format Optional Format object. :ref:`Format ` - * - * - * The `worksheet_write_rich_string()` method is used to write strings with multiple - * formats. For example to write the string "This is **bold** and this is - * *italic*" you would use the following: - * - * @code - * bold = workbook:add_format({bold = true}); - * italic = workbook:add_format({italic = true}); - * - * worksheet:worksheet_write_rich_string(0, 0, - * "This is ", - * bold, "bold", - * " and this is ", - * italic, "italic"); - * - * @endcode - * - * @image html rich_strings_small.png - * - * The basic rule is to break the string into fragments and put a - * :func:`Format ` object before the fragment that you want to format. - * For example: - * - * @code - * // Unformatted string. - * "This is an example string" - * - * // Break it into fragments. - * "This is an ", "example", " string" - * - * // Add formatting before the fragments you want formatted. - * "This is an ", format, "example", " string" - * - * // In XlsxWriter. - * worksheet:worksheet_write_rich_string(0, 0, - * "This is an ", format, "example", " string"); - * - * @endcode - * - * String fragments that don't have a format are given a default format. So for - * example when writing the string "Some **bold** text" you would use the first - * example below but it would be equivalent to the second: - * - * @code - * // Some bold format and a default format. - * bold = workbook:add_format({bold = true}); - * default = workbook:add_format(); - * - * // With default formatting: - * worksheet:worksheet_write_rich_string(0, 0, - * "Some ", - * bold, "bold", - * " text"); - * - * // Or more explicitly: - * worksheet:worksheet_write_rich_string(0, 0, - * default, "Some ", - * bold, "bold", - * default, " text"); - * - * @endcode - * - * In Excel only the font properties of the format such as font name, style, size, - * underline, color and effects are applied to the string fragments in a rich - * string. Other features such as border, background, text wrap and alignment - * must be applied to the cell. - * - * The `worksheet_write_rich_string()` method allows you to do this by using the last - * argument as a cell format (if it is a format object). The following example - * centers a rich string in the cell: - * - * @code - * bold = workbook:add_format({bold = true}); - * center = workbook:add_format({align = "center"}); - * - * worksheet:worksheet_write_rich_string("A5", - * "Some ", - * bold, "bold text", - * " centered", - * center); - * - * - * @endcode - * - * See also :ref:`ex_rich_strings` and :ref:`ex_merge_rich`. - * - * worksheet:worksheet_write_row() - */ - - * -/** - * @brief Write a row of data starting from (row, col). - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param row The zero indexed row number. - * @param col The zero indexed column number. - * @param data Cell data to write. Variable types. - * @param format Optional Format object. :ref:`Format ` - * - * The `worksheet_write_row()` method can be used to write a list of data in one go. This - * is useful for converting the results of a database query into an Excel - * worksheet: The :func:`write()` method is called for each element of the data. - * For example: - * - * @code - * // Some sample data. - * data = ("Foo", "Bar", "Baz"); - * - * // Write the data to a sequence of cells. - * worksheet:worksheet_write_row(0, 0, data); - * - * // The above example is equivalent to: - * worksheet:write(0, 0, data[0]); - * worksheet:write("B1", data[1]); - * worksheet:write("C1", data[2]); - * - * - * @endcode - * - * worksheet:worksheet_write_column() - */ - - * -/** - * @brief Write a column of data starting from (row, col). - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param row The zero indexed row number. - * @param col The zero indexed column number. - * @param data Cell data to write. Variable types. - * @param format Optional Format object. :ref:`Format ` - * - * The `worksheet_write_column()` method can be used to write a list of data in one go. - * This is useful for converting the results of a database query into an Excel - * worksheet: The :func:`write()` method is called for each element of the data. - * For example: - * - * @code - * // Some sample data. - * data = ("Foo", "Bar", "Baz"); - * - * // Write the data to a sequence of cells. - * worksheet:worksheet_write_column(0, 0, data); - * - * // The above example is equivalent to: - * worksheet:write(0, 0, data[0]); - * worksheet:write(1, 0, data[1]); - * worksheet:write(2, 0, data[2]); - * - * - * @endcode - * - * worksheet:set_row() - */ - - * -/** - * @brief Set properties for a row of cells. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param int row The worksheet row (zero indexed). - * @param float height The row height. - * @param format Optional Format object. :ref:`Format ` - * @param dict options Optional row parameters: hidden, level, collapsed. - * - * The `set_row()` method is used to change the default properties of a row. The - * most common use for this method is to change the height of a row: - * - * @code - * worksheet:set_row(0, 20); // Set the height of Row 1 to 20. - * - * @endcode - * - * The other common use for `set_row()` is to set the :ref:`Format ` for - * all cells in the row: - * - * @code - * format = workbook:add_format({bold = true}); - * - * worksheet:set_row(0, 20, format); - * - * @endcode - * - * If you wish to set the format of a row without changing the height you can pass - * `None` as the height parameter or use the default row height of 15: - * - * @code - * worksheet:set_row(1, None, format); - * worksheet:set_row(1, 15, format); // Same as above. - * - * @endcode - * - * The `format` parameter will be applied to any cells in the row that - * don't have a format. As with Excel it is overridden by an explicit cell - * format. For example: - * - * @code - * worksheet:set_row(0, None, format1); // Row 1 has format1. - * - * worksheet:write(0, 0, "Hello"); // Cell A1 defaults to format1. - * worksheet:write("B1", "Hello", format2); // Cell B1 keeps format2. - * - * @endcode - * - * The `options` parameter is a dictionary with the following possible keys: - * - * * `"hidden"` - * * `"level"` - * * `"collapsed"` - * - * Options can be set as follows: - * - * @code - * worksheet:set_row(0, 20, format, {hidden = true}); - * - * // Or use defaults for other properties and set the options only. - * worksheet:set_row(0, None, None, {hidden = true}); - * - * @endcode - * - * The `"hidden"` option is used to hide a row. This can be used, for example, - * to hide intermediary steps in a complicated calculation: - * - * @code - * worksheet:set_row(0, 20, format, {hidden = true}); - * - * @endcode - * - * The `"level"` parameter is used to set the outline level of the row. Outlines - * are described in :ref:`outlines`. Adjacent rows with the same outline level - * are grouped together into a single outline. - * - * The following example sets an outline level of 1 for some rows: - * - * @code - * worksheet:set_row(0, None, None, {level = 1}); - * worksheet:set_row(1, None, None, {level = 1}); - * worksheet:set_row(2, None, None, {level = 1}); - * - * @endcode - * - * Excel allows up to 7 outline levels. The `"level"` parameter should be in the - * range `0 <= level <= 7`. - * - * The `"hidden"` parameter can also be used to hide collapsed outlined rows - * when used in conjunction with the `"level"` parameter: - * - * @code - * worksheet:set_row(1, None, None, {hidden = 1, level = 1}); - * worksheet:set_row(2, None, None, {hidden = 1, level = 1}); - * - * @endcode - * - * The `"collapsed"` parameter is used in collapsed outlines to indicate which - * row has the collapsed `'+'` symbol: - * - * @code - * worksheet:set_row(3, None, None, {collapsed = 1}); - * - * - * @endcode - * - * worksheet:set_column() - */ - - * -/** - * @brief Set properties for one or more columns of cells. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param int first_col First column (zero-indexed). - * @param int last_col Last column (zero-indexed). Can be same as firstcol. - * @param float width The width of the column(s). - * @param format Optional Format object. :ref:`Format ` - * @param dict options Optional parameters: hidden, level, collapsed. - * - * The `set_column()` method can be used to change the default properties of a - * single column or a range of columns: - * - * @code - * worksheet:set_column(1, 3, 30); // Width of columns B:D set to 30. - * - * @endcode - * - * If `set_column()` is applied to a single column the value of `first_col` - * and `last_col` should be the same: - * - * @code - * worksheet:set_column(1, 1, 30); // Width of column B set to 30. - * - * @endcode - * - * It is also possible, and generally clearer, to specify a column range using the - * form of A1 notation used for columns. See :ref:`cell_notation` for more - * details. - * - * Examples: - * - * @code - * worksheet:set_column(0, 0, 20); // Column A width set to 20. - * worksheet:set_column(1, 3, 30); // Columns B-D width set to 30. - * worksheet:set_column("E:E", 20); // Column E width set to 20. - * worksheet:set_column("F:H", 30); // Columns F-H width set to 30. - * - * @endcode - * - * The width corresponds to the column width value that is specified in Excel. It - * is approximately equal to the length of a string in the default font of - * Calibri 11. Unfortunately, there is no way to specify "AutoFit" for a column - * in the Excel file format. This feature is only available at runtime from - * within Excel. It is possible to simulate "AutoFit" by tracking the width of - * the data in the column as your write it. - * - * As usual the `format` :ref:`Format ` parameter is optional. If - * you wish to set the format without changing the width you can pass `None` as - * the width parameter: - * - * @code - * format = workbook:add_format({bold = true}); - * - * worksheet:set_column(0, 0, None, format); - * - * @endcode - * - * The `format` parameter will be applied to any cells in the column that - * don't have a format. For example: - * - * @code - * worksheet:set_column("A:A", None, format1); // Col 1 has format1. - * - * worksheet:write(0, 0, "Hello"); // Cell A1 defaults to format1. - * worksheet:write(1, 0, "Hello", format2); // Cell A2 keeps format2. - * - * @endcode - * - * A row format takes precedence over a default column format: - * - * @code - * worksheet:set_row(0, None, format1); // Set format for row 1. - * worksheet:set_column("A:A", None, format2); // Set format for col 1. - * - * worksheet:write(0, 0, "Hello"); // Defaults to format1 - * worksheet:write(1, 0, "Hello"); // Defaults to format2 - * - * @endcode - * - * The `options` parameter is a dictionary with the following possible keys: - * - * * `"hidden"` - * * `"level"` - * * `"collapsed"` - * - * Options can be set as follows: - * - * @code - * worksheet:set_column("D:D", 20, format, {hidden = 1}); - * - * // Or use defaults for other properties and set the options only. - * worksheet:set_column("E:E", None, None, {hidden = 1}); - * - * @endcode - * - * The `"hidden"` option is used to hide a column. This can be used, for - * example, to hide intermediary steps in a complicated calculation: - * - * @code - * worksheet:set_column("D:D", 20, format, {hidden = 1}); - * - * @endcode - * - * The `"level"` parameter is used to set the outline level of the column. - * Outlines are described in :ref:`outlines`. Adjacent columns with the same - * outline level are grouped together into a single outline. - * - * The following example sets an outline level of 1 for columns B to G: - * - * @code - * worksheet:set_column("B:G", None, None, {level = 1}); - * - * @endcode - * - * Excel allows up to 7 outline levels. The `"level"` parameter should be in the - * range `0 <= level <= 7`. - * - * The `"hidden"` parameter can also be used to hide collapsed outlined columns - * when used in conjunction with the `"level"` parameter: - * - * @code - * worksheet:set_column("B:G", None, None, {hidden = 1, level = 1}); - * - * @endcode - * - * The `"collapsed"` parameter is used in collapsed outlines to indicate which - * column has the collapsed `'+'` symbol: - * - * @code - * worksheet:set_column("H:H", None, None, {collapsed = 1}); - * - * @endcode - * - * worksheet:insert_image() - */ - - * -/** - * @brief Write a string to a worksheet cell. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param row The zero indexed row number. - * @param col The zero indexed column number. - * @param image Image filename (with path if required). - * @param options Optional parameters for image position, scale and url. - * - * This method can be used to insert a image into a worksheet: The image can be in - * PNG, JPEG or BMP format: - * - * @code - * worksheet:insert_image("B2", "python.png"); - * - * @endcode - * - * @image html insert_image.png - * - * A file path can be specified with the image name: - * - * @code - * worksheet1.insert_image("B10", "../images/python.png"); - * worksheet2.insert_image("B20", r"c:\images\python.png"); - * - * @endcode - * - * The `insert_image()` method takes optional parameters in a dictionary to - * position and scale the image. The available parameters with their default - * values are: - * - * @code - * { - * x_offset = 0, - * y_offset = 0, - * x_scale = 1, - * y_scale = 1, - * url = None, - * tip = None, - * } - * - * @endcode - * - * The offset values are in pixels: - * - * @code - * worksheet1.insert_image("B2", "python.png", {x_offset = 15, y_offset = 10}); - * - * @endcode - * - * The offsets can be greater than the width or height of the underlying cell. - * This can be occasionally useful if you wish to align two or more images - * relative to the same cell. - * - * The `x_scale` and `y_scale` parameters can be used to scale the image - * horizontally and vertically: - * - * @code - * worksheet:insert_image("B3", "python.png", {x_scale = 0.5, y_scale = 0.5}); - * - * @endcode - * - * The `url` parameter can used to add a hyperlink/url to the image. The `tip` - * parameter gives an option mouseover tooltip for images with hyperlinks: - * - * @code - * worksheet:insert_image("By", "python.png", {url = "http://python.org"}); - * - * @endcode - * - * See also worksheet_write_url() for details on supported URIs. - * - * .. Note:: - * The scaling of a image may be affected if is crosses a row that has its - * default height changed due to a font that is larger than the default font - * size or that has text wrapping turned on. To avoid this you should - * explicitly set the height of the row using `set_row()` if it crosses an - * inserted image. - * - * Inserting images into headers or a footers isn't supported. - * - * BMP images are only supported for backward compatibility. In general it is best - * to avoid BMP images since they aren't compressed. If used, BMP images must be - * 24 bit, true colour, bitmaps. - * - * See also :ref:`ex_insert_image`. - * - * worksheet:insert_chart() - */ - - * -/** - * @brief Write a string to a worksheet cell. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param row The zero indexed row number. - * @param col The zero indexed column number. - * @param chart A chart object. - * @param options Optional parameters to position and scale the chart. - * - * This method can be used to insert a chart into a worksheet: A chart object is - * created via the Workbook :func:`add_chart()` method where the chart type is - * specified: - * - * @code - * chart = workbook:add_chart({type, "column"}); - * - * @endcode - * - * It is then inserted into a worksheet as an embedded chart: - * - * @code - * worksheet:insert_chart("B5", chart); - * - * @endcode - * - * @image html chart_simple.png - * :scale: 75 % - * - * See :ref:`chart_class`, :ref:`working_with_charts` and :ref:`chart_examples`. - * - * The `insert_chart()` method takes optional parameters in a dictionary to - * position and scale the chart. The available parameters with their default - * values are: - * - * @code - * { - * x_offset = 0, - * y_offset = 0, - * x_scale = 1, - * y_scale = 1, - * } - * - * @endcode - * - * The offset values are in pixels: - * - * @code - * worksheet:insert_chart("B5", chart, {x_offset = 25, y_offset = 10}); - * - * @endcode - * - * The `x_scale` and `y_scale` parameters can be used to scale the chart - * horizontally and vertically: - * - * @code - * worksheet:insert_chart("B5", chart, {x_scale = 0.5, y_scale = 0.5}); - * - * @endcode - * - * These properties can also be set via the Chart set_size() method. - * - * .. Note:: - * The scaling of a chart may be affected if is crosses a row that has its - * default height changed due to a font that is larger than the default font - * size or that has text wrapping turned on. To avoid this you should - * explicitly set the height of the row using `set_row()` if it crosses an - * inserted chart. - * - * - * worksheet:data_validation() - */ - - * -/** - * @brief * - * Write a conditional format to range of cells. - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @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 options Data validation options. - * - * - * The `data_validation()` method is used to construct an Excel data validation - * or to limit the user input to a dropdown list of values: - * - * @code - * worksheet:data_validation("B3", {validate = "integer", - * criteria = "between", - * minimum = 1, - * maximum = 10}); - * - * - * worksheet:data_validation("B13", {validate = "list", - * source = ["open", "high", "close"]}); - * - * @endcode - * - * @image html data_validate1.png - * - * The data validation can be applied to a single cell or a range of cells. As - * usual you can use A1 or Row/Column notation, see :ref:`cell_notation`. - * - * With Row/Column notation you must specify all four cells in the range: - * `(first_row, first_col, last_row, last_col)`. If you need to refer to a - * single cell set the `last_` values equal to the `first_` values. With A1 - * notation you can refer to a single cell or a range of cells: - * - * @code - * worksheet:data_validation(0, 0, 4, 1, {...}); - * worksheet:data_validation("B1", {...}); - * worksheet:data_validation("C1:E5", {...}); - * - * - * @endcode - * - * The options parameter in `data_validation()` must be a dictionary containing - * the parameters that describe the type and style of the data validation. There - * are a lot of available options which are described in detail in a separate - * section: :ref:`working_with_data_validation`. See also :ref:`ex_data_valid`. - * - * - * - * worksheet:conditional_format() - */ - - * -/** - * @brief * - * Write a conditional format to range of cells. - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @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 options Conditional formatting options. - * - * The `conditional_format()` method is used to add formatting to a cell or - * range of cells based on user defined criteria: - * - * @code - * worksheet:conditional_format("B3:K12", {type = "cell", - * criteria = ">=", - * value = 50, - * format = format1}); - * - * @endcode - * - * @image html conditional_format1.png - * - * The conditional format can be applied to a single cell or a range of cells. As - * usual you can use A1 or Row/Column notation, see :ref:`cell_notation`. - * - * With Row/Column notation you must specify all four cells in the range: - * `(first_row, first_col, last_row, last_col)`. If you need to refer to a - * single cell set the `last_` values equal to the `first_` values. With A1 - * notation you can refer to a single cell or a range of cells: - * - * @code - * worksheet:conditional_format(0, 0, 4, 1, {...}); - * worksheet:conditional_format("B1", {...}); - * worksheet:conditional_format("C1:E5", {...}); - * - * - * @endcode - * - * The options parameter in `conditional_format()` must be a dictionary - * containing the parameters that describe the type and style of the conditional - * format. There are a lot of available options which are described in detail in - * a separate section: :ref:`working_with_conditional_formats`. See also - * :ref:`ex_cond_format`. - * - * - * worksheet:add_table() - */ - - * -/** - * @brief Add an Excel table to a worksheet: - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @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 options Table formatting options. (Optional) - * - * - * The `add_table()` method is used to group a range of cells into an Excel - * Table: - * - * @code - * worksheet:add_table("B3:F7", { ... }); - * - * @endcode - * - * This method contains a lot of parameters and is described in :ref:`tables`. - * - * See also :ref:`ex_tables`. - * - * - * worksheet:add_sparkline() - */ - - * -/** - * @brief Add sparklines to a worksheet: - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param int row The zero indexed row number. - * @param int col The zero indexed column number. - * @param dict options Sparkline formatting options. - * - * - * Sparklines are small charts that fit in a single cell and are used to show - * trends in data. - * - * @image html sparklines1.png - * - * The `add_sparkline()` worksheet method is used to add sparklines to a cell or - * a range of cells: - * - * @code - * worksheet:add_sparkline("F1", {range = "A1:E1"}); - * - * @endcode - * - * This method contains a lot of parameters and is described in detail in - * :ref:`sparklines`. - * - * - * - * See also :ref:`ex_sparklines1` and :ref:`ex_sparklines2`. - * - * .. Note:: - * Sparklines are a feature of Excel 2010+ only. You can write them to - * an XLSX file that can be read by Excel 2007 but they won't be displayed. - * - * - * worksheet:worksheet_write_comment() - */ - - * -/** - * @brief Write a comment to a worksheet cell. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param row The zero indexed row number. - * @param col The zero indexed column number. - * @param comment String to write to cell. - * @param options Comment formatting options.. - * - * The `worksheet_write_comment()` method is used to add a comment to a cell. A comment is - * indicated in Excel by a small red triangle in the upper right-hand corner of - * the cell. Moving the cursor over the red triangle will reveal the comment. - * - * The following example shows how to add a comment to a cell: - * - * @code - * worksheet:write(0, 0, "Hello"); - * worksheet:worksheet_write_comment(0, 0, "This is a comment"); - * - * @endcode - * - * @image html comments1.png - * - * As usual you can replace the `row` and `col` parameters with an `A1` cell - * reference. See :ref:`cell_notation` for more details. - * - * The properties of the cell comment can be modified by passing an optional - * dictionary of key/value pairs to control the format of the comment. For - * example: - * - * @code - * worksheet:worksheet_write_comment("C3", "Hello", {x_scale = 1.2, y_scale = 0.8}); - * - * @endcode - * - * Most of these options are quite specific and in general the default comment - * behaviour will be all that you need. However, should you need greater control - * over the format of the cell comment the following options are available: - * - * @code - * author - * visible - * x_scale - * width - * y_scale - * height - * color - * start_cell - * start_row - * start_col - * x_offset - * y_offset - * - * @endcode - * - * For more details see :ref:`cell_comments` and :ref:`ex_comments2` . - * - * worksheet:show_comments() - */ - - * -/** - * @brief Make any comments in the worksheet visible. - * - * - * This method is used to make all cell comments visible when a worksheet is - * opened: - * - * @code - * worksheet:show_comments(); - * - * @endcode - * - * Individual comments can be made visible using the `visible` parameter of the - * `worksheet_write_comment` method (see above): - * - * @code - * worksheet:worksheet_write_comment("C3", "Hello", {visible = true}); - * - * @endcode - * - * If all of the cell comments have been made visible you can hide individual - * comments as follows: - * - * @code - * worksheet:show_comments(); - * worksheet:worksheet_write_comment("C3", "Hello", {visible = false}); - * - * @endcode - * - * For more details see :ref:`cell_comments` and :ref:`ex_comments2` . - * - * - * worksheet:set_comments_author() - */ - - * -/** - * @brief Set the default author of the cell comments. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param string author Comment author. - * - * This method is used to set the default author of all cell comments: - * - * @code - * worksheet:set_comments_author("John Smith"); - * - * @endcode - * - * Individual comment authors can be set using the `author` parameter of the - * `worksheet_write_comment` method (see above). - * - * If no author is specified the default comment author name is an empty string. - * - * For more details see :ref:`cell_comments` and :ref:`ex_comments2` . - * - * - * worksheet:get_name() - */ - - * -/** - * @brief Retrieve the worksheet name. - * - * - * The `get_name()` method is used to retrieve the name of a worksheet: This is - * something useful for debugging or logging: - * - * @code - * for worksheet in workbook:worksheets(): - * print worksheet:get_name(); - * - * @endcode - * - * There is no `set_name()` method. The only safe way to set the worksheet name - * is via the `add_worksheet()` method. - * - * - * worksheet:activate() - */ - - * -/** - * @brief Make a worksheet the active, i.e., visible worksheet: - * - * - * The `activate()` method is used to specify which worksheet is initially - * visible in a multi-sheet workbook: - * - * @code - * worksheet1 = workbook:add_worksheet(); - * worksheet2 = workbook:add_worksheet(); - * worksheet3 = workbook:add_worksheet(); - * - * worksheet3.activate(); - * - * @endcode - * - * @image html worksheet_activate.png - * - * More than one worksheet can be selected via the `select()` method, see below, - * however only one worksheet can be active. - * - * The default active worksheet is the first worksheet: - * - * - * worksheet:select() - */ - - * -/** - * @brief Set a worksheet tab as selected. - * - * - * The `select()` method is used to indicate that a worksheet is selected in a - * multi-sheet workbook: - * - * @code - * worksheet1.activate(); - * worksheet2.select(); - * worksheet3.select(); - * - * @endcode - * - * A selected worksheet has its tab highlighted. Selecting worksheets is a way of - * grouping them together so that, for example, several worksheets could be - * printed in one go. A worksheet that has been activated via the `activate()` - * method will also appear as selected. - * - * - * worksheet:hide() - */ - - * -/** - * @brief Hide the current worksheet: - * - * - * The `hide()` method is used to hide a worksheet: - * - * @code - * worksheet2.hide(); - * - * @endcode - * - * You may wish to hide a worksheet in order to avoid confusing a user with - * intermediate data or calculations. - * - * @image html hide_sheet.png - * - * A hidden worksheet can not be activated or selected so this method is mutually - * exclusive with the :func:`activate()` and :func:`select()` methods. In - * addition, since the first worksheet will default to being the active - * worksheet, you cannot hide the first worksheet without activating another - * sheet: - * - * @code - * worksheet2.activate(); - * worksheet1.hide(); - * - * @endcode - * - * See :ref:`ex_hide_sheet` for more details. - * - * worksheet:set_first_sheet() - */ - - * -/** - * @brief Set current worksheet as the first visible sheet tab. - * - * - * The :func:`activate()` method determines which worksheet is initially selected. - * However, if there are a large number of worksheets the selected worksheet may - * not appear on the screen. To avoid this you can select which is the leftmost - * visible worksheet tab using `set_first_sheet()`: - * - * @code - * for in range(1, 21): - * workbook:add_worksheet - * - * worksheet19.set_first_sheet(); // First visible worksheet tab. - * worksheet20.activate(); // First visible worksheet: - * - * @endcode - * - * This method is not required very often. The default value is the first - * worksheet: - * - * - * worksheet:merge_range() - */ - - * -/** - * @brief * - * Merge a range of cells. - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @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 data Cell data to write. Variable types. - * @param format Optional Format object. :ref:`Format ` - * - * - * The `merge_range()` method allows cells to be merged together so that they - * act as a single area. - * - * Excel generally merges and centers cells at same time. To get similar behaviour - * with XlsxWriter you need to apply a :ref:`Format `: - * - * @code - * merge_format = workbook:add_format({align = "center"}); - * - * worksheet:merge_range("B3:D4", "Merged Cells", merge_format); - * - * @endcode - * - * It is possible to apply other formatting to the merged cells as well: - * - * @code - * merge_format = workbook:add_format({ - * bold = true, - * border = 6, - * align = "center", - * valign = "vcenter", - * fg_color = "#D7E4BC", - * }); - * - * worksheet:merge_range("B3:D4", "Merged Cells", merge_format); - * - * @endcode - * - * @image html merge_range.png - * - * See :ref:`ex_merge1` for more details. - * - * The `merge_range()` method writes its `data` argument using - * :func:`write()`. Therefore it will handle numbers, strings and formulas as - * usual. If this doesn't handle your data correctly then you can overwrite the - * first cell with a call to one of the other - * `worksheet_write_*()` methods using the same :ref:`Format - * ` as in the merged cells. See :ref:`ex_merge_rich`. - * - * @image html merge_rich.png - * - * - * worksheet:autofilter() - */ - - * -/** - * @brief Set the autofilter area in the worksheet: - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @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. - * - * The `autofilter()` method allows an autofilter to be added to a worksheet: An - * autofilter is a way of adding drop down lists to the headers of a 2D range of - * worksheet data. This allows users to filter the data based on simple criteria - * so that some data is shown and some is hidden. - * - * @image html autofilter3.png - * - * To add an autofilter to a worksheet: - * - * @code - * worksheet:autofilter("A1:D11"); - * worksheet:autofilter(0, 0, 10, 3)// Same as above. - * - * @endcode - * - * Filter conditions can be applied using the :func:`filter_column()` or - * :func:`filter_column_list()` methods. - * - * See :ref:`working_with_autofilters` for more details. - * - * - * worksheet:filter_column() - */ - - * -/** - * @brief Set the column filter criteria. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param int col Filter column (zero-indexed). - * @param string criteria Filter criteria. - * - * - * The `filter_column` method can be used to filter columns in a autofilter - * range based on simple conditions. - * - * - * The conditions for the filter are specified using simple expressions: - * - * @code - * worksheet:filter_column("A", "x > 2000"); - * worksheet:filter_column("B", "x > 2000 and x < 5000"); - * - * @endcode - * - * The `col` parameter can either be a zero indexed column number or a string - * column name. - * - * It isn't sufficient to just specify the filter condition. You must also hide - * any rows that don't match the filter condition. See - * :ref:`working_with_autofilters` for more details. - * - * - * worksheet:filter_column_list() - */ - - * -/** - * @brief Set the column filter criteria in Excel 2007 list style. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param int col Filter column (zero-indexed). - * @param list filters List of filter criteria to match. - * - * The `filter_column_list()` method can be used to represent filters with - * multiple selected criteria: - * - * @code - * worksheet:filter_column_list("A", "March", "April", "May"); - * - * @endcode - * - * The `col` parameter can either be a zero indexed column number or a string - * column name. - * - * One or more criteria can be selected: - * - * @code - * worksheet:filter_column_list("A", "March"); - * worksheet:filter_column_list("C", 100, 110, 120, 130); - * - * @endcode - * - * It isn't sufficient to just specify filters. You must also hide any rows that - * don't match the filter condition. See :ref:`working_with_autofilters` for more - * details. - * - * - * worksheet:set_selection() - */ - -/** - * @brief Set the selected cell or cells in a worksheet: - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @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. - * - * - * The `set_selection()` method can be used to specify which cell or range of - * cells is selected in a worksheet: The most common requirement is to select a - * single cell, in which case the `first_` and `last_` parameters should be - * the same. - * - * The active cell within a selected range is determined by the order in which - * `first_` and `last_` are specified. - * - * Examples: - * - * @code - * worksheet1.set_selection(3, 3, 3, 3); // 1. Cell D4. - * worksheet2.set_selection(3, 3, 6, 6); // 2. Cells D4 to G7. - * worksheet3.set_selection(6, 6, 3, 3); // 3. Cells G7 to D4. - * worksheet4.set_selection("D4"); // Same as 1. - * worksheet5.set_selection("D4:G7"); // Same as 2. - * worksheet6.set_selection("G7:D4"); // Same as 3. - * - * @endcode - * - * As shown above, both row-column and A1 style notation are supported. See - * :ref:`cell_notation` for more details. The default cell selection is - * `(0, 0)`, `0, 0`. - * - * - * - * worksheet:freeze_panes() - */ - - * -/** - * @brief Create worksheet panes and mark them as frozen. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param int row The zero indexed row number. - * @param int col The zero indexed column number. - * @param int top_row Topmost visible row in scrolling region of pane. - * @param int left_col Leftmost visible row in scrolling region of pane. - * - * This `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(1, 0); // Freeze the first row. - * worksheet:freeze_panes(1, 0); // Same using A1 notation. - * worksheet:freeze_panes(0, 1); // Freeze the first column. - * worksheet:freeze_panes("B1"); // Same using A1 notation. - * worksheet:freeze_panes(1, 2); // Freeze first row and first 2 columns. - * worksheet:freeze_panes("C2"); // Same using A1 notation. - * - * @endcode - * - * The parameters `top_row` and `left_col` are optional. They are used to - * specify the top-most or left-most visible row or column in the scrolling - * region of the panes. For example to freeze the first row and to have the - * scrolling region begin at row twenty: - * - * @code - * worksheet:freeze_panes(1, 0, 20, 0); - * - * @endcode - * - * You cannot use A1 notation for the `top_row` and `left_col` parameters. - * - * See :ref:`ex_panes` for more details. - * - * - * worksheet:split_panes() - */ - - * -/** - * @brief Create worksheet panes and mark them as split. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param float x The position for the vertical split. - * @param float y The position for the horizontal split. - * @param int top_row Topmost visible row in scrolling region of pane. - * @param int left_col Leftmost visible row in scrolling region of pane. - * - * The `split_panes` method can be used to divide a worksheet into horizontal - * or vertical regions known as panes. This method is different from the - * `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 `y` and `x` are used to specify the vertical and horizontal - * position of the split. The units for `y` and `x` 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 `y` and `x` 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. - * - * You can set one of the `y` and `x` parameters as zero if you do not want - * either a vertical or horizontal split. The parameters `top_row` and - * `left_col` are optional. They are used to specify the top-most or left-most - * visible row or column in the bottom-right pane. - * - * Example: - * - * @code - * worksheet:split_panes(15, 0); // First row. - * worksheet:split_panes(0, 8.43); // First column. - * worksheet:split_panes(15, 8.43); // First row and column. - * - * @endcode - * - * You cannot use A1 notation with this method. - * - * See :ref:`ex_panes` for more details. - * - * - * worksheet:set_zoom() - */ - - * -/** - * @brief Set the worksheet zoom factor. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param int zoom Worksheet zoom factor. - * - * Set the worksheet zoom factor in the range `10 <= zoom <= 400`: - * - * @code - * worksheet1.set_zoom(50); - * worksheet2.set_zoom(75); - * worksheet3.set_zoom(300); - * worksheet4.set_zoom(400); - * - * @endcode - * - * The default zoom factor is 100. It isn't possible to set the zoom to - * "Selection" because it is calculated by Excel at run-time. - * - * Note, `set_zoom()` does not affect the scale of the printed page. For that - * you should use :func:`set_print_scale()`. - * - * - * worksheet:right_to_left() - */ - - * -/** - * @brief Display the worksheet cells from right to left for some versions of Excel. - * - * - * The `right_to_left()` method is used to change the default direction of the - * worksheet from left-to-right, with the A1 cell in the top left, to - * right-to-left, with the A1 cell in the top right. - * - * worksheet:right_to_left() - * - * This is useful when creating Arabic, Hebrew or other near or far eastern - * worksheets that use right-to-left as the default direction. - * - * - * worksheet:hide_zero() - */ - - * -/** - * @brief Hide zero values in worksheet cells. - * - * - * The `hide_zero()` method is used to hide any zero values that appear in - * cells: - * - * @code - * worksheet:hide_zero(); - * - * - * @endcode - * - * worksheet:set_tab_color() - */ - - * -/** - * @brief Set the colour of the worksheet tab. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param string color The tab color. - * - * The `set_tab_color()` method is used to change the colour of the worksheet - * tab: - * - * @code - * worksheet1.set_tab_color("red"); - * worksheet2.set_tab_color("#FF9900"); // Orange - * - * @endcode - * - * The colour can be a Html style `#RRGGBB` string or a limited number named - * colours, see :ref:`colors`. - * - * See :ref:`ex_tab_colors` for more details. - * - * - * worksheet:protect() - */ - - * -/** - * @brief Set the colour of the worksheet tab. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param string password A worksheet password. - * @param dict options A dictionary of worksheet options to protect. - * - * - * The `protect()` method is used to protect a worksheet from modification: - * - * @code - * worksheet:protect(); - * - * @endcode - * - * The `protect()` method also has the effect of enabling a cell's `locked` - * and `hidden` properties if they have been set. A *locked* cell cannot be - * edited and this property is on by default for all cells. A *hidden* cell will - * display the results of a formula but not the formula itself. These properties - * can be set using the set_locked() and set_hidden() format methods. - * - * You can optionally add a password to the worksheet protection: - * - * @code - * worksheet:protect("abc123"); - * - * @endcode - * - * Passing the empty string `""` is the same as turning on protection without a - * password. - * - * You can specify which worksheet elements you wish to protect by passing a - * dictionary in the `options` argument with any or all of the following keys: - * - * @code - * // Default values shown. - * options = { - * objects = false, - * scenarios = false, - * format_cells = false, - * format_columns = false, - * format_rows = false, - * insert_columns = false, - * insert_rows = false, - * insert_hyperlinks = false, - * delete_columns = false, - * delete_rows = false, - * select_locked_cells = true, - * sort = false, - * autofilter = false, - * pivot_tables = false, - * select_unlocked_cells = true, - * } - * - * @endcode - * - * The default boolean values are shown above. Individual elements can be - * protected as follows: - * - * @code - * worksheet:protect("acb123", { insert_rows = 1 }); - * - * @endcode - * - * See also the set_locked() and set_hidden() format methods and - * :ref:`ex_protection`. - * - * .. Note:: - * Worksheet level passwords in Excel offer very weak protection. They not - * encrypt your data and are very easy to deactivate. Full workbook encryption - * is not supported by `XlsxWriter` since it requires a completely different - * file format and would take several man months to implement. - * - * - * worksheet:set_default_row() - */ - - * -/** - * @brief Set the default row properties. - * - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param float height Default height. Optional, defaults to 15. - * @param bool hide_unused_rows Hide unused rows. Optional, defaults to false. - * - * - * The `set_default_row()` method is used to set the limited number of default - * row properties allowed by Excel which are the default height and the option to - * hide unused rows. These parameters are an optimisation used by Excel to set - * row properties without generating a very large file with an entry for each row. - * - * To set the default row height: - * - * @code - * worksheet:set_default_row(24); - * - * @endcode - * - * To hide unused rows: - * - * @code - * worksheet:set_default_row(hide_unused_rows=true); - * - * @endcode - * - * See :ref:`ex_hide_row_col` for more details. - * - * worksheet:outline_settings() - */ - - * -/** - * @brief * - * Control outline settings. - * - * @param worksheet Pointer to a lxw_worksheet instance.. - * @param bool visible Outlines are visible. Optional, defaults to true. - * @param bool symbols_below Show row outline symbols below the outline bar. - * Optional, defaults to true. - * @param bool symbols_right Show column outline symbols to the right of the - * outline bar. Optional, defaults to true. - * @param bool auto_style Use Automatic style. Optional, defaults to false. - * - * - * The `outline_settings()` method is used to control the appearance of outlines - * in Excel. Outlines are described in :ref:`outlines`: - * - * @code - * worksheet1.outline_settings(false, false, false, true); - * - * @endcode - * - * The `"visible"` parameter is used to control whether or not outlines are - * visible. Setting this parameter to `false` will cause all outlines on the - * worksheet to be hidden. They can be un-hidden in Excel by means of the "Show - * Outline Symbols" command button. The default setting is `true` for visible - * outlines. - * - * The `"symbols_below"` parameter is used to control whether the row outline - * symbol will appear above or below the outline level bar. The default setting - * is `true` for symbols to appear below the outline level bar. - * - * The `"symbols_right"` parameter is used to control whether the column outline - * symbol will appear to the left or the right of the outline level bar. The - * default setting is `true` for symbols to appear to the right of the outline - * level bar. - * - * The `"auto_style"` parameter is used to control whether the automatic outline - * generator in Excel uses automatic styles when creating an outline. This has no - * effect on a file generated by `XlsxWriter` but it does have an effect on how - * the worksheet behaves after it is created. The default setting is `false` - * for "Automatic Styles" to be turned off. - * - * The default settings for all of these parameters correspond to Excel's default - * parameters. - * - * The worksheet parameters controlled by `outline_settings()` are rarely used. - * - * - * - * diff --git a/include/xlsxwriter/workbook.h b/include/xlsxwriter/workbook.h index ea696b47..c87b3986 100644 --- a/include/xlsxwriter/workbook.h +++ b/include/xlsxwriter/workbook.h @@ -61,7 +61,7 @@ enum lxw_close_error { LXW_CLOSE_ERROR_NONE, /** Error encountered when creating file zip container */ LXW_CLOSE_ERROR_ZIP - /* TODO. Need to add/document more. */ + /* TODO. Need to add/document more. */ }; /** diff --git a/include/xlsxwriter/worksheet.h b/include/xlsxwriter/worksheet.h index 8d8072e5..ef50ce80 100644 --- a/include/xlsxwriter/worksheet.h +++ b/include/xlsxwriter/worksheet.h @@ -1,6 +1,6 @@ /* * libxlsxwriter - * + * * Copyright 2014, John McNamara, jmcnamara@cpan.org. See LICENSE.txt. */ @@ -12,7 +12,7 @@ * layout. * * See @ref worksheet.h for full details of the functionality. - * + * * @file worksheet.h * * @brief Functions related to adding data and formatting to a worksheet. @@ -24,7 +24,7 @@ * A Worksheet object isn’t created directly. Instead a worksheet is * created by calling the workbook_add_worksheet() method from a * Workbook object: - * + * * @code * #include "xlsxwriter.h" * @@ -53,6 +53,11 @@ #include "format.h" #include "utility.h" +#define LXW_COL_META_MAX 128 + +/** Default column width in Excel */ +#define LXW_DEF_COL_WIDTH 8.43 + /** Error codes from `worksheet_write*()` functions. */ enum lxw_write_error { LXW_WRITE_ERROR_NONE = 0, @@ -85,6 +90,23 @@ enum cell_types { TAILQ_HEAD(lxw_table_cells, lxw_cell); TAILQ_HEAD(lxw_table_rows, lxw_row); +/** Options struct for the worksheet_set_column() and worksheet_set_row(). */ +typedef struct lxw_row_col_options { + uint8_t hidden; + uint8_t level; + uint8_t collapsed; +} lxw_row_col_options; + +typedef struct lxw_col_options { + lxw_col_t firstcol; + lxw_col_t lastcol; + double width; + lxw_format *format; + uint8_t hidden; + uint8_t level; + uint8_t collapsed; +} lxw_col_options; + /** * @brief Struct to represent an Excel worksheet. * @@ -110,6 +132,16 @@ typedef struct lxw_worksheet { uint8_t selected; uint8_t hidden; + lxw_col_options **col_options; + uint16_t col_options_max; + + uint8_t *col_sizes; + uint16_t col_sizes_max; + + lxw_format **col_formats; + uint16_t col_formats_max; + uint8_t col_size_changed; + STAILQ_ENTRY (lxw_worksheet) list_pointers; } lxw_worksheet; @@ -409,9 +441,13 @@ int8_t worksheet_write_datetime(lxw_worksheet *worksheet, * As such, if you write an empty cell without formatting it is ignored. * */ - int8_t worksheet_write_blank(lxw_worksheet *worksheet, - lxw_row_t row, lxw_col_t col, lxw_format *format); + lxw_row_t row, lxw_col_t col, + lxw_format *format); + +int8_t worksheet_set_column(lxw_worksheet *self, lxw_col_t firstcol, + lxw_col_t lastcol, double width, + lxw_format *format, lxw_row_col_options *options); lxw_worksheet *_new_worksheet(lxw_worksheet_init_data *init_data); void _free_worksheet(lxw_worksheet *worksheet); @@ -429,6 +465,8 @@ STATIC void _worksheet_write_sheet_format_pr(lxw_worksheet *worksheet); STATIC void _worksheet_write_sheet_data(lxw_worksheet *worksheet); STATIC void _worksheet_write_page_margins(lxw_worksheet *worksheet); STATIC void _write_row(lxw_worksheet *worksheet, lxw_row *row, char *spans); +STATIC void _write_col_info(lxw_worksheet *worksheet, + lxw_col_options *options); STATIC lxw_row *_get_row(struct lxw_table_rows *table, lxw_row_t row_num); #endif /* TESTING */ diff --git a/include/xlsxwriter/xmlwriter.h b/include/xlsxwriter/xmlwriter.h index 226e42db..16dc7322 100644 --- a/include/xlsxwriter/xmlwriter.h +++ b/include/xlsxwriter/xmlwriter.h @@ -71,9 +71,9 @@ struct xml_attribute *_new_attribute_dbl(const char *key, double value); } while (0) /* Macro to add attribute double values to xml_attribute_list. */ -#define _PUSH_ATTRIBUTES_FLT(key, value) \ +#define _PUSH_ATTRIBUTES_DBL(key, value) \ do { \ - attribute = _new_attribute_flt((key), (value)); \ + attribute = _new_attribute_dbl((key), (value)); \ STAILQ_INSERT_TAIL(&attributes, attribute, list_entries); \ } while (0) diff --git a/src/Makefile b/src/Makefile index ee230b3d..554a6af4 100644 --- a/src/Makefile +++ b/src/Makefile @@ -70,6 +70,8 @@ $(LIBXLSXWRITER_SO) : $(SOBJS) $(LIBXLSXWRITER_TO) : $(TOBJS) $(Q)$(AR) $(ARFLAGS) $@ $(MINIZIP_DIR)/ioapi.o $(MINIZIP_DIR)/zip.o $^ +# Minimal target for quick compile without creating the libs. +test_compile : $(OBJS) # Targets for the object files. %.o : %.c $(HDRS) diff --git a/src/worksheet.c b/src/worksheet.c index 44489482..9b5f8a47 100644 --- a/src/worksheet.c +++ b/src/worksheet.c @@ -39,6 +39,19 @@ _new_worksheet(lxw_worksheet_init_data *init_data) worksheet->table = calloc(1, sizeof(struct lxw_table_rows)); GOTO_LABEL_ON_MEM_ERROR(worksheet->table, mem_error); + worksheet->col_options = + calloc(LXW_COL_META_MAX, sizeof(lxw_col_options *)); + worksheet->col_options_max = LXW_COL_META_MAX; + GOTO_LABEL_ON_MEM_ERROR(worksheet->col_options, mem_error); + + worksheet->col_sizes = calloc(LXW_COL_META_MAX, sizeof(double)); + worksheet->col_sizes_max = LXW_COL_META_MAX; + GOTO_LABEL_ON_MEM_ERROR(worksheet->col_sizes, mem_error); + + worksheet->col_formats = calloc(LXW_COL_META_MAX, sizeof(uint16_t *)); + worksheet->col_formats_max = LXW_COL_META_MAX; + GOTO_LABEL_ON_MEM_ERROR(worksheet->col_formats, mem_error); + TAILQ_INIT(worksheet->table); worksheet->file = NULL; @@ -69,10 +82,29 @@ _free_worksheet(lxw_worksheet *worksheet) { lxw_row *row; lxw_cell *cell; + lxw_col_t col; if (!worksheet) return; + if (worksheet->col_options) { + for (col = 0; col < worksheet->col_options_max; col++) { + if (worksheet->col_options[col]) + free(worksheet->col_options[col]); + } + } + free(worksheet->col_options); + + free(worksheet->col_sizes); + + if (worksheet->col_formats) { + for (col = 0; col < worksheet->col_formats_max; col++) { + if (worksheet->col_formats[col]) + free(worksheet->col_formats[col]); + } + } + free(worksheet->col_formats); + if (worksheet->table) { while (!TAILQ_EMPTY(worksheet->table)) { @@ -97,6 +129,7 @@ _free_worksheet(lxw_worksheet *worksheet) free(worksheet->name); free(worksheet); + worksheet = NULL; } /* @@ -668,6 +701,98 @@ _write_rows(lxw_worksheet *self) } } +/* + * Write the element. + */ +STATIC void +_write_col_info(lxw_worksheet *self, lxw_col_options *options) +{ + + struct xml_attribute_list attributes; + struct xml_attribute *attribute; + + double width = options->width; + uint8_t has_custom_width = LXW_TRUE; + int32_t xf_index = 0; + double max_digit_width = 7.0; /* For Calabri 11. */ + double padding = 5.0; + + /* Get the format index. */ + if (options->format) { + xf_index = _get_xf_index(options->format); + } + + /* Check if width is the Excel default. */ + if (width == LXW_DEF_COL_WIDTH) { + + /* The default col width changes to 0 for hidden columns. */ + if (options->hidden) + width = 0; + else + has_custom_width = LXW_FALSE; + + } + + /* Convert column width from user units to character width. */ + if (width > 0) { + if (width < 1) { + width = (uint16_t) (((uint16_t) + (width * (max_digit_width + padding) + 0.5)) + / max_digit_width * 256.0) / 256.0; + } + else { + width = (uint16_t) (((uint16_t) + (width * max_digit_width + 0.5) + padding) + / max_digit_width * 256.0) / 256.0; + } + } + + _INIT_ATTRIBUTES(); + _PUSH_ATTRIBUTES_INT("min", 1 + options->firstcol); + _PUSH_ATTRIBUTES_INT("max", 1 + options->lastcol); + _PUSH_ATTRIBUTES_DBL("width", width); + + if (xf_index) + _PUSH_ATTRIBUTES_INT("style", xf_index); + + if (options->hidden) + _PUSH_ATTRIBUTES_STR("hidden", "1"); + + if (has_custom_width) + _PUSH_ATTRIBUTES_STR("customWidth", "1"); + + if (options->level) + _PUSH_ATTRIBUTES_INT("outlineLevel", options->level); + + if (options->collapsed) + _PUSH_ATTRIBUTES_STR("collapsed", "1"); + + _xml_empty_tag(self->file, "col", &attributes); + + _FREE_ATTRIBUTES(); +} + +/* + * Write the element and sub elements. + */ +STATIC void +_write_cols(lxw_worksheet *self) +{ + lxw_col_t col; + + if (!self->col_size_changed) + return; + + _xml_start_tag(self->file, "cols", NULL); + + for (col = 0; col < self->col_options_max; col++) { + if (self->col_options[col]) + _write_col_info(self, self->col_options[col]); + } + + _xml_end_tag(self->file, "cols"); +} + /* * Check that row and col are within the allowed Excel range and store max * and min values for use in other methods/elements. @@ -724,6 +849,9 @@ _worksheet_assemble_xml_file(lxw_worksheet *self) /* Write the sheet format properties. */ _worksheet_write_sheet_format_pr(self); + /* Write the sheet column info. */ + _write_cols(self); + /* Write the sheetData element. */ _worksheet_write_sheet_data(self); @@ -744,18 +872,20 @@ _worksheet_assemble_xml_file(lxw_worksheet *self) * Write a number to a cell in Excel. */ int8_t -worksheet_write_number(lxw_worksheet *worksheet, +worksheet_write_number(lxw_worksheet *self, lxw_row_t row_num, lxw_col_t col_num, double value, lxw_format *format) { lxw_row *row; lxw_cell *cell; - int8_t err = _check_dimensions(worksheet, row_num, col_num, 0, 0); + int8_t err; + + err = _check_dimensions(self, row_num, col_num, LXW_FALSE, LXW_FALSE); if (err) return err; - row = _get_row(worksheet->table, row_num); + row = _get_row(self->table, row_num); cell = _new_number_cell(row_num, col_num, value, format); _insert_cell(row->cells, cell, col_num); @@ -767,7 +897,7 @@ worksheet_write_number(lxw_worksheet *worksheet, * Write a string to an Excel file. */ int8_t -worksheet_write_string(lxw_worksheet *worksheet, +worksheet_write_string(lxw_worksheet *self, lxw_row_t row_num, lxw_col_t col_num, const char *string, lxw_format *format) @@ -775,17 +905,19 @@ worksheet_write_string(lxw_worksheet *worksheet, lxw_row *row; lxw_cell *cell; int32_t string_id; - int8_t err = _check_dimensions(worksheet, row_num, col_num, 0, 0); + int8_t err; + + err = _check_dimensions(self, row_num, col_num, LXW_FALSE, LXW_FALSE); if (err) return err; /* Treat a NULL string with formatting as a blank cell. */ if (!string && format) - return worksheet_write_blank(worksheet, row_num, col_num, format); + return worksheet_write_blank(self, row_num, col_num, format); /* Get the SST string ID for the string. */ - string_id = _get_sst_index(worksheet->sst, string); + string_id = _get_sst_index(self->sst, string); if (string_id < 0) return LXW_STRING_HASH_ERROR; @@ -793,7 +925,7 @@ worksheet_write_string(lxw_worksheet *worksheet, if (strlen(string) > LXW_STR_MAX) return LXW_STRING_LENGTH_ERROR; - row = _get_row(worksheet->table, row_num); + row = _get_row(self->table, row_num); cell = _new_string_cell(row_num, col_num, string_id, format); _insert_cell(row->cells, cell, col_num); @@ -805,7 +937,7 @@ worksheet_write_string(lxw_worksheet *worksheet, * Write a formula with a numerical result to a cell in Excel. */ int8_t -worksheet_write_formula_num(lxw_worksheet *worksheet, +worksheet_write_formula_num(lxw_worksheet *self, lxw_row_t row_num, lxw_col_t col_num, const char *formula, @@ -814,7 +946,9 @@ worksheet_write_formula_num(lxw_worksheet *worksheet, lxw_row *row; lxw_cell *cell; char *formula_copy; - int8_t err = _check_dimensions(worksheet, row_num, col_num, 0, 0); + int8_t err; + + err = _check_dimensions(self, row_num, col_num, LXW_FALSE, LXW_FALSE); if (err) return err; @@ -825,7 +959,7 @@ worksheet_write_formula_num(lxw_worksheet *worksheet, else formula_copy = __builtin_strdup(formula); - row = _get_row(worksheet->table, row_num); + row = _get_row(self->table, row_num); cell = _new_formula_cell(row_num, col_num, formula_copy, format); cell->formula_result.number = result; @@ -838,12 +972,12 @@ worksheet_write_formula_num(lxw_worksheet *worksheet, *Write a formula with a default result to a cell in Excel . */ int8_t -worksheet_write_formula(lxw_worksheet *worksheet, +worksheet_write_formula(lxw_worksheet *self, lxw_row_t row_num, lxw_col_t col_num, const char *formula, lxw_format *format) { - return worksheet_write_formula_num(worksheet, row_num, col_num, formula, + return worksheet_write_formula_num(self, row_num, col_num, formula, format, 0); } @@ -852,7 +986,7 @@ worksheet_write_formula(lxw_worksheet *worksheet, */ int8_t -worksheet_write_blank(lxw_worksheet *worksheet, +worksheet_write_blank(lxw_worksheet *self, lxw_row_t row_num, lxw_col_t col_num, lxw_format *format) { @@ -864,12 +998,12 @@ worksheet_write_blank(lxw_worksheet *worksheet, if (!format) return 0; - err = _check_dimensions(worksheet, row_num, col_num, 0, 0); + err = _check_dimensions(self, row_num, col_num, LXW_FALSE, LXW_FALSE); if (err) return err; - row = _get_row(worksheet->table, row_num); + row = _get_row(self->table, row_num); cell = _new_blank_cell(row_num, col_num, format); _insert_cell(row->cells, cell, col_num); @@ -881,7 +1015,7 @@ worksheet_write_blank(lxw_worksheet *worksheet, * Write a date and or time to a cell in Excel. */ int8_t -worksheet_write_datetime(lxw_worksheet *worksheet, +worksheet_write_datetime(lxw_worksheet *self, lxw_row_t row_num, lxw_col_t col_num, lxw_datetime *datetime, lxw_format *format) @@ -889,17 +1023,93 @@ worksheet_write_datetime(lxw_worksheet *worksheet, lxw_row *row; lxw_cell *cell; double excel_date; - int8_t err = _check_dimensions(worksheet, row_num, col_num, 0, 0); + int8_t err; + + err = _check_dimensions(self, row_num, col_num, LXW_FALSE, LXW_FALSE); if (err) return err; excel_date = _datetime_to_excel_date(datetime, EPOCH_1900); - row = _get_row(worksheet->table, row_num); + row = _get_row(self->table, row_num); cell = _new_number_cell(row_num, col_num, excel_date, format); _insert_cell(row->cells, cell, col_num); return 0; } + +/* + * Set the properties of a single column or a range of columns. + */ +int8_t +worksheet_set_column(lxw_worksheet *self, + lxw_col_t firstcol, + lxw_col_t lastcol, + double width, + lxw_format *format, lxw_row_col_options *options) +{ + lxw_col_options *col_options; + uint8_t ignore_row = LXW_TRUE; + uint8_t ignore_col = LXW_TRUE; + lxw_col_t col; + int8_t err; + + /* Ensure 2nd col is larger than first. */ + if (firstcol > lastcol) { + lxw_col_t tmp = firstcol; + firstcol = lastcol; + lastcol = tmp; + } + + /* Temp workaround. Only support 128 cols for now. */ + if (lastcol > LXW_COL_META_MAX) + return -1; + + /* Ensure that the cols are valid and store max and min values. + * NOTE: The check shouldn't modify the row dimensions and should only + * modify the column dimensions in certain cases. */ + if (format != NULL || width > 0) + ignore_col = LXW_FALSE; + + err = _check_dimensions(self, 0, firstcol, ignore_row, ignore_col); + + if (!err) + err = _check_dimensions(self, 0, lastcol, ignore_row, ignore_col); + + if (err) + return err; + + col_options = calloc(1, sizeof(lxw_col_options)); + RETURN_ON_MEM_ERROR(col_options, -1); + + /* Store the column option based on the first column. */ + col_options->firstcol = firstcol; + col_options->lastcol = lastcol; + col_options->width = width; + col_options->format = format; + + if (options) { + col_options->hidden = options->hidden; + col_options->level = options->level; + col_options->collapsed = options->collapsed; + } + + self->col_options[firstcol] = col_options; + + /* Store the col sizes for use when calculating image vertices taking + * hidden columns into account. Also store the column formats. */ + if (options->hidden) + width = 0; + + for (col = firstcol; col <= lastcol; col++) { + self->col_sizes[col] = width; + self->col_formats[col] = format; + } + + /* Store the column change to allow optimisations. */ + self->col_size_changed = LXW_TRUE; + + return 0; +} diff --git a/test/functional/src/test_simple01.c b/test/functional/src/test_simple01.c new file mode 100644 index 00000000..3186a58d --- /dev/null +++ b/test/functional/src/test_simple01.c @@ -0,0 +1,21 @@ +/***************************************************************************** + * Test cases for libxlsxwriter. + * + * Simple test case to test data writing. + * + * Copyright 2014, John McNamara, jmcnamara@cpan.org + * + */ + +#include "xlsxwriter.h" + +int main() { + + lxw_workbook *workbook = new_workbook("test_simple01.xlsx"); + lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL); + + worksheet_write_string(worksheet, 0, 0, "Hello", NULL); + worksheet_write_number(worksheet, 1, 0, 123, NULL); + + return workbook_close(workbook); +} diff --git a/test/functional/src/test_simple02.c b/test/functional/src/test_simple02.c new file mode 100644 index 00000000..ad4218d1 --- /dev/null +++ b/test/functional/src/test_simple02.c @@ -0,0 +1,35 @@ +/***************************************************************************** + * Test cases for libxlsxwriter. + * + * Simple test case to test data writing. + * + * Copyright 2014, John McNamara, jmcnamara@cpan.org + * + */ + +#include "xlsxwriter.h" + +/* Ignore warnings about unused variables since this file is testing how + * unused formats are handled. + */ +#pragma GCC diagnostic ignored "-Wunused-variable" + +int main() { + + lxw_workbook *workbook = new_workbook("test_simple02.xlsx"); + lxw_worksheet *worksheet1 = workbook_add_worksheet(workbook, NULL); + lxw_worksheet *worksheet2 = workbook_add_worksheet(workbook, "Data Sheet"); + lxw_worksheet *worksheet3 = workbook_add_worksheet(workbook, NULL); + + lxw_format *format = workbook_add_format(workbook); + format_set_bold(format); + + worksheet_write_string(worksheet1, 0, 0, "Foo", NULL); + worksheet_write_number(worksheet1, 1, 0, 123, NULL); + + worksheet_write_string(worksheet3, 1, 1, "Foo", NULL); + worksheet_write_string(worksheet3, 2, 1, "Bar", format); + worksheet_write_number(worksheet3, 3, 2, 234, NULL); + + return workbook_close(workbook); +} diff --git a/test/functional/src/test_simple04.c b/test/functional/src/test_simple04.c new file mode 100644 index 00000000..cf2442b2 --- /dev/null +++ b/test/functional/src/test_simple04.c @@ -0,0 +1,31 @@ +/***************************************************************************** + * Test cases for libxlsxwriter. + * + * Simple test case to test data writing. + * + * Copyright 2014, John McNamara, jmcnamara@cpan.org + * + */ + +#include "xlsxwriter.h" + +int main() { + + lxw_datetime datetime1 = {0, 0, 0, 12, 0, 0}; + lxw_datetime datetime2 = {2013, 1, 27, 0, 0, 0}; + + lxw_workbook *workbook = new_workbook("test_simple04.xlsx"); + lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL); + + lxw_format *format1 = workbook_add_format(workbook); + lxw_format *format2 = workbook_add_format(workbook); + format_set_num_format_index(format1, 20); + format_set_num_format_index(format2, 14); + + worksheet_set_column(worksheet, 0, 0, 12, NULL, NULL); + + worksheet_write_datetime(worksheet, 0, 0, &datetime1, format1); + worksheet_write_datetime(worksheet, 1, 0, &datetime2, format2); + + return workbook_close(workbook); +} diff --git a/test/functional/test_simple.py b/test/functional/test_simple.py new file mode 100644 index 00000000..8cf4aa0c --- /dev/null +++ b/test/functional/test_simple.py @@ -0,0 +1,29 @@ +############################################################################### +# +# Tests for libxlsxwriter. +# +# Copyright (c), 2014, John McNamara, jmcnamara@cpan.org +# + +import base_test_class + +class TestCompareXLSXFiles(base_test_class.XLSXBaseTest): + """ + Test file created with libxlsxwriter against a file created by Excel. + + """ + + def test_simple01(self): + self.run_exe_test('test_simple01') + + def test_simple02(self): + self.run_exe_test('test_simple02') + + # def test_simple03(self): + # self.run_exe_test('test_simple03') + + def test_simple04(self): + self.run_exe_test('test_simple04') + + # def test_simple05(self): + # self.run_exe_test('test_simple05') diff --git a/test/functional/xlsx_files/simple01.xlsx b/test/functional/xlsx_files/simple01.xlsx new file mode 100644 index 00000000..dddce905 Binary files /dev/null and b/test/functional/xlsx_files/simple01.xlsx differ diff --git a/test/functional/xlsx_files/simple02.xlsx b/test/functional/xlsx_files/simple02.xlsx new file mode 100644 index 00000000..be7a8c95 Binary files /dev/null and b/test/functional/xlsx_files/simple02.xlsx differ diff --git a/test/functional/xlsx_files/simple03.xlsx b/test/functional/xlsx_files/simple03.xlsx new file mode 100644 index 00000000..1f8db55c Binary files /dev/null and b/test/functional/xlsx_files/simple03.xlsx differ diff --git a/test/functional/xlsx_files/simple04.xlsx b/test/functional/xlsx_files/simple04.xlsx new file mode 100644 index 00000000..d9282fab Binary files /dev/null and b/test/functional/xlsx_files/simple04.xlsx differ diff --git a/test/functional/xlsx_files/simple05.xlsx b/test/functional/xlsx_files/simple05.xlsx new file mode 100644 index 00000000..5e4af77a Binary files /dev/null and b/test/functional/xlsx_files/simple05.xlsx differ diff --git a/test/unit/worksheet/test_worksheet_write_col_info.cpp b/test/unit/worksheet/test_worksheet_write_col_info.cpp new file mode 100644 index 00000000..e7ffe332 --- /dev/null +++ b/test/unit/worksheet/test_worksheet_write_col_info.cpp @@ -0,0 +1,164 @@ +/* + * Tests for the lib_xlsx_writer library. + * + * Copyright 2014, John McNamara, jmcnamara@cpan.org + * + */ + +#include +#include "../helper.h" + +#include "xlsxwriter/worksheet.h" +#include "xlsxwriter/format.h" + +// Test the _write_col_info() function. +TEST(worksheet, write_col_info01) { + + char* got; + char exp[] = ""; + FILE* testfile = tmpfile(); + lxw_col_options col_options = {.firstcol = 1, + .lastcol = 3, + .width = 5, + .format = NULL, + .hidden = 0, + .level = 0, + .collapsed = 0}; + + lxw_worksheet *worksheet = _new_worksheet(NULL); + worksheet->file = testfile; + + _write_col_info(worksheet, &col_options); + + RUN_XLSX_STREQ(exp, got); + + _free_worksheet(worksheet); +} + + +TEST(worksheet, write_col_info02) { + + char* got; + char exp[] = ""; + FILE* testfile = tmpfile(); + lxw_col_options col_options = {.firstcol = 5, + .lastcol = 5, + .width = 8, + .format = NULL, + .hidden = 1, + .level = 0, + .collapsed = 0}; + + lxw_worksheet *worksheet = _new_worksheet(NULL); + worksheet->file = testfile; + + _write_col_info(worksheet, &col_options); + + RUN_XLSX_STREQ(exp, got); + + _free_worksheet(worksheet); +} + + +TEST(worksheet, write_col_info03) { + + char* got; + char exp[] = ""; + FILE* testfile = tmpfile(); + + lxw_format *format = _new_format(); + format->xf_index = 1; + + lxw_col_options col_options = {.firstcol = 7, + .lastcol = 7, + .width = LXW_DEF_COL_WIDTH, + .format = format, + .hidden = 0, + .level = 0, + .collapsed = 0}; + + lxw_worksheet *worksheet = _new_worksheet(NULL); + worksheet->file = testfile; + + _write_col_info(worksheet, &col_options); + + RUN_XLSX_STREQ(exp, got); + + _free_worksheet(worksheet); +} + + +TEST(worksheet, write_col_info04) { + + char* got; + char exp[] = ""; + FILE* testfile = tmpfile(); + + lxw_format *format = _new_format(); + format->xf_index = 1; + + lxw_col_options col_options = {.firstcol = 8, + .lastcol = 8, + .width = LXW_DEF_COL_WIDTH, + .format = format, + .hidden = 0, + .level = 0, + .collapsed = 0}; + + lxw_worksheet *worksheet = _new_worksheet(NULL); + worksheet->file = testfile; + + _write_col_info(worksheet, &col_options); + + RUN_XLSX_STREQ(exp, got); + + _free_worksheet(worksheet); +} + + +TEST(worksheet, write_col_info05) { + + char* got; + char exp[] = ""; + FILE* testfile = tmpfile(); + lxw_col_options col_options = {.firstcol = 9, + .lastcol = 9, + .width = 2, + .format = NULL, + .hidden = 0, + .level = 0, + .collapsed = 0}; + + lxw_worksheet *worksheet = _new_worksheet(NULL); + worksheet->file = testfile; + + _write_col_info(worksheet, &col_options); + + RUN_XLSX_STREQ(exp, got); + + _free_worksheet(worksheet); +} + + +TEST(worksheet, write_col_info06) { + + char* got; + char exp[] = ""; + FILE* testfile = tmpfile(); + lxw_col_options col_options = {.firstcol = 11, + .lastcol = 11, + .width = LXW_DEF_COL_WIDTH, + .format = NULL, + .hidden = 1, + .level = 0, + .collapsed = 0}; + + lxw_worksheet *worksheet = _new_worksheet(NULL); + worksheet->file = testfile; + + _write_col_info(worksheet, &col_options); + + RUN_XLSX_STREQ(exp, got); + + _free_worksheet(worksheet); +}