# StructElement Class

> Internal wrapper for a single node in the 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/StructElement
- Version index: https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/llms.txt

```cpp
class StructElement
```

**Namespace:** `datalogics_interface`

## Description

Internal wrapper for a single node in the PDF logical structure tree.

Owns a non-owning reference to its CDocument. Exposes type (/S) access, the backing dict (for arbitrary attribute reads/writes), child creation, and marked-content reference insertion.

Threading: single-thread use. A `StructElement` 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 `StructElement` must not outlive the `Document` that produced it.

**Referenced by:** [`StructElement`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/StructElement.md), [`StructTreeRoot`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/StructTreeRoot.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), [`Page`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Page.md), [`StructElement`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/StructElement.md), [`StructKidType`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/enum/StructKidType.md)

## Constructors

### StructElement

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

*constructor*

**Parameters**

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

### ~StructElement

```cpp
datalogics_interface::StructElement::~StructElement()
```

*destructor*

## Methods

### add_child

```cpp
StructElement datalogics_interface::StructElement::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 child element with the given struct type (/S).

### add_marked_content_ref

```cpp
void datalogics_interface::StructElement::add_marked_content_ref(Page &page, const Container &container)
```

**Parameters**

- `page` ([`Page &`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Page.md))
- `container` ([`const Container &`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Container.md))

**Returns:** `void`

Append a marked-content reference. `/StructParents` on the page and the parent tree are wired automatically.

### as_pdf_object

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

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

Non-owning indirect handle for use in containers.

### get_kid_as_element

```cpp
StructElement datalogics_interface::StructElement::get_kid_as_element(size_t index) const
```

**Parameters**

- `index` (`size_t`)

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

Kid at `index` interpreted as a child struct element.

**Exceptions**

- `std::invalid_argument`: if the kid is not a struct element.

### get_kid_as_marked_content_mcid

```cpp
int datalogics_interface::StructElement::get_kid_as_marked_content_mcid(size_t index) const
```

**Parameters**

- `index` (`size_t`)

**Returns:** `int`

MCID of the marked-content kid at `index`.

**Exceptions**

- `std::invalid_argument`: if the kid is not a marked-content ref.

### get_kid_as_marked_content_page

```cpp
Page datalogics_interface::StructElement::get_kid_as_marked_content_page(size_t index) const
```

**Parameters**

- `index` (`size_t`)

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

Page containing the marked-content kid at `index`.

**Exceptions**

- `std::invalid_argument`: if the kid is not a marked-content ref.

### get_kid_count

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

**Returns:** `size_t`

Number of kids in this element's /K array.

### get_kid_type

```cpp
StructKidType datalogics_interface::StructElement::get_kid_type(size_t index) const
```

**Parameters**

- `index` (`size_t`)

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

Classify the kid at `index`. Caller should gate type-specific accessors on this result.

### get_parent

```cpp
std::optional< StructElement > datalogics_interface::StructElement::get_parent() const
```

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

Immediate parent element in the tree, or std::nullopt when the parent is the struct tree root (use parent_is_tree_root() to tell the two nullopt conditions apart explicitly).

### get_pdf_dict

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

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

Full backing dict — escape hatch for all attributes (/Alt, /ActualText, /Lang, /E, /T, /ID, /A, etc.).

### get_type

```cpp
std::string datalogics_interface::StructElement::get_type() const
```

**Returns:** `std::string`

Struct type (/S) value as a string.

### operator=

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

**Parameters**

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

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

### parent_is_tree_root

```cpp
bool datalogics_interface::StructElement::parent_is_tree_root() const
```

**Returns:** `bool`

True when this element's immediate parent is the struct tree root.