Model — Content Containers

Complex content nodes that contain children or structured data.

DocraftText

Text node with font, color, alignment, styling, and optional multi-line layout via internal line children.

class DocraftText : public docraft::model::DocraftChildrenContainerNode, public docraft::model::IDocraftClonable

Text node with styling, alignment, and optional line splits.

Text nodes can generate internal line children for wrapping/justification.

Subclassed by docraft::model::DocraftPageNumber

Public Functions

DocraftText()

Creates an empty text node.

explicit DocraftText(const std::string &text)

Creates a text node with initial text content.

Parameters:

text – Initial text string.

DocraftText(const DocraftText &node) = default
~DocraftText() override = default
virtual void draw(const std::shared_ptr<DocraftDocumentContext> &context) override

Draws the text node using the provided context.

Parameters:

context – Document context.

virtual std::shared_ptr<DocraftNode> clone() const override

Clones the text node and its line children.

Returns:

Shared pointer to the cloned node.

const std::string &text() const

Returns the text content.

Returns:

Text string.

float font_size() const

Returns the font size in points.

Returns:

Font size in points.

const std::string &font_name() const

Returns the font family name.

Returns:

Font family name.

const DocraftColor &color() const

Returns the text color.

Returns:

Text color.

TextStyle style() const

Returns the text style.

Returns:

Text style enum.

TextAlignment alignment() const

Returns the text alignment.

Returns:

Text alignment enum.

bool underline() const

Returns whether underline is enabled.

Returns:

true if underline is enabled.

void set_text(const std::string &text)

Sets the text content.

Parameters:

text – New text string.

void set_font_size(float font_size)

Sets the font size in points.

Parameters:

font_size – Font size in points.

void set_font_name(const std::string &font_name)

Sets the font family name.

Parameters:

font_name – Font family name.

void set_color(const DocraftColor &color)

Sets the text color.

Parameters:

color – Text color.

void set_style(TextStyle style)

Sets the text style.

Parameters:

style – Text style enum.

void set_alignment(TextAlignment alignment)

Sets the text alignment.

Parameters:

alignment – Text alignment enum.

void set_underline(bool underline)

Enables or disables underline.

Parameters:

underline – true to enable underline.

void add_line(const std::shared_ptr<DocraftText> &line)

Adds a line node for multi-line layout.

Parameters:

line – Line node to add.

std::vector<std::shared_ptr<DocraftText>> lines() const

Returns the list of line nodes.

Returns:

Vector of line nodes.

void clear_lines()

Clears all line nodes.

virtual void set_x_for_children(float x) override

Propagates x position to child line nodes.

Parameters:

x – New x coordinate.

virtual void set_y_for_children(float y) override

Propagates y position to child line nodes.

Parameters:

y – New y coordinate.

void set_color_template_expression(const std::string &color_template)

Sets the text color from a template expression.

Parameters:

color_template – Template expression like ${data(“field”)} or ${variable}

const std::string &color_template_expression() const

Gets the color template expression if this text has a templated color.

Returns:

Color template expression or empty string if color is static.

bool has_color_template_expression() const

Checks if this text has a templated color.

Returns:

true if color is a template expression.

DocraftChildrenContainerNode(const DocraftChildrenContainerNode &node) = default
explicit DocraftChildrenContainerNode(DocraftChildrenContainerNode *node)

Constructs from an existing node pointer (copy).

DocraftPageNumber

Special text node that renders the current page number.

class DocraftPageNumber : public docraft::model::DocraftText

Text node that renders the current page number.

The value is managed by the library and resolved from the document context at layout/render time.

Public Functions

DocraftPageNumber()
~DocraftPageNumber() override = default
void update_text_from_context(const std::shared_ptr<DocraftDocumentContext> &context)

Updates the internal text to the current page number.

Parameters:

context – Document context.

virtual void draw(const std::shared_ptr<DocraftDocumentContext> &context) override

Draws the page number using the provided context.

Parameters:

context – Document context.

virtual std::shared_ptr<DocraftNode> clone() const override

Clones the page number node and its line children.

