### Basic Document Creation with Text

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/blankfilemaker.md

Demonstrates creating a blank HWP file, accessing the first section and paragraph, adding text, and saving the document. This is a fundamental example for starting document creation.

```java
// 빈 문서 생성
HWPFile hwpFile = BlankFileMaker.make();

// 기본 구역 가져오기
Section section = hwpFile.getBodyText().getSectionList().get(0);

// 기본 문단에 텍스트 추가
Paragraph firstPara = section.getParagraph(0);
firstPara.createText();
firstPara.getText().addString("안녕하세요!");

// 새 문단 추가
Paragraph newPara = section.addNewParagraph();
newPara.createText();
newPara.getText().addString("이것은 새로운 문단입니다.");

// 저장
HWPWriter.toFile(hwpFile, "new_document.hwp");
```

--------------------------------

### Create Line Control

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

Example of creating a line control using FactoryForControl. The created control is then cast to ControlLine for further property settings.

```java
// 선 그리기
Control lineControl = FactoryForControl.createControl(ControlType.Line);
ControlLine line = (ControlLine) lineControl;
// 선의 속성 설정
```

--------------------------------

### Create a New Empty HWP File

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/blankfilemaker.md

Use the make() method to create a new HWPFile object with default structure. This is the starting point for creating new HWP documents programmatically.

```java
public static HWPFile make()
```

```java
HWPFile newFile = BlankFileMaker.make();

// 파일에 내용 추가
Section section = newFile.getBodyText().getSectionList().get(0);
Paragraph para = section.addNewParagraph();
para.createText();
para.getText().addString("새로운 문서입니다.");

// 파일 저장
HWPWriter.toFile(newFile, "new_document.hwp");
```

--------------------------------

### Create New Section

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/section-paragraph.md

Instantiates a new Section object. This is the starting point for creating a new section within an HWP document.

```java
public Section()
```

--------------------------------

### Create Polygon Control

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

Example of creating a polygon control using FactoryForControl. The created control is then cast to ControlPolygon for further property settings.

```java
// 다각형 그리기
Control polygonControl = FactoryForControl.createControl(ControlType.Polygon);
ControlPolygon polygon = (ControlPolygon) polygonControl;
// 다각형의 속성 설정
```

--------------------------------

### ControlField - Hyperlinks

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

Explains that hyperlinks are implemented using field controls. It provides an example of how to find all `ControlField` instances within an HWP file.

```APIDOC
## ControlField - Hyperlinks

### Description
Hyperlinks are implemented through field controls. This documentation shows how to retrieve all field controls present in an HWP document.

### Method
Java API calls

### Endpoint
N/A (SDK method)

### Parameters
N/A

### Request Example
```java
HWPFile hwpFile = HWPReader.fromFile("document.hwp");

// 필드 컨트롤 찾기
ArrayList<ControlField> fields = FieldFinder.findAll(hwpFile);
for (ControlField field : fields) {
    String fieldName = field.getName();
    // 필드 처리
}
```

### Response
N/A (SDK method)
```

--------------------------------

### Create Arc Control

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

Example of creating an arc control using FactoryForControl. The created control is then cast to ControlArc for further property settings.

```java
// 호형 그리기
Control arcControl = FactoryForControl.createControl(ControlType.Arc);
ControlArc arc = (ControlArc) arcControl;
// 호형의 속성 설정
```

--------------------------------

### Create Curve Control

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

Example of creating a curve control using FactoryForControl. The created control is then cast to ControlCurve for further property settings.

```java
// 곡선 그리기
Control curveControl = FactoryForControl.createControl(ControlType.Curve);
ControlCurve curve = (ControlCurve) curveControl;
// 곡선의 속성 설정
```

--------------------------------

### Memory Efficient Extraction with StringBuilder

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/text-extraction.md

This example demonstrates memory-efficient extraction for large files, appending extracted text chunks to a StringBuilder. The final combined text is printed upon completion.

```java
HWPFile hwpFile = HWPReader.fromFile("large_file.hwp");
StringBuilder result = new StringBuilder();

TextExtractor.extract(hwpFile, TextExtractMethod.OnlyMainParagraph,
    new TextExtractorListener() {
        @Override
        public void onTextExtracted(String text) {
            result.append(text);
        }
        
        @Override
        public void onFinish() {
            System.out.println("전체 텍스트: " + result.toString());
        }
    });
```

--------------------------------

### Find All Tables in HWP Document

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/control-finder.md

This example shows how to retrieve all table controls from an HWP document. It uses a ControlFilter to identify controls of type ControlType.Table and then iterates through the found tables to access their rows.

```java
HWPFile hwpFile = HWPReader.fromFile("document.hwp");

ArrayList<Control> tables = ControlFinder.find(hwpFile, 
    new ControlFilter() {
        @Override
        public boolean isMatched(Control control, Paragraph paragraph, Section section) {
            return control.getType() == ControlType.Table;
        }
    });

for (Control control : tables) {
    ControlTable table = (ControlTable) control;
    Row row = table.getFirstRow();
    // 표 처리
}
```

--------------------------------

### Create Rectangle Control

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

