.. _richtext-api:

Richtext Interface
==================

The Richtext interface represents formatted text content with multiple segments
, each potentially having different styling properties.

Classes
-------

.. cpp:class:: oo::iRichtext

   Interface for managing rich text content with multiple formatted segments.

   Content Information
   ~~~~~~~~~~~~~~~~~~~

   .. cpp:function:: int segments_num() const

      Get the number of text segments in the rich text.

      :returns: Number of text segments

   .. cpp:function:: const char* plain_text() const

      Get the complete text content without formatting.

      :returns: Plain text content

   Text Segment Access
   ~~~~~~~~~~~~~~~~~~~

   .. cpp:function:: const char* text(int index, iStyle** style = nullptr) const

      Get text and style for a specific segment.

      :param index: Segment index (0-based)
      :param style: Pointer to store style object pointer (optional)
      :returns: Text content of the segment

      .. note::
         If the style parameter is provided and the segment has styling, the style object pointer will be stored.

   Content Modification
   ~~~~~~~~~~~~~~~~~~~~

   .. cpp:function:: void append(const char* s, iStyle* style = nullptr)

      Append a new text segment to the rich text.

      :param s: Text content to append
      :param style: Style to apply to the new segment (optional)

   .. cpp:function:: void insert(int index, const char* s, iStyle* style = nullptr)

      Insert a new text segment at the specified position.

      :param index: Position to insert (0-based)
      :param s: Text content to insert
      :param style: Style to apply to the new segment (optional)

   .. cpp:function:: void remove(int index)

      Remove a text segment.

      :param index: Segment index to remove (0-based)

   .. cpp:function:: void modify(int index, const char* s, iStyle* style = nullptr)

      Modify an existing text segment.

      :param index: Segment index to modify (0-based)
      :param s: New text content
      :param style: New style to apply (optional, nullptr keeps existing style)

   Resource Management
   ~~~~~~~~~~~~~~~~~~~

   .. cpp:function:: void release()

      Release the rich text object and free associated resources.

      .. note::
         This should be called when the rich text object is no longer needed to prevent memory leaks.

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

.. code-block:: cpp

   #include "oosxl.hxx"

   // Create rich text object
   oo::iRichtext* richText = workbook->make_richtext();

   // Create styles for different segments
   oo::iStyle* boldStyle = workbook->make_normal_style();
   boldStyle->set_bold(true);
   boldStyle->set_font_size(14);

   oo::iStyle* redStyle = workbook->make_normal_style();
   redStyle->set_font_color(RGB(255, 0, 0));
   redStyle->set_italic(true);

   // Add formatted segments
   richText->append("This is ", nullptr);  // Normal text
   richText->append("bold", boldStyle);    // Bold text
   richText->append(" and ", nullptr);     // Normal text
   richText->append("red italic", redStyle); // Red italic text

   // Apply to cell
   worksheet->set_richtext(0, 0, richText);

   // Get information about segments
   int segmentCount = richText->segments_num();
   for (int i = 0; i < segmentCount; ++i) {
       oo::iStyle* segmentStyle = nullptr;
       const char* text = richText->text(i, &segmentStyle);
       // Process segment...
   }

   // Get plain text
   const char* plainText = richText->plain_text();
   // plainText = "This is bold and red italic"

   // Clean up
   boldStyle->release();
   redStyle->release();
   richText->release();
