.. _richtext-c-api:

Rich Text API Reference
=======================

Overview
--------

The Rich Text API provides functions to create and manipulate rich text content
in Excel cells, allowing formatted text with multiple styles
within a single cell.

Rich Text Information
---------------------

.. c:function:: int rt_segments_num(RichtextHandle rt)

    Get the number of text segments in the rich text.

    :param rt: Rich text handle.
    :return: Number of text segments.

.. c:function:: const char* rt_plain_text(RichtextHandle rt)

    Get the plain text content of the rich text.

    :param rt: Rich text handle.
    :return: Plain text string.

Text Segment Operations
-----------------------

.. c:function:: const char* rt_text(RichtextHandle rt, int index, StyleHandle* style)

    Get text and style of a specific segment.

    :param rt: Rich text handle.
    :param index: Segment index (0-based).
    :param style: Pointer to store the segment's style handle.
    :return: Text content of the segment.

.. c:function:: void rt_append(RichtextHandle rt, const char* s, StyleHandle style)

    Append a new text segment to the rich text.

    :param rt: Rich text handle.
    :param s: Text content to append.
    :param style: Style for the new segment.

.. c:function:: void rt_insert(RichtextHandle rt, int index, const char* s, StyleHandle style)

    Insert a new text segment at specified position.

    :param rt: Rich text handle.
    :param index: Position to insert the segment.
    :param s: Text content to insert.
    :param style: Style for the new segment.

.. c:function:: void rt_remove(RichtextHandle rt, int index)

    Remove a text segment from the rich text.

    :param rt: Rich text handle.
    :param index: Index of segment to remove.

.. c:function:: void rt_modify(RichtextHandle rt, int index, const char* s, StyleHandle style)

    Modify an existing text segment.

    :param rt: Rich text handle.
    :param index: Index of segment to modify.
    :param s: New text content.
    :param style: New style for the segment.

Resource Management
-------------------

.. c:function:: void rt_release(RichtextHandle rt)

    Release rich text resources.

    :param rt: Rich text handle to release.

Usage Example
-------------

Typical usage pattern for rich text:

.. code-block:: c

    // Create rich text from workbook
    RichtextHandle rt = wb_make_richtext(workbook);

    // Append segments with different styles
    rt_append(rt, "This is ", normal_style);
    rt_append(rt, "bold", bold_style);
    rt_append(rt, " and ", normal_style);
    rt_append(rt, "italic", italic_style);
    rt_append(rt, " text.", normal_style);

    // Apply to cell
    ws_set_richtext(worksheet, 1, 1, rt);

    // Release when done
    rt_release(rt);