Example of creating a rectangle control using FactoryForControl. The created control is then cast to ControlRectangle for further property settings.

```java
// 사각형 그리기
Control rectControl = FactoryForControl.createControl(ControlType.Rectangle);
ControlRectangle rect = (ControlRectangle) rectControl;
// 사각형의 속성 설정
```

--------------------------------

### Basic Text Extraction Example

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/text-extraction.md

Use this snippet to extract only the main paragraph text from an HWP document. Ensure HWPFile is properly loaded.

```java
HWPFile hwpFile = HWPReader.fromFile("document.hwp");
String text = TextExtractor.extract(hwpFile, TextExtractMethod.OnlyMainParagraph);
System.out.println(text);
```

--------------------------------

### Create Ellipse Control

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

Example of creating an ellipse control using FactoryForControl. The created control is then cast to ControlEllipse for further property settings.

```java
// 원형 그리기
Control ellipseControl = FactoryForControl.createControl(ControlType.Ellipse);
ControlEllipse ellipse = (ControlEllipse) ellipseControl;
// 원형의 속성 설정
```

--------------------------------

### Find Form Controls in HWP Document

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/control-finder.md

This example demonstrates how to find various form-related controls, such as buttons, checkboxes, radio buttons, and text fields, within a form-type HWP document. The filter checks for multiple ControlType values.

```java
HWPFile hwpFile = HWPReader.fromFile("form.hwp");

ArrayList<Control> formControls = ControlFinder.find(hwpFile, 
    new ControlFilter() {
        @Override
        public boolean isMatched(Control control, Paragraph paragraph, Section section) {
            ControlType type = control.getType();
            return type == ControlType.Button || 
                   type == ControlType.CheckBox ||
                   type == ControlType.RadioButton ||
                   type == ControlType.TextField;
        }
    });

System.out.println("찾은 양식 컨트롤: " + formControls.size());
```

--------------------------------

### Get First Cell of a Row

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/table-control.md

Retrieves the first cell within a given Row. This is typically used to start processing cells in a row.

```java
public Cell getFirstCell()

**반환형**: `Cell` - 행의 첫 번째 셀

**설명**: 행의 첫 번째 셀을 반환합니다.

**사용 예**:
```java
Row row = table.getFirstRow();
Cell cell = row.getFirstCell();
```
```

--------------------------------

### 파일을 찾을 수 없는 오류 처리

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/errors.md

지정된 경로에 HWP 파일이 존재하지 않을 때 발생하는 `FileNotFoundException`을 처리합니다. 파일 경로를 확인하거나 파일 존재 여부를 미리 검사하는 것이 좋습니다.

```java
try {
    HWPFile hwpFile = HWPReader.fromFile("nonexistent.hwp");
} catch (FileNotFoundException e) {
    System.out.println("파일을 찾을 수 없습니다: " + e.getMessage());
} catch (Exception e) {
    System.out.println("파일 읽기 실패: " + e.getMessage());
}
```

--------------------------------

### Get First Row of a Table

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/table-control.md

Retrieves the first row of a ControlTable. Useful for starting iteration or accessing the initial row's data.

```java
public Row getFirstRow()

**반환형**: `Row` - 표의 첫 번째 행

**설명**: 표의 첫 번째 행을 반환합니다.

**사용 예**:
```java
ControlTable table = (ControlTable) control;
Row firstRow = table.getFirstRow();
Cell firstCell = firstRow.getFirstCell();
```
```

--------------------------------

### Create New HWP File and Add Content

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/SUMMARY.md

Create a new blank HWP file, add a section, a paragraph, and then insert text content. Finally, save the new file.

```java
HWPFile newFile = BlankFileMaker.make();
Section section = newFile.getBodyText().getSectionList().get(0);
Paragraph para = section.addNewParagraph();
para.createText();
para.getText().addString("내용");
HWPWriter.toFile(newFile, "output.hwp");
```

--------------------------------

### Get Control Type

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/control-finder.md

Returns the type of the control. This method is part of the base Control interface.

```java
public ControlType getType()
```

--------------------------------

### BlankFileMaker.make()

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/blankfilemaker.md

Creates a new, empty HWP file with a default structure. This is the primary method for initializing a blank HWP document.

```APIDOC
## BlankFileMaker.make()

### Description
Creates a new, empty HWP file with a default structure. This is the primary method for initializing a blank HWP document.

### Method
```java
public static HWPFile make()
```

### Returns
`HWPFile` - A newly created blank HWP file object.

### Usage Example
```java
// Create a new blank HWP file
HWPFile newFile = BlankFileMaker.make();

// Add content to the file
Section section = newFile.getBodyText().getSectionList().get(0);
Paragraph para = section.addNewParagraph();
para.createText();
para.getText().addString("This is a new document.");

// Save the file
HWPWriter.toFile(newFile, "new_document.hwp");
```
```

--------------------------------

### Get Control Header

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/control-finder.md

Retrieves the header information for a control. This method is part of the base Control interface.

```java
public CtrlHeader getCtrlHeader()
```

--------------------------------

### 잘못된 파일 형식 오류 처리

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/errors.md