Returns:

Shared pointer to the cloned node.

DocraftText()

Creates an empty text node.

explicit DocraftText(const std::string &text)

Creates a text node with initial text content.

Parameters:

text – Initial text string.

DocraftText(const DocraftText &node) = default

DocraftImage

Image node supporting file-based and raw pixel sources (PNG, JPEG, raw RGB).

class DocraftImage : public docraft::model::DocraftNode, public docraft::model::IDocraftClonable

Image node that draws bitmap content.

Images can be loaded from file or provided as raw pixel data.

Public Functions

DocraftImage()

Creates an empty image node.

DocraftImage(const DocraftImage &node) = default
~DocraftImage() override = default
explicit DocraftImage(DocraftImage *node)

Constructs from an existing node pointer (copy).

virtual void draw(const std::shared_ptr<DocraftDocumentContext> &context) override

Draws the image using the provided context.

Parameters:

context – Document context.

virtual std::shared_ptr<DocraftNode> clone() const override

Clones the image node.

Returns:

Shared pointer to the cloned node.

void set_path(const std::string &path)

Sets the image file path.

Parameters:

path – Image file path.

void set_raw_data(const std::vector<unsigned char> &data, int pixel_width, int pixel_height)

Sets raw image data and its pixel dimensions.

Parameters:

  • data – Raw pixel data.

  • pixel_width – Image width in pixels.

  • pixel_height – Image height in pixels.

void set_has_raw_data(bool has_raw_data)

Sets whether the image has raw pixel data.

Parameters:

has_raw_data – True if raw data is set, false otherwise.

ImageFormat format() const

Returns the image format.

Returns:

Image format enum.

const std::string &path() const

Returns the image file path.

Returns:

Image file path.

const std::vector<unsigned char> &raw_data() const

Returns raw image data.

Returns:

Raw pixel buffer.

int raw_pixel_width() const

Returns raw image pixel width.

Returns:

Pixel width.

int raw_pixel_height() const

Returns raw image pixel height.

Returns:

Pixel height.

bool has_raw_data() const

Checks if the image has raw pixel data.

raw data is considered set if the format is kRaw and the raw_data vector is not empty. This is used to determine if the image should be rendered from raw data instead of a file path.

Returns:

True if raw data is set, false otherwise.

Public Static Functions

static std::pair<float, float> get_image_dimensions(const std::string &path, ImageFormat format)

Returns image dimensions from a file path.

Parameters:

  • path – Image file path.

  • format – Image format.

Returns:

Pair of width/height in points.

DocraftTable

Table node with titles, headers, column/row weights, and cell content. Supports horizontal and vertical orientations and JSON model binding.

class DocraftTable : public docraft::model::DocraftNode, public docraft::model::IDocraftClonable

Table node with titles and cell content.

Supports horizontal or vertical models, with per-row/column weights and title/content nodes stored separately.

Public Functions

DocraftTable()

Creates an empty table.

~DocraftTable() override = default
virtual void draw(const std::shared_ptr<DocraftDocumentContext> &context) override

Draws the table using the provided context.

Parameters:

context – Document context.

virtual std::shared_ptr<DocraftNode> clone() const override

Clones the table node and its content.

Returns:

Shared pointer to the cloned node.

void set_rows(int rows)

Sets the number of rows.

Parameters:

rows – Row count.

void set_cols(int cols)

Sets the number of columns.

Parameters:

cols – Column count.

void set_orientation(LayoutOrientation orientation)

Sets the table orientation.

Parameters:

orientation – Layout orientation.

void set_column_weight(int index, float weight)

Sets the weight for a column.

Parameters:

  • index – Column index.

  • weight – Weight value.

void set_row_weight(int index, float weight)

Sets the weight for a row.

Parameters:

  • index – Row index.

  • weight – Weight value.

void set_baseline_offset(float offset)

Sets the baseline offset for text alignment.

Parameters:

offset – Offset value.

void set_title(int index, const std::string &title)

Sets a column title string by index.

Parameters:

  • index – Column index.

  • title – Title text.

void set_titles(const std::vector<std::string> &titles)

Sets all column titles.

Parameters:

titles – Vector of titles.

void set_content_cols(int cols)

Sets the number of content columns (data cells per row).

Parameters:

cols – Content column count.

void set_column_weights(const std::vector<float> &weights)

Sets all column weights.

Parameters:

weights – Vector of weights.

void set_row_weights(const std::vector<float> &weights)

Sets all row weights.

Parameters:

weights – Vector of weights.

void set_title_node(int index, const std::shared_ptr<DocraftText> &node)

Sets a title node by index.

Parameters:

  • index – Column index.

  • node – Title node.

void set_htitle_node(int index, const std::shared_ptr<DocraftText> &node)

Sets a header title node by index (vertical tables only).

Parameters:

  • index – Header title index.

  • node – Header title node.

void set_content_node(int index, const std::shared_ptr<DocraftNode> &node)

Sets a content node by flat index.

Parameters:

  • index – Content index (row-major).

  • node – Content node.

void set_content_node_background(int index, const DocraftColor &color)

Sets a content node background by flat index.

Parameters:

  • index – Content index (row-major).

  • color – Background color.

void set_title_nodes(const std::vector<std::shared_ptr<DocraftText>> &nodes)

Sets all title nodes.

Parameters:

nodes – Vector of title nodes.

void set_htitle_nodes(const std::vector<std::shared_ptr<DocraftText>> &nodes)

Sets all header title nodes (vertical tables only).

Parameters:

nodes – Vector of header title nodes.

void set_content_nodes(const std::vector<std::shared_ptr<DocraftNode>> &nodes)

Sets all content nodes.

Parameters:

nodes – Vector of content nodes.

void add_title_node(const std::shared_ptr<DocraftText> &node, std::optional<DocraftColor> background = std::nullopt)

Adds a title node.

Parameters:

  • node – Title node.

  • background – Optional background color.

void add_htitle_node(const std::shared_ptr<DocraftText> &node, std::optional<DocraftColor> background = std::nullopt)

Adds a header title node (vertical tables only).

Parameters:

  • node – Header title node.

  • background – Optional background color.

void add_content_node(const std::shared_ptr<DocraftNode> &node, std::optional<DocraftColor> background = std::nullopt)

Adds a content node.

Parameters:

  • node – Content node.

  • background – Optional background color.

void add_row_background(std::optional<DocraftColor> background)

Adds a row background.

Parameters:

background – Optional background color.

void set_row_background(int index, const DocraftColor &background)

Sets a row background.

Parameters:

  • index – Row index.

  • background – Background color.

void set_default_cell_background(std::optional<DocraftColor> background)

Sets the default background for data cells.

Parameters:

background – Optional background color.

void set_model_template(const std::string &model_template)

Sets a template placeholder for JSON model data.

Parameters:

model_template – Template string (e.g. “${prodotti}”).

void set_header_template(const std::string &header_template)

Sets a template placeholder for JSON header data.

Parameters:

header_template – Template string (e.g. “${prodotti_header}”).

bool has_model_template() const

Returns whether a model template is set.

Returns:

true if template is set.

bool has_header_template() const

Returns whether a header template is set.

Returns:

true if template is set.

const std::string &model_template() const

Returns the model template string.

Returns:

Template string.

const std::string &header_template() const

Returns the header template string.

Returns:

Template string.

void clear_model_template()

Clears the model template string.

void clear_header_template()

Clears the header template string.

void apply_json_rows(const std::string &json_str)

Applies JSON matrix model to the table (horizontal only).

Parameters:

json_str – JSON matrix string.

void apply_json_header(const std::string &json_str)

Applies JSON header array to the table (horizontal only).

Parameters:

json_str – JSON array string.

std::shared_ptr<DocraftTable> split_after_row(std::size_t rows_to_keep, bool repeat_header)

Splits the table after the given number of rows.

Parameters:

  • rows_to_keep – Number of rows to keep in the current table.

  • repeat_header – Whether to repeat titles/header in the remainder table.

Returns:

New table containing the remaining rows, or nullptr if no split.

int rows() const

Returns the number of rows.

Returns:

Row count.

int cols() const

Returns the number of columns.

Returns:

Column count.

int content_cols() const

Returns the number of content columns.

Returns:

Content column count.

LayoutOrientation orientation() const

Returns the table orientation.

Returns:

Orientation enum.

const std::vector<std::string> &titles() const

Returns title strings.

Returns:

Vector of titles.

const std::vector<float> &column_weights() const

Returns column weights.

Returns:

Vector of column weights.

const std::vector<float> &row_weights() const

Returns row weights.

Returns:

Vector of row weights.

int last_row_weight_index() const

Returns the last row-weight index used.

Returns:

Index of last row weight.

int last_column_weight_index() const

Returns the last column-weight index used.

Returns:

Index of last column weight.

const std::vector<std::shared_ptr<DocraftText>> &title_nodes() const

Returns title nodes.

Returns:

Vector of title nodes.

const std::vector<std::shared_ptr<DocraftText>> &htitle_nodes() const

Returns header title nodes (vertical tables only).

Returns:

Vector of header title nodes.

std::vector<std::vector<std::shared_ptr<DocraftNode>>> content_nodes() const

Returns content nodes as a 2D array.

Returns:

2D vector of content nodes.

const std::vector<std::optional<DocraftColor>> &title_backgrounds() const

Returns title cell background colors.

Returns:

Vector of optional title background colors.

const std::vector<std::optional<DocraftColor>> &htitle_backgrounds() const

Returns header title cell background colors.

Returns:

Vector of optional header title background colors.

const std::vector<std::optional<DocraftColor>> &content_backgrounds() const

Returns content cell background colors.

Returns:

Vector of optional content background colors.

const std::vector<std::optional<DocraftColor>> &row_backgrounds() const

Returns row background colors.

Returns:

Vector of optional row background colors.

const std::optional<DocraftColor> &default_cell_background() const

Returns the default background for data cells.

Returns:

Optional background color.

int last_title_node_index() const

Returns the last title node index.

Returns:

Index of last title node.

int last_content_node_index() const

Returns the last content node index.

Returns:

Index of last content node.

float baseline_offset() const

Returns the baseline offset.

Returns:

Baseline offset.

DocraftModelType model_type() const

Returns the model type.

Returns:

Model type enum.

void set_model_type(DocraftModelType model_type)

Sets the model type.

Parameters:

model_type – Model type enum.

Public Static Functions

static DocraftModelType identify_model_type(const std::string &model_str)

DocraftList

List node with markers (ordered or unordered) and child items.

class DocraftList : public docraft::model::DocraftChildrenContainerNode, public docraft::model::IDocraftClonable

List node with markers and child items.

Markers are computed from the list style and stored for layout and rendering.

Public Functions

DocraftList(const DocraftList &node) = default
~DocraftList() override = default
virtual void draw(const std::shared_ptr<DocraftDocumentContext> &context) override

Draws the list using the provided context.

Parameters:

context – Document context.

virtual std::shared_ptr<DocraftNode> clone() const override

Clones the list node and its children.

Returns:

Shared pointer to the cloned node.

ListKind kind() const

Returns the list kind.

Returns:

List kind enum.

OrderedListStyle ordered_style() const

Returns the ordered list style.

Returns:

Ordered list style enum.

UnorderedListDot unordered_dot() const

Returns the unordered list marker type.

Returns:

Unordered list marker enum.

void set_kind(ListKind kind)

Sets the list kind.

Parameters:

kind – List kind enum.

void set_ordered_style(OrderedListStyle style)

Sets the ordered list style.

Parameters:

style – Ordered list style enum.

void set_unordered_dot(UnorderedListDot dot)

Sets the unordered list marker type.

Parameters:

dot – Unordered list marker enum.

void update_items()

Rebuilds item markers based on children.

void apply_text_transform(const std::function<std::string(const std::string&)> &transform)

Applies a text transform to all items and updates cached raw values.

Parameters:

transform – Text transform function.

std::string marker_for_index(int index) const

Returns the marker text for a given index.

Parameters:

index – Item index.

Returns:

Marker string.

bool marker_is_box() const

Returns whether the marker is rendered as a box.

Returns:

true if markers should be drawn as boxes.

void clear_markers()

Clears all markers.

void set_marker(int index, const std::string &text, const DocraftPoint &position, Marker::Kind kind = Marker::Kind::kText, float size = 0.0F)

Sets a marker at the given index.

Parameters:
const std::vector<Marker> &markers() const

Returns all markers.

Returns:

Vector of markers.

DocraftChildrenContainerNode(const DocraftChildrenContainerNode &node) = default
explicit DocraftChildrenContainerNode(DocraftChildrenContainerNode *node)

Constructs from an existing node pointer (copy).

struct Marker

Marker metadata for layout and rendering.

Public Types

enum class Kind

Marker rendering type.

Values:

enumerator kText
enumerator kBox

Public Members

std::string text
DocraftPoint position
Kind kind = Kind::kText
float size = 0.0F

DocraftLayout

Layout node that arranges children horizontally or vertically with weights.

class DocraftLayout : public docraft::model::DocraftChildrenContainerNode, public docraft::model::IDocraftClonable

Layout node that arranges children horizontally or vertically.

Children can be weighted to control how available space is distributed.

Public Functions

DocraftLayout(const DocraftLayout &node) = default
~DocraftLayout() override = default
explicit DocraftLayout(DocraftLayout *node)

Constructs from an existing node pointer (copy).

LayoutOrientation orientation() const

Returns the layout orientation.

Returns:

Orientation enum.

void set_orientation(LayoutOrientation orientation)

Sets the layout orientation.

Parameters:

orientation – Orientation enum.

virtual void draw(const std::shared_ptr<DocraftDocumentContext> &context) override

Draws the layout and its children.

Parameters:

context – Document context.

virtual std::shared_ptr<DocraftNode> clone() const override

Clones the layout node and its children.

Returns:

Shared pointer to the cloned node.

void set_weight_for_child(int index, float weight) const

Sets the layout weight for a child at the given index.

Parameters:

  • index – Child index.

  • weight – Weight value.

std::vector<float> weights() const

Returns the list of child weights.

Returns:

Vector of weights.

DocraftChildrenContainerNode(const DocraftChildrenContainerNode &node) = default
explicit DocraftChildrenContainerNode(DocraftChildrenContainerNode *node)

Constructs from an existing node pointer (copy).

DocraftForeach

Template loop node that repeats children for each item in a data collection.

class DocraftForeach : public docraft::model::DocraftChildrenContainerNode, public docraft::model::IDocraftClonable

Represents a foreach loop in the document, allowing for dynamic generation of content based on a collection of items.

The foreach node should have a “docraft/model” attribute that specifies the collection to iterate over, and its children will be rendered for each item in the collection with template variables available for the current item.

Public Functions

DocraftForeach() = default
DocraftForeach(const DocraftForeach&) = default
~DocraftForeach() override = default
virtual void draw(const std::shared_ptr<DocraftDocumentContext> &context) override

Draws the node using the provided context.

virtual std::shared_ptr<DocraftNode> clone() const override

Clones the foreach node, its rendered children, and its template nodes.

Returns:

Shared pointer to cloned node.

void set_template_nodes(const std::vector<std::shared_ptr<DocraftNode>> &nodes)

Sets the template nodes that will be rendered for each item in the collection.

Parameters:

nodes – The template nodes to render for each item.

const std::vector<std::shared_ptr<DocraftNode>> &template_nodes() const

Gets the template nodes that will be rendered for each item in the collection.

Returns:

The template nodes to render for each item.

void set_model(const std::string &model)

Sets the model attribute that specifies the collection to iterate over.

Parameters:

model – The model attribute value.

const std::string &model() const

Gets the model attribute that specifies the collection to iterate over.

Returns:

The model attribute value.

void clear_template_nodes()

Clears the template nodes from the foreach node after rendering, to prevent them from being rendered again in subsequent iterations or when the document is rendered again.