Enum Control 

#[non_exhaustive]
pub enum Control {
    TextBox {
        paragraphs: Vec<Paragraph>,
        width: HwpUnit,
        height: HwpUnit,
        horz_offset: i32,
        vert_offset: i32,
        caption: Option<Caption>,
        style: Option<ShapeStyle>,
        text_vertical_align: VerticalAlign,
    },
    Hyperlink {
        text: String,
        url: String,
    },
    Footnote {
        inst_id: Option<ObjectId>,
        paragraphs: Vec<Paragraph>,
    },
    Endnote {
        inst_id: Option<ObjectId>,
        paragraphs: Vec<Paragraph>,
    },
    Line {
        start: ShapePoint,
        end: ShapePoint,
        width: HwpUnit,
        height: HwpUnit,
        horz_offset: i32,
        vert_offset: i32,
        caption: Option<Caption>,
        style: Option<ShapeStyle>,
    },
    Ellipse {
        center: ShapePoint,
        axis1: ShapePoint,
        axis2: ShapePoint,
        width: HwpUnit,
        height: HwpUnit,
        horz_offset: i32,
        vert_offset: i32,
        paragraphs: Vec<Paragraph>,
        caption: Option<Caption>,
        style: Option<ShapeStyle>,
        text_vertical_align: VerticalAlign,
    },
    EmbeddedChart {
        chart_xml: String,
        ole_bytes: Vec<u8>,
        width: HwpUnit,
        height: HwpUnit,
        horz_offset: i32,
        vert_offset: i32,
    },
    Rect {
        width: HwpUnit,
        height: HwpUnit,
        horz_offset: i32,
        vert_offset: i32,
        caption: Option<Caption>,
        style: Option<ShapeStyle>,
    },
    Polygon {
        vertices: Vec<ShapePoint>,
        width: HwpUnit,
        height: HwpUnit,
        horz_offset: i32,
        vert_offset: i32,
        paragraphs: Vec<Paragraph>,
        caption: Option<Caption>,
        style: Option<ShapeStyle>,
        text_vertical_align: VerticalAlign,
    },
    Equation {
        script: String,
        width: HwpUnit,
        height: HwpUnit,
        base_line: u32,
        text_color: Color,
        font: String,
        inst_id: Option<ObjectId>,
    },
    Chart {

        chart_type: ChartType,
        data: ChartData,
        width: HwpUnit,
        height: HwpUnit,
        title: Option<String>,
        legend: LegendPosition,
        grouping: ChartGrouping,
        bar_shape: Option<BarShape>,
        explosion: Option<u32>,
        of_pie_type: Option<OfPieType>,
        radar_style: Option<RadarStyle>,
        wireframe: Option<bool>,
        bubble_3d: Option<bool>,
        scatter_style: Option<ScatterStyle>,
        show_markers: Option<bool>,
        stock_variant: Option<StockVariant>,
    
},
    Dutmal {
        main_text: String,
        sub_text: String,
        position: DutmalPosition,
        sz_ratio: u32,
        align: DutmalAlign,
        metadata: DutmalMetadata,
    },
    Compose {
        compose_text: String,
        circle_type: String,
        char_sz: i32,
        compose_type: String,
        char_pr_ids: Vec<u32>,
    },
    Arc {

        arc_type: ArcType,
        center: ShapePoint,
        axis1: ShapePoint,
        axis2: ShapePoint,
        start1: ShapePoint,
        end1: ShapePoint,
        start2: ShapePoint,
        end2: ShapePoint,
        width: HwpUnit,
        height: HwpUnit,
        horz_offset: i32,
        vert_offset: i32,
        caption: Option<Caption>,
        style: Option<ShapeStyle>,
    
},
    Curve {
        points: Vec<ShapePoint>,
        segment_types: Vec<CurveSegmentType>,
        width: HwpUnit,
        height: HwpUnit,
        horz_offset: i32,
        vert_offset: i32,
        caption: Option<Caption>,
        style: Option<ShapeStyle>,
    },
    ConnectLine {
        start: ShapePoint,
        end: ShapePoint,
        control_points: Vec<ShapePoint>,
        connect_type: String,
        width: HwpUnit,
        height: HwpUnit,
        horz_offset: i32,
        vert_offset: i32,
        caption: Option<Caption>,
        style: Option<ShapeStyle>,
    },
    Group {
        children: Vec<Control>,
        width: HwpUnit,
        height: HwpUnit,
        horz_offset: i32,
        vert_offset: i32,
        inst_id: Option<ObjectId>,
    },
    TextArt {

        text: String,
        shape: String,
        font_name: String,
        font_style: String,
        align: String,
        line_spacing: u32,
        char_spacing: u32,
        width: HwpUnit,
        height: HwpUnit,
        horz_offset: i32,
        vert_offset: i32,
        fill_color: Option<Color>,
        inst_id: Option<ObjectId>,
    
},
    Bookmark {
        name: String,
        bookmark_type: BookmarkType,
    },
    CrossRef {
        target: RefTarget,
        ref_type: RefType,
        content_type: RefContentType,
        as_hyperlink: bool,
        display_text: String,
    },
    Field {
        field_type: FieldType,
        hint_text: Option<String>,
        help_text: Option<String>,
        name: Option<String>,
        display_text: String,
    },
    Memo {
        content: Vec<Paragraph>,
        anchor_runs: Vec<Run>,
        metadata: MemoMetadata,
    },
    IndexMark {
        primary: String,
        secondary: Option<String>,
    },
    UnknownSummary {
        token: String,
        display_text: String,
    },
    DateCodeField {
        is_time_mode: bool,
        display_text: String,
    },
    PathField {
        command: PathFieldCommand,
        display_text: String,
    },
    InlinePageNumber {
        kind: InlinePageKind,
    },
    Unknown {
        tag: String,
        data: Option<String>,
    },
}