HWP 파일 형식이 아닌 다른 형식의 파일을 읽으려고 할 때 발생하는 예외를 처리합니다. HWP 파일만 읽도록 파일 형식을 확인하거나 올바른 파일을 지정해야 합니다.

```java
try {
    HWPFile hwpFile = HWPReader.fromFile("document.txt");
} catch (Exception e) {
    System.out.println("HWP 파일 형식이 아닙니다: " + e.getMessage());
}
```

--------------------------------

### Document Creation with Styled Text

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/blankfilemaker.md

Demonstrates creating a HWP document and applying character formatting to text. This involves creating text, then creating and configuring a character shape for styling.

```java
HWPFile hwpFile = BlankFileMaker.make();
Section section = hwpFile.getBodyText().getSectionList().get(0);

Paragraph para = section.getParagraph(0);
para.createText();

// 일반 텍스트
ParaText text = para.getText();
text.addString("일반 텍스트");

// 글자 모양 설정
para.createCharShape();
ParaCharShape charShape = para.getCharShape();

// 글자 모양의 속성 설정 (폰트 ID, 크기 등)
// charShape.setBold(true);
// charShape.setItalic(false);
// charShape.setFontId(fontId);

HWPWriter.toFile(hwpFile, "styled_document.hwp");
```

--------------------------------

### Get All Paragraphs as Array

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/section-paragraph.md

Returns all paragraphs within the section as an array. This provides a convenient way to process all paragraphs at once.

```java
public Paragraph[] getParagraphs()
```

```java
Section section = hwpFile.getBodyText().getSectionList().get(0);
Paragraph[] paragraphs = section.getParagraphs();
for (Paragraph para : paragraphs) {
    // 각 문단 처리
}
```

--------------------------------

### Get Paragraph Count in Section

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/section-paragraph.md

Retrieves the total number of paragraphs within a section. This is useful for iterating through all paragraphs.

```java
public int getParagraphCount()
```

```java
Section section = hwpFile.getBodyText().getSectionList().get(0);
int paraCount = section.getParagraphCount();
for (int i = 0; i < paraCount; i++) {
    Paragraph para = section.getParagraph(i);
}
```

--------------------------------

### 타입 정의

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/INDEX.md

hwplib에서 사용되는 모든 공개 타입과 인터페이스를 정의합니다. HWP 파일 구조, 컨트롤 계층, 열거형 등을 포함합니다.

```APIDOC
## Types and Interfaces

### Description
hwplib 라이브러리에서 사용되는 모든 공개 타입과 인터페이스를 정의합니다.

### Key Types
- **HWPFile Structure**: HWP 파일의 전체 구조
- **Document Structure Types**: `FileHeader`, `BodyText`, `Section`, `Paragraph` 등 문서 구조 관련 타입
- **Paragraph Component Types**: `ParaText`, `ParaCharShape`, `ParaHeader`, `ParaLineSeg` 등 문단 구성 요소
- **Control Hierarchy**: `Control`, `ControlTable`, `ControlField` 등 컨트롤 계층 구조
- **Table Structure**: `ControlTable`, `Row`, `Cell` 등 표 구조 관련 타입
- **Enumerations**: `ControlType`, `TextExtractMethod` 등 열거형
- **Interfaces**: `ControlFilter`, `TextExtractorListener` 등 주요 인터페이스
```

--------------------------------

### 암호화된 파일 접근 시 예외 처리

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/errors.md

암호화된 HWP 파일을 읽으려고 할 때 발생하는 예외를 처리합니다. 암호화된 파일은 지원되지 않으므로, 사용자에게 알리고 한글 프로그램에서 암호를 제거하도록 안내해야 합니다.

```java
try {
    HWPFile hwpFile = HWPReader.fromFile("protected.hwp");
} catch (Exception e) {
    if (e.getMessage().contains("password")) {
        System.out.println("암호화된 파일입니다. 지원되지 않습니다.");
    } else {
        System.out.println("파일 읽기 오류: " + e.getMessage());
    }
}
```

--------------------------------

### Get Click Here Field Text (Basic)

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/field-finder.md

Retrieves the text content of a specified 'Click Here' field. Returns null if the field is not found.

```java
public static String getClickHereText(HWPFile hwpFile, String fieldName)
```

```java
HWPFile hwpFile = HWPReader.fromFile("form.hwp");
String fieldText = FieldFinder.getClickHereText(hwpFile, "필드1");
System.out.println("필드1의 텍스트: " + fieldText);
```

--------------------------------

### Document Creation with a Table

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/blankfilemaker.md

Shows how to create a HWP document containing a table. This involves creating a table control, adding rows and cells, and populating them with data.

```java
HWPFile hwpFile = BlankFileMaker.make();
Section section = hwpFile.getBodyText().getSectionList().get(0);

// 제목 문단
Paragraph titlePara = section.getParagraph(0);
titlePara.createText();
titlePara.getText().addString("표 예제");

// 표 생성
Paragraph tablePara = section.addNewParagraph();
Control tableControl = FactoryForControl.createControl(ControlType.Table);
ControlTable table = (ControlTable) tableControl;

// 표 내용 작성
Row row = table.getFirstRow();
Cell cell = row.getFirstCell();

Paragraph cellPara = cell.getFirstParagraph();
if (cellPara == null) {
    cellPara = cell.addNewParagraph();
}
cellPara.createText();
cellPara.getText().addString("셀 데이터");

HWPWriter.toFile(hwpFile, "table_document.hwp");
```

