
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.hxx"

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++

    Document* doc = create_document(); // Create a blank document
    // or
    // Document* doc = load_document("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 create_document() or load_document() function returns a Document 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++

    Workbook* wb = doc->get_workbook();

Third, create or get a worksheet.

Use add_worksheet() to create a new worksheet:

.. code-block:: C++

    // Create an auto-named worksheet
    Worksheet* ws = wb->add_worksheet();
    // Create a worksheet named "My Sheet"
    Worksheet* ws = wb->add_worksheet("My Sheet");

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

.. code-block:: C++

    // Get the first worksheet
    Worksheet* ws = wb->get_sheet(0);

Now, using the returned Worksheet pointer 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.hxx"

    #include <iostream>
    #include <vector>

    using namespace oo;

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

        // Step 3: Get the workbook and worksheet
        Workbook* wb = doc->get_workbook();
        Worksheet* ws = wb->add_worksheet(); // Get the worksheet
        if (!ws)
        {
            std::cout << "Error adding worksheet: " << run_msg() << std::endl;
            doc->release();
            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(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(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(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(row + 3, 4, column3[row]);

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

        // Merge cell(6,2) - cell(6,4)
        ws->merge(6, 2, 6, 4);
        ws->set_text(6, 2, "Total");

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

        Style* fmt = wb->make_normal_style();

        // Add borders
        fmt->set_border(BORDERINDEX_EDGE, BORDER_THICK);
        fmt->set_border(BORDERINDEX_INSIDE, BORDER_THIN);
        ws->set_range_style(2, 2, 6, 5, fmt);

        // Set title style
        fmt->unapply_all();
        fmt->set_align_h(HALIGN_CENTER);
        fmt->set_align_v(VALIGN_CENTER);
        fmt->set_pattern_fg_color(0xDDDDDD);
        fmt->set_fill_pattern(PATTERNTYPE_SOLID);
        ws->set_range_style(2, 2, 2, 5, fmt);

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

        doc->release();
        return 0;
    }

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

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