
Quick Start with C
==================

This section demonstrates a simple use case in C,
showing how to use the oosxl library functions,
such as creating an xlsx document, setting cell content,
and setting cell formatting.

First, include the oosxl library header file:

.. code-block:: C

    #include "oosxl.h"

Second, in the main function, use the parameterless create_document()
function to create a blank document,
or use load_document() to load a document from an existing xlsx file.

.. code-block:: C

    DocumentHandle doc = doc_create(); // Create a blank document
    // or
    // DocumentHandle doc = doc_load("path/to/xlsx/file");

If loading a non-existent file, load_document() will return a null pointer.
You can handle this as follows:

.. code-block:: C

    if (!doc)
    {
        std::cout << run_msg() << std::endl;
        //...
    }

.. note::

    The oosxl library does not propagate exceptions.
    To get program errors, use the string output by the run_msg()
    function to get the corresponding information
    (an empty string indicates no error).
    run_msg() outputs the last error or informational message (if any).

The doc_create() or doc_load() function returns a DocumentHandle pointer
(e.g., doc in the example).
The instance pointed to by this pointer implicitly contains a Workbook pointer,
which points to the workbook instance within the xlsx document:

.. code-block:: C

    WorkbookHandle wb = doc_get_workbook(doc);

Third, create or get a worksheet.

Use wb_add_worksheet() to create a new worksheet:

.. code-block:: C

    // Create an auto-named worksheet
    WorksheetHandle ws1 = wb_add_worksheet(wb);
    // Create a worksheet named "My Sheet"
    WorksheetHandle ws2 = wb_add_worksheet(wb, "My Sheet");

Use wb_get_sheet() to get a worksheet,
using the 0-based index as the parameter:

.. code-block:: C

    // Get the first econd worksheet
    WorksheetHandle ws = wb_get_sheet(0);

Now, using the returned Worksheet handle ws,
we can interact with the cells in the worksheet instance it points to.

The following is a complete C program example
demonstrating the usage of the oosxl library:

.. code-block:: C

    // Step 1: include the header
    #include "oosxl.h"

    #include <iostream>
    #include <vector>

    int test_example()
    {
        // Step 2: create a document
        DocumentHandle doc = doc_create();
        if (!doc)
        {
            std::cout << "Error creating document: " << run_msg() << std::endl;
            return -1;
        }

        // Step 3: Get the workbook and worksheet
        WorkbookHandle wb = doc_get_workbook(doc);
        WorksheetHandle ws = wb_add_worksheet(wb); // Get the worksheet
        if (!ws)
        {
            std::cout << "Error adding worksheet: " << run_msg() << std::endl;
            doc_release(doc);
            return -1;
        }

        // Set titles
        std::vector<std::string> titles = { "Item", "Units", "Unit Cost", "Total" };
        for (int col = 0; col < titles.size(); ++col)
            ws_set_text(ws, 2, col + 2, titles[col].c_str());

        // Set the first column
        std::vector<std::string> column1 = { "Baby doll", "Kite", "Toy guitar" };
        for (int row = 0; row < 3; ++row)
            ws_set_text(ws, row + 3, 2, column1[row].c_str());

        // Set the second column
        std::vector<int> column2 = { 95, 60, 75 };
        for (int row = 0; row < 3; ++row)
            ws_set_num(ws, row + 3, 3, column2[row]);

        // Set the third column
        std::vector<double> column3 = { 1.99, 2.99, 6.99 };
        for (int row = 0; row < 3; ++row)
            ws_set_num(ws, row + 3, 4, column3[row]);

        // Set the fourth column
        ws_set_formula(ws, 3, 5, "=C3*D3");
        ws_set_formula(ws, 4, 5, "=C4*D4");
        ws_set_formula(ws, 5, 5, "=C5*D5");

        // Merge cell(6,2) - cell(6,4)
        ws_merge(ws, 6, 2, 6, 4);
        ws_set_text(ws, 6, 2, "Total");

        // Set total
        ws_set_formula(ws, 6, 5, "=SUM(E3:E5)");

        StyleHandle fmt = wb_make_normal_style(wb);

        // Add borders
        style_set_border(fmt, BORDERINDEX_EDGE, BORDER_THICK);
        style_set_border(fmt, BORDERINDEX_INSIDE, BORDER_THIN);
        style_set_range_style(fmt, 2, 2, 6, 5, fmt);

        // Set title style
        style_unapply_all(fmt);
        style_set_align_h(fmt, HALIGN_CENTER);
        style_set_align_v(fmt, VALIGN_CENTER);
        style_set_pattern_fg_color(fmt, 0xDDDDDD);
        style_set_fill_pattern(fmt, PATTERNTYPE_SOLID);
        ws_set_range_style(ws, 2, 2, 2, 5, fmt);

        // Save document
        if (!doc_save(doc, "example.xlsx"))
        {
            std::cout << "Error saving file: " << run_msg() << std::endl;
            doc_release(doc);
            return -1;
        }

        doc_release(doc);
        return 0;
    }

Open the example.xlsx file with the Microsoft Excel application
to verify the output:

.. figure:: ../_static/images/quick-start-example.png