--------------------------------

### 파일에서 그림 읽어오기 및 삽입

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

파일에서 그림을 읽어와 HWP 문서의 섹션에 추가하는 예제입니다. 표를 찾아 셀에 이미지를 삽입하는 방법을 보여줍니다.

```java
HWPFile hwpFile = HWPReader.fromFile("document.hwp");
Section section = hwpFile.getBodyText().getSectionList().get(0);
Paragraph para = section.addNewParagraph();
para.createText();
para.getText().addString("그림 예제");

// 표를 찾아서 셀에 이미지 추가
ArrayList<Control> tables = ControlFinder.find(hwpFile, 
    new ControlFilter() {
        @Override
        public boolean isMatched(Control control, Paragraph paragraph, Section section) {
            return control.getType() == ControlType.Table;
        }
    });

if (tables.size() > 0) {
    ControlTable table = (ControlTable) tables.get(0);
    Row row = table.getFirstRow();
    Cell cell = row.getFirstCell();
    Paragraph cellPara = cell.getFirstParagraph();
    
    // 이미지 삽입 (구현은 ControlPicture의 메서드 사용)
    ControlPicture picture = new ControlPicture();
    // 이미지 속성 설정
}
```

--------------------------------

### Read HWP File

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/SUMMARY.md

Use HWPReader.fromFile to load an HWP document. Ensure the file path is correct.

```java
HWPFile hwpFile = HWPReader.fromFile("document.hwp");
```

--------------------------------

### Create Container Control in HWP

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

Illustrates how to create a container control, which can hold multiple other controls, and access its first row.

```java
// 컨테이너 생성
Control containerControl = FactoryForControl.createControl(ControlType.Container);
ControlContainer container = (ControlContainer) containerControl;

// 컨테이너 내부의 컨트롤 접근
Row row = container.getFirstRow();
```

--------------------------------

### Create Form Controls in HWP

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

Demonstrates how to create different types of form controls like checkboxes, radio buttons, and text fields using the HWP library.

```java
// 체크 박스 생성
Control checkboxControl = FactoryForControl.createControl(ControlType.CheckBox);
ControlForm form = (ControlForm) checkboxControl;

// 라디오 버튼 생성
Control radioControl = FactoryForControl.createControl(ControlType.RadioButton);
form = (ControlForm) radioControl;

// 텍스트 필드 생성
Control textControl = FactoryForControl.createControl(ControlType.TextField);
form = (ControlForm) textControl;
```

--------------------------------

### Check HWP File Version

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/configuration.md

Use HWPReader to load a file and check its version from the FileHeader. Handle very old versions separately as some features may be lost.

```java
HWPFile hwpFile = HWPReader.fromFile("old_format.hwp");
FileHeader header = hwpFile.getFileHeader();

// 버전 확인
int version = header.getVersion();
if (version < 5000000) {
    // 매우 오래된 버전
}
```

--------------------------------

### Basic HWP File Reading and Manipulation Pattern

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/README.md

This pattern outlines the fundamental steps for reading an HWP file, navigating its content, modifying it, and saving the changes.

```text
1. 파일 읽기 (HWPReader.fromFile)
2. 문서 탐색 (getBodyText() → getSectionList() → getParagraph())
3. 내용 읽기/수정 (getText(), getControl() 등)
4. 파일 저장 (HWPWriter.toFile)
```

--------------------------------

### Get Specific Paragraph by Index

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/section-paragraph.md

Retrieves a paragraph from the section at a specified index. Ensure the index is within the valid range to avoid exceptions.

```java
public Paragraph getParagraph(int index)
```

```java
Section section = hwpFile.getBodyText().getSectionList().get(0);
Paragraph firstPara = section.getParagraph(0);
String text = firstPara.getText().toString();
```

--------------------------------

### Create TextArt Control in HWP

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

Shows how to create a TextArt (글맵시) control in an HWP document.

```java
// 글맵시 생성
Control textArtControl = FactoryForControl.createControl(ControlType.TextArt);
ControlTextArt textArt = (ControlTextArt) textArtControl;
```

--------------------------------

### Get Column Count of a Table

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/table-control.md

Returns the total number of columns in a ControlTable. Useful for understanding the table's dimensions or for loop bounds.

```java
public int getColCount()

**반환형**: `int` - 표의 열 개수

**설명**: 표의 총 열 개수를 반환합니다.

**사용 예**:
```java
ControlTable table = (ControlTable) control;
int colCount = table.getColCount();
System.out.println("열 개수: " + colCount);
```
```

--------------------------------

### Document Creation with Multiple Sections

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/blankfilemaker.md

Illustrates creating a HWP file with multiple sections. Note that adding new sections in HWP might involve specific mechanisms within the BodyText object.

