# StructTreeRoot Class

> Internal wrapper for the root of a PDF logical structure tree.

- Product: Adobe PDF Library 21
- Language: Modern C++
- Version: 21.4.0
- HTML page: https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/StructTreeRoot
- Version index: https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/llms.txt

```cpp
class StructTreeRoot
```

**Namespace:** `datalogics_interface`

## Description

Internal wrapper for the root of a PDF logical structure tree.

Owns a non-owning reference to its CDocument. The underlying PDF structure tree is owned by the document; this wrapper provides C++ access to catalog- level struct tree operations (add children, access the backing dict).

Root of the PDF logical structure tree. Obtained exclusively via Document::create_struct_tree_root() or Document::get_struct_tree_root().

Threading: single-thread use. A `StructTreeRoot` is bound to its owning `Document`'s thread; do not share it across threads. See `datalogics_interface.hpp` for the full threading model.

Lifetime: a `StructTreeRoot` must not outlive the `Document` that produced it.

**Referenced by:** [`Document`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Document.md)

**Uses types:** [`PDFDict`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/PDFDict.md), [`PDFObject`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/PDFObject.md), [`StructElement`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/StructElement.md)

## Constructors

### StructTreeRoot

```cpp
datalogics_interface::StructTreeRoot::StructTreeRoot(StructTreeRoot &&) noexcept
```

*constructor*

**Parameters**

- (unnamed) ([`StructTreeRoot &&`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/StructTreeRoot.md))

### ~StructTreeRoot

```cpp
datalogics_interface::StructTreeRoot::~StructTreeRoot()
```

*destructor*

## Methods

### add_child

```cpp
StructElement datalogics_interface::StructTreeRoot::add_child(const std::string &struct_type)
```

**Parameters**

- `struct_type` (`const std::string &`)

**Returns:** [`StructElement`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/StructElement.md)

Create and append a top-level child element with the given struct type.

### as_pdf_object

```cpp
PDFObject datalogics_interface::StructTreeRoot::as_pdf_object() const
```

**Returns:** [`PDFObject`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/PDFObject.md)

Non-owning handle suitable for use in dicts/arrays as an indirect reference. The StructTreeRoot dict is always indirect.

### find_element_by_id

```cpp
std::optional< StructElement > datalogics_interface::StructTreeRoot::find_element_by_id(const std::string &id) const
```

**Parameters**

- `id` (`const std::string &`)

**Returns:** [`std::optional< StructElement >`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/StructElement.md)

Element whose /ID (via the tree's /IDTree) matches `id`, or std::nullopt when no element with that ID exists.

### get_kid

```cpp
StructElement datalogics_interface::StructTreeRoot::get_kid(size_t index) const
```

**Parameters**

- `index` (`size_t`)

**Returns:** [`StructElement`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/StructElement.md)

Top-level kid at `index`. Always a struct element per the PDF spec.

**Exceptions**

- `std::out_of_range`: if `index` is not less than get_kid_count().

### get_kid_count

```cpp
size_t datalogics_interface::StructTreeRoot::get_kid_count() const
```

**Returns:** `size_t`

Number of top-level kids on this tree root. Per the PDF spec, all kids of a tree root are struct elements (no MCRs / OBJRs), so the counterpart accessor is `get_kid(index)`.

### get_pdf_dict

```cpp
PDFDict datalogics_interface::StructTreeRoot::get_pdf_dict() const
```

**Returns:** [`PDFDict`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/PDFDict.md)

Returns the raw catalog-side dict for this StructTreeRoot — used as the escape hatch for /RoleMap, /IDTree, /ParentTreeNextKey and any other entry without a dedicated accessor.

### operator=

```cpp
StructTreeRoot & datalogics_interface::StructTreeRoot::operator=(StructTreeRoot &&) noexcept
```

**Parameters**

- (unnamed) ([`StructTreeRoot &&`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/StructTreeRoot.md))

**Returns:** [`StructTreeRoot &`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/StructTreeRoot.md)