An inline control element.

Controls are non-text elements that appear within a Run. Each variant carries its own data; the enum is #[non_exhaustive] for forward compatibility.

Examples

use hwpforge_core::control::Control;
use hwpforge_core::paragraph::Paragraph;
use hwpforge_foundation::{HwpUnit, ParaShapeIndex};

let text_box = Control::TextBox {
    paragraphs: vec![Paragraph::new(ParaShapeIndex::new(0))],
    width: HwpUnit::from_mm(80.0).unwrap(),
    height: HwpUnit::from_mm(40.0).unwrap(),
    horz_offset: 0,
    vert_offset: 0,
    caption: None,
    style: None,
};
assert!(text_box.is_text_box());
assert!(!text_box.is_hyperlink());

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

TextBox

An inline text box with its own paragraph content. Maps to HWPX <hp:rect> + <hp:drawText> (drawing object, not control).

Fields

paragraphs: Vec<Paragraph>

Paragraphs inside the text box.

width: HwpUnit

Box width (HWPUNIT).

height: HwpUnit

Box height (HWPUNIT).

horz_offset: i32

Horizontal offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

vert_offset: i32

Vertical offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

caption: Option<Caption>

Optional caption attached to this text box.

style: Option<ShapeStyle>

Optional visual style overrides (border color, fill, line width).

text_vertical_align: VerticalAlign

Vertical alignment of the embedded text within the box. Maps to HWPX <hp:drawText><hp:subList vertAlign="..."> and HWP5 문단 리스트 헤더 속성 bits 5–6. Defaults to VerticalAlign::Top.

Hyperlink

A hyperlink with display text and URL.

Fields

text: String

Visible text of the link.

url: String

Target URL.

Footnote

A footnote containing paragraph content. Maps to HWPX <hp:ctrl><hp:footNote>.

Fields

inst_id: Option<ObjectId>

Object identity for cross-ref linking (optional). Shares the ObjectId space with RefTarget::Object.

paragraphs: Vec<Paragraph>

Paragraphs that form the footnote body.

Endnote

An endnote containing paragraph content. Maps to HWPX <hp:ctrl><hp:endNote>.

Fields

inst_id: Option<ObjectId>

Object identity for cross-ref linking (optional). Shares the ObjectId space with RefTarget::Object.

paragraphs: Vec<Paragraph>

Paragraphs that form the endnote body.

Line

A line drawing object (2 endpoints). Maps to HWPX <hp:line>.

Fields

start: ShapePoint

Start point (x, y in HWPUNIT).

end: ShapePoint

End point (x, y in HWPUNIT).

width: HwpUnit

Bounding box width (HWPUNIT).

height: HwpUnit

Bounding box height (HWPUNIT).

horz_offset: i32

Horizontal offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

vert_offset: i32

Vertical offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

caption: Option<Caption>

Optional caption attached to this line.

style: Option<ShapeStyle>

Optional visual style overrides (border color, fill, line width).

Ellipse

An ellipse (or circle) drawing object. Maps to HWPX <hp:ellipse>.

Fields

center: ShapePoint

Center point (x, y in HWPUNIT).

axis1: ShapePoint

Axis 1 endpoint (defines semi-major axis direction and length).

axis2: ShapePoint

Axis 2 endpoint (perpendicular to axis1, defines semi-minor axis).

width: HwpUnit

Bounding box width (HWPUNIT).

height: HwpUnit

Bounding box height (HWPUNIT).

horz_offset: i32

Horizontal offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

vert_offset: i32

Vertical offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

paragraphs: Vec<Paragraph>

Optional text content inside the ellipse.

caption: Option<Caption>

Optional caption attached to this ellipse.

style: Option<ShapeStyle>

Optional visual style overrides (border color, fill, line width).

text_vertical_align: VerticalAlign

Vertical alignment of the embedded text within the ellipse. Maps to HWPX <hp:drawText><hp:subList vertAlign="..."> and HWP5 문단 리스트 헤더 속성 bits 5–6. Defaults to VerticalAlign::Top.

EmbeddedChart

A HWP5 chart carried as opaque OOXML + OLE blob passthrough.

Used when chart data is extracted from a HWP5 BinData OLE container and emitted to HWPX without round-tripping through the structured Control::Chart data model. Renders in 한컴 via the <hp:switch> block with full OOXML chart inside <hp:case> and an OLE fallback inside <hp:default>.

Wave 4c passthrough: the chart XML and OLE bytes are carried as-is from the source HWP5 file. The encoder writes:

• Chart/chartN.xml (NOT registered in manifest — gotcha #5)
• BinData/oleN.ole (registered in content.hpf as application/ole)
• section <hp:switch> with <hp:case> chart + <hp:default> ole

Fields

chart_xml: String

Full OOXML chart XML (starts with <?xml, contains <c:chartSpace>).

ole_bytes: Vec<u8>

Raw OLE2 compound file bytes for <hp:ole> fallback rendering.

width: HwpUnit

Chart width (HWPUNIT).

height: HwpUnit

Chart height (HWPUNIT).

horz_offset: i32

Horizontal offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

vert_offset: i32

Vertical offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

Rect

A pure rectangle drawing object (no embedded text).

Distinct from Control::TextBox, which uses <hp:rect> with a <hp:drawText> child for inline text. A pure Rect carries only the rectangle geometry and visual style and emits <hp:rect> without <hp:drawText>.

Fields

width: HwpUnit

Bounding box width (HWPUNIT).

height: HwpUnit

Bounding box height (HWPUNIT).

horz_offset: i32

Horizontal offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

vert_offset: i32

Vertical offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

caption: Option<Caption>

Optional caption attached to this rectangle.

style: Option<ShapeStyle>

Optional visual style overrides (border color, fill, line width).

Polygon

A polygon drawing object (3+ vertices). Maps to HWPX <hp:polygon>.

Fields

vertices: Vec<ShapePoint>

Ordered list of vertices (minimum 3).

width: HwpUnit

Bounding box width (HWPUNIT).

height: HwpUnit

Bounding box height (HWPUNIT).

horz_offset: i32

Horizontal offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

vert_offset: i32

Vertical offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

paragraphs: Vec<Paragraph>

Optional text content inside the polygon.

caption: Option<Caption>

Optional caption attached to this polygon.

style: Option<ShapeStyle>

Optional visual style overrides (border color, fill, line width).

text_vertical_align: VerticalAlign

Vertical alignment of the embedded text within the polygon. Maps to HWPX <hp:drawText><hp:subList vertAlign="..."> and HWP5 문단 리스트 헤더 속성 bits 5–6. Defaults to VerticalAlign::Top.

Equation

An inline equation (수식) using HancomEQN script format. Maps to HWPX <hp:equation> with <hp:script> child.

Equations have NO shape common block (no offset, orgSz, curSz, flip, rotation, lineShape, fillBrush, shadow). Only sz + pos + outMargin + script.

Fields

script: String

HancomEQN script text (e.g. "{a+b} over {c+d}").

width: HwpUnit

Bounding box width (HWPUNIT).

height: HwpUnit

Bounding box height (HWPUNIT).

base_line: u32

Baseline position (51-90 typical range).

text_color: Color

Text color.

font: String

Font name (typically "HancomEQN").

inst_id: Option<ObjectId>

Wave 12p Step 2c: instance ID for cross-ref target lookup. HWP5 변환 시 eqed CtrlHeader trailer 의 instance ID 가 채워지고, HWPX encoder 가 <hp:equation id="..."> attribute 로 emit. None 이면 encoder fallback 허용.

Chart

An OOXML chart embedded in the document. Maps to HWPX <hp:switch><hp:case><hp:chart> with separate Chart XML file.

Charts have NO shape common block (like Equation): only sz + pos + outMargin.

Fields

chart_type: ChartType

Chart type (18 variants covering all OOXML chart types).

data: ChartData

Chart data (category-based or XY-based).

width: HwpUnit

Chart width (HWPUNIT, default ~32250 ≈ 114mm).

height: HwpUnit

Chart height (HWPUNIT, default ~18750 ≈ 66mm).

title: Option<String>

Optional chart title.

legend: LegendPosition

Legend position.

grouping: ChartGrouping

Series grouping mode.

bar_shape: Option<BarShape>

3D bar/column shape (None = default Box).

explosion: Option<u32>

Exploded pie/doughnut percentage (None = not exploded, Some(25) = 25% explosion).

of_pie_type: Option<OfPieType>

Pie-of-pie or bar-of-pie sub-type (None = default pie-of-pie).

radar_style: Option<RadarStyle>

Radar chart rendering style (None = default Standard).

wireframe: Option<bool>

Surface chart wireframe mode (None = default solid).

bubble_3d: Option<bool>

3D bubble effect (None = default flat).

scatter_style: Option<ScatterStyle>

Scatter chart style (None = default Dots).

show_markers: Option<bool>

Show data point markers on line charts (None = no markers).

stock_variant: Option<StockVariant>

Stock chart sub-variant (None = default HLC, 3 series).

VHLC and VOHLC generate a composite <c:plotArea> with both <c:barChart> (volume) and <c:stockChart> (price) elements.

Dutmal

Dutmal (덧말): annotation text displayed above or below main text. Maps to HWPX <hp:dutmal>.

Fields

main_text: String

Main text that receives the annotation.

sub_text: String

Annotation text displayed above/below.

position: DutmalPosition

Position of the annotation relative to main text.

sz_ratio: u32

Size ratio of annotation text relative to main (0 = auto).

align: DutmalAlign

Alignment of the annotation text.

metadata: DutmalMetadata

Optional metadata that mirrors HWPX <hp:dutmal> attributes HwpForge doesn’t promote to typed fields yet — currently carries option verbatim so HWP5↔HWPX round-trips preserve it. #[non_exhaustive] so future fields are additive.

Compose

Compose (글자겹침): overlaid/combined characters. Maps to HWPX <hp:compose>.

Fields

compose_text: String

The combined text (e.g. “12” for two overlaid digits).

circle_type: String

Circle/frame type for the composition.

char_sz: i32

Character size adjustment (-3 = slightly smaller).

compose_type: String

Composition layout type.

char_pr_ids: Vec<u32>

10 <hp:charPr prIDRef="N"/> references (HWPX charPrCnt is fixed at 10). u32::MAX is the “no override” sentinel — 한컴 emits it for unused slots. A Vec shorter or longer than 10 is normalized by the HWPX encoder (pad / truncate).

Arc

An arc (partial ellipse) drawing object. Maps to HWPX <hp:ellipse> with hasArcPr="1".

Fields

arc_type: ArcType

Arc type (normal open arc, pie/sector, chord).

center: ShapePoint

Center point of the parent ellipse.

axis1: ShapePoint

Axis 1 endpoint (semi-major axis).

axis2: ShapePoint

Axis 2 endpoint (semi-minor axis).

start1: ShapePoint

Arc start point 1.

end1: ShapePoint

Arc end point 1.

start2: ShapePoint

Arc start point 2.

end2: ShapePoint

Arc end point 2.

width: HwpUnit

Bounding box width (HWPUNIT).

height: HwpUnit

Bounding box height (HWPUNIT).

horz_offset: i32

Horizontal offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

vert_offset: i32

Vertical offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

caption: Option<Caption>

Optional caption attached to this arc.

style: Option<ShapeStyle>

Optional visual style overrides.

Curve

A curve drawing object (bezier/polyline). Maps to HWPX <hp:curve>.

Fields

points: Vec<ShapePoint>

Ordered control points for the curve path.

segment_types: Vec<CurveSegmentType>

Segment types (one per segment between points).

width: HwpUnit

Bounding box width (HWPUNIT).

height: HwpUnit

Bounding box height (HWPUNIT).

horz_offset: i32

Horizontal offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

vert_offset: i32

Vertical offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

caption: Option<Caption>

Optional caption attached to this curve.

style: Option<ShapeStyle>

Optional visual style overrides.

ConnectLine

A connect line drawing object (line with control points for routing). Maps to HWPX <hp:connectLine>.

Fields

start: ShapePoint

Start point of the connect line.

end: ShapePoint

End point of the connect line.

control_points: Vec<ShapePoint>

Intermediate control points for routing.

connect_type: String

Connect line type (e.g. “STRAIGHT”, “BENT”, “CURVED”).

width: HwpUnit

Bounding box width (HWPUNIT).

height: HwpUnit

Bounding box height (HWPUNIT).

horz_offset: i32

Horizontal offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

vert_offset: i32

Vertical offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

caption: Option<Caption>

Optional caption attached to this connect line.

style: Option<ShapeStyle>

Optional visual style overrides.

Group

A group of drawing objects (묶음 객체 / 개체 묶기). Maps to HWPX <hp:container> and HWP5 gso → ShapeComponent with the "$con" type tag wrapping child ShapeComponents.

children reuses the shape Control variants (Rect/Ellipse/ Line/Polygon/Curve/ConnectLine/Image/EmbeddedChart and, recursively, Group). Non-shape variants are rejected by validate rather than the type system, matching how every other recursive container (TextBox/Footnote/Memo.content) carries a loose Vec<Paragraph> / Vec<Run>.

Fields

children: Vec<Control>

Child drawing objects, in z-order. May nest further Groups.

width: HwpUnit

Bounding box width (HWPUNIT).

height: HwpUnit

Bounding box height (HWPUNIT).

horz_offset: i32

Horizontal offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

vert_offset: i32

Vertical offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

inst_id: Option<ObjectId>

HWP5 ParaHeader / GSO trailer instance ID, mirrored to the HWPX <hp:container instid> attribute. None = not carried.

TextArt

A TextArt (글맵시) decorative warped-text object. Maps to HWPX <hp:textart> with <hp:textartPr>.

TextArt warps a short string into a shape (wave, arch, circle, …) and renders it as a drawing object. The HWP5 wire stores shape as an integer enum (0..=54); the HWPX wire stores it as a string name (e.g. "WAVE2"). This carries the HWPX string form directly.

Fields

text: String

The displayed text content.

shape: String

HWPX textShape name (e.g. "WAVE2"). One of 55 known shapes.

font_name: String

Font family name (e.g. "함초롬바탕").

font_style: String

Font style label (e.g. "보통").

align: String

HWPX align value within the textart (e.g. "LEFT").

line_spacing: u32

Line spacing (percent, HWPX lineSpacing).

char_spacing: u32

Character spacing (percent, HWPX charSpacing).

width: HwpUnit

Bounding box width (HWPUNIT).

height: HwpUnit

Bounding box height (HWPUNIT).

horz_offset: i32

Horizontal offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

vert_offset: i32

Vertical offset from anchor point (HWPUNIT, 0 = inline/treat-as-char).

fill_color: Option<Color>

Fill color (the <hc:winBrush faceColor> of the textart glyphs). None = no explicit fill carried.

inst_id: Option<ObjectId>

HWP5 GSO trailer instance ID, mirrored to HWPX <hp:textart instid>. None = not carried.

Bookmark

A bookmark marking a named location in the document. Maps to HWPX <hp:ctrl><hp:bookmark> (point) or fieldBegin/fieldEnd type="BOOKMARK" (span).

Fields

name: String

Bookmark name (unique within the document).

bookmark_type: BookmarkType

Type: point bookmark or span start/end.

CrossRef

A cross-reference (상호참조) to a bookmark, footnote, endnote, outline heading, table/figure/equation caption.

Maps to HWPX fieldBegin type="CROSSREF" with parameters.

Wave 12m Phase 2: target_name: String 가 target: RefTarget 로 변경 (breaking). 책갈피 이름과 한컴 자동 ID (#) 가 타입으로 구분되어 caller 가 의미를 정확히 알 수 있음.

Wave 12m Phase 2 Step 4 (breaking): display_text: String 추가. HWPX wire 는 <hp:fieldBegin> 과 <hp:fieldEnd> 사이의 visible run 으로 display text 를 embedding 한다. HWP5 %xrf wire 는 display text 를 직접 carry 하지 않고 ParaText 본문에 풀어 두지만, projection 이 FieldBegin..FieldEnd span 을 읽어 이 필드에 채워 넣는다. 빈 문자열은 “display text 없음” 의미 (Hyperlink::text 와 동일).

Fields

target: RefTarget

Reference target — Bookmark name (Name(String)) or system id (SystemId(u64)) or unparseable raw (Raw(String)).

ref_type: RefType

What kind of target is being referenced.

content_type: RefContentType

What content to display at the reference site.

as_hyperlink: bool

Whether to render the reference as a clickable hyperlink.

display_text: String

Visible body text shown between fieldBegin and fieldEnd in the encoded wire. HWP5 sources this from the FieldBegin span; native builders may leave this empty.

Field

A press-field (누름틀) — an interactive form field. Maps to HWPX fieldBegin type="CLICK_HERE" with parameters and metaTag.

Fields

field_type: FieldType

Field type (ClickHere, Date, Time, etc.).

hint_text: Option<String>

Hint/visible text shown in the field placeholder.

help_text: Option<String>

Help text shown when hovering or clicking the field.

name: Option<String>

Form-mode identifier used to reference the field programmatically. Maps to HWPX fieldBegin name="..." attribute. None represents the empty string convention (한컴 wire stores it as a 0-length BSTR).

display_text: String

Cached resolved value rendered between <hp:fieldBegin> and <hp:fieldEnd> (e.g. the author name, the locale-formatted date). HWP5 sources this from the FieldBegin..FieldEnd span; 한컴 native HWPX carries the same cached render and recomputes it on save. Empty string = “no cached value” (same convention as Self::CrossRef::display_text / Self::Hyperlink::text). For ClickHere this is the user-filled value; an unfilled field carries either the same string as Self::Field::hint_text (decoded from a native body) or the empty string (constructed). When empty, the HWPX encoder emits hint_text as the body.

An empty body triggers 한컴’s “낮은 보안 수준 복구” warning on open for SUMMERY fields (#120/#136) — carrying the verbatim source value avoids it.

Memo

A memo (메모) annotation attached to text.

Maps to HWPX fieldBegin type="MEMO" + anchor body runs + fieldEnd flat inside one <hp:run>. The memo’s body lives inside fieldBegin’s <hp:subList>; the anchor runs sit between fieldBegin and fieldEnd so 한컴 can pair the markers and render the [메모 시작]…[메모 끝] UI labels instead of generic [메모 시작]…[필드 끝].

Wave 12e: author/date fields removed (no wire path populated them).

Wave 12f: anchor_runs added. Without it, the encoder produced an empty <hp:t/> between fieldBegin and fieldEnd, which 한컴 reads as an unpaired field — visible bug.

Fields

content: Vec<Paragraph>

Paragraphs forming the memo body content (rendered in <hp:subList>).

anchor_runs: Vec<Run>

Runs that form the visible anchor text — the body span the memo is attached to. Encoders interleave these between fieldBegin and fieldEnd inside one <hp:run>. Should normally hold only RunContent::Text; other variants are downgraded by the encoder with a warning (memos cannot anchor on tables/images/nested controls in HWPX).

metadata: MemoMetadata

HWPX <hp:parameters> for the memo. Carrying these as a dedicated MemoMetadata (instead of half-empty hard-coded values) keeps the metadata format-agnostic — encoders for HWPX (and any future format with similar metadata) consume the same struct.

IndexMark

An index mark for building a document index (찾아보기). Maps to HWPX <hp:ctrl><hp:indexmark>.

Fields

primary: String

Primary index key (required).

secondary: Option<String>

Secondary (sub-entry) index key.

UnknownSummary

An unknown SUMMERY (%smr) $token carried verbatim for forward compatibility (Wave 12n).

Wave 12n only models the five HwpForge-observed tokens ($author, $lastsaveby, $createtime, $modifiedtime, $title) as typed FieldType variants. Any other %smr Command (e.g. additional 한컴 metadata tokens not yet measured) is preserved here instead of being silently coerced to ClickHere.

Fields

token: String

Raw Command string after envelope (e.g. "$company").

display_text: String

Cached resolved value rendered between fieldBegin/fieldEnd. Same semantics as Self::Field::display_text; empty = none.

DateCodeField

A %dte date/time format-pattern field (Wave 12n).

HWP5 family %dte (ctrl_id 0x2564_7465) used by 한컴 입력 → 날짜/시간/파일 이름 → 날짜/시간 코드 menu. Unlike SUMMERY (which carries semantic tokens like $createtime), %dte carries a raw format pattern string (e.g. "\:1년 2월 3일 (6);0;" for date, "T\:;0;" for time-only). The HWP5 wire format pattern is smithy-internal; the format-agnostic core retains only the derived is_time_mode helper (was based on the T prefix at projection time).

Fields

is_time_mode: bool

Helper view: true for a time-only (T-prefixed) format, false for a date format. Derived at HWP5 projection time.

display_text: String

Cached resolved value rendered between fieldBegin/fieldEnd (the locale-formatted date/time string). Same semantics as Self::Field::display_text; empty = none.

PathField

A %pat path / file-name field (Wave 12n).

HWP5 family %pat (ctrl_id 0x2570_6174) emitted by 한컴 상용구 → 파일 이름 / 파일 이름과 경로. Uses $P (path) and $F (file name) format codes.

Fields

command: PathFieldCommand

Typed variant of the observed Command pattern.

display_text: String

Cached resolved value rendered between fieldBegin/fieldEnd (the absolute path/file name 한컴 last evaluated). Same semantics as Self::Field::display_text; empty = none. 한컴 recomputes $P/$F against the file’s on-disk path on save, but an empty body on open triggers the recovery warning (#120).

InlinePageNumber

An atno inline page number control (Wave 12n).

HWP5 family atno (ctrl_id 0x6174_6E6F) used by 한컴 상용구 → 현재 쪽 번호 / 전체 쪽수 / 현재 쪽/전체 쪽수. Distinct from pgnp (section-level page numbering control already modeled as Section.page_number). Inline atno renders to HWPX <hp:autoNum> inside a <hp:run>.

The 16-byte wire envelope carries a single 4-byte flag that distinguishes current-page from total-pages; the HWP5 projection maps it to InlinePageKind.

Fields

kind: InlinePageKind

Typed variant of the observed flag byte.

Unknown

An unrecognized control element preserved for round-trip fidelity.

tag holds the element’s tag name or type identifier. data holds optional serialized content for lossless preservation.

Fields

tag: String

Tag name or type identifier of the unrecognized element.

data: Option<String>

Optional serialized data for round-trip preservation.

Implementations

impl Control

pub fn is_text_box(&self) -> bool

Returns true if this is a Control::TextBox.

pub fn is_hyperlink(&self) -> bool

Returns true if this is a Control::Hyperlink.

pub fn is_footnote(&self) -> bool

Returns true if this is a Control::Footnote.

pub fn is_endnote(&self) -> bool

Returns true if this is a Control::Endnote.

pub fn is_line(&self) -> bool

Returns true if this is a Control::Line.

pub fn is_ellipse(&self) -> bool

Returns true if this is a Control::Ellipse.

pub fn is_rect(&self) -> bool

Returns true if this is a Control::Rect.

pub fn is_polygon(&self) -> bool

Returns true if this is a Control::Polygon.

pub fn is_equation(&self) -> bool

Returns true if this is a Control::Equation.

pub fn is_chart(&self) -> bool

Returns true if this is a Control::Chart.

pub fn is_embedded_chart(&self) -> bool

Returns true if this is a Control::EmbeddedChart.

pub fn is_unknown(&self) -> bool

Returns true if this is a Control::Unknown.

pub fn is_dutmal(&self) -> bool

Returns true if this is a Control::Dutmal.

pub fn is_compose(&self) -> bool

Returns true if this is a Control::Compose.

pub fn is_arc(&self) -> bool

Returns true if this is a Control::Arc.

pub fn is_curve(&self) -> bool

Returns true if this is a Control::Curve.

pub fn is_connect_line(&self) -> bool

Returns true if this is a Control::ConnectLine.

pub fn is_group(&self) -> bool

Returns true if this is a Control::Group.

pub fn is_bookmark(&self) -> bool

Returns true if this is a Control::Bookmark.

pub fn is_cross_ref(&self) -> bool

Returns true if this is a Control::CrossRef.

pub fn is_field(&self) -> bool

Returns true if this is a Control::Field.

pub fn is_memo(&self) -> bool

Returns true if this is a Control::Memo.

pub fn is_index_mark(&self) -> bool

Returns true if this is a Control::IndexMark.

pub fn bookmark(name: &str) -> Self

Creates a point bookmark at a named location.

Examples

use hwpforge_core::control::Control;

let bm = Control::bookmark("section1");
assert!(bm.is_bookmark());

pub fn field(hint: &str) -> Self

Creates a press-field (누름틀) with the given hint text.

Examples

use hwpforge_core::control::Control;

let field = Control::field("이름을 입력하세요");
assert!(field.is_field());

pub fn index_mark(primary: &str) -> Self

Creates an index mark with a primary key.

Examples

use hwpforge_core::control::Control;

let mark = Control::index_mark("한글");
assert!(mark.is_index_mark());

pub fn memo(content: Vec<Paragraph>) -> Self

Creates a memo annotation with the given paragraph body.

Examples

use hwpforge_core::control::Control;
use hwpforge_core::paragraph::Paragraph;
use hwpforge_foundation::ParaShapeIndex;

let para = Paragraph::new(ParaShapeIndex::new(0));
let memo = Control::memo(vec![para]);
assert!(memo.is_memo());

pub fn memo_with_anchor(content: Vec<Paragraph>, anchor_runs: Vec<Run>) -> Self

Creates a memo annotation with both body content and anchor runs.

anchor_runs are the visible body span the memo is attached to (the text between HWPX <hp:fieldBegin type="MEMO"> and <hp:fieldEnd>); content is the memo body inside <hp:subList>.

Examples

use hwpforge_core::control::Control;
use hwpforge_core::paragraph::Paragraph;
use hwpforge_core::run::Run;
use hwpforge_foundation::{CharShapeIndex, ParaShapeIndex};

let body = vec![Paragraph::new(ParaShapeIndex::new(0))];
let anchor = vec![Run::text("hello", CharShapeIndex::new(0))];
let memo = Control::memo_with_anchor(body, anchor);
assert!(memo.is_memo());

pub fn cross_ref( target: RefTarget, ref_type: RefType, content_type: RefContentType, ) -> Self

Creates a cross-reference to a bookmark target (convenience helper).

Wave 12m Phase 2: 인자 타입이 &str 에서 RefTarget 로 변경 (breaking). 책갈피 이름이라면 RefTarget::Name(...), 한컴 시스템 ID 라면 RefTarget::SystemId(...) 를 명시.

Examples

use hwpforge_core::control::{Control, RefTarget};
use hwpforge_foundation::{RefType, RefContentType};

let xref = Control::cross_ref(
    RefTarget::Name("section1".to_string()),
    RefType::Bookmark,
    RefContentType::Page,
);
assert!(xref.is_cross_ref());

pub fn chart(chart_type: ChartType, data: ChartData) -> Self

Creates a chart control with default dimensions and settings.

Defaults: width ≈ 114mm, height ≈ 66mm, no title, right legend, clustered grouping.

Examples

use hwpforge_core::control::Control;
use hwpforge_core::chart::{ChartType, ChartData};

let data = ChartData::category(&["A", "B"], &[("S1", &[10.0, 20.0])]);
let ctrl = Control::chart(ChartType::Column, data);
assert!(ctrl.is_chart());

pub fn equation(script: &str) -> Self

Creates an equation control with default dimensions for the given HancomEQN script.

Defaults: width ≈ 31mm (8779 HWPUNIT), height ≈ 9.2mm (2600 HWPUNIT), baseline 71%, black text, HancomEQN font.

Examples

use hwpforge_core::control::Control;

let ctrl = Control::equation("{a+b} over {c+d}");
assert!(ctrl.is_equation());

pub fn text_box( paragraphs: Vec<Paragraph>, width: HwpUnit, height: HwpUnit, ) -> Self

Creates a text box control with the given paragraphs and dimensions.

Defaults: inline positioning (horz_offset=0, vert_offset=0), no caption, no style override.

Examples

use hwpforge_core::control::Control;
use hwpforge_core::paragraph::Paragraph;
use hwpforge_foundation::{HwpUnit, ParaShapeIndex};

let para = Paragraph::new(ParaShapeIndex::new(0));
let width = HwpUnit::from_mm(80.0).unwrap();
let height = HwpUnit::from_mm(40.0).unwrap();
let ctrl = Control::text_box(vec![para], width, height);
assert!(ctrl.is_text_box());

pub fn footnote(paragraphs: Vec<Paragraph>) -> Self

Creates a footnote control with the given paragraph content.

Defaults: no inst_id.

Examples

use hwpforge_core::control::Control;
use hwpforge_core::run::Run;
use hwpforge_core::paragraph::Paragraph;
use hwpforge_foundation::{CharShapeIndex, ParaShapeIndex};

let para = Paragraph::with_runs(
    vec![Run::text("Note text", CharShapeIndex::new(0))],
    ParaShapeIndex::new(0),
);
let ctrl = Control::footnote(vec![para]);
assert!(ctrl.is_footnote());

pub fn endnote(paragraphs: Vec<Paragraph>) -> Self

Creates an endnote control with the given paragraph content.

Defaults: no inst_id.

Examples

use hwpforge_core::control::Control;
use hwpforge_core::run::Run;
use hwpforge_core::paragraph::Paragraph;
use hwpforge_foundation::{CharShapeIndex, ParaShapeIndex};

let para = Paragraph::with_runs(
    vec![Run::text("End note", CharShapeIndex::new(0))],
    ParaShapeIndex::new(0),
);
let ctrl = Control::endnote(vec![para]);
assert!(ctrl.is_endnote());

pub fn footnote_with_id(inst_id: u64, paragraphs: Vec<Paragraph>) -> Self

Creates a footnote with an explicit instance ID for cross-referencing.

Use this when you need stable inst_id references (e.g. matching decoder output). For simple footnotes without cross-references, prefer Control::footnote.

Examples

use hwpforge_core::control::Control;
use hwpforge_core::paragraph::Paragraph;
use hwpforge_foundation::ParaShapeIndex;

let ctrl = Control::footnote_with_id(1, vec![Paragraph::new(ParaShapeIndex::new(0))]);
assert!(ctrl.is_footnote());

pub fn endnote_with_id(inst_id: u64, paragraphs: Vec<Paragraph>) -> Self

Creates an endnote with an explicit instance ID for cross-referencing.

Use this when you need stable inst_id references (e.g. matching decoder output). For simple endnotes without cross-references, prefer Control::endnote.

Examples

use hwpforge_core::control::Control;
use hwpforge_core::paragraph::Paragraph;
use hwpforge_foundation::ParaShapeIndex;

let ctrl = Control::endnote_with_id(2, vec![Paragraph::new(ParaShapeIndex::new(0))]);
assert!(ctrl.is_endnote());

pub fn ellipse(width: HwpUnit, height: HwpUnit) -> Self

Creates an ellipse control with the given bounding box dimensions.

Geometry is auto-derived: center=(w/2, h/2), axis1=(w, h/2), axis2=(w/2, h). Defaults: inline positioning (horz_offset=0, vert_offset=0), no paragraphs, no caption, no style.

Examples

use hwpforge_core::control::Control;
use hwpforge_foundation::HwpUnit;

let width = HwpUnit::from_mm(40.0).unwrap();
let height = HwpUnit::from_mm(30.0).unwrap();
let ctrl = Control::ellipse(width, height);
assert!(ctrl.is_ellipse());

pub fn ellipse_with_text( width: HwpUnit, height: HwpUnit, paragraphs: Vec<Paragraph>, ) -> Self

Creates an ellipse control with paragraph content inside.

Same as Control::ellipse but accepts paragraphs for text drawn inside the ellipse. Geometry is auto-derived: center=(w/2, h/2), axis1=(w, h/2), axis2=(w/2, h). Defaults: inline positioning (horz_offset=0, vert_offset=0), no caption, no style.

Examples

use hwpforge_core::control::Control;
use hwpforge_core::paragraph::Paragraph;
use hwpforge_foundation::{HwpUnit, ParaShapeIndex};

let width = HwpUnit::from_mm(40.0).unwrap();
let height = HwpUnit::from_mm(30.0).unwrap();
let para = Paragraph::new(ParaShapeIndex::new(0));
let ctrl = Control::ellipse_with_text(width, height, vec![para]);
assert!(ctrl.is_ellipse());

pub fn rect(width: HwpUnit, height: HwpUnit) -> CoreResult<Self>

Creates a pure rectangle control with the given bounding box dimensions.

Pure rectangle means no embedded text content; for a textbox-style rect with inline paragraphs, use Control::text_box. Defaults: inline positioning (horz_offset=0, vert_offset=0), no caption, no style.

Errors

Returns CoreError::InvalidStructure if either dimension is zero.

Examples

use hwpforge_core::control::Control;
use hwpforge_foundation::HwpUnit;

let width = HwpUnit::from_mm(40.0).unwrap();
let height = HwpUnit::from_mm(20.0).unwrap();
let ctrl = Control::rect(width, height).unwrap();
assert!(ctrl.is_rect());

pub fn polygon(vertices: Vec<ShapePoint>) -> CoreResult<Self>

Creates a polygon control from the given vertices.

The bounding box is auto-derived from the min/max of vertex coordinates. Defaults: no paragraphs, no caption, no style.

Returns an error if fewer than 3 vertices are provided.

Errors

Returns CoreError::InvalidStructure if vertices.len() < 3.

Examples

use hwpforge_core::control::{Control, ShapePoint};

let vertices = vec![
    ShapePoint::new(0, 1000),
    ShapePoint::new(500, 0),
    ShapePoint::new(1000, 1000),
];
let ctrl = Control::polygon(vertices).unwrap();
assert!(ctrl.is_polygon());

pub fn line(start: ShapePoint, end: ShapePoint) -> CoreResult<Self>

Creates a line control between two endpoints.

The bounding box width and height are derived from the absolute difference of the endpoint coordinates: width = |end.x - start.x|, height = |end.y - start.y|. Each axis is clamped to a minimum of 100 HwpUnit (~1pt) because 한글 cannot render lines with a zero-dimension bounding box. Defaults: no caption, no style.

Returns an error if start and end are the same point (degenerate line).

Errors

Returns CoreError::InvalidStructure if start equals end.

Examples

use hwpforge_core::control::{Control, ShapePoint};

let ctrl = Control::line(ShapePoint::new(0, 0), ShapePoint::new(5000, 0)).unwrap();
assert!(ctrl.is_line());

pub fn horizontal_line(width: HwpUnit) -> Self

Creates a horizontal line of the given width.

Shortcut for line(ShapePoint::new(0, 0), ShapePoint::new(width.as_i32(), 0)). The bounding box height is clamped to 100 HwpUnit (~1pt minimum) because 한글 cannot render lines with a zero-dimension bounding box. Defaults: no caption, no style.

Examples

use hwpforge_core::control::Control;
use hwpforge_foundation::HwpUnit;

let width = HwpUnit::from_mm(100.0).unwrap();
let ctrl = Control::horizontal_line(width);
assert!(ctrl.is_line());

pub fn dutmal(main_text: impl Into<String>, sub_text: impl Into<String>) -> Self

Creates a dutmal (annotation text) control with default positioning.

Defaults: position = Top, sz_ratio = 0 (auto), align = Center.

Examples

use hwpforge_core::control::Control;

let ctrl = Control::dutmal("본문", "주석");
assert!(ctrl.is_dutmal());

pub fn compose(text: impl Into<String>) -> Self

Creates a compose (글자겹침) control with default settings.

Defaults: circle_type = "SHAPE_REVERSAL_TIRANGLE" (spec typo preserved), char_sz = -3, compose_type = "SPREAD".

Examples

use hwpforge_core::control::Control;

let ctrl = Control::compose("12");
assert!(ctrl.is_compose());

pub fn arc(arc_type: ArcType, width: HwpUnit, height: HwpUnit) -> Self

Creates an arc control with the given bounding box dimensions.

Geometry is auto-derived from the bounding box. Defaults: inline positioning, no caption, no style.

Examples

use hwpforge_core::control::Control;
use hwpforge_foundation::{ArcType, HwpUnit};

let width = HwpUnit::from_mm(40.0).unwrap();
let height = HwpUnit::from_mm(30.0).unwrap();
let ctrl = Control::arc(ArcType::Pie, width, height);
assert!(ctrl.is_arc());

pub fn curve(points: Vec<ShapePoint>) -> CoreResult<Self>

Creates a curve control from the given control points.

All segments default to CurveSegmentType::Curve. The bounding box is auto-derived from min/max of point coordinates.

Returns an error if fewer than 2 points are provided.

Errors

Returns CoreError::InvalidStructure if points.len() < 2.

Examples

use hwpforge_core::control::{Control, ShapePoint};

let pts = vec![
    ShapePoint::new(0, 0),
    ShapePoint::new(2500, 5000),
    ShapePoint::new(5000, 0),
];
let ctrl = Control::curve(pts).unwrap();
assert!(ctrl.is_curve());

pub fn connect_line(start: ShapePoint, end: ShapePoint) -> CoreResult<Self>

Creates a connect line between two endpoints.

Defaults: no control points, type “STRAIGHT”, no caption, no style.

Returns an error if start equals end.

Errors

Returns CoreError::InvalidStructure if start equals end.

Examples

use hwpforge_core::control::{Control, ShapePoint};

let ctrl = Control::connect_line(
    ShapePoint::new(0, 0),
    ShapePoint::new(5000, 5000),
).unwrap();
assert!(ctrl.is_connect_line());

pub fn hyperlink(text: &str, url: &str) -> Self

Creates a hyperlink control with the given display text and URL.

Examples

use hwpforge_core::control::Control;

let ctrl = Control::hyperlink("Visit Rust", "https://rust-lang.org");
assert!(ctrl.is_hyperlink());

Trait Implementations

impl Clone for Control

fn clone(&self) -> Control

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Control

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Control

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Control

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl JsonSchema for Control

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl PartialEq for Control

fn eq(&self, other: &Control) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Control

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Control