DOCSEARCHbyAlgolia
Submit Docs

QXlsx Documentation

repository·master·Indexed 23 days ago

https://github.com/qtexcel/qxlsx

A C++ library built on Qt for reading and writing Excel (.xlsx) files, serving as a modern replacement for QtXlsxWriter. It provides the QXlsx::Document class for workbook manipulation, a SAX reader for memory-efficient parsing of large files, and support for exporting to CSV. The library includes utilities like FormulaDump for extracting and evaluating formulas and LargeData for performance benchmarking, with integration support for both qmake and CMake.

Tokens
5K
Snippets
18
Records
33
Agent score
77%

What's inside QXlsx

  1. Overview of QXlsx

    master

    QXlsx is a C++ library built on top of the Qt framework designed for reading and writing Excel (*.xlsx) files. It was created as a successor to the no longer supported QtXlsxWriter.

    Key characteristics:

    • Developed in C++ using the Qt framework.
    • Designed to be used without requiring static or dynamic libraries, though it can be used as a static library if desired.

  2. Overview of ExcelTableEditor example

    master
    ExcelTableEditor is an example project that demonstrates how to build a simple Excel editor by combining Qt Widgets and QXlsx. It provides a blueprint for loading workbook data into Qt models, providing a user interface for editing sheets, and writing the modified content back to an .xlsx file.

  3. Features of the ExcelTableEditor implementation

    master

    The ExcelTableEditor example implements the following capabilities:

    • Workbook Loading: Supports Excel files with multiple sheets.
    • Data Display: Uses QTableView to display sheet contents.
    • Cell Editing: All cells (including row 1) are editable.
    • Data Types: Boolean values are automatically displayed as checkboxes.
    • Formatting: Reads and preserves basic cell formatting such as font, alignment, and colors.
    • Sheet Management:
      • Rename sheet
      • Add new sheet
      • Delete sheet
      • Reorder sheets (move left/right)
    • File Operations: Supports 'Save' and 'Save As' to output modified workbooks.

  4. How ExcelTableEditor maps QXlsx data to Qt models

    master

    The application follows this architectural pattern to bridge QXlsx and Qt Widgets:

    1. Model Mapping: Each worksheet from the QXlsx::Document is mapped to its own QStandardItemModel.
    2. Data Loading: All sheet data, including the first row, is loaded into these models as editable items.
    3. Formatting: Cell formatting is stored on a per-cell basis and reapplied to the item view.
    4. Saving Workflow: To save changes, the application:
      • Creates a new QXlsx::Document instance.
      • Adds sheets to the new document in the current UI order.
      • Writes cell values and available formatting back to the new file.

  5. Use the SAX reader for memory-efficient parsing

    master

    For large files where RAM usage is a concern, use read_sheet_sax instead of standard loading. This uses a SAX parser to process cells one by one via a callback.

    Configuration with sax_options:

    • resolve_shared_strings: Set to true to resolve strings, or false to save RAM (though you may get shared string indices instead).
    • read_formulas_as_text: If true, outputs the formula string instead of the calculated result.
    • stop_on_empty_sheetdata: If false, continues processing even if sheetData is empty.
    void dump_all_sheets_sax(QXlsx::Document& doc)
{
    QXlsx::sax_options opt;
    opt.resolve_shared_strings = true;
    opt.read_formulas_as_text  = true;
    opt.stop_on_empty_sheetdata = false;

    const QStringList sheets = doc.sheetNames();

    for (const QString& sheet_name : sheets) {
        doc.read_sheet_sax(
            sheet_name,
            opt,
            [&](const QXlsx::sax_cell& cell) -> bool {
                qDebug().noquote()
                << QString("%1!R%2C%3 = %4")
                        .arg(cell.sheet_name)
                        .arg(cell.row)
                        .arg(cell.col)
                        .arg(cell.value.toString());
                return true; // continue
            });
    }
}

  6. Use QXlsx via CMake FetchContent

    master

    To use QXlsx without a system-wide installation, you can use the FetchContent module to download the repository automatically. Ensure you set SOURCE_SUBDIR to QXlsx.

    FetchContent_Declare(
  QXlsx
  GIT_REPOSITORY https://github.com/QtExcel/QXlsx.git
  GIT_TAG        sha-of-the-commit
  SOURCE_SUBDIR  QXlsx
)
FetchContent_MakeAvailable(QXlsx)
target_link_libraries(myapp PRIVATE QXlsx::QXlsx)

  7. Install QXlsx using CMake

    master

    To install QXlsx on your system, create a build directory and use CMake to configure, build, and install the library. You should specify a CMAKE_INSTALL_PREFIX to determine the installation location and set the build type to Release.

    mkdir build
cd build
cmake ../QXlsx/ -DCMAKE_INSTALL_PREFIX=... -DCMAKE_BUILD_TYPE=Release
cmake --build .
cmake --install .

  9. Use QXlsx via CMake subdirectory

    master

    To use QXlsx without a system-wide installation, you can include the QXlsx source directory directly in your project using add_subdirectory and then link against QXlsx::QXlsx.

    add_subdirectory(QXlsx)
target_link_libraries(myapp PRIVATE QXlsx::QXlsx)

  10. Install and set up QXlsx

    master

    To integrate QXlsx into your project, follow the specific setup guides based on your build system:

    • For qmake users: Refer to HowToSetProject.md.
    • For CMake users: Refer to HowToSetProject-cmake.md.

    You can check the tested environments via the GitHub Actions tab.

  11. How to set up QXlsx with qmake or CMake

    master

    To integrate QXlsx into your project, follow the specific setup guides based on your build system:

    • For qmake projects, refer to HowToSetProject.md.
    • For CMake projects, refer to HowToSetProject-cmake.md.

  12. Set up QXlsx in a qmake project

    master

    To use QXlsx in a Qt project built with qmake, follow these steps:

    1. Clone the repository: Obtain the source code from GitHub.
    2. Create a Qt Project: Create a new Qt project (e.g., a Console Application) in Qt Creator.
    3. Integrate QXlsx Source: Copy the QXlsx source directory into your project directory.
    4. Configure the .pro file: Add the QXlsx configuration code to your project file to include the library.
    5. Use the API: Include the necessary headers and use the QXlsx namespace to manipulate Excel files.

    Note: This guide is for qmake. If you are using CMake, refer to the CMake-specific documentation.

    git clone https://github.com/j2doll/QXlsx.git