```java
HWPFile hwpFile = BlankFileMaker.make();

// 첫 번째 구역
Section section1 = hwpFile.getBodyText().getSectionList().get(0);
Paragraph para1 = section1.getParagraph(0);
para1.createText();
para1.getText().addString("섹션 1");

// 추가 구역 생성 (HWP 문서는 BodyText에서 직접 구역 생성)
// 참고: 구역 추가는 특별한 메커니즘을 사용합니다

HWPWriter.toFile(hwpFile, "multi_section.hwp");
```

--------------------------------

### Get Row Count of a Table

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/table-control.md

Returns the total number of rows in a ControlTable. Useful for understanding the table's dimensions or for loop bounds.

```java
public int getRowCount()

**반환형**: `int` - 표의 행 개수

**설명**: 표의 총 행 개수를 반환합니다.

**사용 예**:
```java
ControlTable table = (ControlTable) control;
int rowCount = table.getRowCount();
System.out.println("행 개수: " + rowCount);
```
```

--------------------------------

### ControlPicture - Inserting Images

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

Demonstrates how to load an image file and add it to a document, specifically within a table cell. This involves finding a table, accessing its cells, and then creating and configuring a `ControlPicture` object.

```APIDOC
## ControlPicture - Inserting Images

### Description
This section shows how to load an image from a file and insert it into a HWP document. It includes finding a table, selecting a cell, and then adding a `ControlPicture` object with its properties configured.

### Method
Java API calls

### Endpoint
N/A (SDK method)

### Parameters
N/A

### Request Example
```java
// 파일에서 그림을 읽어 문서에 추가하기
HWPFile hwpFile = HWPReader.fromFile("document.hwp");
Section section = hwpFile.getBodyText().getSectionList().get(0);
Paragraph para = section.addNewParagraph();
para.createText();
para.getText().addString("그림 예제");

// 표를 찾아서 셀에 이미지 추가
ArrayList<Control> tables = ControlFinder.find(hwpFile, 
    new ControlFilter() {
        @Override
        public boolean isMatched(Control control, Paragraph paragraph, Section section) {
            return control.getType() == ControlType.Table;
        }
    });

if (tables.size() > 0) {
    ControlTable table = (ControlTable) tables.get(0);
    Row row = table.getFirstRow();
    Cell cell = row.getFirstCell();
    Paragraph cellPara = cell.getFirstParagraph();
    
    // 이미지 삽입 (구현은 ControlPicture의 메서드 사용)
    ControlPicture picture = new ControlPicture();
    // 이미지 속성 설정
}
```

### Response
N/A (SDK method)
```

--------------------------------

### BlankFileMaker

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/INDEX.md

새로운 빈 HWP 파일을 생성하는 기능을 제공합니다. 문단 추가 및 기본 요소 초기화가 포함됩니다.

```APIDOC
## BlankFileMaker

### Description
새로운 빈 HWP 파일을 생성하는 클래스입니다.

### Methods
- `make()`: 빈 HWP 파일을 생성합니다.

## ParagraphAdder

### Description
문단을 병합하거나 추가하는 기능을 제공합니다.

### Methods
- `merge(paragraph1: Paragraph, paragraph2: Paragraph)`: 두 문단을 병합합니다.
- `addParagraph(paragraph: Paragraph)`: 문단을 추가합니다.
```

--------------------------------

### Create Control using FactoryForControl

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

Shows how to use the FactoryForControl class to create various types of controls, such as Picture, Table, and Line. The controlType parameter specifies the type of control to be created.

```java
Control picture = FactoryForControl.createControl(ControlType.Picture);
Control table = FactoryForControl.createControl(ControlType.Table);
Control line = FactoryForControl.createControl(ControlType.Line);
```

--------------------------------

### Get All Click Here Field Texts

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/field-finder.md

Retrieves a map containing all 'Click Here' fields and their corresponding text content from the document. Returns an empty map if no fields are found.

```java
public static Map<String, String> getAllClickHereText(HWPFile hwpFile)
```

```java
HWPFile hwpFile = HWPReader.fromFile("form.hwp");
Map<String, String> allFields = FieldFinder.getAllClickHereText(hwpFile);
for (String fieldName : allFields.keySet()) {
    System.out.println(fieldName + " = " + allFields.get(fieldName));
}
```

--------------------------------

### Creating New HWP Documents or Modifying Existing Ones

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/README.md

This pattern covers the process of generating new HWP documents from scratch or by modifying existing ones. It includes adding sections, paragraphs, and content, followed by saving the document.

```text
1. BlankFileMaker.make() 또는 기존 파일 읽기
2. Section/Paragraph 추가
3. 텍스트 및 컨트롤 생성
4. HWPWriter.toFile() 저장
```

--------------------------------

### Get Click Here Field Text (with Method)

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/field-finder.md

Retrieves the text of a 'Click Here' field using a specified text extraction method. Useful when the field contains other controls.

```java
public static String getClickHereText(HWPFile hwpFile, String fieldName, TextExtractMethod method)
```

```java
HWPFile hwpFile = HWPReader.fromFile("form.hwp");
String fieldText = FieldFinder.getClickHereText(hwpFile, "필드1", 
    TextExtractMethod.InsertControlTextBetweenParagraphText);
System.out.println("필드1의 텍스트: " + fieldText);
```

--------------------------------

### General HWP Control Manipulation Workflow

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

Provides a step-by-step workflow for reading an HWP file, accessing its content, manipulating controls (like tables and pictures), and saving the modified file.

```java
// 1. 문서 읽기
HWPFile hwpFile = HWPReader.fromFile("template.hwp");

// 2. 구역과 문단 접근
Section section = hwpFile.getBodyText().getSectionList().get(0);
Paragraph para = section.getParagraph(0);

// 3. 컨트롤 조작
for (int i = 0; i < para.getControlCount(); i++) {
    Control control = para.getControl(i);
    
    if (control.getType() == ControlType.Table) {
        ControlTable table = (ControlTable) control;
        // 표 처리
    } else if (control.getType() == ControlType.Picture) {
        ControlPicture picture = (ControlPicture) control;
        // 그림 처리
    }
}

// 4. 수정된 문서 저장
HWPWriter.toFile(hwpFile, "output.hwp");
```

--------------------------------

### Load Small HWP Files (< 10MB)

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/configuration.md

For small files, direct full loading is sufficient. Use TextExtractor to extract text with control characters inserted between paragraph texts.

```java
// 직접 전체 로드
HWPFile hwpFile = HWPReader.fromFile("small_file.hwp");
String text = TextExtractor.extract(hwpFile, 
    TextExtractMethod.InsertControlTextBetweenParagraphText);
```

--------------------------------

### Handle Cell Merge Failure

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/errors.md

This snippet illustrates how to catch errors when attempting to merge table cells. Ensure that the specified cell range is valid and that the cells are not already merged. Provide the correct start and end cells for the merge operation.

```java
ControlTable table = (ControlTable) control;
Row startRow = table.getFirstRow();
Cell startCell = startRow.getFirstCell();

try {
    TableCellMerger.merge(table, startRow, startCell, startRow, startCell);
    System.out.println("셀 병합 완료");
} catch (Exception e) {
    System.out.println("셀 병합 실패: " + e.getMessage());
}
```

--------------------------------

### HWPReader.fromURL(String url)

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/hwpreader-writer.md

Reads an HWP file from a specified URL and converts it into an HWPFile object. This is useful for fetching HWP files from web resources.

```APIDOC
## HWPReader.fromURL(String url)

### Description
Reads an HWP file from a specified URL and converts it into an HWPFile object. This is useful for fetching HWP files from web resources.

### Method
static HWPFile

### Parameters
#### Path Parameters
- **url** (String) - Required - The URL path of the HWP file.

### Response
#### Success Response
- **HWPFile** - The HWPFile object representing the read HWP file.

### Exceptions
- **Exception** - Thrown in case of network errors or file reading failures.

### Request Example
```java
String url = "http://example.com/sample.hwp";
HWPFile hwpFile = HWPReader.fromURL(url);
```
```

--------------------------------

### HWPReader 및 HWPWriter

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/INDEX.md

HWP 파일을 읽고 쓰는 기능을 제공하는 클래스입니다. 다양한 소스에서 파일을 읽거나 파일로 저장할 수 있습니다.

```APIDOC
## HWPReader

### Description
HWP 파일을 다양한 소스에서 읽는 기능을 제공합니다.

### Methods
- `fromFile(filePath: String)`: 파일 경로로부터 HWP 파일을 읽습니다.
- `fromURL(url: String)`: URL로부터 HWP 파일을 읽습니다.
- `fromInputStream(inputStream: InputStream)`: InputStream으로부터 HWP 파일을 읽습니다.
- `fromBase64String(base64String: String)`: Base64 문자열로부터 HWP 파일을 읽습니다.

## HWPWriter

### Description
HWP 파일을 지정된 대상으로 저장하는 기능을 제공합니다.

### Methods
- `toFile(hwpFile: HWPFile, filePath: String)`: HWPFile 객체를 지정된 경로에 저장합니다.
- `toStream(hwpFile: HWPFile, outputStream: OutputStream)`: HWPFile 객체를 OutputStream으로 저장합니다.

## HWPFile

### Description
HWP 파일의 핵심 데이터를 나타내는 객체입니다.

### Methods
- `getFileHeader()`: 파일 헤더 정보를 가져옵니다.
- `getDocInfo()`: 문서 정보를 가져옵니다.
- `getBodyText()`: 본문 텍스트를 가져옵니다.
- `getBinData()`: 바이너리 데이터를 가져옵니다.
```

--------------------------------

### 설정 및 호환성

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/INDEX.md

hwplib의 설정 옵션, 지원되는 HWP 버전, Java 요구사항 및 의존성에 대한 정보를 제공합니다.

```APIDOC
## Configuration and Compatibility

### Description
hwplib 라이브러리의 설정, 호환성 및 환경 요구사항에 대한 정보를 제공합니다.

### Key Information
- **Supported HWP Versions**: HWP 5.0.0.0부터 2024 버전까지 지원
- **FileHeader Properties**: 파일 헤더 관련 속성
- **Document Info Components**: `FaceNames`, `CharShapes`, `ParaShapes`, `Styles` 등 문서 정보 구성 요소
- **Java Version Requirements**: 요구되는 Java 버전 정보
- **Dependencies**: Apache POI 등 외부 라이브러리 의존성
- **File Structure Defaults**: 파일 구조의 기본값
- **Usage Scenario Specific Settings**: 사용 시나리오에 따른 설정 조정
- **Performance Optimization**: 성능 향상을 위한 설정 팁
```

--------------------------------

### ControlField를 이용한 하이퍼링크 처리

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/image-hyperlink.md

HWP 문서 내의 모든 필드 컨트롤을 찾아 이름을 기반으로 처리하는 예제입니다. 하이퍼링크는 필드 컨트롤을 통해 구현됩니다.

```java
HWPFile hwpFile = HWPReader.fromFile("document.hwp");

// 필드 컨트롤 찾기
ArrayList<ControlField> fields = FieldFinder.findAll(hwpFile);
for (ControlField field : fields) {
    String fieldName = field.getName();
    // 필드 처리
}
```

--------------------------------

### TextExtractor

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/INDEX.md

HWP 문서에서 텍스트를 추출하는 기능을 제공합니다. 다양한 추출 방법을 지원하며 스트리밍 처리가 가능합니다.

```APIDOC
## TextExtractor

### Description
HWP 문서에서 텍스트를 추출하는 클래스입니다.

### Methods
- `extract(hwpFile: HWPFile, method: TextExtractMethod)`: 지정된 방법으로 HWP 파일에서 텍스트를 추출합니다.

### TextExtractMethod
- `OnlyMainParagraph`: 메인 문단만 추출합니다.
- `InsertControl`: 컨트롤을 삽입하여 추출합니다.
- `AppendControl`: 컨트롤을 추가하여 추출합니다.

## TextExtractorListener

### Description
텍스트 추출 과정을 스트리밍으로 처리하기 위한 리스너 인터페이스입니다.

### Methods
- `onTextExtracted(text: String)`: 텍스트가 추출될 때 호출됩니다.
- `onFinish()`: 텍스트 추출이 완료되었을 때 호출됩니다.
```

--------------------------------

### Read HWP file from URL

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/hwpreader-writer.md

Fetches and loads an HWP file from a given URL into an HWPFile object. This is useful for accessing HWP documents hosted online. Network errors or file reading problems can lead to exceptions.

```java
public static HWPFile fromURL(String url) throws Exception
```

```java
String url = "http://example.com/sample.hwp";
HWPFile hwpFile = HWPReader.fromURL(url);
```

--------------------------------

### Handle File I/O Exceptions in Java

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/README.md

Use a try-catch block to handle potential exceptions when reading HWP files. This includes `FileNotFoundException`, `IndexOutOfBoundsException`, and general `Exception` for format or write errors.

```java
try {
    HWPFile hwpFile = HWPReader.fromFile("document.hwp");
} catch (Exception e) {
    System.err.println("파일 읽기 실패: " + e.getMessage());
}
```

--------------------------------

### HWPReader.fromFile(String filepath)

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/hwpreader-writer.md

Reads an HWP file from a given local file path and converts it into an HWPFile object. This method is suitable for reading files directly from the file system.

```APIDOC
## HWPReader.fromFile(String filepath)

### Description
Reads an HWP file from a given local file path and converts it into an HWPFile object. This method is suitable for reading files directly from the file system.

### Method
static HWPFile

### Parameters
#### Path Parameters
- **filepath** (String) - Required - The path to the HWP file.

### Response
#### Success Response
- **HWPFile** - The HWPFile object representing the read HWP file.

### Exceptions
- **Exception** - Thrown if there is a file reading failure or if accessing an encrypted file.

### Request Example
```java
HWPFile hwpFile = HWPReader.fromFile("document.hwp");
Section section = hwpFile.getBodyText().getSectionList().get(0);
Paragraph paragraph = section.getParagraph(0);
```
```

--------------------------------

### HWPReader.fromFile(File file)

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/hwpreader-writer.md

Reads an HWP file from a given File object and converts it into an HWPFile object. This method allows reading HWP files when you already have a File object instance.

```APIDOC
## HWPReader.fromFile(File file)

### Description
Reads an HWP file from a given File object and converts it into an HWPFile object. This method allows reading HWP files when you already have a File object instance.

### Method
static HWPFile

### Parameters
#### Path Parameters
- **file** (File) - Required - The File object representing the HWP file.

### Response
#### Success Response
- **HWPFile** - The HWPFile object representing the read HWP file.

### Exceptions
- **Exception** - Thrown if there is a file reading failure or if accessing an encrypted file.

### Request Example
```java
File hwpFile = new File("document.hwp");
HWPFile hwp = HWPReader.fromFile(hwpFile);
```
```

--------------------------------

### Image 및 Hyperlink 처리

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/INDEX.md

이미지 컨트롤과 하이퍼링크를 처리하는 방법을 설명합니다. 다양한 GSO 및 양식 컨트롤도 다룹니다.

```APIDOC
## ControlPicture

### Description
이미지 컨트롤을 나타내는 클래스입니다.

## ControlField

### Description
필드를 통한 하이퍼링크 구현을 지원합니다.

## Paragraph.getControl()

### Description
문단 내의 컨트롤에 접근하는 메서드입니다.

## FactoryForControl

### Description
컨트롤을 생성하는 팩토리 클래스입니다.

### Methods
- `createControl(controlType: ControlType)`: 지정된 타입의 컨트롤을 생성합니다.

### Control Types
- GSO 컨트롤: Line, Rectangle, Ellipse, Polygon, Curve, Arc
- 양식 컨트롤: CheckBox, RadioButton, TextField
```

--------------------------------

### Accessing Styles in HWP

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/configuration.md

Retrieve and process style information defined within the document's DocInfo, such as style names.

```java
DocInfo docInfo = hwpFile.getDocInfo();
ArrayList<Style> styles = docInfo.getStyleList();

for (Style style : styles) {
    String styleName = style.getStyleName();
    // 스타일 속성 처리
}
```

--------------------------------

### ControlFinder

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/INDEX.md

문서 내의 다양한 컨트롤을 검색하는 기능을 제공합니다. 특정 타입이나 조건에 맞는 컨트롤을 찾을 수 있습니다.

```APIDOC
## ControlFinder

### Description
문서 내의 컨트롤을 검색하는 클래스입니다.

### Methods
- `find(filter: ControlFilter)`: 지정된 필터 조건에 맞는 컨트롤을 검색합니다.

### ControlFilter

### Description
컨트롤 검색 조건을 정의하는 인터페이스입니다.

### Methods
- `isMatched(control: Control)`: 컨트롤이 필터 조건에 맞는지 확인합니다.

### ControlType

### Description
컨트롤의 타입을 나타내는 열거형입니다.

### Examples
- `Table`: 표 컨트롤
- `Picture`: 그림 컨트롤
- `OLE`: OLE 컨트롤
- `Equation`: 수식 컨트롤
```

--------------------------------

### Comprehensive HWP File Processing with Error Handling

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/errors.md

A robust pattern for processing HWP files, including reading, checking for encryption, handling potential exceptions like FileNotFoundException and IndexOutOfBoundsException, and saving the file.

```java
public static void processHWPFile(String inputPath, String outputPath) {
    HWPFile hwpFile = null;
    try {
        // 파일 읽기
        hwpFile = HWPReader.fromFile(inputPath);
        
        // 암호 확인
        if (hwpFile.getFileHeader().hasPassword()) {
            System.out.println("오류: 암호화된 파일입니다.");
            return;
        }
        
        // 문서 처리
        Section section = hwpFile.getBodyText().getSectionList().get(0);
        Paragraph para = section.getParagraph(0);
        if (para.getText() != null) {
            String text = para.getText().toString();
            System.out.println("텍스트: " + text);
        }
        
        // 파일 저장
        HWPWriter.toFile(hwpFile, outputPath);
        System.out.println("저장 완료: " + outputPath);
        
    } catch (FileNotFoundException e) {
        System.err.println("파일을 찾을 수 없습니다: " + inputPath);
    } catch (IndexOutOfBoundsException e) {
        System.err.println("인덱스 범위 오류: " + e.getMessage());
    } catch (Exception e) {
        System.err.println("오류 발생: " + e.getMessage());
        e.printStackTrace();
    }
}
```

--------------------------------

### 오류 및 예외 처리

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/INDEX.md

hwplib 사용 중 발생할 수 있는 다양한 오류와 예외 처리 방법에 대한 가이드라인을 제공합니다.

```APIDOC
## Errors and Exceptions

### Description
hwplib 사용 중 발생할 수 있는 오류 유형과 일반적인 처리 패턴에 대한 가이드라인을 제공합니다.

### Common Error Scenarios
- **File Reading Errors**: 암호화된 파일, 존재하지 않는 파일, 잘못된 형식의 파일 처리
- **File Saving Errors**: 쓰기 권한 부족, 디스크 공간 부족 문제
- **Field Setting Errors**: 필드 값 설정 시 발생하는 오류
- **Table Manipulation Errors**: 표 관련 작업 중 발생하는 오류
- **Paragraph Merging/Adding Errors**: 문단 병합 또는 추가 시 오류

### General Error Handling Patterns
- 오류 발생 시 적절한 예외 처리
- 디버깅을 위한 로그 기록 활용
- 사용자에게 명확한 오류 메시지 제공
```

--------------------------------

### Read HWP file from file path

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/api-reference/hwpreader-writer.md

Use this method to load an HWP file into an HWPFile object by providing its file path. It can throw exceptions for file reading failures or access to encrypted files.

```java
public static HWPFile fromFile(String filepath) throws Exception
```

```java
HWPFile hwpFile = HWPReader.fromFile("document.hwp");
Section section = hwpFile.getBodyText().getSectionList().get(0);
Paragraph paragraph = section.getParagraph(0);
```

--------------------------------

### Process Latest HWP File Version

Source: https://github.com/neolord0/hwplib/blob/main/_autodocs/configuration.md

Load the latest HWP file and check for distribution specific features using isDistribution(). Note that not all features of the latest HWP 2024 version may be supported.

```java
HWPFile hwpFile = HWPReader.fromFile("latest.hwp");

// 최신 버전의 새로운 기능 처리
if (hwpFile.getFileHeader().isDistribution()) {
    // 배포용 문서 처리
}
```