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:

#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.

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:

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:

WorkbookHandle wb = doc_get_workbook(doc);

Third, create or get a worksheet.

Use wb_add_worksheet() to create a new worksheet:

// 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:

// 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:

// 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: