Layout Engine

The layout engine computes position and size for every node in the document tree. It uses a chain-of-responsibility pattern: specialized handlers claim specific node types, while a fallback handler covers generic nodes.

How It Works

The public class DocraftLayoutEngine is a facade over an internal DocraftLayoutEngine::Impl. The split keeps the public header stable while hiding implementation details (handlers, pagination internals, section plan, helper state).

Execution model:

  1. compute_document_layout(...) splits top-level sections (Header/Body/Footer).

  2. A section plan is computed from navigation ratios and section visibility.

  3. Header is laid out (if visible), then Body, then Footer.

  4. Body layout applies pagination rules and assigns page_owner recursively.

Node-level model:

  • compute_layout(node, cursor) evaluates visibility and positioning mode.

  • Flow nodes advance the cursor; absolute nodes are laid out independently.

  • Container nodes recursively layout children, then handlers compute final box.

  • Cursor spacing is adjusted with fixed horizontal/vertical spacing rules.

Pagination model in body:

  • NewPage forces page advance.

  • Overflowing non-absolute nodes are re-laid on a new page.

  • Tables are split when only a subset of rows fits in remaining body space.

Implementation files

  • Public API: docraft/include/docraft/layout/docraft_layout_engine.h

  • Facade: docraft/src/docraft/layout/docraft_layout_engine.cc

  • Private impl declaration: docraft/src/docraft/layout/docraft_layout_engine_impl.h

  • Private impl definition: docraft/src/docraft/layout/docraft_layout_engine_impl.cc

DocraftLayoutEngine

Main engine that walks the DOM and delegates box computation to handlers.

class DocraftLayoutEngine

Computes layout boxes for document nodes using a chain of handlers.

The engine walks node trees and delegates box computation to specialized handlers (text, table, list, etc.), maintaining a cursor for flow layout.

Public Functions

explicit DocraftLayoutEngine(const std::shared_ptr<DocraftDocumentContext> &context, bool reset_cursor = true)

Creates a layout engine for the given document context.

Parameters:

  • context – Document context used for measurements and page info.

  • reset_cursor – Whether to reset the cursor before layout.

DocraftLayoutEngine(const DocraftLayoutEngine&) = delete
DocraftLayoutEngine &operator=(const DocraftLayoutEngine&) = delete
DocraftLayoutEngine(DocraftLayoutEngine&&) noexcept
DocraftLayoutEngine &operator=(DocraftLayoutEngine&&) noexcept
virtual ~DocraftLayoutEngine()

Destructor.

model::DocraftTransform compute_layout(const std::shared_ptr<model::DocraftNode> &node)

Computes the layout for a single node tree.

Parameters:

node – A shared pointer to a DocraftNode object.

Returns:

A DocraftTransform representing the computed layout box.

model::DocraftTransform compute_layout(const std::shared_ptr<model::DocraftNode> &node, DocraftCursor &cursor)

Computes the layout for a single node tree with a custom cursor.

Parameters:

  • node – A shared pointer to a DocraftNode object.

  • cursor – Cursor used for layout traversal.

Returns:

A DocraftTransform representing the computed layout box.

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

Computes the layout for a full document represented by a vector of nodes.

Parameters:

nodes – A vector of shared pointers to DocraftNode objects.

AbstractDocraftLayoutHandler

Base template for all layout handlers.

template<typename T>
class AbstractDocraftLayoutHandler : public docraft::generic::DocraftChainOfResponsibilityHandler<model::DocraftNode, model::DocraftTransform>

Public Functions

~AbstractDocraftLayoutHandler() override = default
inline explicit AbstractDocraftLayoutHandler(const std::shared_ptr<DocraftDocumentContext> &context)

Creates a handler bound to a document context.

Throws:

docraft::exception::InvalidInputException – if context is null.

virtual void compute(const std::shared_ptr<T> &node, model::DocraftTransform *box, DocraftCursor &cursor) = 0

Computes the layout box for a concrete node type.

Parameters:

  • node – Node to layout.

  • box – Output transform.

  • cursor – Layout cursor.

inline std::shared_ptr<DocraftDocumentContext> edit_context() const

Returns the bound document context.

Returns:

Document context.

inline std::shared_ptr<const DocraftDocumentContext> context() const

Returns the bound document context as a const pointer.

Returns:

DocraftBasicLayoutHandler

Fallback handler for generic nodes.

class DocraftBasicLayoutHandler : public docraft::layout::handler::AbstractDocraftLayoutHandler<model::DocraftNode>

Fallback layout handler for generic nodes.

Used when no specialized handler claims the node.

Public Functions

virtual void compute(const std::shared_ptr<model::DocraftNode> &node, model::DocraftTransform *box, DocraftCursor &cursor) override

Computes the layout box for a basic node.

Parameters:

  • node – Node to layout.

  • box – Output transform.

  • cursor – Layout cursor.

virtual bool handle(const std::shared_ptr<model::DocraftNode> &request, model::DocraftTransform *result, DocraftCursor &cursor) override

Handles a node if no specialized handler applies.

Parameters:

  • request – Node to handle.

  • result – Output transform.

  • cursor – Layout cursor.

Returns:

true if handled.

inline explicit AbstractDocraftLayoutHandler(const std::shared_ptr<DocraftDocumentContext> &context)

Creates a handler bound to a document context.

Throws:

docraft::exception::InvalidInputException – if context is null.

DocraftLayoutTextHandler

Handles text measurement, alignment, and line-breaking.

class DocraftLayoutTextHandler : public docraft::layout::handler::AbstractDocraftLayoutHandler<model::DocraftText>

Layout handler for text nodes.

Measures text width, handles alignment, and manages line breaks.

Public Functions

virtual void compute(const std::shared_ptr<model::DocraftText> &node, model::DocraftTransform *box, DocraftCursor &cursor) override

Computes the layout box for a text node.

Parameters:

  • node – Text node.

  • box – Output transform.

  • cursor – Layout cursor.

virtual bool handle(const std::shared_ptr<model::DocraftNode> &request, model::DocraftTransform *result, DocraftCursor &cursor) override

Handles a node if it is a DocraftText.

Parameters:

  • request – Node to handle.

  • result – Output transform.

  • cursor – Layout cursor.

Returns:

true if handled.

inline explicit AbstractDocraftLayoutHandler(const std::shared_ptr<DocraftDocumentContext> &context)

Creates a handler bound to a document context.

Throws:

docraft::exception::InvalidInputException – if context is null.

DocraftLayoutTableHandler

Calculates cell boxes and header/content areas.

class DocraftLayoutTableHandler : public docraft::layout::handler::AbstractDocraftLayoutHandler<model::DocraftTable>

Base layout handler for table nodes.

Handles the degenerate case of tables with no titles (zero-size output). Provides shared state and helper methods for orientation-specific sub-handlers:

  • DocraftLayoutHorizontalTableHandler (kHorizontal)

  • DocraftLayoutVerticalTableHandler (kVertical)

Register all three in the handler chain so each handles its own case.

Subclassed by docraft::layout::handler::DocraftLayoutHorizontalTableHandler, docraft::layout::handler::DocraftLayoutVerticalTableHandler

Public Functions

virtual void compute(const std::shared_ptr<model::DocraftTable> &node, model::DocraftTransform *box, DocraftCursor &cursor) override

Computes the layout box for a table node.

Parameters:

  • node – Table node.

  • box – Output transform.

  • cursor – Layout cursor.

virtual bool handle(const std::shared_ptr<model::DocraftNode> &request, model::DocraftTransform *result, DocraftCursor &cursor) override

Handles a node if it is a DocraftTable.

Parameters:

  • request – Node to handle.

  • result – Output transform.

  • cursor – Layout cursor.

Returns:

true if handled.

DocraftLayoutListHandler

Computes marker positions and list item content.

class DocraftLayoutListHandler : public docraft::layout::handler::AbstractDocraftLayoutHandler<model::DocraftList>

Layout handler for list nodes.

Computes marker positions and lays out list item content.

Public Functions

virtual void compute(const std::shared_ptr<model::DocraftList> &node, model::DocraftTransform *box, DocraftCursor &cursor) override

Computes the layout box for a list node.

Parameters:

  • node – List node.

  • box – Output transform.

  • cursor – Layout cursor.

void compute_children(const std::shared_ptr<model::DocraftList> &node, DocraftCursor &cursor, std::vector<model::DocraftTransform> &child_boxes, const std::function<model::DocraftTransform(const std::shared_ptr<model::DocraftNode>&, DocraftCursor&)> &layout_child, float max_width) const

Computes layout for list children using a provided layout function.

Parameters:

  • node – List node.

  • cursor – Layout cursor.

  • child_boxes – Output transforms for children.

  • layout_child – Layout function for a child node.

  • max_width – Available width in points.

virtual bool handle(const std::shared_ptr<model::DocraftNode> &request, model::DocraftTransform *result, DocraftCursor &cursor) override

Handles a node if it is a DocraftList.

Parameters:

  • request – Node to handle.

  • result – Output transform.

  • cursor – Layout cursor.

Returns:

true if handled.

DocraftLayoutHandler

Handler for DocraftLayout nodes (horizontal/vertical children).

class DocraftLayoutHandler : public docraft::layout::handler::AbstractDocraftLayoutHandler<model::DocraftLayout>

Layout handler for DocraftLayout nodes.

Computes child boxes based on orientation and weights.

Public Functions

virtual void compute(const std::shared_ptr<model::DocraftLayout> &node, model::DocraftTransform *box, DocraftCursor &cursor) override

Computes the layout for a layout node.

Parameters:

  • node – Layout node.

  • box – Output transform.

  • cursor – Layout cursor.

virtual bool handle(const std::shared_ptr<model::DocraftNode> &request, model::DocraftTransform *result, DocraftCursor &cursor) override

Handles a node if it is a DocraftLayout.

Parameters:

  • request – Node to handle.

  • result – Output transform.

  • cursor – Layout cursor.

Returns:

true if handled.

DocraftLayoutBlankLine

Advances the cursor for blank-line spacing.

class DocraftLayoutBlankLine : public docraft::layout::handler::AbstractDocraftLayoutHandler<model::DocraftBlankLine>

Layout handler for blank line nodes.

Advances the cursor to create vertical spacing.

Public Functions

virtual void compute(const std::shared_ptr<model::DocraftBlankLine> &node, model::DocraftTransform *box, DocraftCursor &cursor) override

Computes the layout box for a blank line.

Parameters:

  • node – Blank line node.

  • box – Output transform.

  • cursor – Layout cursor.

virtual bool handle(const std::shared_ptr<model::DocraftNode> &request, model::DocraftTransform *result, DocraftCursor &cursor) override

Handles a node if it is a DocraftBlankLine.

Parameters:

  • request – Node to handle.

  • result – Output transform.

  • cursor – Layout cursor.

Returns:

true if handled.