API 문서

Tip

/ 키를 누르면 바로 검색창이 열립니다.

pyhwpx.core

Ctrl

아래아한글의 모든 개체(표, 그림, 글상자 및 각주/미주 등)를 다루기 위한 클래스.

CtrlCh property

선택한 개체(Ctrl)의 타입 확인할 수 있는 컨트롤 문자를 리턴

일반적으로 컨트롤 ID를 사용해 컨트롤의 종류를 판별하지만, 이보다 더 포괄적인 범주를 나타내는 컨트롤 문자로 판별할 수도 있다. 예를 들어 각주와 미주는 ID는 다르지만, 컨트롤 문자는 17로 동일하다. 컨트롤 문자는 1부터 31사이의 값을 사용한다. (그럼에도, CtrlCh는 개인적으로 잘 사용하지 않는다.)

Returns:

Type	Description
int	1~31의 정수 1: 예약 2: 구역/단 정의 3: 필드 시작 4: 필드 끝 5: 예약 6: 예약 7: 예약 8: 예약 9: 탭 10: 강제 줄 나눔 11: 그리기 개체 / 표 12: 예약 13: 문단 나누기 14: 예약 15: 주석 16: 머리말 / 꼬리말 17: 각주 / 미주 18: 자동 번호 19: 예약 20: 예약 21: 쪽바뀜 22: 책갈피 / 찾아보기 표시 23: 덧말 / 글자 겹침 24: 하이픈 25: 예약 26: 예약 27: 예약 28: 예약 29: 예약 30: 묶음 빈칸 31: 고정 폭 빈칸

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()  # 표 두 개가 들어있는 문서에서
>>> for ctrl in hwp.ctrl_list:
...     print(ctrl.CtrlCh)
...
11
11

CtrlID property

컨트롤 아이디

컨트롤 ID는 컨트롤의 종류를 나타내기 위해 할당된 ID로서, 최대 4개의 문자로 구성된 문자열이다. 예를 들어 표는 "tbl", 각주는 "fn"이다. 이와 비슷하게 CtrlCh는 정수로, UserDesc는 한글 문자열로 리턴한다.

한/글에서 현재까지 지원되는 모든 컨트롤의 ID는 아래 Returns 참조.

Returns:

Type

Description

str

해당 컨트롤의 컨트롤아이디 "cold" : (ColDef) 단 "secd" : (SecDef) 구역 "fn" : (FootnoteShape) 각주 "en" : (FootnoteShape) 미주 "tbl" : (TableCreation) 표 "eqed" : (EqEdit) 수식 "gso" : (ShapeObject) 그리기 개체 "atno" : (AutoNum) 번호 넣기 "nwno" : (AutoNum) 새 번호로 "pgct" : (PageNumCtrl) 페이지 번호 제어(97의 홀수 쪽에서 시작) "pghd" : (PageHiding) 감추기 "pgnp" : (PageNumPos) 쪽 번호 위치 "head" : (HeaderFooter) 머리말 "foot" : (HeaderFooter) 꼬리말 "%dte" : (FieldCtrl) 현재의 날짜/시간 필드 "%ddt" : (FieldCtrl) 파일 작성 날짜/시간 필드 "%pat" : (FieldCtrl) 문서 경로 필드 "%bmk" : (FieldCtrl) 블록 책갈피 "%mmg" : (FieldCtrl) 메일 머지 "%xrf" : (FieldCtrl) 상호 참조 "%fmu" : (FieldCtrl) 계산식 "%clk" : (FieldCtrl) 누름틀 "%smr" : (FieldCtrl) 문서 요약 정보 필드 "%usr" : (FieldCtrl) 사용자 정보 필드 "%hlk" : (FieldCtrl) 하이퍼링크 "bokm" : (TextCtrl) 책갈피 "idxm" : (IndexMark) 찾아보기 "tdut" : (Dutmal) 덧말 "tcmt" : (None) 주석

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()  # 2x2 표의 각 셀 안에 이미지가 총 4장 들어있는 문서
>>> for ctrl in hwp.ctrl_list:
...     print(ctrl.CtrlID)
...
tbl
gso
gso
gso
gso

Next property

다음 컨트롤.

문서 중의 모든 컨트롤(표, 그림 등의 특수 문자들)은 linked list로 서로 연결되어 있는데, list 중 다음 컨트롤을 나타낸다.

Returns:

Type	Description
'Ctrl'	현재 컨트롤의 다음 컨트롤

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()  # 표 하나만 들어 있는 문서에서
>>> print(hwp.HeadCtrl.Next.Next.UserDesc)
표

Prev property

앞 컨트롤.

문서 중의 모든 컨트롤(표, 그림 등의 특수 문자들)은 linked list로 서로 연결되어 있는데, list 중 앞 컨트롤을 나타낸다.

Returns:

Type	Description
'Ctrl'	현재 컨트롤의 이전 컨트롤

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()  # 빈 표, 그 아래에 그림 한 개 삽입된 문서에서
>>> print(hwp.LastCtrl.Prev.UserDesc)
표

Properties property writable

컨트롤의 속성을 나타낸다.

모든 컨트롤은 대응하는 parameter set으로 속성을 읽고 쓸 수 있다.

Examples:

>>> # 문서의 모든 그림의 너비, 높이를 각각 절반으로 줄이는 코드
>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> for ctrl in hwp.ctrl_list:
...     if ctrl.UserDesc == "그림":
...         prop = ctrl.Properties
...         width = prop.Item("Width")
...         height = prop.Item("Height")
...         prop.SetItem("Width", width // 2)
...         prop.SetItem("Height", height // 2)
...         ctrl.Properties = prop

UserDesc property

컨트롤의 종류를 사용자에게 보여줄 수 있는 localize된 문자열로 나타낸다.

GetAnchorPos(type_=0)

해당 컨트롤의 앵커(조판부호)의 위치를 반환한다.

Parameters:

Name	Type	Description	Default
type_	int	기준위치 0: 바로 상위 리스트에서의 앵커 위치(기본값) 1: 탑레벨 리스트에서의 앵커 위치 2: 루트 리 스트에서의 앵커 위치	0

Returns:

Type	Description
'Hwp.HParameterSet'	성공했을 경우 ListParaPos ParameterSet이 반환된다. 실패했을 때는 None을 리턴함.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()  # 표만 두 개 있는 문서에 연결됨.
>>> for ctrl in hwp.ctrl_list:
...     print(ctrl.GetAnchorPos().Item("List"), end=" ")
...     print(ctrl.GetAnchorPos().Item("Para"), end=" ")
...     print(ctrl.GetAnchorPos().Item("Pos"))
0 0 16
0 2 0

GetCtrlInstID()

[한글2024전용] 컨트롤의 고유 아이디를 정수형태 문자열로 리턴하는 메서드

한글2024부터 제공하는 기능으로 정확하게 컨트롤을 선택하기 위한 새로운 수단이다. 기존의 FindCtrl(), hwp.SelectCtrlFront()나 hwp.SelectCtrlReverse() 등 인접 컨트롤을 선택하는 방법에는 문제의 소지가 있었다. 대표적인 예로, 이미지가 들어있는 셀 안에서 표 컨트롤을 선택하려고 하면, 어떤 방법을 쓰든 이미지가 선택돼버리기 때문에 이미지를 선택하지 않는 여러 꼼수를 생각해내야 했다. 하지만 ctrl.GetCtrlInstID()와 hwp.SelectCtrl()을 같이 사용하면 그럴 걱정이 전혀 없게 된다.

다만 사용시 주의할 점이 하나 있는데,

Get/SetTextFile이나 save_block_as 등의 메서드 혹은 Cut/Paste 사용시에는, 문서상에서 컨트롤이 지워졌다 다시 씌어지는 시점에 CtrlInstID가 바뀌게 된다. (다만, 마우스로 드래그해 옮길 땐 아이디가 바뀌지 않는다.)

Returns:

Type	Description
str	10자리 정수 형태의 문자열로 구성된 CtrlInstID를 리턴한다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.insert_random_picture()
>>> hwp.insert_random_picture()
>>> hwp.insert_random_picture()
>>> for ctrl in hwp.ctrl_list:
...     print(ctrl.GetCtrlInstID())
...
1816447703
1816447705
1816447707
>>> hwp.hwp.SelectCtrl("")

Hwp

Bases: ParamHelpers, RunMethods

아래아한글 인스턴스를 실행합니다.

실행방법은 간단합니다. from pyhwpx import Hwp로 Hwp 클래스를 임포트한 후, hwp = Hwp() 명령어를 실행하면 아래아한글이 자동으로 열립니다. 만약 기존에 아래아한글 창이 하나 이상 열려 있다면, 가장 마지막에 접근했던 아래아한글 창과 연결됩니다.

Parameters:

Name	Type	Description	Default
new	bool	new=True 인 경우, 기존에 열려 있는 한/글 인스턴스와 무관한 새 인스턴스를 생성하게 됩니다. new=False (기본값)인 경우, 우선적으로 기존에 열려 있는 한/글 창에 연결을 시도합니다. (연결되지 않기도 합니다.)	False
visible	bool	한/글 인스턴스를 백그라운드에서 실행할지, 화면에 나타낼지 선택합니다. 기본값은 True 이며, 한/글 창이 화면에 나타나게 됩니다. visible=False 파라미터를 추가할 경우 한/글 창이 보이지 않는 상태로 백그라운드에서 작업할 수 있습니다.	True
register_module	bool	보안모듈을 Hwp 클래스에서 직접 실행하게 허용합니다. 기본값은 True 입니다. hwp.RegisterModule("FilePathCheckDLL", "FilePathCheckerModule") 메서드를 직접 실행하는 것과 동일합니다.	True

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.insert_text("Hello world!")
True
>>> hwp.save_as("./hello.hwp")
True
>>> hwp.clear()
>>> hwp.quit()

Application property

저수준의 아래아한글 오토메이션API에 직접 접근하기 위한 속성입니다.

hwp.Application.~~~ 로 실행 가능한 모든 속성은, 간단히 hwp.~~~ 로 실행할 수도 있지만 pyhwpx와 API의 작동방식을 동일하게 하기 위해 구현해 두었습니다.

Returns: 저수준의 HwpApplication 객체

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.Application.XHwpWindows.Item(0).Visible = True

CLSID property

파라미터셋의 CLSID(클래스아이디)를 조회함. 읽기전용 속성이며, 사용할 일이 없음..

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.CharShape.CLSID
IID('{599CBB08-7780-4F3B-8ADA-7F2ECFB57181}')

CellShape property writable

셀(또는 표) 모양을 관리하는 파라미터셋 속성입니다.

Returns: CellShape 파라미터셋

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.CellShape.Item("Height")  # 현재 표의 높이를 HwpUnit 단위로 리턴
6410
>>> hwp.HwpUnitToMili(hwp.CellShape.Item("Height"))
22.6131
>>> hwp.get_table_height()  # 위와 동일한 값을 리턴함
22.6131
>>> hwp.get_row_height()  # 현재 셀의 높이를 밀리미터 단위로 리턴
4.5226

CharShape property writable

글자모양 파라미터셋을 조회하거나 업데이트할 수 있는 파라미터셋 속성.

여러 속성값을 조회하고 싶은 경우에는 hwp.CharShape 대신 hwp.get_charshape_as_dict() 메서드를 사용하면 편리합니다. CharShape 속성을 변경할 때는 아래 예시처럼 hwp.set_font() 함수를 사용하는 것을 추천합니다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>>
>>> # 현재 캐럿위치 또는 선택영역의 글자크기를 포인트단위로 출력
>>> hwp.HwpUnitToPoint(hwp.CharShape.Item("Height"))
10.0
>>> # 여러 속성값을 확인하고 싶은 경우에는 아래처럼~
>>> hwp.get_charshape_as_dict()
{'Bold': 0,
 'BorderFill': <win32com.gen_py.HwpObject 1.0 Type Library.IDHwpParameterSet instance at 0x2267681890512>,
 'DiacSymMark': 0,
 'Emboss': 0,
 'Engrave': 0,
 'FaceNameHangul': '함초롬바탕',
 'FaceNameHanja': '함초롬바탕',
 'FaceNameJapanese': '함초롬바탕',
 'FaceNameLatin': '함초롬바탕',
 'FaceNameOther': '함초롬바탕',
 'FaceNameSymbol': '함초롬바탕',
 'FaceNameUser': '함초롬바탕',
 'FontTypeHangul': 1,
 'FontTypeHanja': 1,
 'FontTypeJapanese': 1,
 'FontTypeLatin': 1,
 'FontTypeOther': 1,
 'FontTypeSymbol': 1,
 'FontTypeUser': 1,
 'HSet': None,
 'Height': 2000,
 'Italic': 0,
 'OffsetHangul': 0,
 'OffsetHanja': 0,
 'OffsetJapanese': 0,
...
 'UnderlineColor': 0,
 'UnderlineShape': 0,
 'UnderlineType': 0,
 'UseFontSpace': 0,
 'UseKerning': 0}
>>>
>>> # 속성을 변경하는 예시
>>> prop = hwp.CharShape  # 글자속성 개체를 복사한 후
>>> prop.SetItem("Height", hwp.PointToHwpUnit(20))  # 파라미터 아이템 변경 후
>>> hwp.CharShape = prop  # 글자속성을 prop으로 업데이트
>>>
>>> # 위 세 줄의 코드는 간단히 아래 단축메서드로도 실행가능
>>> hwp.set_font(Height=30)  # 글자크기를 30으로 변경

CurFieldState property

현재 캐럿이 들어있는 영역의 상태를 조회할 수 있는 속성.

필드 안에 들어있지 않으면(본문, 캡션이나 주석 포함) 0을 리턴하며, 셀 안이면 1, 글상자 안이면 4를 리턴합니다. 셀필드 안에 있으면 17, 누름틀 안에 있으면 18을 리턴합니다. 셀필드 안의 누름틀 안에서도 누름틀과 동일하게 18을 리턴하는 점에 유의하세요. 정수값에 따라 현재 캐럿의 위치를 파악할 수 있기 때문에 다양하게 활용할 수 있습니다. 예를 들어 필드와 무관하게 "캐럿이 셀 안에 있는가"를 알고 싶은 경우에도 hwp.CurFieldState 가 1을 리턴하는지 확인하는 방식을 사용할 수 있습니다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> # 캐럿이 현재 표 안에 들어있는지 확인하고 싶은 경우
>>> if hwp.CurFieldState == 1:
...     print("캐럿이 셀 안에 들어있습니다.")
... else:
...     print("캐럿이 셀 안에 들어있지 않습니다.")
캐럿이 셀 안에 들어있습니다.

CurMetatagState property

(한글2024 이상) 현재 캐럿이 들어가 있는 메타태그 상태를 조회할 수 있는 속성.

1: 셀 메타태그 영역에 들어있음 4: 메타태그가 부여된 글상자 또는 그리기개체 컨트롤 내부의 텍스트 공간에 있음 8: 메타태그가 부여된 이미지 또는 글맵시, 글상자 등의 컨트롤 선택상태임 16: 메타태그가 부여된 표 컨트롤 선택 상태임 32: 메타태그 영역에 들어있지 않음 40: 컨트롤을 선택하고 있긴 한데, 메타태그는 지정되어 있지 않은 상태(8+32) 64: 본문 메타태그 영역에 들어있음

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> if hwp.CurMetatagState == 1:
...     print("현재 캐럿이 셀 메타태그 영역에 들어있습니다.")

CurSelectedCtrl property

현재 선택된 오브젝트의 컨트롤을 리턴하는 속성

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> # 문서의 첫 번째 표를 선택하고 "글자처럼 취급" 속성 켜기
>>> hwp.get_into_nth_table()  # 문서 첫 번째 표의 A1 셀로 이동
>>> hwp.SelectCtrlFront()  # 표 오브젝트 선택
>>> ctrl = hwp.CurSelectedCtrl  # <-- 표 오브젝트의 컨트롤정보 변수지정
>>> prop = ctrl.Properties  # 컨트롤정보의 속성(일종의 파라미터셋) 변수지정
>>> prop.SetItem("TreatAsChar", True)  # 복사한 파라미터셋의 글자처럼취급 아이템값을 True로 변경
>>> ctrl.Properties = prop  # 파라미터셋 속성을 표 오브젝트 컨트롤에 적용
>>> hwp.Cancel()  # 적용을 마쳤으면 표선택 해제(권장)

EditMode property writable

현재 편집모드(a.k.a. 읽기전용)를 리턴하는 속성. 일반적으로 자동화에 쓸 일이 없으므로 무시해도 됩니다. 편집모드로 변경하고 싶으면 1, 읽기전용으로 변경하고 싶으면 0 대입합니다.

Returns: 편집모드는 1을, 읽기전용인 경우 0을 리턴

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.EditMode
1
>>> hwp.EditMode = 0  # 읽기 전용으로 변경됨

HAction property

한/글의 액션을 설정하고 실행하기 위한 속성.

GetDefalut, Execute, Run 등의 메서드를 가지고 있습니다. 저수준의 액션과 파라미터셋을 조합하여 기능을 실행할 때에 필요합니다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> # "Hello world!" 문자열을 입력하는 액션
>>> pset = hwp.HParameterSet.HInsertText
>>> act_id = "InsertText"
>>> pset.Text = "Hello world!\r\n"  # 줄바꿈 포함
>>> hwp.HAction.Execute(act_id, pset.HSet)
>>> # 위 네 줄의 명령어는 아래 방법으로도 실행 가능
>>> hwp.insert_text("Hello world!")
>>> hwp.BreakPara()  # 줄바꿈 메서드
True

HParameterSet property

한/글에서 실행되는 대부분의 액션을 설정하는 데 필요한 파라미터셋들이 들어있는 속성.

HAction과 HParameterSet을 조합하면 어떤 복잡한 동작이라도 구현해낼 수 있지만 공식 API 문서를 읽으며 코딩하기보다는, 해당 동작을 한/글 내에서 스크립트매크로로 녹화하고 녹화된 매크로에서 액션아이디와 파라미터셋을 참고하는 방식이 훨씬 효율적이다. HParameterSet을 활용하는 예시코드는 아래와 같다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> pset = hwp.HParameterSet.HInsertText
>>> pset.Text = "Hello world!"
>>> hwp.HAction.Execute("InsertText", pset.HSet)
True

HeadCtrl property

문서의 첫 번째 컨트롤을 리턴한다.

문서의 첫 번째, 두 번째 컨트롤은 항상 "구역 정의"와 "단 정의"이다. (이 둘은 숨겨져 있음) 그러므로 hwp.HeadCtrl 은 항상 구역정의(secd: section definition)이며, hwp.HeadCtrl.Next 는 단 정의(cold: column definition)이다.

사용자가 삽입한 첫 번째 컨트롤은 항상 hwp.HeadCtrl.Next.Next 이다.

HeadCtrl과 반대로 문서의 가장 마지막 컨트롤은 hwp.LastCtrl이며, 이전 컨트롤로 순회하려면 .Next 대신 .Prev 를 사용하면 된다. hwp.HeadCtrl의 기본적인 사용법은 아래와 같다.

Examples:

>>> # 문서에 삽입된 모든 표의 "글자처럼 취급" 속성을 해제하는 코드
>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> ctrl = hwp.HeadCtrl
>>> while ctrl:
...     if ctrl.UserDesc == "표":  # 이제 ctrl 변수가 해당 표 컨트롤을 가리키고 있으므로
...         prop = ctrl.Properties
...         prop.SetItem("TreatAsChar", True)
...         ctrl.Properties = prop
...     ctrl = ctrl.Next
>>> print("모든 표의 글자처럼 취급 속성 해제작업이 완료되었습니다.")
모든 표의 글자처럼 취급 속성 해제작업이 완료되었습니다.

IsEmpty property

아무 내용도 들어있지 않은 빈 문서인지 여부를 나타낸다. 읽기전용임

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> # 특정 문서를 열고, 비어있는지 확인
>>> hwp.open("./example.hwpx")
>>> if hwp.IsEmpty:
...     print("빈 문서입니다.")
... else:
...     print("빈 문서가 아닙니다.")
빈 문서가 아닙니다.

IsModified property

최근 저장 또는 생성 이후 수정이 있는지 여부를 나타낸다. 읽기전용이며, 자동화에 활용하는 경우는 거의 없다. 패스~

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.open("./example.hwpx")
>>> # 신나게 작업을 마친 후, 종료하기 직전, 혹시 하는 마음에
>>> # 수정사항이 있으면 저장하고 끄기 & 수정사항이 없으면 그냥 한/글 종료하기
>>> if hwp.IsModified:
...     hwp.save()
... hwp.quit()

LastCtrl property

문서의 가장 마지막 컨트롤 객체를 리턴한다.

연결리스트 타입으로, HeadCtrl부터 LastCtrl까지 모두 연결되어 있고 LastCtrl.Prev.Prev 또는 HeadCtrl.Next.Next 등으로 컨트롤 순차 탐색이 가능하다. 혹자는 hwp.HeadCtrl 만 있으면 되는 거 아닌가 생각할 수 있지만, 특정 조건의 컨트롤을 삭제!!하는 경우 삭제한 컨트롤 이후의 모든 컨트롤의 인덱스가 변경되어버리므로 이런 경우에는 LastCtrl에서 역순으로 진행해야 한다. (HeadCtrl부터 Next 작업을 하면 인덱스 꼬임)

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> # 문서 내의 모든 그림 삭제하기
>>> ctrl = hwp.LastCtrl  # <---
>>> while ctrl:
...     if ctrl.UserDesc == "그림":
...         hwp.DeleteCtrl(ctrl)
...     ctrl = ctrl.Prev
... print("모든 그림을  삭제하였습니다.")
모든 그림을 삭제하였습니다.
>>> # 아래처럼 for문과 hwp.ctrl_list로도 구현할 수 있음
>>> for ctrl in [i for i in hwp.ctrl_list if i.UserDesc == "그림"][::-1]:  # 역순 아니어도 무관.
...     hwp.DeleteCtrl(ctrl)

PageCount property

현재 문서의 총 페이지 수를 리턴.

Returns:

Type	Description
int	현재 문서의 총 페이지 수

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.open("./example.hwpx")
>>> print(f"현재 이 문서의 총 페이지 수는 {hwp.PageCount}입니다.")
현재 이 문서의 총 페이지 수는 20입니다.

ParaShape property writable

CharShape, CellShape과 함께 가장 많이 사용되는 단축Shape 삼대장 중 하나.

현재 캐럿이 위치한, 혹은 선택한 문단(블록)의 문단모양 파라미터셋을 리턴한다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.open("./example.hwp")
>>> # 현재 캐럿위치의 줄간격 조회
>>> val = hwp.ParaShape.Item("LineSpacing")
>>> print(f"현재 문단의 줄간격은 {val}%입니다.")
현재 문단의 줄간격은 160%입니다.
>>>
>>> # 본문 모든 문단의 줄간격을 200%로 수정하기
>>> hwp.SelectAll()  # 전체선택
>>> prop = hwp.ParaShape
>>> prop.SetItem("LineSpacing", 200)
>>> hwp.ParaShape = prop
>>> print("본문 전체의 줄간격을 200%로 수정하였습니다.")
본문 전체의 줄간격을 200%로 수정하였습니다.

ParentCtrl property

현재 선택되어 있거나, 캐럿이 들어있는 컨트롤을 포함하는 상위 컨트롤을 리턴한다.

Returns:

Type	Description
Ctrl	상위 컨트롤(Ctrl)

Path property

현재 빈 문서가 아닌 경우, 열려 있는 문서의 파일명을 포함한 전체경로를 리턴한다.

Returns: 현재 문서의 전체경로

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.open("./example.hwpx")
>>> hwp.Path
C:/Users/User/desktop/example.hwpx

SelectionMode property

현재 선택모드가 어떤 상태인지 리턴한다.

Returns:

Title property

현재 연결된 아래아한글 창의 제목표시줄 타이틀을 리턴한다.

Returns:

Type	Description
str	현재 연결된 아래아한글 창의 제목표시줄 타이틀

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> print(hwp.Title)
빈 문서 1 - 한글

Version property

아래아한글 프로그램의 버전을 리스트로 리턴한다.

Returns:

Type	Description
list[int]	아래아한글 프로그램의 버전(문서 버전이 아님)

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.Version
[13, 0, 0, 2151]

ViewProperties property writable

현재 한/글 프로그램의 보기 속성 파라미터셋을 리턴한다.

Returns:

XHwpDocuments property

HwpApplication의 XHwpDocuments 객체를 리턴한다.

Returns:

XHwpMessageBox property

메시지박스 객체 리턴

Returns:

coclass_clsid property

coclass의 clsid를 리턴하는 읽기전용 속성. 사용하지 않음.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.coclass_clsid
IID('{2291CF00-64A1-4877-A9B4-68CFE89612D6}')

ctrl_list property

문서 내 모든 ctrl를 리스트로 반환한다.

단, 기본으로 삽입되어 있는 두 개의 컨트롤인 secd(섹션정의)와 cold(단정의) 두 개는 어차피 선택불가하므로 ctrl_list에서 제외했다. (모든 컨트롤을 제거하는 등의 경우, 편의를 위함)

Returns:

Type	Description
list	문서 내 모든 컨트롤의 리스트. 단, HeadCtrl(secd), HeadCtrl.Next(cold)는 포함하지 않는다.

current_page property

새쪽번호나 구역과 무관한 현재 쪽의 순서를 리턴.

1페이지에 있다면 1을 리턴한다. 새쪽번호가 적용되어 있어도 페이지의 인덱스를 리턴한다.

Returns:

Type	Description
int	현재 쪽번호

current_printpage property

페이지인덱스가 아닌, 종이에 표시되는 쪽번호를 리턴.

1페이지에 있다면 1을 리턴한다. 새쪽번호가 적용되어 있다면 수정된 쪽번호를 리턴한다.

Returns:

is_empty property

아무 내용도 들어있지 않은 빈 문서인지 여부를 나타낸다. 읽기전용

is_modified property

최근 저장 또는 생성 이후 수정이 있는지 여부를 나타낸다. 읽기전용

Run(act_id)

액션을 실행한다.

ActionTable.hwp 액션 리스트 중에서 "별도의 파라미터가 필요하지 않은" 단순 액션을 hwp.Run(액션아이디)으로 호출할 수 있다. 단, hwp.Run("BreakPara") 처럼 실행하는 대신 hwp.BreakPara() 방식으로 실행 가능하다.

Parameters:

Name	Type	Description	Default
act_id	str	액션 ID (ActionIDTable.hwp 참조)	required

Returns:

Type	Description
bool	성공시 True, 실패시 False를 반환한다.

SelectCtrl(ctrllist, option=1)

한글2024 이상의 버전에서 사용 가능한 API 기반의 신규 메서드.

가급적 hwp.select_ctrl(ctrl)을 실행할 것을 추천.

Parameters:

Name	Type	Description	Default
ctrllist	str | int	특정 컨트롤의 인스턴스 아이디(11자리 정수 또는 문자열). 인스턴스아이디는 ctrl.GetCtrlInstID() 로 구할 수 있으며 이는 한/글 2024부터 반영된 개념(2022 이하에서는 제공하지 않음)	required
option	Literal[0, 1]	특정 컨트롤(들)을 선택하고 있는 상태에서, 추가선택할 수 있는 옵션. - 0: 추가선택 - 1: 기존 선택해제 후 컨트롤 선택	1

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()  # 한글2024 이상의 버전
>>> # 문서 마지막 컨트롤 선택하기
>>> hwp.SelectCtrl(hwp.LastCtrl.GetCtrlInstID(), 0)

add_doc()

새 문서를 추가한다.

원래 창이 백그라운드로 숨겨져 있어도 추가된 문서는 보이는 상태가 기본값이다. 숨기려면 hwp.set_visible(False)를 실행해야 한다. 새 탭을 추가하고 싶은 경우는 add_doc 대신 add_tab을 실행하면 된다.

Returns:

Name	Type	Description
XHwpDocument	XHwpDocument	생성한 문서 오브젝트

add_tab()

새 문서를 현재 창의 새 탭에 추가한다.

백그라운드 상태에서 새 창을 만들 때 윈도우에 나타나는 경우가 있는데, add_tab() 함수를 사용하면 백그라운드 작업이 보장된다. 탭 전환은 switch_to() 메서드로 가능하다.

새 창을 추가하고 싶은 경우는 add_tab 대신 hwp.FileNew()나 hwp.add_doc()을 실행하면 된다.

adjust_cellwidth(width, as_='ratio')

칼럼의 너비를 변경할 수 있는 메서드.

정수(int)나 부동소수점수(float) 입력시 현재 칼럼의 너비가 변경되며, 리스트나 튜플 등 iterable 타입 입력시에는 각 요소들의 비에 따라 칼럼들의 너비가 일괄변경된다. 예를 들어 3행 3열의 표 안에서 set_col_width([1,2,3]) 을 실행하는 경우 1열너비:2열너비:3열너비가 1:2:3으로 변경된다. (표 전체의 너비가 148mm라면, 각각 24mm : 48mm : 72mm로 변경된다는 뜻이다.)

단, 열너비의 비가 아닌 "mm" 단위로 값을 입력하려면 as_="mm"로 파라미터를 수정하면 된다. 이 때, width에 정수 또는 부동소수점수를 입력하는 경우 as_="ratio"를 사용할 수 없다.

Parameters:

Name	Type	Description	Default
width	int | float | list | tuple	열 너비	required
as_	Literal['mm', 'ratio']	단위	'ratio'

Returns:

Type	Description
bool	성공시 True

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.create_table(3,3)
>>> hwp.get_into_nth_table(0)
>>> hwp.adjust_cellwidth([1,2,3])

auto_spacing(init_spacing=0, init_ratio=100, max_spacing=40, min_spacing=40, verbose=True)

자동 자간조정 메서드(beta)

라인 끝에 단어가 a와 b로 잘려 있는 경우 a>b인 경우 라인의 자간을 줄이고, a<b인 경우 자간을 넓혀 잘린 단어가 합쳐질 때까지 자간조정을 계속한다. 단, max_spacing이나 min_spacing을 넘어야 하는 경우에는 원상태로 되돌린 후 해당 라인의 정보를 콘솔에 출력한다. (아주 너비가 작은 셀이나 글상자 등에서는 제대로 작동하지 않을 수 있음.)

init_spacing과 init_ratio 파라미터를 통해 자동자간조정을 실행하기 전에 모든 문서의 기본 자간장평을 설정할 수 있다.

cell_fill(face_color=(217, 217, 217))

선택한 셀에 색 채우기

Parameters:

Name	Type	Description	Default
face_color	tuple[int, int, int]	(red, green, blue) 형태의 튜플. 각 정수는 0~255까지이며, 만약	(217, 217, 217)

Returns:

clear(option=1)

현재 편집중인 문서의 내용을 닫고 빈문서 편집 상태로 돌아간다.

Parameters:

Name	Type	Description	Default
option	int	편집중인 문서의 내용에 대한 처리 방법, 생략하면 1(hwpDiscard)가 선택된다. 0: 문서의 내용이 변경되었을 때 사용자에게 저장할지 묻는 대화상자를 띄운다. (hwpAskSave) 1: 문서의 내용을 버린다. (hwpDiscard, 기본값) 2: 문서가 변경된 경우 저장한다. (hwpSaveIfDirty) 3: 무조건 저장한다. (hwpSave)	1

Returns:

Type	Description
None	None

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.clear()

clipboard_to_pyfunc()

한/글 프로그램에서 스크립트매크로 녹화 코드를 클립보드에 복사하고

clipboard_to_pyfunc()을 실행하면, 클립보드의 매크로가 파이썬 함수로 변경된다. 곧 정규식으로 업데이트 예정(2023. 11. 30)

close(is_dirty=False, interval=0.01)

문서를 버리고 닫은 후, 새 문서창을 여는 메서드.

굳이 새 문서파일이 필요한 게 아니라면 hwp.close() 대신 hwp.clear()를 사용할 것.

Parameters:

Name	Type	Description	Default
is_dirty	bool	True인 경우 변경사항이 있을 때 문서를 닫지 않는다. False일 때는 변경사항을 버리고 문서를 닫음	False

Returns:

Type	Description
bool	문서창을 닫으면 True, 문서창 닫기에 실패하면 False 리턴

compose_chars(Chars='', CharSize=-3, CheckCompose=0, CircleType=0, **kwargs)

글자 겹치기 메서드(원문자 만들기)

캐럿 위치의 서체를 따라가지만, 임의의 키워드로 폰트 수정 가능(예: Bold=True, Italic=True, TextColor=hwp.RGBColor(255,0,0) 등)

Parameters:

Name	Type	Description	Default
Chars	str | int	겹칠 글자(정수도 문자열로 인식)	''
CharSize	int	글자확대(2:150%, 1:140%, 0:130%, -1:120%, -2:110%, -3:100%, -4:90%, -5:80%, -6:70%, -7:60%, -8:50%)	-3
CheckCompose	int	모양 안에 글자 겹치기 여부(1이면 글자들끼리도 겹침)	0
CircleType	int	테두리 모양(0:없음, 1:원, 2:반전원, 3:사각, 4:반전사각, 5:삼각, 6:반전삼각, 7:해, 8:마름모, 9:반전마름모, 10:뭉툭사각, 11:재활용빈화살표, 12:재활용화살표, 13:재활용채운화살표)	0

Returns:

Type	Description
bool	성공하면 True, 실패하면 False를 리턴

create_action(actidstr)

Action 객체를 생성한다.

액션에 대한 세부적인 제어가 필요할 때 사용한다. 예를 들어 기능을 수행하지 않고 대화상자만을 띄운다든지, 대화상자 없이 지정한 옵션에 따라 기능을 수행하는 등에 사용할 수 있다.

Parameters:

Name	Type	Description	Default
actidstr	str	액션 ID (ActionIDTable.hwp 참조)	required

Returns:

Type	Description
Any	Action object

Examples:

>>> from pyhwpx import Hwp
>>>
>>> hwp = Hwp()
>>> # 현재 커서의 폰트 크기(Height)를 구하는 코드
>>> act = hwp.create_action("CharShape")
>>> cs = act.CreateSet()  # equal to "cs = hwp.create_set(act)"
>>> act.GetDefault(cs)
>>> print(cs.Item("Height"))
2800
>>> # 현재 선택범위의 폰트 크기를 20pt로 변경하는 코드
>>> act = hwp.create_action("CharShape")
>>> cs = act.CreateSet()  # equal to "cs = hwp.create_set(act)"
>>> act.GetDefault(cs)
>>> cs.SetItem("Height", hwp.point_to_hwp_unit(20))
>>> act.Execute(cs)
True

create_field(name, direction='', memo='')

캐럿의 현재 위치에 누름틀을 생성한다.

Parameters:

Name	Type	Description	Default
name	str	누름틀 필드에 대한 필드 이름(중요)	required
direction	str	누름틀에 입력이 안 된 상태에서 보이는 안내문/지시문.	''
memo	str	누름틀에 대한 설명/도움말	''

Returns:

Type	Description
bool	성공이면 True, 실패면 False

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.create_field(direction="이름", memo="이름을 입력하는 필드", name="name")
True
>>> hwp.put_field_text("name", "일코")

create_page_image(path, pgno=-1, resolution=300, depth=24, format='bmp')

pgno로 지정한 페이지를 path 라는 파일명으로 저장한다. 이 때 페이지번호는 1부터 시작하며,(1-index) pgno=0이면 현재 페이지, pgno=-1(기본값)이면 전체 페이지를 이미지로 저장한다. 내부적으로 pillow 모듈을 사용하여 변환하므로, 사실상 pillow에서 변환 가능한 모든 포맷으로 입력 가능하다.

Parameters:

Name	Type	Description	Default
path	str	생성할 이미지 파일의 경로(전체경로로 입력해야 함)	required
pgno	int	페이지 번호(1페이지 저장하려면 pgno=1). 1부터 hwp.PageCount 사이에서 pgno 입력시 선택한 페이지만 저장한다. 생략하면(기본값은 -1) 전체 페이지가 저장된다. 이 때 path가 "img.jpg"라면 저장되는 파일명은 "img001.jpg", "img002.jpg", "img003.jpg",..,"img099.jpg" 가 된다. 현재 캐럿이 있는 페이지만 저장하고 싶을 때에는 pgno=0으로 설정하면 된다.	-1
resolution	int	이미지 해상도. DPI단위(96, 300, 1200 등)로 지정한다. 생략하면 300이 사용된다.	300
depth	int	이미지파일의 Color Depth(1, 4, 8, 24)를 지정한다. 생략하면 24	24
format	str	이미지파일의 포맷. "bmp", "gif"중의 하나. 생략하면 "bmp"가 사용된다.	'bmp'

Returns:

Type	Description
bool	성공하면 True, 실패하면 False

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.create_page_image("c:/Users/User/Desktop/a.bmp")
True

create_set(setidstr)

ParameterSet을 생성한다.

단독으로 쓰이는 경우는 거의 없으며, 대부분 create_action과 같이 사용한다.

ParameterSet은 일종의 정보를 지니는 객체이다. 어떤 Action들은 그 Action이 수행되기 위해서 정보가 필요한데 이 때 사용되는 정보를 ParameterSet으로 넘겨준다. 또한 한/글 컨트롤은 특정정보(ViewProperties, CellShape, CharShape 등)를 ParameterSet으로 변환하여 넘겨주기도 한다. 사용 가능한 ParameterSet의 ID는 ParameterSet Table.hwp문서를 참조한다.

Parameters:

Name	Type	Description	Default
setidstr	str	생성할 ParameterSet의 ID (ParameterSet Table.hwp 참고)	required

Returns:

Type	Description
'Hwp.HParameterSet'	생성된 ParameterSet Object

create_table(rows=1, cols=1, treat_as_char=True, width_type=0, height_type=0, header=True, height=0)

표를 생성하는 메서드.

기본적으로 rows와 cols만 지정하면 되며, 용지여백을 제외한 구간에 맞춰 표 너비가 결정된다. 이는 일반적인 표 생성과 동일한 수치이다.

아래의 148mm는 종이여백 210mm에서 60mm(좌우 각 30mm)를 뺀 150mm에다가, 표 바깥여백 각 1mm를 뺀 148mm이다. (TableProperties.Width = 41954) 각 열의 너비는 5개 기준으로 26mm인데 이는 셀마다 안쪽여백 좌우 각각 1.8mm를 뺀 값으로, 148 - (1.8 x 10 =) 18mm = 130mm 그래서 셀 너비의 총 합은 130이 되어야 한다. 아래의 라인28~32까지 셀너비의 합은 16+36+46+16+16=130 표를 생성하는 시점에는 표 안팎의 여백을 없애거나 수정할 수 없으므로 이는 고정된 값으로 간주해야 한다.

Parameters:

Name	Type	Description	Default
rows	int	행 수	1
cols	int	열 수	1
treat_as_char	bool	글자처럼 취급 여부	True
width_type	int	너비 정의 형식	0
height_type	int	높이 정의 형식	0
header	bool	1행을 제목행으로 설정할지 여부	True
height	int		0

Returns:

Type	Description
bool	표 생성 성공시 True, 실패시 False를 리턴한다.

delete_ctrl(ctrl)

문서 내 컨트롤을 삭제한다.

Parameters:

Name	Type	Description	Default
ctrl	Ctrl	삭제할 문서 내 컨트롤	required

Returns:

Type	Description
bool	성공하면 True, 실패하면 False

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> ctrl = hwp.HeadCtrl.Next.Next
>>> if ctrl.UserDesc == "표":
...     hwp.delete_ctrl(ctrl)
...
True

delete_style_by_name(src, dst)

주의사항

매번 메서드를 호출할 때마다 문서를 저장함(구현 편의를 위해ㅜ)!!! 다소 번거롭더라도 StyleDelete 액션을 직접 실행하는 것을 추천함.

특정 스타일을 이름 (또는 인덱스번호)로 삭제하고 대체할 스타일 또한 이름 (또는 인덱스번호)로 지정해주는 메서드.

export_mathml(mml_path, delay=0.2)

MathML 포맷의 수식문서 파일경로를 입력하면

아래아한글 수식으로 삽입하는 함수

export_style(sty_filepath)

현재 문서의 Style을 sty 파일로 Export한다. #스타일 #내보내기

Parameters:

Name	Type	Description	Default
sty_filepath	str	Export할 sty 파일의 전체경로 문자열	required

Returns:

Type	Description
bool	성공시 True, 실패시 False

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.export_style("C:/Users/User/Desktop/new_style.sty")
True

field_exist(field)

문서에 해당 이름의 데이터 필드가 존재하는지 검사한다.

Parameters:

Name	Type	Description	Default
field	str	필드이름	required

Returns:

Type	Description
bool	필드가 존재하면 True, 존재하지 않으면 False

fields_to_dict()

현재 문서에 저장된 필드명과 필드값을

dict 타입으로 리턴하는 메서드.

Returns:

file_translate(cur_lang='ko', trans_lang='en')

문서를 번역함(Ctrl-Z 안 됨.) 한 달 10,000자 무료

Parameters:

Name	Type	Description	Default
cur_lang	str	현재 문서 언어(예 - ko)	'ko'
trans_lang	str	목표언어(예 - en)	'en'

Returns:

Type	Description
bool	성공 후 True 리턴(실패하면 프로그램 종료됨ㅜ)

fill_addr_field()

현재 표 안에서 모든 셀에 엑셀 셀주소 스타일("A1")의 셀필드를 채우는 메서드

find(src, direction='Forward', regex=False, MatchCase=1, SeveralWords=1, UseWildCards=1, WholeWordOnly=0, AutoSpell=1, HanjaFromHangul=1, AllWordForms=0, FindStyle='', ReplaceStyle='', FindJaso=0, FindType=1)

direction 방향으로 특정 단어를 찾아가는 메서드.

해당 단어를 선택한 상태가 되며, 탐색방향에 src 문자열이 없는 경우 False를 리턴

Parameters:

Name	Type	Description	Default
src	str	찾을 단어	required
direction	Literal['Forward', 'Backward', 'AllDoc']	탐색방향 - "Forward": 아래쪽으로(기본값) - "Backward": 위쪽으로 - "AllDoc": 아래쪽 우선으로 찾고 문서끝 도달시 처음으로 돌아감.	'Forward'
regex	bool	정규식 탐색(기본값 False)	False
MatchCase	int	대소문자 구분(기본값 1)	1
SeveralWords	int	여러 단어 찾기	1
UseWildCards	int	아무개 문자(1),	1
WholeWordOnly	int	온전한 낱말(0),	0
AutoSpell	int		1
HanjaFromHangul	int	한글로 한자 찾기(1),	1
AllWordForms	int		0
FindStyle	str	찾을 글자모양	''
ReplaceStyle	str	바꿀 글자모양	''
FindJaso	int	자소 단위 찾기(0),	0
FindType	int		1

Returns:

Type	Description
bool	단어를 찾으면 찾아가서 선택한 후 True를 리턴,
bool	단어가 더이상 없으면 False를 리턴

find_backward(src, regex=False)

문서 위쪽으로 find 메서드를 수행.

해당 단어를 선택한 상태가 되며, 문서 처음에 도달시 False 리턴

Parameters:

Name	Type	Description	Default
src	str	찾을 단어	required

Returns:

Type	Description
bool	단어를 찾으면 찾아가서 선택한 후 True를 리턴, 단어가 더이상 없으면 False를 리턴

find_ctrl()

컨트롤 선택하기

find_forward(src, regex=False)

문서 아래쪽으로 find를 수행하는 메서드.

해당 단어를 선택한 상태가 되며, 문서 끝에 도달시 False 리턴.

Parameters:

Name	Type	Description	Default
src	str	찾을 단어	required

Returns:

Type	Description
bool	단어를 찾으면 찾아가서 선택한 후 True를 리턴, 단어가 더이상 없으면 False를 리턴

find_private_info(private_type, private_string)

개인정보를 찾는다. (비밀번호 설정 등의 이유, 현재 비활성화된 것으로 추정)

Parameters:

Name	Type	Description	Default
private_type	int	보호할 개인정보 유형. 다음의 값을 하나이상 조합한다. - 0x0001: 전화번호 - 0x0002: 주민등록번호 - 0x0004: 외국인등록번호 - 0x0008: 전자우편 - 0x0010: 계좌번호 - 0x0020: 신용카드번호 - 0x0040: IP 주소 - 0x0080: 생년월일 - 0x0100: 주소 - 0x0200: 사용자 정의 - 0x0400: 기타	required
private_string	str	기타 문자열. 0x0400 유형이 존재할 경우에만 유효하므로, 생략가능하다. (예: "신한카드")	required

Returns:

Type	Description
int	찾은 개인정보의 유형 값. 개인정보가 없는 경우에는 0을 반환한다. 또한, 검색 중 문서의 끝(end of document)을 만나면 –1을 반환한다. 이는 함수가 무한히 반복하는 것을 막아준다. 구체적으로는 아래와 같다. 0x0001 : 전화번호 0x0002 : 주민등록번호 0x0004 : 외국인등록번호 0x0008 : 전자우편 0x0010 : 계좌번호 0x0020 : 신용카드번호 0x0040 : IP 주소 0x0080 : 생년월일 0x0100 : 주소 0x0200 : 사용자 정의 0x0400 : 기타

find_replace(src, dst, regex=False, direction='Forward', MatchCase=1, AllWordForms=0, SeveralWords=1, UseWildCards=1, WholeWordOnly=0, AutoSpell=1, IgnoreFindString=0, IgnoreReplaceString=0, ReplaceMode=1, HanjaFromHangul=1, FindJaso=0, FindStyle='', ReplaceStyle='', FindType=1)

아래아한글의 찾아바꾸기와 동일한 액션을 수항해지만,

re=True로 설정하고 실행하면, 문단별로 잘라서 문서 전체를 순회하며 파이썬의 re.sub 함수를 실행한다.

find_replace_all(src, dst, regex=False, MatchCase=1, AllWordForms=0, SeveralWords=1, UseWildCards=1, WholeWordOnly=0, AutoSpell=1, IgnoreFindString=0, IgnoreReplaceString=0, ReplaceMode=1, HanjaFromHangul=1, FindJaso=0, FindStyle='', ReplaceStyle='', FindType=1)

아래아한글의 찾아바꾸기와 동일한 액션을 수항해지만,

re=True로 설정하고 실행하면, 문단별로 잘라서 문서 전체를 순회하며 파이썬의 re.sub 함수를 실행한다.

get_available_font()

현재 사용 가능한 폰트 리스트를 리턴. API 사용시 발생하는 오류로 인해 현재는 한글 폰트만 지원하고 있음.

Returns: 현재 사용 가능한 폰트 리스트

get_bin_data_path(binid)

Binary Data(Temp Image 등)의 경로를 가져온다.

Parameters:

Name	Type	Description	Default
binid	int	바이너리 데이터의 ID 값 (1부터 시작)	required

Returns:

Type	Description
str	바이너리 데이터의 경로

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> path = hwp.get_bin_data_path(2)
>>> print(path)
C:/Users/User/AppData/Local/Temp/Hnc/BinData/EMB00004dd86171.jpg

get_cell_addr(as_='str')

현재 캐럿이 위치한 셀의 주소를 "A1" 또는 (0, 0)으로 리턴.

캐럿이 표 안에 있지 않은 경우 False를 리턴함

Parameters:

Name	Type	Description	Default
as_	Literal['str', 'tuple']	"str"의 경우 엑셀처럼 "A1" 방식으로 리턴, "tuple"인 경우 (0,0) 방식으로 리턴.	'str'

Returns:

get_cell_margin(as_='mm')

표 중 커서가 위치한 셀 또는 다중선택한 모든 셀의 안 여백을 조회하는 메서드.

표 안에서만 실행가능하며, 전체 셀이 아닌 표 자체를 선택한 상태에서는 여백이 조회되지 않음.

Parameters:

Name	Type	Description	Default
as_	Literal['mm', 'hwpunit']	리턴값의 단위("mm" 또는 "hwpunit" 중 지정가능. 기본값은 "mm")	'mm'

Returns:

Type	Description
None | dict[str, int] | bool | dict[str, float]	모든 셀의 안여백을 dict로 리턴. 표 안에 있지 않으면 False를 리턴

get_col_num()

캐럿이 표 안에 있을 때,

현재 셀의 열번호, 즉 셀주소 문자열의 정수 부분을 리턴

Returns:

get_col_width(as_='mm')

현재 캐럿이 위치한 셀(칼럼)의 너비를 리턴하는 메서드.

기본 단위는 mm이지만, as_ 파라미터를 사용하여 단위를 hwpunit이나 point, inch 등으로 변경 가능하다.

Parameters:

Name	Type	Description	Default
as_	Literal['mm', 'hwpunit', 'point', 'inch']	리턴값의 단위(mm, HwpUnit, Pt, Inch 등 4종류)	'mm'

Returns:

Type	Description
int | float	현재 칼럼의 너비(기본단위는 mm)

get_ctrl_pos(ctrl=None, option=0, as_tuple=True)

특정 컨트롤의 앵커(빨간 조판부호) 좌표를 리턴하는 메서드. 한글2024 미만의 버전에서, 컨트롤의 정확한 위치를 파악하기 위함

Parameters:

Name	Type	Description	Default
ctrl	Any	컨트롤 오브젝트. 특정하지 않으면 현재 선택된 컨트롤의 좌표를 리턴	None
option	Literal[0, 1]	"표안의 표"처럼 컨트롤이 중첩된 경우에 어느 좌표를 리턴할지 결정할 수 있음 - 0: 현재 컨트롤이 포함된 리스트 기준으로 좌표 리턴 - 1: 현재 컨트롤을 포함하는 최상위 컨트롤 기준의 좌표 리턴	0
as_tuple	bool	리턴값을 (List, Para, Pos) 형태의 튜플로 리턴할지 여부. 기본값은 True. as_tuple=False 의 경우에는 ListParaPos 파라미터셋 자체를 리턴	True

Returns:

Type	Description
tuple[int, int, int]	기본적으로 (List, Para, Pos) 형태의 튜플로 리턴하며, as_tuple=False 옵션 추가시에는 해당 ListParaPos 파라미터셋 자체를 리턴한다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> # 2x2표의 A1셀 안에 2x2표를 삽입하고, 표안의 표를 선택한 상태에서
>>> # 컨트롤이 포함된 영역의 좌표를 리턴하려면(가장 많이 쓰임)
>>> hwp.get_ctrl_pos()
(3, 0, 0)
>>> # 현재컨트롤을 포함한 최상위컨트롤의 본문기준 좌표를 리턴하려면
>>> hwp.get_ctrl_pos(option=1)
(0, 0, 16)
>>> # 특정 컨트롤의 위치를 저장해 뒀다가 해당 위치로 이동하고 싶은 경우
>>> pos = hwp.get_ctrl_pos(hwp.CurSelectedCtrl)  # 좌표 저장
>>> # 모종의 작업으로 컨트롤 위치가 바뀌더라도, 컨트롤을 찾아갈 수 있음
>>> hwp.set_pos(*pos)  # 해당 컨트롤 앞으로 이동함
True
>>> # 특정 컨트롤 위치 앞으로 이동하기 액션은 아래처럼도 실행 가능
>>> hwp.move_to_ctrl(hwp.ctrl_list[-1])
True

get_cur_field_name(option=0)

현재 캐럿이 위치하는 곳의 필드이름을 구한다. 이 함수를 통해 현재 필드가 셀필드인지 누름틀필드인지 구할 수 있다. 참고로, 필드 좌측에 커서가 붙어있을 때는 이름을 구할 수 있지만, 우측에 붙어 있을 때는 작동하지 않는다. GetFieldList()의 옵션 중에 hwpFieldSelection(=4)옵션은 사용하지 않는다.

Parameters:

Name	Type	Description	Default
option	int	다음과 같은 옵션을 지정할 수 있다. 0: 모두 off. 생략하면 0이 지정된다. 1: 셀에 부여된 필드 리스트만을 구한다. hwpFieldClickHere와는 함께 지정할 수 없다.(hwpFieldCell) 2: 누름틀에 부여된 필드 리스트만을 구한다. hwpFieldCell과는 함께 지정할 수 없다.(hwpFieldClickHere)	0

Returns:

Type	Description
str	필드이름이 돌아온다. 필드이름이 없는 경우 빈 문자열이 돌아온다.

get_cur_metatag_name()

현재 캐럿위치의 메타태그 이름을 리턴하는 메서드.

Returns:

Name	Type	Description
str	str	현재 위치의 메타태그 이름

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> # "#test"라는 메타태그 이름이 부여된 표를 선택한 상태에서
>>> hwp.get_cur_metatag_name()
#test

get_field_info()

문서 내의 모든 누름틀의 정보(지시문 및 메모)를 추출하는 메서드.

셀필드는 지시문과 메모가 없으므로 이 메서드에서는 추출하지 않는다. 만약 셀필드를 포함하여 모든 필드의 이름만 추출하고 싶다면 hwp.get_field_list().split("\r\n") 메서드를 쓰면 된다.

Returns:

Type	Description
list[dict]	[{'name': 'zxcv', 'direction': 'adsf', 'memo': 'qwer'}] 형식의 사전 리스트

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.get_field_info()
[{'name': '누름틀1', 'direction': '안내문1', 'memo': '메모1'},
{'name': '누름틀2', 'direction': '안내문2', 'memo': '메모2'}]

get_field_list(number=1, option=0)

문서에 존재하는 필드의 목록을 구한다.

문서 중에 동일한 이름의 필드가 여러 개 존재할 때는 number에 지정한 타입에 따라 3 가지의 서로 다른 방식 중에서 선택할 수 있다. 예를 들어 문서 중 title, body, title, body, footer 순으로 5개의 필드가 존재할 때, hwpFieldPlain, hwpFieldNumber, HwpFieldCount 세 가지 형식에 따라 다음과 같은 내용이 돌아온다.

- hwpFieldPlain: "titlebodytitlebodyfooter"
- hwpFieldNumber: "title{{0}}body{{0}}title{{1}}body{{1}}footer{{0}}"
- hwpFieldCount: "title{{2}}body{{2}}footer{{1}}"

Parameters:

Name	Type	Description	Default
number	int	문서 내에서 동일한 이름의 필드가 여러 개 존재할 경우 이를 구별하기 위한 식별방법을 지정한다. 생략하면 0(hwpFieldPlain)이 지정된다. - 0: 아무 기호 없이 순서대로 필드의 이름을 나열한다.(hwpFieldPlain) - 1: 필드이름 뒤에 일련번호가 ``{{#}}``과 같은 형식으로 붙는다.(hwpFieldNumber) - 2: 필드이름 뒤에 그 필드의 개수가 ``{{#}}``과 같은 형식으로 붙는다.(hwpFieldCount)	1
option	int	다음과 같은 옵션을 조합할 수 있다. 0을 지정하면 모두 off이다. 생략하면 0이 지정된다. - 0x01: 셀에 부여된 필드 리스트만을 구한다. hwpFieldClickHere과는 함께 지정할 수 없다.(hwpFieldCell) - 0x02: 누름틀에 부여된 필드 리스트만을 구한다. hwpFieldCell과는 함께 지정할 수 없다.(hwpFieldClickHere) - 0x04: 선택된 내용 안에 존재하는 필드 리스트를 구한다.(HwpFieldSelection)	0

Returns:

Type	Description
str	각 필드 사이를 문자코드 0x02로 구분하여 다음과 같은 형식으로 리턴 한다.
str	(가장 마지막 필드에는 0x02가 붙지 않는다.)
str	"필드이름#1\x02필드이름#2\x02...필드이름#n"

get_field_text(field, idx=0)

지정한 필드에서 문자열을 구한다.

Parameters:

Name	Type	Description	Default
field	str | list | tuple | set	텍스트를 구할 필드 이름의 리스트. 다음과 같이 필드 사이를 문자 코드 0x02로 구분하여 한 번에 여러 개의 필드를 지정할 수 있다. "필드이름#1\x02필드이름#2\x02...필드이름#n" 지정한 필드 이름이 문서 중에 두 개 이상 존재할 때의 표현 방식은 다음과 같다. "필드이름": 이름의 필드 중 첫 번째 "필드이름{{n}}": 지정한 이름의 필드 중 n 번째 예를 들어 "제목{{1}}\x02본문\x02이름{{0}}" 과 같이 지정하면 '제목'이라는 이름의 필드 중 두 번째, '본문'이라는 이름의 필드 중 첫 번째, '이름'이라는 이름의 필드 중 첫 번째를 각각 지정한다. 즉, '필드이름'과 '필드이름{{0}}'은 동일한 의미로 해석된다.	required
idx	int	특정 필드가 여러 개이고, 각각의 값이 다를 때, field{{n}} 대신 hwp.get_field_text(field, idx=n)라고 작성할 수 있다.	0

Returns:

Type	Description
str	텍스트 데이터가 돌아온다.
str	텍스트에서 탭은 '\t'(0x9),
str	문단 바뀜은 CR/LF(0x0D/0x0A == \r\n)로 표현되며,
str	이외의 특수 코드는 포함되지 않는다.
str	필드 텍스트의 끝은 0x02(\x02)로 표현되며,
str	그 이후 다음 필드의 텍스트가 연속해서
str	지정한 필드 리스트의 개수만큼 위치한다.
str	지정한 이름의 필드가 없거나,
str	사용자가 해당 필드에 아무 텍스트도 입력하지 않았으면
str	해당 텍스트에는 빈 문자열이 돌아온다.

get_file_info(filename)

파일 정보를 알아낸다.

한글 문서를 열기 전에 암호가 걸린 문서인지 확인할 목적으로 만들어졌다. (현재 한/글2022 기준으로 hwpx포맷에 대해서는 파일정보를 파악할 수 없다.)

Parameters:

Name	Type	Description	Default
filename	str	정보를 구하고자 하는 hwp 파일의 전체 경로	required

Returns:

Type	Description
'Hwp.HParameterSet'	"FileInfo" ParameterSet이 반환된다. 파라미터셋의 ItemID는 아래와 같다. Format(string) : 파일의 형식.(HWP : 한/글 파일, UNKNOWN : 알 수 없음.) VersionStr(string) : 파일의 버전 문자열. ex)5.0.0.3 VersionNum(unsigned int) : 파일의 버전. ex) 0x05000003 Encrypted(int) : 암호 여부. 현재는 파일 버전 3.0.0.0 이후 문서-한/글97, 한/글 워디안 및 한/글 2002 이상의 버전-에 대해서만 판단한다. (-1: 판단할 수 없음, 0: 암호가 걸려 있지 않음, 양수: 암호가 걸려 있음.)

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> pset = hwp.get_file_info("C:/Users/Administrator/Desktop/이력서.hwp")
>>> print(pset.Item("Format"))
>>> print(pset.Item("VersionStr"))
>>> print(hex(pset.Item("VersionNum")))
>>> print(pset.Item("Encrypted"))
HWP
5.1.1.0
0x5010100
0

get_font_list(langid='')

현재 문서에 사용되고 있는 폰트 목록 리턴

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.get_font_list()
['D2Coding,R', 'Pretendard Variable Thin,R', '나눔명조,R', '함초롬바탕,R']

get_heading_string()

현재 커서가 위치한 문단 시작부분의 글머리표/문단번호/개요번호를 추출한다.

글머리표/문단번호/개요번호가 있는 경우, 해당 문자열을 얻어올 수 있다. 문단에 글머리표/문단번호/개요번호가 없는 경우, 빈 문자열이 추출된다.

Returns:

Type	Description
str	(글머리표/문단번호/개요번호가 있다면) 해당 문자열이 반환된다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.get_heading_string()
'1.'

get_image_info(ctrl=None)

이미지 컨트롤의 원본 그림의 이름과 원본 그림의 크기 정보를 추출하는 메서드

Parameters:

Name	Type	Description	Default
ctrl	Any	아래아한글의 이미지 컨트롤. ctrl을 지정하지 않으면 현재 선택된 이미지의 정보를 추출	None

Returns: 해당 이미지의 삽입 전 파일명과, [Width, Height] 리스트

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> # 이미지 선택 상태에서
>>> hwp.get_image_info()
{'name': 'tmpmj2md6uy', 'size': [200, 200]}
>>> # 문서 마지막그림 정보
>>> ctrl = [i for i in hwp.ctrl_list if i.UserDesc == "그림"][-1]
>>> hwp.get_image_info(ctrl)
{'name': 'tmpxk_5noth', 'size': [1920, 1080]}

get_into_nth_table(n=0, select_cell=False)

문서 n번째 표의 첫 번째 셀로 이동하는 함수.

첫 번째 표의 인덱스가 0이며, 음수인덱스 사용 가능. 단, 표들의 인덱스 순서는 표의 위치 순서와 일치하지 않을 수도 있으므로 유의해야 한다.

get_into_table_caption()

표 캡션(정확히는 표번호가 있는 리스트공간)으로 이동하는 메서드.

(추후 개선예정 : 캡션 스타일로 찾아가기 기능 추가할 것)

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴

get_linespacing(method='Percent')

현재 캐럿 위치의 줄간격(%) 리턴.

단, 줄간격 기준은 "글자에 따라(%)" 로 설정되어 있어야 하며, "글자에 따라"가 아닌 경우에는 method 파라미터를 실제 옵션과 일치시켜야 함.

Parameters:

Name	Type	Description	Default
method	Literal['Fixed', 'Percent', 'BetweenLines', 'AtLeast']	줄간격 단위기준. 일치하지 않아도 값은 출력되지만, 단위를 모르게 됨.. - "Fixed": 고정값(포인트 단위) - "Percent": 글자에 따라(기본값, %) - "BetweenLines": 여백만 지정(포인트 단위) - "AtLeast": 최소(포인트 단위)	'Percent'

Returns:

Type	Description
int | float	현재 캐럿이 위치한 문단의 줄간격(% 또는 Point). method에 따라 값이 바뀌므로 주의.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.get_linespacing()
160
>>> # 줄간격을 "최소" 기준 17.0point로 설정했다면, 아래처럼 실행해야 함
>>> hwp.get_linespacing("AtLeast")
170

get_markpen_color()

현재 선택된 영역의 형광펜 색(RGB)을 튜플로 리턴하는 메서드

Returns:

get_message_box_mode()

현재 메시지 박스의 Mode를 int로 얻어온다.

set_message_box_mode와 함께 쓰인다. 6개의 대화상자에서 각각 확인/취소/종료/재시도/무시/예/아니오 버튼을 자동으로 선택할 수 있게 설정할 수 있으며 조합 가능하다. 리턴하는 정수의 의미는 set_message_box_mode를 참고한다.

get_metatag_list(number, option)

메타태그리스트 가져오기

get_metatag_name_text(tag)

메타태그이름 문자열 가져오기

get_mouse_pos(x_rel_to=1, y_rel_to=1)

마우스의 현재 위치를 얻어온다.

단위가 HWPUNIT임을 주의해야 한다. (1 inch = 7200 HWPUNIT, 1mm = 283.465 HWPUNIT)

Parameters:

Name	Type	Description	Default
x_rel_to	int	X좌표계의 기준 위치(기본값은 1:쪽기준) 0: 종이 기준으로 좌표를 가져온다. 1: 쪽 기준으로 좌표를 가져온다.	1
y_rel_to	int	Y좌표계의 기준 위치(기본값은 1:쪽기준) 0: 종이 기준으로 좌표를 가져온다. 1: 쪽 기준으로 좌표를 가져온다.	1

Returns:

Type	Description
'Hwp.HParameterSet'	"MousePos" ParameterSet이 반환된다.
'Hwp.HParameterSet'	아이템ID는 아래와 같다. XRelTo(unsigned long): 가로 상대적 기준(0: 종이, 1: 쪽) YRelTo(unsigned long): 세로 상대적 기준(0: 종이, 1: 쪽) Page(unsigned long): 페이지 번호(0-based) X(long): 가로 클릭한 위치(HWPUNIT) Y(long): 세로 클릭한 위치(HWPUNIT)

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> pset = hwp.get_mouse_pos(1, 1)
>>> print("X축 기준:", "쪽" if pset.Item("XRelTo") else "종이")
>>> print("Y축 기준:", "쪽" if pset.Item("YRelTo") else "종이")
>>> print("현재", pset.Item("Page")+1, "페이지에 커서 위치")
>>> print("좌상단 기준 우측으로", int(pset.Item("X") / 283.465), "mm에 위치")
>>> print("좌상단 기준 아래로", int(pset.Item("Y") / 283.465), "mm에 위치")
X축 기준: 쪽
Y축 기준: 쪽
현재 2 페이지에 커서 위치
좌상단 기준 우측으로 79 mm에 위치
좌상단 기준 아래로 217 mm에 위치

get_page_text(pgno=0, option=4294967295)

페이지 단위의 텍스트 추출 일반 텍스트(글자처럼 취급 도형 포함)를 우선적으로 추출하고, 도형(표, 글상자) 내의 텍스트를 추출한다. 팁: get_text로는 글머리를 추출하지 않지만, get_page_text는 추출한다. 팁2: 아무리 get_page_text라도 유일하게 표번호는 추출하지 못한다. 표번호는 XML태그 속성 안에 저장되기 때문이다.

Parameters:

Name	Type	Description	Default
pgno	int	텍스트를 추출 할 페이지의 번호(0부터 시작)	0
option	hex	추출 대상을 다음과 같은 옵션을 조합하여 지정할 수 있다. 생략(또는 0xffffffff)하면 모든 텍스트를 추출한다. 0x00: 본문 텍스트만 추출한다.(maskNormal) 0x01: 표에대한 텍스트를 추출한다.(maskTable) 0x02: 글상자 텍스트를 추출한다.(maskTextbox) 0x04: 캡션 텍스트를 추출한다. (표, ShapeObject)(maskCaption)	4294967295

Returns:

Type	Description
str	해당 페이지의 텍스트가 추출된다.
str	글머리는 추출하지만, 표번호는 추출하지 못한다.

get_pagedef()

현재 페이지의 용지정보 파라미터셋을 리턴한다.

리턴값은 set_pagedef 메서드를 통해 새로운 문서에 적용할 수 있다. 연관 메서드로, get_pagedef_as_dict는 보다 직관적으로 밀리미터 단위로 변환된 dict를 리턴하므로, get_pagedef_as_dict 메서드를 추천한다.

get_pagedef_as_dict(as_='kor')

현재 페이지의 용지정보를 dict 형태로 리턴한다.

dict의 각 값은 밀리미터 단위로 변환된 값이며, set_pagedef 실행시 내부적으로 HWPUnit으로 자동변환하여 적용한다. (as_ 파라미터를 "eng"로 변경하면 원래 영문 아이템명의 사전을 리턴한다.)

현재 페이지의 용지정보(dict) 각 키의 원래 아이템명은 아래와 같다.

PaperWidth: 용지폭
PaperHeight: 용지길이
Landscape: 용지방향(0: 가로, 1:세로)
GutterType: 제본타입(0: 한쪽, 1:맞쪽, 2:위쪽)
TopMargin: 위쪽
HeaderLen: 머리말
LeftMargin: 왼쪽
GutterLen: 제본여백
RightMargin: 오른쪽
FooterLen: 꼬리말
BottomMargin: 아래쪽

get_pos()

캐럿의 위치를 얻어온다.

파라미터 중 리스트는, 문단과 컨트롤들이 연결된 한/글 문서 내 구조를 뜻한다. 리스트 아이디는 문서 내 위치 정보 중 하나로서 SelectText에 넘겨줄 때 사용한다. (파이썬 자료형인 list가 아님)

Returns:

Type	Description
tuple[int]	(List, Para, Pos) 튜플. List: 캐럿이 위치한 문서 내 list ID(본문이 0) Para: 캐럿이 위치한 문단 ID(0부터 시작) Pos: 캐럿이 위치한 문단 내 글자 위치(0부터 시작)

get_pos_by_set()

현재 캐럿의 위치 정보를 ParameterSet으로 얻어온다.

해당 파라미터셋은 set_pos_by_set에 직접 집어넣을 수 있어 간편히 사용할 수 있다.

Returns:

Type	Description
'Hwp.HParameterSet'	캐럿 위치에 대한 ParameterSet
'Hwp.HParameterSet'	해당 파라미터셋의 아이템은 아래와 같다.
'Hwp.HParameterSet'	"List": 캐럿이 위치한 문서 내 list ID(본문이 0)
'Hwp.HParameterSet'	"Para": 캐럿이 위치한 문단 ID(0부터 시작)
'Hwp.HParameterSet'	"Pos": 캐럿이 위치한 문단 내 글자 위치(0부터 시작)

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> pset = hwp.get_pos_by_set()  # 캐럿위치 저장
>>> print(pset.Item("List"))
6
>>> print(pset.Item("Para"))
3
>>> print(pset.Item("Pos"))
2
>>> hwp.set_pos_by_set(pset)  # 캐럿위치 복원
True

get_row_height(as_='mm')

표 안에서 캐럿이 들어있는 행(row)의 높이를 리턴함.

기본단위는 mm 이지만, HwpUnit이나 Point 등 보다 작은 단위를 사용할 수 있다. (메서드 내부에서는 HwpUnit으로 연산한다.)

Parameters:

Name	Type	Description	Default
as_	Literal['mm', 'hwpunit', 'point', 'inch']	리턴하는 수치의 단위	'mm'

Returns:

Type	Description
float | int	캐럿이 속한 행의 높이

get_row_num()

캐럿이 표 안에 있을 때,

현재 표의 행의 최대갯수를 리턴

Returns: 최대 행갯수:int

get_script_source(filename)

문서에 포함된 매크로(스크립트매크로 제외) 소스코드를 가져온다. 문서포함 매크로는 기본적으로

function OnDocument_New() {
}
function OnDocument_Open() {
}

형태로 비어있는 상태이며, OnDocument_New와 OnDocument_Open 두 개의 함수에 한해서만 코드를 추가하고 실행할 수 있다.

Parameters:

Name	Type	Description	Default
filename	str	매크로 소스를 가져올 한/글 문서의 전체경로	required

Returns:

Type	Description
str	(문서에 포함된) 스크립트의 소스코드

Examples:

>>> from pyhwpx import Hwp
>>>
>>> hwp = Hwp()
>>> print(hwp.get_script_source("C:/Users/User/Desktop/script.hwp"))
function OnDocument_New()
{
    HAction.GetDefault("InsertText", HParameterSet.HInsertText.HSet);
    HParameterSet.HInsertText.Text = "ㅁㄴㅇㄹㅁㄴㅇㄹ";
    HAction.Execute("InsertText", HParameterSet.HInsertText.HSet);
}
function OnDocument_Open()
{
    HAction.GetDefault("InsertText", HParameterSet.HInsertText.HSet);
    HParameterSet.HInsertText.Text = "ㅋㅌㅊㅍㅋㅌㅊㅍ";
    HAction.Execute("InsertText", HParameterSet.HInsertText.HSet);
}

get_selected_pos()

현재 설정된 블록의 위치정보를 얻어온다.

Returns:

Type	Description
tuple[bool, str, str, int, str, str, int]	블록상태여부, 시작과 끝위치 인덱스인 6개 정수 등 7개 요소의 튜플을 리턴(is_block, slist, spara, spos, elist, epara, epos) is_block: 현재 블록선택상태 여부(블록상태이면 True) slist: 설정된 블록의 시작 리스트 아이디. spara: 설정된 블록의 시작 문단 아이디. spos: 설정된 블록의 문단 내 시작 글자 단위 위치. elist: 설정된 블록의 끝 리스트 아이디. epara: 설정된 블록의 끝 문단 아이디. epos: 설정된 블록의 문단 내 끝 글자 단위 위치.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.get_selected_pos()
(True, 0, 0, 16, 0, 7, 16)

get_selected_pos_by_set(sset, eset)

현재 설정된 블록의 위치정보를 얻어온다.

(GetSelectedPos의 ParameterSet버전) 실행 전 GetPos 형태의 파라미터셋 두 개를 미리 만들어서 인자로 넣어줘야 한다.

Parameters:

Name	Type	Description	Default
sset	Any	설정된 블록의 시작 파라메터셋 (ListParaPos)	required
eset	Any	설정된 블록의 끝 파라메터셋 (ListParaPos)	required

Returns:

Type	Description
bool	성공하면 True, 실패하면 False. (실행시 sset과 eset의 아이템 값이 업데이트된다.)

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> # 선택할 블록의 시작 위치에 캐럿을 둔 상태로
>>> sset = hwp.get_pos_by_set()
>>> # 블록 끝이 될 부분으로 이동한 후에
>>> eset = hwp.get_pos_by_set()
>>> hwp.get_selected_pos_by_set(sset, eset)
>>> hwp.set_pos_by_set(eset)
True

get_selected_range()

선택한 범위의 셀주소를 리스트로 리턴함

캐럿이 표 안에 있어야 함

get_selected_text(as_='str')

한/글 문서 선택 구간의 텍스트를 리턴하는 메서드.

Returns: 선택한 문자열

get_style()

현재 캐럿이 위치한 문단의 스타일정보를 사전 형태로 리턴한다.

Returns:

Type	Description
dict	스타일 목록 딕셔너리

get_style_dict(as_='list')

스타일 목록을 사전 데이터로 리턴하는 메서드.

(도움 주신 kosohn님께 아주 큰 감사!!!)

get_table_height(as_='mm')

현재 캐럿이 속한 표의 높이(mm)를 리턴함

Returns: 표의 높이(mm)

get_table_outside_margin(as_='mm')

표의 바깥 여백을 딕셔너리로 한 번에 리턴하는 메서드

Parameters:

Name	Type	Description	Default
as_	Literal['mm', 'hwpunit']	리턴하는 여백값의 단위 - "mm": 밀리미터(기본값) - "hwpunit": HwpUnit	'mm'

Returns:

Type	Description
None | dict[str, int] | bool | dict[str, float]	표의 상하좌우 바깥여백값을 담은 딕셔너리. 표 안에서 실행하지 않은 경우에는 False를 리턴한다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.get_table_outside_margin()
{'left': 4.0, 'right': 3.0, 'top': 2.0, 'bottom': 1.0}

get_table_outside_margin_bottom(as_='mm')

표의 바깥 하단 여백값을 리턴하는 메서드

Parameters:

Name	Type	Description	Default
as_	Literal['mm', 'hwpunit']	리턴하는 여백값의 단위 - "mm": 밀리미터(기본값) - "hwpunit": HwpUnit	'mm'

Returns:

Type	Description
int | float | bool	표의 아랫쪽 바깥여백값. 단위에 따라 int|float을 리턴하며, 표 안에서 실행하지 않은 경우에는 False를 리턴한다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.get_table_outside_margin_bottom()
1.0

get_table_outside_margin_left(as_='mm')

표의 바깥 왼쪽 여백값을 리턴하는 메서드

Parameters:

Name	Type	Description	Default
as_	Literal['mm', 'hwpunit']	리턴하는 여백값의 단위 - "mm": 밀리미터(기본값) - "hwpunit": HwpUnit	'mm'

Returns:

Type	Description
bool	표의 좌측 바깥여백값. 단위에 따라 int|float을 리턴하며, 표 안에서 실행하지 않은 경우에는 False를 리턴한다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.get_table_outside_margin_left()
4.0

get_table_outside_margin_right(as_='mm')

표의 바깥 오른쪽 여백값을 리턴하는 메서드

Parameters:

Name	Type	Description	Default
as_	Literal['mm', 'hwpunit']	리턴하는 여백값의 단위 - "mm": 밀리미터(기본값) - "hwpunit": HwpUnit	'mm'

Returns:

Type	Description
bool	표의 우측 바깥여백값. 단위에 따라 int|float을 리턴하며, 표 안에서 실행하지 않은 경우에는 False를 리턴한다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.get_table_outside_margin_left()
3.0

get_table_outside_margin_top(as_='mm')

표의 바깥 상단 여백값을 리턴하는 메서드

Parameters:

Name	Type	Description	Default
as_	Literal['mm', 'hwpunit']	리턴하는 여백값의 단위 - "mm": 밀리미터(기본값) - "hwpunit": HwpUnit	'mm'

Returns:

Type	Description
bool	표의 위쪽 바깥여백값. 단위에 따라 int|float을 리턴하며, 표 안에서 실행하지 않은 경우에는 False를 리턴한다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.get_table_outside_margin_top()
2.0

get_table_width(as_='mm')

현재 캐럿이 속한 표의 너비(mm)를 리턴함.

이 때 수치의 단위는 as_ 파라미터를 통해 변경 가능하며, "mm", "HwpUnit", "Pt", "Inch" 등을 쓸 수 있다.

Returns:

Type	Description
float	표의 너비(mm)

get_text()

문서 내에서 텍스트를 얻어온다.

줄바꿈 기준으로 텍스트를 얻어오므로 반복실행해야 한다. get_text()의 사용이 끝나면 release_scan()을 반드시 호출하여 관련 정보를 초기화 해주어야 한다. get_text()로 추출한 텍스트가 있는 문단으로 캐럿을 이동 시키려면 move_pos(201)을 실행하면 된다.

Returns:

Type	Description
int	(state: int, text: str) 형태의 튜플을 리턴한다. text는 추출한 텍스트 데이터이다. 텍스트에서 탭은 '\t'(0x9), 문단 바뀜은 '\r\n'(0x0D/0x0A)로 표현되며, 이외의 특수 코드는 포함되지 않는다.
str	state의 의미는 아래와 같다. 0: 텍스트 정보 없음 1: 리스트의 끝 2: 일반 텍스트 3: 다음 문단 4: 제어문자 내부로 들어감 5: 제어문자를 빠져나옴 101: 초기화 안 됨(init_scan() 실패 또는 init_scan()을 실행하지 않은 경우) 102: 텍스트 변환 실패

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.init_scan()
>>> while True:
...     state, text = hwp.get_text()
...     print(state, text)
...     if state <= 1:
...         break
... hwp.release_scan()
2
2
2 ㅁㄴㅇㄹ
3
4 ㅂㅈㄷㄱ
2 ㅂㅈㄷㄱ
5
1

get_text_file(format='UNICODE', option='saveblock:true')

현재 열린 문서 전체 또는 선택한 범위를 문자열로 리턴한다.

이 함수는 JScript나 VBScript와 같이 직접적으로 local disk를 접근하기 힘든 언어를 위해 만들어졌으므로 disk를 접근할 수 있는 언어에서는 사용하지 않기를 권장. disk를 접근할 수 있다면, Save나 SaveBlockAction을 사용할 것. 이 함수 역시 내부적으로는 save나 SaveBlockAction을 호출하도록 되어있고 텍스트로 저장된 파일이 메모리에서 3~4번 복사되기 때문에 느리고, 메모리를 낭비함.

팁1: hwp.Copy(), hwp.Paste() 대신 get_text_file/set_text_file을 사용하기 추천.

팁2: format="HTML"로 추출시 표번호가 유지된다.

Parameters:

Name	Type	Description	Default
format	Literal['HWP', 'HWPML2X', 'HTML', 'UNICODE', 'TEXT']	파일의 형식. 기본값은 "UNICODE". 내부적으로 str.lower() 메서드가 포함되어 있으므로 소문자로 입력해도 된다. - "HWP": HWP native format, BASE64로 인코딩되어 있다. 저장된 내용을 다른 곳에서 보여줄 필요가 없다면 이 포맷을 사용하기를 권장합니다.ver:0x0505010B - "HWPML2X": HWP 형식과 호환. 문서의 모든 정보를 유지 - "HTML": 인터넷 문서 HTML 형식. 한/글 고유의 서식은 손실된다. - "UNICODE": 유니코드 텍스트, 서식정보가 없는 텍스트만 저장. - "TEXT": 일반 텍스트. 유니코드에만 있는 정보(한자, 고어, 특수문자 등)는 모두 손실된다.	'UNICODE'
option	str	option 파라미터에 "saveblock"을 지정하면 선택된 블록만 저장한다. 개체 선택 상태에서는 동작하지 않는다.	'saveblock:true'

Returns:

Type	Description
str	지정된 포맷에 맞춰 파일을 문자열로 변환한 값을 반환한다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.get_text_file()
'ㅁㄴㅇㄹ\r\nㅁㄴㅇㄹ\r\nㅁㄴㅇㄹ\r\n\r\nㅂㅈㄷㄱ\r\nㅂㅈㄷㄱ\r\nㅂㅈㄷㄱ\r\n'

get_title()

한/글 프로그램의 타이틀을 조회한다. 내부적으로 윈도우핸들을 이용한다.

SetTitleName이라는 못난 이름의 API가 있는데, 차마 get_title_name이라고 따라짓지는 못했다ㅜ (파일명을 조회하려면 title 대신 Path나 FullName 등을 조회하면 된다.)

Returns:

Type	Description
str	한/글 창의 상단 타이틀. Path와 달리 빈 문서 상태라도 "빈 문서 1 - 한글" 문자열을 리턴한다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> print(hwp.get_title())
빈 문서 1 - 한글

goto_addr(addr='A1', col=0, select_cell=False)

셀 주소를 문자열로 입력받아 해당 주소로 이동하는 메서드. 셀 주소는 "C3"처럼 문자열로 입력하거나, 행번호, 열번호를 입력할 수 있음. 시작값은 1.

Parameters:

Name	Type	Description	Default
addr	str | int	셀 주소 문자열("A1") 또는 행번호(1부터).	'A1'
col	int	셀 주소를 정수로 입력하는 경우 열번호(1부터)	0
select_cell	bool	이동 후 셀블록 선택 여부	False

Returns:

Type	Description
bool	이동 성공 여부(성공시 True/실패시 False)

goto_page(page_index=1)

새쪽번호와 관계없이 페이지 순서를 통해

특정 페이지를 찾아가는 메서드. 1이 1페이지임.

Parameters:

Name	Type	Description	Default
page_index	int | str	찾아갈 페이지(시작페이지는 1)	1

Returns:

Type	Description
tuple[int, int]	tuple(인쇄기준페이지, 페이지인덱스)

goto_printpage(page_num=1)

인쇄페이지 기준으로 해당 페이지로 이동

1페이지의 page_num은 1이다.

Parameters:

Name	Type	Description	Default
page_num	int	이동할 페이지번호	1

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴

goto_style(style)

특정 스타일이 적용된 위치로 이동하는 메서드.

탐색은 문서아랫방향으로만 수행하며 현재위치 이후 해당 스타일이 없거나, 스타일이름/인덱스번호가 잘못된 경우 False를 리턴 참고로, API의 Goto는 1부터 시작하므로 메서드 내부에서 인덱스에 1을 더하고 있음

Parameters:

Name	Type	Description	Default
style	Union[int, str]	스타일이름(str) 또는 스타일번호(첫 번째 스타일이 0)	required

Returns:

Type	Description
bool	성공시 True, 실패시 False

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.goto_style(0)  # 캐럿 뒤의 "바탕글" 스타일로 이동
True
>>> hwp.goto_style("개요 1")  # 캐럿 뒤의 "개요 1" 스타일로 이동
True

gradation_on_cell(color_list=[(0, 0, 0), (255, 255, 255)], grad_type='Linear', angle=0, xc=0, yc=0, pos_list=None, step_center=50, step=255)

셀에 그라데이션을 적용하는 메서드

Parameters:

Name	Type	Description	Default
color_list	list[tuple[int, int, int]] | list[str, str]	시작RGB 튜플과 종료RGB 튜플의 리스트	[(0, 0, 0), (255, 255, 255)]
grad_type	Literal['Linear', 'Radial', 'Conical', 'Square']	그라데이션 형태(선형, 방사형, 콘형, 사각형)	'Linear'
angle	int	그라데이션 각도	0
xc	int	x 중심점	0
yc	int	y 중심점	0
pos_list	list[int]	변곡점 목록	None
step_center	int	그라데이션 단계의 중심점	50
step	int	그라데이션 단계 수	255

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> for i in range(0, 256, 2):
...     hwp.gradation_on_cell(
...         color_list=[(255,i,i), (i,255,i)],
...         grad_type="Square",
...         xc=40, yc=60,
...         pos_list=[20,80],
...         step_center=int(i/255*100),
...         step=i,
...     )
...

hwp_unit_to_inch(HwpUnit) staticmethod

HwpUnit을 인치로 변환

hwp_unit_to_point(HwpUnit) staticmethod

HwpUnit을 포인트 단위로 변환

import_mathml(mml_path, delay=0.2)

MathML 포맷의 수식문서 파일경로를 입력하면

아래아한글 수식으로 삽입하는 함수

import_style(sty_filepath)

미리 저장된 특정 sty파일의 스타일을 임포트한다.

Parameters:

Name	Type	Description	Default
sty_filepath	str	sty파일의 경로	required

Returns:

Type	Description
bool	성공시 True, 실패시 False

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.import_style("C:/Users/User/Desktop/new_style.sty")
True

inch_to_hwp_unit(inch) staticmethod

인치 단위를 HwpUnit으로 변환

init_scan(option=7, range=119, spara=0, spos=0, epara=-1, epos=-1)

문서의 내용을 검색하기 위해 초기설정을 한다.

문서의 검색 과정은 InitScan()으로 검색위한 준비 작업을 하고 GetText()를 호출하여 본문의 텍스트를 얻어온다. GetText()를 반복호출하면 연속하여 본문의 텍스트를 얻어올 수 있다. 검색이 끝나면 ReleaseScan()을 호출하여 관련 정보를 Release해야 한다.

Parameters:

Name	Type	Description	Default
option	int	기본값은 0x7(모든 컨트롤 대상) 찾을 대상을 다음과 같은 옵션을 조합하여 지정할 수 있다. 생략하면 모든 컨트롤을 찾을 대상으로 한다. - 0x00: 본문을 대상으로 검색한다.(서브리스트를 검색하지 않는다.) - maskNormal - 0x01: char 타입 컨트롤 마스크를 대상으로 한다.(강제줄나눔, 문단 끝, 하이픈, 묶움빈칸, 고정폭빈칸, 등...) - maskChar - 0x02: inline 타입 컨트롤 마스크를 대상으로 한다.(누름틀 필드 끝, 등...) - maskInline - 0x04: extende 타입 컨트롤 마스크를 대상으로 한다.(바탕쪽, 프레젠테이션, 다단, 누름틀 필드 시작, Shape Object, 머리말, 꼬리말, 각주, 미주, 번호관련 컨트롤, 새 번호 관련 컨트롤, 감추기, 찾아보기, 글자 겹침, 등...) - maskCtrl	7
range	int	검색의 범위를 다음과 같은 옵션을 조합(sum)하여 지정할 수 있다. 생략하면 "문서 시작부터 - 문서의 끝까지" 검색 범위가 지정된다. - 0x0000: 캐럿 위치부터. (시작 위치) - scanSposCurrent - 0x0010: 특정 위치부터. (시작 위치) - scanSposSpecified - 0x0020: 줄의 시작부터. (시작 위치) - scanSposLine - 0x0030: 문단의 시작부터. (시작 위치) - scanSposParagraph - 0x0040: 구역의 시작부터. (시작 위치) - scanSposSection - 0x0050: 리스트의 시작부터. (시작 위치) - scanSposList - 0x0060: 컨트롤의 시작부터. (시작 위치) - scanSposControl - 0x0070: 문서의 시작부터. (시작 위치) - scanSposDocument - 0x0000: 캐럿 위치까지. (끝 위치) - scanEposCurrent - 0x0001: 특정 위치까지. (끝 위치) - scanEposSpecified - 0x0002: 줄의 끝까지. (끝 위치) - scanEposLine - 0x0003: 문단의 끝까지. (끝 위치) - scanEposParagraph - 0x0004: 구역의 끝까지. (끝 위치) - scanEposSection - 0x0005: 리스트의 끝까지. (끝 위치) - scanEposList - 0x0006: 컨트롤의 끝까지. (끝 위치) - scanEposControl - 0x0007: 문서의 끝까지. (끝 위치) - scanEposDocument - 0x00ff: 검색의 범위를 블록으로 제한. - scanWithinSelection - 0x0000: 정뱡향. (검색 방향) - scanForward - 0x0100: 역방향. (검색 방향) - scanBackward	119
spara	int	검색 시작 위치의 문단 번호. scanSposSpecified 옵션이 지정되었을 때만 유효하다. (예: range=0x0011)	0
spos	int	검색 시작 위치의 문단 중에서 문자의 위치. scanSposSpecified 옵션이 지정되었을 때만 유효하다. (예: range=0x0011)	0
epara	int	검색 끝 위치의 문단 번호. scanEposSpecified 옵션이 지정되었을 때만 유효하다.	-1
epos	int	검색 끝 위치의 문단 중에서 문자의 위치. scanEposSpecified 옵션이 지정되었을 때만 유효하다.	-1

Returns:

Type	Description
bool	성공하면 True, 실패하면 False

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.init_scan(range=0xff)
>>> _, text = hwp.get_text()
>>> hwp.release_scan()
>>> print(text)
Hello, world!

insert(path, format='', arg='', move_doc_end=False)

현재 캐럿 위치에 문서파일을 삽입한다.

format, arg 파라미터에 대한 자세한 설명은 open 참조

Parameters:

Name	Type	Description	Default
path	str	문서파일의 경로	required
format	str	문서형식. 빈 문자열을 지정하면 자동으로 선택한다. 생략하면 빈 문자열이 지정된다. 아래에 쓰여 있는 대로 대문자로만 써야 한다. - "HWPX": 한/글 hwpx format - "HWP": 한/글 native format - "HWP30": 한/글 3.X/96/97 - "HTML": 인터넷 문서 - "TEXT": 아스키 텍스트 문서 - "UNICODE": 유니코드 텍스트 문서 - "HWP20": 한글 2.0 - "HWP21": 한글 2.1/2.5 - "HWP15": 한글 1.X - "HWPML1X": HWPML 1.X 문서 (Open만 가능) - "HWPML2X": HWPML 2.X 문서 (Open / SaveAs 가능) - "RTF": 서식 있는 텍스트 문서 - "DBF": DBASE II/III 문서 - "HUNMIN": 훈민정음 3.0/2000 - "MSWORD": 마이크로소프트 워드 문서 - "DOCRTF": MS 워드 문서 (doc) - "OOXML": MS 워드 문서 (docx) - "HANA": 하나워드 문서 - "ARIRANG": 아리랑 문서 - "ICHITARO": 一太郞 문서 (일본 워드프로세서) - "WPS": WPS 문서 - "DOCIMG": 인터넷 프레젠테이션 문서(SaveAs만 가능) - "SWF": Macromedia Flash 문서(SaveAs만 가능)	''
arg	str	세부옵션. 의미는 format에 지정한 파일형식에 따라 다르다. 조합 가능하며, 생략하면 빈 문자열이 지정된다. 공통 - "setcurdir:FALSE;" :로드한 후 해당 파일이 존재하는 폴더로 현재 위치를 변경한다. hyperlink 정보가 상대적인 위치로 되어 있을 때 유용하다. HWP/HWPX - "lock:TRUE;": 로드한 후 해당 파일을 계속 오픈한 상태로 lock을 걸지 여부 - "notext:FALSE;": 텍스트 내용을 읽지 않고 헤더 정보만 읽을지 여부. (스타일 로드 등에 사용) - "template:FALSE;": 새로운 문서를 생성하기 위해 템플릿 파일을 오픈한다. 이 옵션이 주어지면 lock은 무조건 FALSE로 처리된다. - "suspendpassword:FALSE;": TRUE로 지정하면 암호가 있는 파일일 경우 암호를 묻지 않고 무조건 읽기에 실패한 것으로 처리한다. - "forceopen:FALSE;": TRUE로 지정하면 읽기 전용으로 읽어야 하는 경우 대화상자를 띄우지 않는다. - "versionwarning:FALSE;": TRUE로 지정하면 문서가 상위버전일 경우 메시지 박스를 띄우게 된다. HTML - "code"(string, codepage): 문서변환 시 사용되는 코드 페이지를 지정할 수 있으며 code키가 존재할 경우 필터사용 시 사용자 다이얼로그를 띄우지 않는다. - (코드페이지 종류는 아래와 같다.) - ("utf8" : UTF8) - ("unicode": 유니코드) - ("ks": 한글 KS 완성형) - ("acp" : Active Codepage 현재 시스템의 코드 페이지) - ("kssm": 한글 조합형) - ("sjis" : 일본) - ("gb" : 중국 간체) - ("big5" : 중국 번체) - "textunit:(string, pixel);": Export될 Text의 크기의 단위 결정.pixel, point, mili 지정 가능. - "formatunit:(string, pixel);": Export될 문서 포맷 관련 (마진, Object 크기 등) 단위 결정. pixel, point, mili 지정 가능 DOCIMG - "asimg:FALSE;": 저장할 때 페이지를 image로 저장 - "ashtml:FALSE;": 저장할 때 페이지를 html로 저장 TEXT - "code:(string, codepage);": 문서 변환 시 사용되는 코드 페이지를 지정할 수 있으며 - code키가 존재할 경우 필터 사용 시 사용자 다이얼로그를 띄우지 않는다.	''

Returns:

Type	Description
bool	성공하면 True, 실패하면 False

insert_background_picture(path, border_type='SelectedCell', embedded=True, filloption=5, effect=0, watermark=False, brightness=0, contrast=0)

셀에 배경이미지를 삽입한다.

CellBorderFill의 SetItem 중 FillAttr 의 SetItem FileName 에 이미지의 binary data를 지정해 줄 수가 없어서 만든 함수다. 기타 배경에 대한 다른 조정은 Action과 ParameterSet의 조합으로 가능하다.

Parameters:

Name	Type	Description	Default
path	str	삽입할 이미지 파일	required
border_type	Literal['SelectedCell', 'SelectedCellDelete']	배경 유형을 문자열로 지정(파라미터 이름과는 다르게 삽입/제거 기능이다.) - "SelectedCell": 현재 선택된 표의 셀의 배경을 변경한다. - "SelectedCellDelete": 현재 선택된 표의 셀의 배경을 지운다. 단, 배경 제거시 반드시 셀이 선택되어 있어야함. 커서가 위치하는 것만으로는 동작하지 않음.	'SelectedCell'
embedded	bool	이미지 파일을 문서 내에 포함할지 여부 (True/False). 생략하면 True	True
filloption	int	삽입할 그림의 크기를 지정하는 옵션 - 0: 바둑판식으로 - 모두 - 1: 바둑판식으로 - 가로/위 - 2: 바둑판식으로 - 가로/아로 - 3: 바둑판식으로 - 세로/왼쪽 - 4: 바둑판식으로 - 세로/오른쪽 - 5: 크기에 맞추어(기본값) - 6: 가운데로 - 7: 가운데 위로 - 8: 가운데 아래로 - 9: 왼쪽 가운데로 - 10: 왼쪽 위로 - 11: 왼쪽 아래로 - 12: 오른쪽 가운데로 - 13: 오른쪽 위로 - 14: 오른쪽 아래로	5
effect	int	이미지효과 - 0: 원래 그림(기본값) - 1: 그레이 스케일 - 2: 흑백으로	0
watermark	bool	watermark효과 유무(True/False). 기본값은 False. 이 옵션이 True이면 brightness 와 contrast 옵션이 무시된다.	False
brightness	int	밝기 지정(-100 ~ 100), 기본 값은 0	0
contrast	int	선명도 지정(-100 ~ 100), 기본 값은 0	0

Returns:

Type	Description
bool	성공했을 경우 True, 실패했을 경우 False

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.insert_background_picture(path="C:/Users/User/Desktop/KakaoTalk_20230709_023118549.jpg")
True

insert_ctrl(ctrl_id, initparam)

현재 캐럿 위치에 컨트롤을 삽입한다.

ctrlid에 지정할 수 있는 컨트롤 ID는 HwpCtrl.CtrlID가 반환하는 ID와 동일하다. 자세한 것은 Ctrl 오브젝트 Properties인 CtrlID를 참조. initparam에는 컨트롤의 초기 속성을 지정한다. 대부분의 컨트롤은 Ctrl.Properties와 동일한 포맷의 parameter set을 사용하지만, 컨트롤 생성 시에는 다른 포맷을 사용하는 경우도 있다. 예를 들어 표의 경우 Ctrl.Properties에는 "Table" 셋을 사용하지만, 생성 시 initparam에 지정하는 값은 "TableCreation" 셋이다.

Parameters:

Name	Type	Description	Default
ctrl_id	str	삽입할 컨트롤 ID	required
initparam	Any	컨트롤 초기속성. 생략하면 default 속성으로 생성한다.	required

Returns:

Type	Description
Ctrl	생성된 컨트롤 object

Examples:

>>> # 3행5열의 표를 삽입한다.
>>> from pyhwpx import Hwp
>>> from time import sleep
>>> hwp = Hwp()
>>> tbset = hwp.create_set("TableCreation")
>>> tbset.SetItem("Rows", 3)
>>> tbset.SetItem("Cols", 5)
>>> row_set = tbset.CreateItemArray("RowHeight", 3)
>>> col_set = tbset.CreateItemArray("ColWidth", 5)
>>> row_set.SetItem(0, hwp.mili_to_hwp_unit(10))
>>> row_set.SetItem(1, hwp.mili_to_hwp_unit(10))
>>> row_set.SetItem(2, hwp.mili_to_hwp_unit(10))
>>> col_set.SetItem(0, hwp.mili_to_hwp_unit(26))
>>> col_set.SetItem(1, hwp.mili_to_hwp_unit(26))
>>> col_set.SetItem(2, hwp.mili_to_hwp_unit(26))
>>> col_set.SetItem(3, hwp.mili_to_hwp_unit(26))
>>> col_set.SetItem(4, hwp.mili_to_hwp_unit(26))
>>> table = hwp.insert_ctrl("tbl", tbset)  # <---
>>> sleep(3)  # 표 생성 3초 후 다시 표 삭제
>>> hwp.delete_ctrl(table)

insert_lorem(para_num=1)

Lorem Ipsum을 캐럿 위치에 작성한다.

Parameters:

Name	Type	Description	Default
para_num	int	삽입할 Lorem Ipsum 문단 갯수	1

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.insert_lorem(3)
True

insert_memo(text='', memo_type='memo')

선택한 단어 범위에 메모고침표를 삽입하는 코드.

한/글에서 일반 문자열을 삽입하는 코드와 크게 다르지 않다. 선택모드가 아닌 경우 캐럿이 위치한 단어에 메모고침표를 삽입한다.

Parameters:

Name	Type	Description	Default
text	str	삽입할 메모 내용	''

Returns:

Type	Description
None	None

insert_picture(path, treat_as_char=True, embedded=True, sizeoption=0, reverse=False, watermark=False, effect=0, width=0, height=0)

현재 캐럿의 위치에 그림을 삽입한다.

다만, 그림의 종횡비를 유지한 채로 셀의 높이만 키워주는 옵션이 없다. 이런 작업을 원하는 경우에는 그림을 클립보드로 복사하고, Ctrl-V로 붙여넣기를 하는 수 밖에 없다. 또한, 셀의 크기를 조절할 때 이미지의 크기도 따라 변경되게 하고 싶다면 insert_background_picture 함수를 사용하는 것도 좋다.

Parameters:

Name	Type	Description	Default
path	str	삽입할 이미지 파일의 전체경로	required
embedded	bool	이미지 파일을 문서 내에 포함할지 여부 (True/False). 생략하면 True	True
sizeoption	int	삽입할 그림의 크기를 지정하는 옵션. 기본값은 2 - 0: 이미지 원래의 크기로 삽입한다. width와 height를 지정할 필요 없다.(realSize) - 1: width와 height에 지정한 크기로 그림을 삽입한다.(specificSize) - 2: 현재 캐럿이 표의 셀 안에 있을 경우, 셀의 크기에 맞게 자동 조절하여 삽입한다. (종횡비 유지안함)(cellSize) 캐럿이 셀 안에 있지 않으면 이미지의 원래 크기대로 삽입된다. - 3: 현재 캐럿이 표의 셀 안에 있을 경우, 셀의 크기에 맞추어 원본 이미지의 가로 세로의 비율이 동일하게 확대/축소하여 삽입한다.(cellSizeWithSameRatio)	0
reverse	bool	이미지의 반전 유무 (True/False). 기본값은 False	False
watermark	bool	watermark효과 유무 (True/False). 기본값은 False	False
effect	int	그림 효과 - 0: 실제 이미지 그대로 - 1: 그레이 스케일 - 2: 흑백효과	0
width	int	그림의 가로 크기 지정. 단위는 mm(HWPUNIT 아님!)	0
height	int	그림의 높이 크기 지정. 단위는 mm	0

Returns:

Type	Description
Ctrl	생성된 컨트롤 object.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> path = "C:/Users/Administrator/Desktop/KakaoTalk_20230709_023118549.jpg"
>>> ctrl = hwp.insert_picture(path)  # 삽입한 이미지 객체를 리턴함.
>>> pset = ctrl.Properties  # == hwp.create_set("ShapeObject")
>>> pset.SetItem("TreatAsChar", False)  # 글자처럼취급 해제
>>> pset.SetItem("TextWrap", 2)  # 그림을 글 뒤로
>>> ctrl.Properties = pset  # 설정한 값 적용(간단!)

insert_random_picture(x=200, y=200)

랜덤 이미지를 삽입한다.

내부적으로 https://picsum.photos/ API를 사용한다.

Parameters:

Name	Type	Description	Default
x	int	너비 해상도	200
y	int	높이 해상도	200

Returns:

Type	Description
Ctrl	삽입한 이미지 컨트롤

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.insert_random_picture(640, 480)
<CtrlCode: CtrlID=gso, CtrlCH=11, UserDesc=그림>

insert_text(text)

한/글 문서 내 캐럿 위치에 문자열을 삽입하는 메서드.

Returns: 삽입 성공시 True, 실패시 False를 리턴함. Examples: >>> from pyhwpx import Hwp >>> hwp = Hwp() >>> hwp.insert_text('Hello world!') >>> hwp.BreakPara()

is_action_enable(action_id)

액션 실행 가능한지 여부를 bool로 리턴

액션 관련해서는 기존 버전체크보다 이걸 사용하는 게 훨씬 안정적일 것 같기는 하지만(예: CopyPage, PastePage, DeletePage 및 메타태그액션 등) 신규 메서드(SelectCtrl 등) 지원여부는 체크해주지 못한다ㅜ

is_cell()

캐럿이 현재 표 안에 있는지 알려주는 메서드

Returns: 표 안에 있으면 True, 그렇지 않으면 False를 리턴

is_command_lock(action_id)

해당 액션이 잠겨있는지 확인한다.

Parameters:

Name	Type	Description	Default
action_id	str	액션 ID. (ActionIDTable.Hwp 참조)	required

Returns:

Type	Description
bool	잠겨있으면 True, 잠겨있지 않으면 False를 반환한다.

is_empty_para()

본문의 문단을 순회하면서 특정 서식을 적용할 때 빈 문단에서 MoveNext~ 또는 MovePrev~ 등의 액션이 오작동하므로 이를 방지하기 위한 개발자용 헬퍼메서드. 단독으로는 활용하지 말 것.

Returns: 빈 문단일 경우 제자리에서 True, 비어있지 않은 경우 False를 리턴

key_indicator()

상태 바의 정보를 얻어온다.

Returns:

Type	Description
tuple	튜플(succ, seccnt, secno, prnpageno, colno, line, pos, over, ctrlname) succ: 성공하면 True, 실패하면 False (항상 True임..) seccnt: 총 구역 secno: 현재 구역 prnpageno: 쪽 colno: 단 line: 줄 pos: 칸 over: 삽입모드 (True: 수정, False: 삽입) ctrlname: 캐럿이 위치한 곳의 컨트롤이름

Examples:

>>> # 현재 셀 주소(표 안에 있을 때)
>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.key_indicator()[-1][1:].split(")")[0]
"A1"

lock_command(act_id, is_lock)

특정 액션이 실행되지 않도록 잠근다.

Parameters:

Name	Type	Description	Default
act_id	str	액션 ID. (ActionIDTable.Hwp 참조)	required
is_lock	bool	True이면 액션의 실행을 잠그고, False이면 액션이 실행되도록 한다.	required

Returns:

Type	Description
None	None

Examples:

>>> # Undo와 Redo 잠그기
>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.lock_command("Undo", True)
>>> hwp.lock_command("Redo", True)

maximize_window()

현재 창 최대화

minimize_window()

현재 창 최소화

move_all_caption(location='Bottom', align='Justify')

한/글 문서 내 모든 표, 그림의 주석 위치를 일괄 변경하는 메서드.

move_pos(move_id=1, para=0, pos=0)

캐럿의 위치를 옮긴다.

move_id를 200(moveScrPos)으로 지정한 경우에는 스크린 좌표로 마우스 커서의 (x,y)좌표를 그대로 넘겨주면 된다. 201(moveScanPos)는 문서를 검색하는 중 캐럿을 이동시키려 할 경우에만 사용이 가능하다. (솔직히 200 사용법은 잘 모르겠다;)

Parameters:

Name	Type	Description	Default
move_id	int	아래와 같은 값을 지정할 수 있다. 생략하면 1(moveCurList)이 지정된다. - 0: 루트 리스트의 특정 위치.(para pos로 위치 지정) moveMain - 1: 현재 리스트의 특정 위치.(para pos로 위치 지정) moveCurList - 2: 문서의 시작으로 이동. moveTopOfFile - 3: 문서의 끝으로 이동. moveBottomOfFile - 4: 현재 리스트의 시작으로 이동 moveTopOfList - 5: 현재 리스트의 끝으로 이동 moveBottomOfList - 6: 현재 위치한 문단의 시작으로 이동 moveStartOfPara - 7: 현재 위치한 문단의 끝으로 이동 moveEndOfPara - 8: 현재 위치한 단어의 시작으로 이동.(현재 리스트만을 대상으로 동작한다.) moveStartOfWord - 9: 현재 위치한 단어의 끝으로 이동.(현재 리스트만을 대상으로 동작한다.) moveEndOfWord - 10: 다음 문단의 시작으로 이동.(현재 리스트만을 대상으로 동작한다.) moveNextPara - 11: 앞 문단의 끝으로 이동.(현재 리스트만을 대상으로 동작한다.) movePrevPara - 12: 한 글자 뒤로 이동.(서브 리스트를 옮겨 다닐 수 있다.) moveNextPos - 13: 한 글자 앞으로 이동.(서브 리스트를 옮겨 다닐 수 있다.) movePrevPos - 14: 한 글자 뒤로 이동.(서브 리스트를 옮겨 다닐 수 있다. 머리말/꼬리말, 각주/미주, 글상자 포함.) moveNextPosEx - 15: 한 글자 앞으로 이동.(서브 리스트를 옮겨 다닐 수 있다. 머리말/꼬리말, 각주/미주, 글상자 포함.) movePrevPosEx - 16: 한 글자 뒤로 이동.(현재 리스트만을 대상으로 동작한다.) moveNextChar - 17: 한 글자 앞으로 이동.(현재 리스트만을 대상으로 동작한다.) movePrevChar - 18: 한 단어 뒤로 이동.(현재 리스트만을 대상으로 동작한다.) moveNextWord - 19: 한 단어 앞으로 이동.(현재 리스트만을 대상으로 동작한다.) movePrevWord - 20: 한 줄 아래로 이동. moveNextLine - 21: 한 줄 위로 이동. movePrevLine - 22: 현재 위치한 줄의 시작으로 이동. moveStartOfLine - 23: 현재 위치한 줄의 끝으로 이동. moveEndOfLine - 24: 한 레벨 상위로 이동한다. moveParentList - 25: 탑레벨 리스트로 이동한다. moveTopLevelList - 26: 루트 리스트로 이동한다. 현재 루트 리스트에 위치해 있어 더 이상 상위 리스트가 없을 때는 위치 이동 없이 반환한다. 이동한 후의 위치는 상위 리스트에서 서브리스트가 속한 컨트롤 코드가 위치한 곳이다. 위치 이동시 셀렉션은 무조건 풀린다. moveRootList - 27: 현재 캐럿이 위치한 곳으로 이동한다. (캐럿 위치가 뷰의 맨 위쪽으로 올라간다.) moveCurrentCaret - 100: 현재 캐럿이 위치한 셀의 왼쪽 moveLeftOfCell - 101: 현재 캐럿이 위치한 셀의 오른쪽 moveRightOfCell - 102: 현재 캐럿이 위치한 셀의 위쪽 moveUpOfCell - 103: 현재 캐럿이 위치한 셀의 아래쪽 moveDownOfCell - 104: 현재 캐럿이 위치한 셀에서 행(row)의 시작 moveStartOfCell - 105: 현재 캐럿이 위치한 셀에서 행(row)의 끝 moveEndOfCell - 106: 현재 캐럿이 위치한 셀에서 열(column)의 시작 moveTopOfCell - 107: 현재 캐럿이 위치한 셀에서 열(column)의 끝 moveBottomOfCell - 200: 한/글 문서창에서의 screen 좌표로서 위치를 설정 한다. moveScrPos - 201: GetText() 실행 후 위치로 이동한다. moveScanPos	1
para	int	이동할 문단의 번호. 0(moveMain) 또는 1(moveCurList)가 지정되었을 때만 사용된다. 200(moveScrPos)가 지정되었을 때는 문단번호가 아닌 스크린 좌표로 해석된다. (스크린 좌표 : LOWORD = x좌표, HIWORD = y좌표)	0
pos	int	이동할 문단 중에서 문자의 위치. 0(moveMain) 또는 1(moveCurList)가 지정되었을 때만 사용된다.	0

Returns:

Type	Description
bool	성공하면 True, 실패하면 False

move_to_ctrl(ctrl, option=0)

메서드에 넣은 ctrl의 조판부호 앞으로 이동하는 메서드.

Parameters:

Name	Type	Description	Default
ctrl	Any	이동하고자 하는 컨트롤	required

Returns:

Type	Description
bool	성공시 True, 실패시 False 리턴

move_to_field(field, idx=0, text=True, start=True, select=False)

지정한 필드로 캐럿을 이동한다.

Parameters:

Name	Type	Description	Default
field	str	필드이름. GetFieldText()/PutFieldText()와 같은 형식으로 이름 뒤에 ‘{{#}}’로 번호를 지정할 수 있다.	required
idx	int	동일명으로 여러 개의 필드가 존재하는 경우, idx번째 필드로 이동하고자 할 때 사용한다. 기본값은 0. idx를 지정하지 않아도, 필드 파라미터 뒤에 ‘{{#}}’를 추가하여 인덱스를 지정할 수 있다. 이 경우 기본적으로 f스트링을 사용하며, f스트링 내부에 탈출문자열 \가 적용되지 않으므로 중괄호를 다섯 겹 입력해야 한다. 예 : hwp.move_to_field(f"필드명{{{{{i}}}}}")	0
text	bool	필드가 누름틀일 경우 누름틀 내부의 텍스트로 이동할지(True) 누름틀 코드로 이동할지(False)를 지정한다. 누름틀이 아닌 필드일 경우 무시된다. 생략하면 True가 지정된다.	True
start	bool	필드의 처음(True)으로 이동할지 끝(False)으로 이동할지 지정한다. select를 True로 지정하면 무시된다. (캐럿이 처음에 위치해 있게 된다.) 생략하면 True가 지정된다.	True
select	bool	필드 내용을 블록으로 선택할지(True), 캐럿만 이동할지(False) 지정한다. 생략하면 False가 지정된다.	False

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴한다.

move_to_metatag(tag, text, start, select)

특정 메타태그로 이동

new_number(new_number, num_type='Page')

새 번호를 매길 수 있는 메서드.

(쪽번호 외에도 그림, 각주, 표, 미주, 수식 등) 다만, 주의할 점이 세 가지 있다. 1. 기존에 쪽번호가 없는 문서에서는 작동하지 않으므로 쪽번호가 정의되어 있어야 한다. (쪽번호 정의는 PageNumPos 메서드 참조) 2. 새 번호를 지정한 페이지 및 이후 모든 페이지가 영향을 받는다. 3. NewNumber 실행시점의 캐럿위치 뒤쪽(해당 페이지 내)에 NewNumber 조판이 있는 경우, 삽입한 조판은 무효가 된다. (페이지 맨 뒤쪽의 새 번호만 유효함)

Parameters:

Name	Type	Description	Default
new_number	int	새 번호	required
num_type	Literal['Page', 'Figure', 'Footnote', 'Table', 'Endnote', 'Equation']	타입 지정 "Page": 쪽(기본값) "Figure": 그림 "Footnote": 각주 "Table": 표 "Endnote": 미주 "Equation": 수식	'Page'

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴

Examples:

>>> # 쪽번호가 있는 문서에서
>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.NewNumber(5)  # 현재 페이지번호가 5로 바뀜

new_number_modify(new_number, num_type='Page')

새 번호 조판을 수정할 수 있는 메서드.

실행 전 [새 번호] 조판 옆에 캐럿이 위치해 있어야 하며, 그렇지 않을 경우 (쪽번호 외에도 그림, 각주, 표, 미주, 수식 등) 다만, 주의할 점이 세 가지 있다.

1. 기존에 쪽번호가 없는 문서에서는 작동하지 않으므로 쪽번호가 정의되어 있어야 한다. (쪽번호 정의는 `PageNumPos` 메서드 참조)
2. 새 번호를 지정한 페이지 및 이후 모든 페이지가 영향을 받는다.
3. `NewNumber` 실행시점의 캐럿위치 뒤쪽(해당 페이지 내)에 `NewNumber` 조판이 있는 경우, 삽입한 조판은 무효가 된다. (페이지 맨 뒤쪽의 새 번호만 유효함)

Parameters:

Name	Type	Description	Default
new_number	int	새 번호	required
num_type	Literal['Page', 'Figure', 'Footnote', 'Table', 'Endnote', 'Equation']	타입 지정 - "Page": 쪽(기본값) - "Figure": 그림 - "Footnote": 각주 - "Table": 표 - "Endnote": 미주 - "Equation": 수식	'Page'

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴

open(filename, format='', arg='')

문서를 연다.

Parameters:

Name	Type	Description	Default
filename	str	문서 파일의 전체경로	required
format	str	문서 형식. 빈 문자열을 지정하면 자동으로 인식한다. 생략하면 빈 문자열이 지정된다. - "HWP": 한/글 native format - "HWP30": 한/글 3.X/96/97 - "HTML": 인터넷 문서 - "TEXT": 아스키 텍스트 문서 - "UNICODE": 유니코드 텍스트 문서 - "HWP20": 한글 2.0 - "HWP21": 한글 2.1/2.5 - "HWP15": 한글 1.X - "HWPML1X": HWPML 1.X 문서 (Open만 가능) - "HWPML2X": HWPML 2.X 문서 (Open / SaveAs 가능) - "RTF": 서식 있는 텍스트 문서 - "DBF": DBASE II/III 문서 - "HUNMIN": 훈민정음 3.0/2000 - "MSWORD": 마이크로소프트 워드 문서 - "DOCRTF": MS 워드 문서 (doc) - "OOXML": MS 워드 문서 (docx) - "HANA": 하나워드 문서 - "ARIRANG": 아리랑 문서 - "ICHITARO": 一太郞 문서 (일본 워드프로세서) - "WPS": WPS 문서 - "DOCIMG": 인터넷 프레젠테이션 문서(SaveAs만 가능) - "SWF": Macromedia Flash 문서(SaveAs만 가능)	''
arg	str	세부 옵션. 의미는 format에 지정한 파일 형식에 따라 다르다. 생략하면 빈 문자열이 지정된다. arg에 지정할 수 있는 옵션의 의미는 필터가 정의하기에 따라 다르지만, syntax는 다음과 같이 공통된 형식을 사용한다. "key:value;key:value;..." key는 A-Z, a-z, 0-9, _ 로 구성된다. value는 타입에 따라 다음과 같은 3 종류가 있다. boolean: ex) fullsave:true (== fullsave) integer: ex) type:20 string: ex) prefix:_This_ value는 생략 가능하며, 이때는 콜론도 생략한다. arg에 지정할 수 있는 옵션 모든 파일포맷 - `setcurdir` (boolean, true/false): 로드한 후 해당 파일이 존재하는 폴더로 현재 위치를 변경한다. hyperlink 정보가 상대적인 위치로 되어 있을 때 유용하다. HWP(HWPX) - `lock` (boolean, TRUE): 로드한 후 해당 파일을 계속 오픈한 상태로 lock을 걸지 여부 - `notext` (boolean, FALSE): 텍스트 내용을 읽지 않고 헤더 정보만 읽을지 여부. (스타일 로드 등에 사용) - template (boolean, FALSE): 새로운 문서를 생성하기 위해 템플릿 파일을 오픈한다. 이 옵션이 주어지면 lock은 무조건 FALSE로 처리된다. - suspendpassword (boolean, FALSE): TRUE로 지정하면 암호가 있는 파일일 경우 암호를 묻지 않고 무조건 읽기에 실패한 것으로 처리한다. - forceopen (boolean, FALSE): TRUE로 지정하면 읽기 전용으로 읽어야 하는 경우 대화상자를 띄우지 않는다. - versionwarning (boolean, FALSE): TRUE로 지정하면 문서가 상위버전일 경우 메시지 박스를 띄우게 된다. HTML - code(string, codepage): 문서변환 시 사용되는 코드 페이지를 지정할 수 있으며 code키가 존재할 경우 필터사용 시 사용자 다이얼로그를 띄우지 않는다. - textunit(boolean, pixel): Export될 Text의 크기의 단위 결정.pixel, point, mili 지정 가능. - formatunit(boolean, pixel): Export될 문서 포맷 관련 (마진, Object 크기 등) 단위 결정. pixel, point, mili 지정 가능 ※ [codepage 종류] - ks : 한글 KS 완성형 - kssm: 한글 조합형 - sjis : 일본 - utf8 : UTF8 - unicode: 유니코드 - gb : 중국 간체 - big5 : 중국 번체 - acp : Active Codepage 현재 시스템의 코드 페이지 DOCIMG - asimg(boolean, FALSE): 저장할 때 페이지를 image로 저장 - ashtml(boolean, FALSE): 저장할 때 페이지를 html로 저장	''

Returns:

Type	Description
bool	성공하면 True, 실패하면 False

open_pdf(pdf_path, this_window=1)

pdf를 hwp문서로 변환하여 여는 함수.

(최초 실행시 "다시 표시 안함ㅁ" 체크박스에 체크를 해야 한다.)

Parameters:

Name	Type	Description	Default
pdf_path	str	pdf파일의 경로	required
this_window	int	현재 창에 열고 싶으면 1, 새 창에 열고 싶으면 0. 하지만 아직(2023.12.11.) 작동하지 않음.	1

Returns:

Type	Description
bool	성공시 True, 실패시 False 리턴

page_num_pos(global_start=1, position='BottomCenter', number_format='Digit', side_char=True)

문서 전체에 쪽번호를 삽입하는 메서드.

Parameters:

Name	Type	Description	Default
global_start	int	시작번호를 지정할 수 있음(새 번호 아님. 새 번호는 hwp.NewNumber(n)을 사용할 것)	1
position	Literal['TopLeft', 'TopCenter', 'TopRight', 'BottomLeft', 'BottomCenter', 'BottomRight', 'InsideTop', 'OutsideTop', 'InsideBottom', 'OutsideBottom', 'None']	쪽번호 위치를 지정하는 파라미터 - TopLeft - TopCenter - TopRight - BottomLeft - BottomCenter(기본값) - BottomRight - InsideTop - OutsideTop - InsideBottom - OutsideBottom - None(쪽번호숨김과 유사)	'BottomCenter'
number_format	Literal['Digit', 'CircledDigit', 'RomanCapital', 'RomanSmall', 'LatinCapital', 'HangulSyllable', 'Ideograph', 'DecagonCircle', 'DecagonCircleHanja']	쪽번호 서식을 지정하는 파라미터 - "Digit": (1 2 3), - "CircledDigit": (① ② ③), - "RomanCapital":(I II III), - "RomanSmall": (i ii iii) , - "LatinCapital": (A B C), - "HangulSyllable": (가 나 다), - "Ideograph": (一 二 三), - "DecagonCircle": (갑 을 병), - "DecagonCircleHanja": (甲 乙 丙),	'Digit'
side_char	bool	줄표 삽입 여부(bool) - True : 줄표 삽입(기본값) - False : 줄표 삽입하지 않음	True

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴

paste(option=4)

붙여넣기 확장메서드.

(참고로 paste가 아닌 Paste는 API 그대로 작동한다.)

Parameters:

Name	Type	Description	Default
option	Literal[0, 1, 2, 3, 4, 5, 6]	파라미터에 할당할 수 있는 값은 모두 7가지로, - 0: (셀) 왼쪽에 끼워넣기 - 1: 오른쪽에 끼워넣기 - 2: 위쪽에 끼워넣기 - 3: 아래쪽에 끼워넣기 - 4: 덮어쓰기 - 5: 내용만 덮어쓰기 - 6: 셀 안에 표로 넣기	4

point_to_hwp_unit(point)

글자에 쓰이는 포인트 단위를 HwpUnit으로 변환

protect_private_info(protecting_char, private_pattern_type)

개인정보를 보호한다.

한/글의 경우 “찾아서 보호”와 “선택 글자 보호”를 다른 기능으로 구현하였지만, API에서는 하나의 함수로 구현한다.

Parameters:

Name	Type	Description	Default
protecting_char	str	보호문자. 개인정보는 해당문자로 가려진다.	required
private_pattern_type	int	보호유형. 개인정보 유형마다 설정할 수 있는 값이 다르다. 0값은 기본 보호유형으로 모든 개인정보를 보호문자로 보호한다.	required

Returns:

Type	Description
bool	개인정보를 보호문자로 치환한 경우에 true를 반환한다. 개인정보를 보호하지 못할 경우 false를 반환한다. 문자열이 선택되지 않은 상태이거나, 개체가 선택된 상태에서는 실패한다. 또한, 보호유형이 잘못된 설정된 경우에도 실패한다. 마지막으로 보호암호가 설정되지 않은 경우에도 실패하게 된다.

put_field_text(field='', text='', idx=None)

지정한 필드의 내용을 채운다.

현재 필드에 입력되어 있는 내용은 지워진다. 채워진 내용의 글자모양은 필드에 지정해 놓은 글자모양을 따라간다. fieldlist의 필드 개수와, textlist의 텍스트 개수는 동일해야 한다. 존재하지 않는 필드에 대해서는 무시한다.

Parameters:

Name	Type	Description	Default
field	Any	내용을 채울 필드 이름의 리스트. 한 번에 여러 개의 필드를 지정할 수 있으며, 형식은 GetFieldText와 동일하다. 다만 필드 이름 뒤에 "{{#}}"로 번호를 지정하지 않으면 해당 이름을 가진 모든 필드에 동일한 텍스트를 채워 넣는다. 즉, PutFieldText에서는 ‘필드이름’과 ‘필드이름{{0}}’의 의미가 다르다. 단, field에 dict를 입력하는 경우에는 text 파라미터를 무시하고 dict.keys를 필드명으로, dict.values를 필드값으로 입력한다.	''
text	Union[str, list, tuple, Series]	필드에 채워 넣을 문자열의 리스트. 형식은 필드 리스트와 동일하게 필드의 개수만큼 텍스트를 0x02로 구분하여 지정한다.	''

Returns:

Type	Description
None	None

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> # 현재 캐럿 위치에 zxcv 필드 생성
>>> hwp.create_field("zxcv")
>>> # zxcv 필드에 "Hello world!" 텍스트 삽입
>>> hwp.put_field_text("zxcv", "Hello world!")

put_metatag_name_text(tag, text)

메타태그에 텍스트 삽입

quit(save=False)

한/글을 종료한다.

단, 저장되지 않은 변경사항이 있는 경우 팝업이 뜨므로 clear나 save 등의 메서드를 실행한 후에 quit을 실행해야 한다.

Parameters:

Name	Type	Description	Default
save	bool	변경사항이 있는 경우 저장할지 여부. 기본값은 저장안함(False)	False

Returns:

Type	Description
None	None

register_module(module_type='FilePathCheckDLL', module_data='FilePathCheckerModule')

(인스턴스 생성시 자동으로 실행된다.)

한/글 컨트롤에 부가적인 모듈을 등록한다. 사용자가 모르는 사이에 파일이 수정되거나 서버로 전송되는 것을 막기 위해 한/글 오토메이션은 파일을 불러오거나 저장할 때 사용자로부터 승인을 받도록 되어있다. 그러나 이미 검증받은 웹페이지이거나, 이미 사용자의 파일 시스템에 대해 강력한 접근 권한을 갖는 응용프로그램의 경우에는 이러한 승인절차가 아무런 의미가 없으며 오히려 불편하기만 하다. 이런 경우 register_module을 통해 보안승인모듈을 등록하여 승인절차를 생략할 수 있다.

Parameters:

Name	Type	Description	Default
module_type	str	모듈의 유형. 기본값은 "FilePathCheckDLL"이다. 파일경로 승인모듈을 DLL 형태로 추가한다.	'FilePathCheckDLL'
module_data	str	Registry에 등록된 DLL 모듈 ID	'FilePathCheckerModule'

Returns:

Type	Description
bool	추가모듈등록에 성공하면 True를, 실패하면 False를 반환한다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> # 사전에 레지스트리에 보안모듈이 등록되어 있어야 한다.
>>> # 보다 자세한 설명은 공식문서 참조
>>> hwp.register_module("FilePathChekDLL", "FilePathCheckerModule")
True

register_private_info_pattern(private_type, private_pattern)

개인정보의 패턴을 등록한다.

(현재 작동하지 않는다.)

Parameters:

Name	Type	Description	Default
private_type	int	등록할 개인정보 유형. 다음의 값 중 하나다. - 0x0001: 전화번호 - 0x0002: 주민등록번호 - 0x0004: 외국인등록번호 - 0x0008: 전자우편 - 0x0010: 계좌번호 - 0x0020: 신용카드번호 - 0x0040: IP 주소 - 0x0080: 생년월일 - 0x0100: 주소 - 0x0200: 사용자 정의	required
private_pattern	str	등록할 개인정보 패턴. 예를 들면 이런 형태로 입력한다. (예) 주민등록번호 - "NNNNNN-NNNNNNN" 한/글이 이미 정의한 패턴은 정의하면 안 된다. 함수를 여러 번 호출하는 것을 피하기 위해 패턴을 “;”기호로 구분 반속해서 입력할 수 있도록 한다.	required

Returns:

Type	Description
bool	등록이 성공하였으면 True, 실패하였으면 False

Examples:

>>> from pyhwpx import Hwp()
>>> hwp = Hwp()
>>>
>>> hwp.register_private_info_pattern(0x01, "NNNN-NNNN;NN-NN-NNNN-NNNN")  # 전화번호패턴

register_regedit(dll_name='FilePathCheckerModule.dll') staticmethod

레지스트리 에디터에 한/글 보안모듈을 자동등록하는 메서드.

가장 먼저 파이썬과 pyhwpx 모듈이 설치된 상태라고 가정하고 'site-packages/pyhwpx' 폴더에서 'FilePathCheckerModule.dll' 파일을 찾는다. 두 번째로는 pyinstaller로 컴파일했다고 가정하고, MEIPASS 하위폴더를 탐색한다. 이후로, 차례대로 실행파일과 동일한 경로, 사용자 폴더를 탐색한 후에도 보안모듈 dll파일을 찾지 못하면 아래아한글 깃헙 저장소에서 직접 보안모듈을 다운받아 사용자 폴더에 설치하고, 레지스트리를 수정한다.

Parameters:

Name	Type	Description	Default
dll_name	str	보안모듈 dll 파일명. 관례적으로 FilePathCheckerModule.dll을 쓴다.	'FilePathCheckerModule.dll'

Returns:

Type	Description
None	None

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()  # 이 때 내부적으로 register_regedit를 실행한다.

release_scan()

InitScan()으로 설정된 초기화 정보를 해제한다.

텍스트 검색작업이 끝나면 반드시 호출하여 설정된 정보를 해제해야 한다.

Returns:

Type	Description
None	None

remove_background_picture()

표 안에 백그라운드 이미지가 삽입되어 있고,

캐럿이 해당 셀 안에 들어있는 경우, 이를 제거하는 메서드

Returns:

rename_field(oldname, newname)

지정한 필드의 이름을 바꾼다.

예를 들어 oldname에 "title{{0}}\x02title{{1}}", newname에 "tt1\x02tt2로 지정하면 첫 번째 title은 tt1로, 두 번째 title은 tt2로 변경된다. oldname의 필드 개수와, newname의 필드 개수는 동일해야 한다. 존재하지 않는 필드에 대해서는 무시한다.

Parameters:

Name	Type	Description	Default
oldname	str	이름을 바꿀 필드 이름의 리스트. 형식은 PutFieldText와 동일하게 "\x02"로 구분한다.	required
newname	str	새로운 필드 이름의 리스트. oldname과 동일한 개수의 필드 이름을 "\x02"로 구분하여 지정한다.	required

Returns:

Type	Description
bool	None

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.create_field("asdf")  # "asdf" 필드 생성
>>> hwp.rename_field("asdf", "zxcv")  # asdf 필드명을 "zxcv"로 변경
>>> hwp.put_field_text("zxcv", "Hello world!")  # zxcv 필드에 텍스트 삽입

rename_metatag(oldtag, newtag)

메타태그 이름 변경

replace_action(old_action_id, new_action_id)

특정 Action을 다른 Action으로 대체한다.

이는 메뉴나 단축키로 호출되는 Action을 대체할 뿐, CreateAction()이나, Run() 등의 함수를 이용할 때에는 아무런 영향을 주지 않는다. 즉, ReplaceAction(“Cut", "Copy")을 호출하여 ”오려내기“ Action을 ”복사하기“ Action으로 교체하면 Ctrl+X 단축키나 오려내기 메뉴/툴바 기능을 수행하더라도 복사하기 기능이 수행되지만, 코드 상에서 Run("Cut")을 실행하면 오려내기 Action이 실행된다. 또한, 대체된 Action을 원래의 Action으로 되돌리기 위해서는 NewActionID의 값을 원래의 Action으로 설정한 뒤 호출한다. 이를테면 이런 식이다.

Parameters:

Name	Type	Description	Default
old_action_id	str	변경될 원본 Action ID. 한/글 컨트롤에서 사용할 수 있는 Action ID는 ActionTable.hwp(별도문서)를 참고한다.	required
new_action_id	str	변경할 대체 Action ID. 기존의 Action ID와 UserAction ID(ver:0x07050206) 모두 사용가능하다.	required

Returns:

Type	Description
bool	Action을 바꾸면 True를 바꾸지 못했다면 False를 반환한다.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.replace_action("Cut", "Cut")

resize_image(width=None, height=None, unit='mm')

이미지 또는 그리기 개체의 크기를 조절하는 메서드.

해당개체 선택 후 실행해야 함.

rgb_color(red_or_colorname, green=255, blue=255)

RGB값을 한/글이 인식하는 정수 형태로 변환해주는 헬퍼 메서드.

주로 글자색이나, 셀 색깔을 적용할 때 사용한다. RGB값을 세 개의 정수로 입력하는 것이 기본적인 사용방법이지만, 자주 사용되는 아래의 24가지 색깔은 문자열로 입력 가능하다.

Parameters:

Name	Type	Description	Default
red_or_colorname	str | tuple | int	R값(0~255)을 입력하거나, 혹은 아래 목록의 색깔 문자열을 직접 입력할 수 있다. - "Red": (255, 0, 0) - "Green": (0, 255, 0) - "Blue": (0, 0, 255) - "Yellow": (255, 255, 0) - "Cyan": (0, 255, 255) - "Magenta": (255, 0, 255) - "Black": (0, 0, 0) - "White": (255, 255, 255) - "Gray": (128, 128, 128) - "Orange": (255, 165, 0) - "DarkBlue": (0, 0, 139) - "Purple": (128, 0, 128) - "Pink": (255, 192, 203) - "Lime": (0, 255, 0) - "SkyBlue": (135, 206, 235) - "Gold": (255, 215, 0) - "Silver": (192, 192, 192) - "Mint": (189, 252, 201) - "Tomato": (255, 99, 71) - "Olive": (128, 128, 0) - "Crimson": (220, 20, 60) - "Navy": (0, 0, 128) - "Teal": (0, 128, 128) - "Chocolate": (210, 105, 30)	required
green	int	G값(0~255)	255
blue	int	B값(0~255)	255

Returns:

Type	Description
int	아래아한글이 인식하는 정수 형태의 RGB값.

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.set_font(TextColor=hwp.RGBColor("Red"))  # 글자를 빨강으로
>>> hwp.insert_text("빨간 글자색\r\n")
>>> hwp.set_font(ShadeColor=hwp.RGBColor(0, 255, 0))  # 음영을 녹색으로
>>> hwp.insert_text("초록 음영색")

run_script_macro(function_name, u_macro_type=0, u_script_type=0)

한/글 문서 내에 존재하는 매크로를 실행한다.

문서매크로, 스크립트매크로 모두 실행 가능하다. 재미있는 점은 한/글 내에서 문서매크로 실행시 New, Open 두 개의 함수 밖에 선택할 수 없으므로 별도의 함수를 정의하더라도 이 두 함수 중 하나에서 호출해야 하지만, (진입점이 되어야 함) self.hwp.run_script_macro 명령어를 통해서는 제한없이 실행할 수 있다.

Parameters:

Name	Type	Description	Default
function_name	str	실행할 매크로 함수이름(전체이름)	required
u_macro_type	int	매크로의 유형. 밑의 값 중 하나이다. - 0: 스크립트 매크로(전역 매크로-HWP_GLOBAL_MACRO_TYPE, 기본값) - 1: 문서 매크로(해당문서에만 저장/적용되는 매크로-HWP_DOCUMENT_MACRO_TYPE)	0
u_script_type	int	스크립트의 유형. 현재는 javascript만을 유일하게 지원한다. 아무 정수나 입력하면 된다. (기본값: 0)	0

Returns:

Type	Description
bool	무조건 True를 반환(매크로의 실행여부와 상관없음)

Examples:

>>> hwp.run_script_macro("OnDocument_New", u_macro_type=1)
True
>>> hwp.run_script_macro("OnScriptMacro_중국어1성")
True

save(save_if_dirty=True)

현재 편집중인 문서를 저장한다.

문서의 경로가 지정되어있지 않으면 “새 이름으로 저장” 대화상자가 뜬다.

Parameters:

Name	Type	Description	Default
save_if_dirty	bool	True를 지정하면 문서가 변경된 경우에만 저장한다. False를 지정하면 변경여부와 상관없이 무조건 저장한다. 생략하면 True가 지정된다.	True

Returns:

Type	Description
bool	성공하면 True, 실패하면 False

save_all_pictures(save_path='./binData')

현재 문서에 삽입된 모든 이미지들을

삽입 당시 파일명으로 복원하여 저장. 단, 문서 안에서 복사했거나 중복삽입한 이미지는 한 개만 저장됨. 기본 저장폴더명은 ./binData이며 기존에 save_path가 존재하는 경우, 그 안의 파일들은 삭제되므로 유의해야 함.

Parameters:

Name	Type	Description	Default
save_path	str	저장할 하위경로 이름	'./binData'

Returns:

Name	Type	Description
bool	bool	성공시 True

save_as(path, format='HWP', arg='', split_page=False)

현재 편집중인 문서를 지정한 이름으로 저장한다.

format, arg의 일반적인 개념에 대해서는 Open()참조.

Parameters:

Name	Type	Description	Default
path	str	문서 파일의 전체경로	required
format	str	문서 형식. 생략하면 "HWP"가 지정된다.	'HWP'
arg	str	세부 옵션. 의미는 format에 지정한 파일 형식에 따라 다르다. 생략하면 빈 문자열이 지정된다. 여러 개를 한꺼번에 할 경우에는 세미콜론으로 구분하여 연속적으로 사용할 수 있다. "lock:TRUE;backup:FALSE;prvtext:1" - "lock:true": 저장한 후 해당 파일을 계속 오픈한 상태로 lock을 걸지 여부 - "backup:false": 백업 파일 생성 여부 - "compress:true": 압축 여부 - "fullsave:false": 스토리지 파일을 완전히 새로 생성하여 저장 - "prvimage:2": 미리보기 이미지 (0=off, 1=BMP, 2=GIF) - "prvtext:1": 미리보기 텍스트 (0=off, 1=on) - "autosave:false": 자동저장 파일로 저장할 지 여부 (TRUE: 자동저장, FALSE: 지정 파일로 저장) - "export": 다른 이름으로 저장하지만 열린 문서는 바꾸지 않는다.(lock:false와 함께 설정되어 있을 시 동작)	''
split_page	bool	html+ 포맷으로 저장할 때, 페이지 나누기 여부	False

Returns:

Type	Description
bool	성공하면 True, 실패하면 False

save_pdf_as_image(path='', img_format='bmp')

문서보안이나 복제방지를 위해 모든 페이지를 이미지로 변경 후 PDF로 저장하는 메서드.

아무 인수가 주어지지 않는 경우 모든 페이지를 bmp로 저장한 후에 현재 폴더에 {문서이름}.pdf로 저장한다. (만약 저장하지 않은 빈 문서의 경우에는 result.pdf로 저장한다.)

Parameters:

Name	Type	Description	Default
path	str	저장경로 및 파일명	''
img_format	str	이미지 변환 포맷	'bmp'

Returns:

Type	Description
bool	성공시 True

select_ctrl(ctrl, anchor_type=0, option=1)

인수로 넣은 컨트롤 오브젝트를 선택하는 pyhwpx 전용 메서드.

Parameters:

Name	Type	Description	Default
ctrl	Ctrl	선택하고자 하는 컨트롤	required
anchor_type	Literal[0, 1, 2]	컨트롤의 위치를 찾아갈 때 List, Para, Pos의 기준위치. (아주 특수한 경우를 제외하면 기본값을 쓰면 된다.) - 0: 바로 상위 리스트에서의 좌표(기본값) - 1: 탑레벨 리스트에서의 좌표 - 2: 루트 리스트에서의 좌표	0

Returns:

Type	Description
bool	성공시 True

select_text(spara=0, spos=0, epara=0, epos=0, slist=0)

특정 범위의 텍스트를 블록선택한다.

epos가 가리키는 문자는 포함되지 않는다.

Parameters:

Name	Type	Description	Default
spara	Union[int, list, tuple]	블록 시작 위치의 문단 번호.	0
spos	int	블록 시작 위치의 문단 중에서 문자의 위치.	0
epara	int	블록 끝 위치의 문단 번호.	0
epos	int	블록 끝 위치의 문단 중에서 문자의 위치.	0

Returns:

Type	Description
bool	성공하면 True, 실패하면 False

select_text_by_get_pos(s_getpos, e_getpos)

hwp.get_pos()로 얻은 두 튜플 사이의 텍스트를 선택하는 메서드.

Parameters:

Name	Type	Description	Default
s_getpos	tuple	선택 시작점 좌표의 get_pos값	required
e_getpos	tuple	선택 끝점 좌표의 get_pos값	required

Returns:

Type	Description
bool	선택 성공시 True, 실패시 False를 리턴함

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> s_pos = hwp.get_pos()  # 선택 시작부분 저장
>>> # 이래저래 좌표 이동 후
>>> e_pos = hwp.get_pos()  # 선택 끝부분 저장
>>> # 이래저래 또 좌표 이동 후
>>> hwp.select_text_by_get_pos(s_pos, e_pos)
True

set_cell_margin(left=1.8, right=1.8, top=0.5, bottom=0.5, as_='mm')

표 중 커서가 위치한 셀 또는 다중선택한 모든 셀의 안 여백을 지정하는 메서드.

표 안에서만 실행가능하며, 전체 셀이 아닌 표 자체를 선택한 상태에서는 여백이 적용되지 않음. 차례대로 왼쪽, 오른쪽, 상단, 하단의 여백을 밀리미터(기본값) 또는 HwpUnit 단위로 지정.

Parameters:

Name	Type	Description	Default
left	float	셀의 좌측 안여백	1.8
right	float	셀의 우측 안여백	1.8
top	float	셀의 상단 안여백	0.5
bottom	float	셀의 하단 안여백	0.5
as_	Literal['mm', 'hwpunit']	입력단위. ["mm", "hwpunit"] 중 기본값은 "mm"	'mm'

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴함

set_col_width(width, as_='ratio')

칼럼의 너비를 변경하는 메서드.

정수(int)나 부동소수점수(float) 입력시 현재 칼럼의 너비가 변경되며, 리스트나 튜플 등 iterable 타입 입력시에는 각 요소들의 비에 따라 칼럼들의 너비가 일괄변경된다. 예를 들어 3행 3열의 표 안에서 set_col_width([1,2,3]) 을 실행하는 경우 1열너비:2열너비:3열너비가 1:2:3으로 변경된다. (표 전체의 너비가 148mm라면, 각각 24mm : 48mm : 72mm로 변경된다는 뜻이다.)

단, 열너비의 비가 아닌 "mm" 단위로 값을 입력하려면 as_="mm"로 파라미터를 수정하면 된다. 이 때, width에 정수 또는 부동소수점수를 입력하는 경우 as_="ratio"를 사용할 수 없다.

Parameters:

Name	Type	Description	Default
width	int | float | list | tuple	열 너비	required
as_	Literal['mm', 'ratio']	단위	'ratio'

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.create_table(3,3)
True
>>> hwp.get_into_nth_table(0)
True
>>> hwp.set_col_width([1,2,3])
True

set_cur_field_name(field='', direction='', memo='', option=0)

표 안에서 현재 캐럿이 위치하는 셀, 또는 블록선택한 셀들의 필드이름을 설정한다.

GetFieldList()의 옵션 중에 4(hwpFieldSelection) 옵션은 사용하지 않는다.

셀필드가 아닌 누름틀 생성은 create_field 메서드를 이용해야 한다.

Parameters:

Name	Type	Description	Default
field	str	데이터 필드 이름	''
direction	str	누름틀 필드의 안내문. 누름틀 필드일 때만 유효하다.	''
memo	str	누름틀 필드의 메모. 누름틀 필드일 때만 유효하다.	''
option	int	다음과 같은 옵션을 지정할 수 있다. 0을 지정하면 모두 off이다. 생략하면 0이 지정된다. - 1: 셀에 부여된 필드 리스트만을 구한다. hwpFieldClickHere와는 함께 지정할 수 없다.(hwpFieldCell) - 2: 누름틀에 부여된 필드 리스트만을 구한다. hwpFieldCell과는 함께 지정할 수 없다.(hwpFieldClickHere)	0

Returns:

Type	Description
bool	성공하면 True, 실패하면 False

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.create_table(5, 5, True)  # 3행3열의 글자처럼 취급한 표 생성(A1셀로 이동)
>>> hwp.TableCellBlockExtendAbs()
>>> hwp.TableCellBlockExtend()  # 셀 전체 선택
>>> hwp.set_cur_field_name("target_table")  # 모든 셀의 셀필드 이름을 "target_table"로 바꿈
>>> hwp.put_field_text("target_table", list(range(1, 26)))  # 각 셀에 1~25까지의 정수를 넣음
>>> hwp.set_cur_field_name("")  # 셀필드 초기화
>>> hwp.Cancel()  # 셀블록 선택취소

set_field_by_bracket()

필드를 지정하는 일련의 반복작업을 간소화하기 위한 메서드.

중괄호 두 겹({{}})으로 둘러싸인 구문을 누름틀로 변환해준다. 만약 본문에 "{{name}}"이라는 문구가 있었다면 해당 단어를 삭제하고 그 위치에 name이라는 누름틀을 생성한다.

지시문(direction)과 메모(memo)도 추가가 가능한데, "{{name:direction}}" 또는 "{{name:direction:memo}}" 방식으로 콜론으로 구분하여 지정할 수 있다. (가급적 direction을 지정해주도록 하자. 그렇지 않으면 누름틀이 보이지 않는다.) 셀 안에서 누름틀을 삽입할 수도 있지만, 편의상 셀필드를 삽입하고 싶은 경우 "[[name]]"으로 지정하면 된다.

Returns:

set_font(Bold='', DiacSymMark='', Emboss='', Engrave='', FaceName='', FontType=1, Height='', Italic='', Offset='', OutLineType='', Ratio='', ShadeColor='', ShadowColor='', ShadowOffsetX='', ShadowOffsetY='', ShadowType='', Size='', SmallCaps='', Spacing='', StrikeOutColor='', StrikeOutShape='', StrikeOutType='', SubScript='', SuperScript='', TextColor='', UnderlineColor='', UnderlineShape='', UnderlineType='', UseFontSpace='', UseKerning='')

글자모양을 메서드 형태로 수정할 수 있는 메서드.

Parameters:

Name	Type	Description	Default
Bold	str | bool	진하게(True/False)	''
DiacSymMark	str | int	1행 선택강조점(0~12)	''
Emboss	str | bool	hwp.TableCellBlockRow()양각(True/False)	''
Engrave	str | bool	hwp.set_font("D2Coding")음각(True/False)	''
FaceName	str	서체	''
FontType	int	1(TTF) 고정	1
Height	str | float	글자크기(pt, 0.1 ~ 4096)	''
Italic	str | bool	이탤릭(True/False)	''
Offset	str | int	글자위치-상하오프셋(-100 ~ 100)	''
OutLineType	str | int	외곽선타입(0~6)	''
Ratio	str | int	장평(50~200)	''
ShadeColor	str | int	음영색(RGB, 0x000000 ~ 0xffffff) ~= hwp.rgb_color(255,255,255), 취소는 0xffffffff(4294967295)	''
ShadowColor	str | int	그림자색(RGB, 0x0~0xffffff) ~= hwp.rgb_color(255,255,255), 취소는 0xffffffff(4294967295)	''
ShadowOffsetX	str | int	그림자 X오프셋(-100 ~ 100)	''
ShadowOffsetY	str | int	그림자 Y오프셋(-100 ~ 100)	''
ShadowType	str | int	그림자 유형(0: 없음, 1: 비연속, 2:연속)	''
Size	str | int	글자크기 축소확대%(10~250)	''
SmallCaps	str | bool	강조점	''
Spacing	str | int	자간(-50 ~ 50)	''
StrikeOutColor	str | int	취소선 색(RGB, 0x0~0xffffff) ~= hwp.rgb_color(255,255,255), 취소는 0xffffffff(4294967295)	''
StrikeOutShape	str | int	취소선 모양(0~12, 0이 일반 취소선)	''
StrikeOutType	str | bool	취소선 유무(True/False)	''
SubScript	str | bool	아래첨자(True/False)	''
SuperScript	str | bool	위첨자(True/False)	''
TextColor	str | int	글자색(RGB, 0x0~0xffffff) ~= hwp.rgb_color(255,255,255), 기본값은 0xffffffff(4294967295)	''
UnderlineColor	str | int	밑줄색(RGB, 0x0~0xffffff) ~= hwp.rgb_color(255,255,255), 기본값은 0xffffffff(4294967295)	''
UnderlineShape	str | int	밑줄형태(0~12)	''
UnderlineType	str | int	밑줄위치(0:없음, 1:하단, 3:상단)	''
UseFontSpace	str | bool	글꼴에 어울리는 빈칸(True/False) : 차이가 나는 폰트를 못 찾았다...	''
UseKerning	str | bool	커닝 적용(True/False) : 차이가 전혀 없다?	''

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.SelectAll()  # 전체선택
>>> hwp.set_font(FaceName="D2Coding", TextColor="Orange")

set_linespacing(value=160, method='Percent')

현재 캐럿 위치의 문단 또는 선택 블록의 줄간격(%) 설정

Parameters:

Name	Type	Description	Default
value	int | float	줄간격 값("Percent"인 경우에는 %, 그 외에는 point 값으로 적용됨). 기본값은 160(%)	160
method	Literal['Fixed', 'Percent', 'BetweenLines', 'AtLeast']	줄간격 단위기준. method가 일치해야 정상적으로 적용됨. - "Fixed": 고정값(포인트 단위) - "Percent": 글자에 따라(기본값, %) - "BetweenLines": 여백만 지정(포인트 단위) - "AtLeast": 최소(포인트 단위)	'Percent'

Returns: 성공시 True, 실패시 False를 리턴

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.SelectAll()  # 전체선택
>>> hwp.set_linespacing(160)  # 본문 모든 문단의 줄간격을 160%로 변경
True
>>> hwp.set_linespacing(20, method="BetweenLines")  # 본문 모든 문단의 줄간격을 "여백만 지정"으로 20pt 적용
True

set_message_box_mode(mode)

메시지박스 버튼 자동클릭

한/글에서 쓰는 다양한 메시지박스가 뜨지 않고,

자동으로 특정 버튼을 클릭한 효과를 주기 위해 사용한다. 한/글에서 한/글이 로드된 후 SetMessageBoxMode()를 호출해서 사용한다. SetMessageBoxMode는 하나의 파라메터를 받으며, 해당 파라메터는 자동으로 스킵할 버튼의 값으로 설정된다. 예를 들어, MB_OK_IDOK (0x00000001)값을 주면, MB_OK형태의 메시지박스에서 OK버튼이 눌린 효과를 낸다.

Parameters:

Name	Type	Description	Default
mode	int	메시지 박스 자동선택 종류 모든 자동설정 해제: 0xFFFFFF 확인 버튼만 있는 팝업의 경우 확인 자동누르기: 0x1 확인 자동누르기 해제: 0xF 확인/취소 버튼이 있는 팝업의 경우 확인 자동누르기: 0x10 취소 자동누르기: 0x20 확인/취소 옵션 해제: 0xF0 종료/재시도/무시 팝업의 경우 종료 자동누르기: 0x100 재시도 자동누르기: 0x200 무시 자동누르기: 0x400 종료/재시도/무시 옵션 해제: 0xF00 예/아니오/취소 팝업의 경우 예 자동누르기: 0x1000 아니오 자동누르기: 0x2000 취소 자동누르기: 0x4000 예/아니오/취소 옵션 해제: 0xF000 예/아니오 팝업의 경우 예 자동누르기: 0x10000 아니오 자동누르기: 0x20000 예/아니오 옵션 해제: 0xF0000 재시도/취소 팝업의 경우 재시도 자동누르기: 0x100000 취소 자동누르기: 0x200000 재시도/취소 옵션 해제: 0xF00000	required

Returns:

Type	Description
int	실행 직전의 MessageBoxMode(현재 값이 아님에 주의)

set_pagedef(pset, apply='cur')

get_pagedef 또는 get_pagedef_as_dict를 통해 얻은 용지정보를 현재구역에 적용하는 메서드

Parameters:

Name	Type	Description	Default
pset	Any	파라미터셋 또는 dict. 용지정보를 담은 객체	required

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴

set_pos(List, para, pos)

캐럿을 문서 내 특정 위치로 옮기기

지정된 좌표로 캐럿을 옮겨준다.

Parameters:

Name	Type	Description	Default
List	int	캐럿이 위치한 문서 내 list ID	required
para	int	캐럿이 위치한 문단 ID. 음수거나, 범위를 넘어가면 문서의 시작으로 이동하며, pos는 무시한다.	required
pos	int	캐럿이 위치한 문단 내 글자 위치. -1을 주면 해당문단의 끝으로 이동한다. 단 para가 범위 밖일 경우 pos는 무시되고 문서의 시작으로 캐럿을 옮긴다.	required

Returns:

Type	Description
bool	성공하면 True, 실패하면 False

set_pos_by_set(disp_val)

캐럿을 ParameterSet으로 얻어지는 위치로 옮긴다.

Parameters:

Name	Type	Description	Default
disp_val	Any	캐럿을 옮길 위치에 대한 ParameterSet 정보	required

Returns:

Type	Description
bool	성공하면 True, 실패하면 False

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> start_pos = hwp.GetPosBySet()  # 현재 위치를 체크포인트처럼 저장하고,
>>> # 특정 작업(이동 및 입력작업) 후에
>>> hwp.set_pos_by_set(start_pos)  # 저장했던 위치로 되돌아가기

set_row_height(height, as_='mm')

캐럿이 표 안에 있는 경우

캐럿이 위치한 행의 셀 높이를 조절하는 메서드(기본단위는 mm)

Parameters:

Name	Type	Description	Default
height	int | float	현재 행의 높이 설정값(기본단위는 mm)	required

Returns:

Type	Description
bool	성공시 True, 실패시 False 리턴

set_style(style)

현재 캐럿이 위치한 문단의 스타일을 변경한다.

스타일 입력은 style 인수로 정수값(스타일번호) 또는 문자열(스타일이름)을 넣으면 된다.

Parameters:

Name	Type	Description	Default
style	int | str	현재 문단에 적용할 스타일 번호(int) 또는 스타일이름(str)	required

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴

set_table_inside_margin(left=1.8, right=1.8, top=0.5, bottom=0.5, as_='mm')

표 내부 모든 셀의 안여백을 일괄설정하는 메서드.

표 전체를 선택하지 않고 표 내부에 커서가 있기만 하면 모든 셀에 적용됨.

Parameters:

Name	Type	Description	Default
left	float	모든 셀의 좌측여백(mm)	1.8
right	float	모든 셀의 우측여백(mm)	1.8
top	float	모든 셀의 상단여백(mm)	0.5
bottom	float	모든 셀의 하단여백(mm)	0.5
as_	Literal['mm', 'hwpunit']	입력단위. "mm", "hwpunit" 중 택일. 기본값은 "mm"	'mm'

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴

set_table_outside_margin(left=-1.0, right=-1.0, top=-1.0, bottom=-1.0, as_='mm')

표의 바깥여백을 변경하는 메서드.

기본 입력단위는 "mm"이며, "HwpUnit" 단위로 변경 가능.

Parameters:

Name	Type	Description	Default
left	float	표의 좌측 바깥여백	-1.0
right	float	표의 우측 바깥여백	-1.0
top	float	표의 상단 바깥여백	-1.0
bottom	float	표의 하단 바깥여백	-1.0
as_	Literal['mm', 'hwpunit']	입력단위. ["mm", "hwpunit"] 중 기본값은 "mm"	'mm'

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴

set_table_width(width=0, as_='mm')

표 전체의 너비를 원래 열들의 비율을 유지하면서 조정하는 메서드.

내부적으로 xml 파싱을 사용하는 방식으로 변경.

Parameters:

Name	Type	Description	Default
width	int	너비(단위는 기본 mm이며, hwpunit으로 변경 가능)	0
as_	Literal['mm', 'hwpunit', 'hu']	단위("mm" or "hwpunit")	'mm'

Returns:

Type	Description
bool	성공시 True

Examples:

>>> # 모든 표의 너비를 본문여백(용지너비 - 좌측여백 - 우측여백 - 제본여백 - 표 좌우 바깥여백)에 맞추기
>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> i = 0
>>> while hwp.get_into_nth_table(i):
...     hwp.set_table_width()
True

set_text_file(data, format='HWPML2X', option='insertfile')

GetTextFile로 저장한 문자열 정보를 문서에 삽입

Parameters:

Name	Type	Description	Default
data	str	문자열로 변경된 text 파일	required
format	Literal['HWP', 'HWPML2X', 'HTML', 'UNICODE', 'TEXT']	파일의 형식 - "HWP": HWP native format. BASE64 로 인코딩되어 있어야 한다. 저장된 내용을 다른 곳에서 보여줄 필요가 없다면 이 포맷을 사용하기를 권장합니다.ver:0x0505010B - "HWPML2X": HWP 형식과 호환. 문서의 모든 정보를 유지 - "HTML": 인터넷 문서 HTML 형식. 한/글 고유의 서식은 손실된다. - "UNICODE": 유니코드 텍스트, 서식정보가 없는 텍스트만 저장 - "TEXT": 일반 텍스트, 유니코드에만 있는 정보(한자, 고어, 특수문자 등)는 모두 손실된다.	'HWPML2X'
option	str	"insertfile"을 지정하면 현재커서 이후에 지정된 파일을 삽입(기본값)	'insertfile'

Returns:

Type	Description
int	성공이면 1을, 실패하면 0을 반환한다.

set_title(title='')

한/글 프로그램의 타이틀을 변경한다.

파일명과 무관하게 설정할 수 있으며, 이모지 등 모든 특수문자를 허용한다. 단, 끝에는 항상 " - 한글"이 붙는다. 타이틀을 빈 문자열로 만들면 자동으로 원래 타이틀로 돌아간다.

Parameters:

Name	Type	Description	Default
title	str	변경할 타이틀 문자열	''

Returns:

Type	Description
bool	성공시 True

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.open("asdf.hwp")
>>> hwp.get_title()
asdf.hwp [c:\Users\user\desktop\] - 한글
>>> hwp.set_title("😘")
>>> hwp.get_title()
😘 - 한글

set_visible(visible)

현재 조작중인 한/글 인스턴스의 백그라운드 숨김여부를 변경할 수 있다.

Parameters:

Name	Type	Description	Default
visible	bool	visible=False로 설정하면 현재 조작중인 한/글 인스턴스가 백그라운드로 숨겨진다.	required

Returns:

Type	Description
None	None

shape_copy_paste(Type='both', cell_attr=False, cell_border=False, cell_fill=False, cell_only=0)

모양복사 메서드

Parameters:

Name	Type	Description	Default
Type	Literal['font', 'para', 'both']	글자("font"), 문단("para"), 글자&문단("both") 중에서 택일	'both'
cell_attr	bool	셀 속성 복사여부(True / False)	False
cell_border	bool	셀 선 복사여부(True / False)	False
cell_fill	bool	셀 음영 복사여부(True / False)	False
cell_only	int	셀만 복사할지, 내용도 복사할지 여부(0 / 1)	0

Returns:

Type	Description
bool	성공시 True, 실패시 False를 리턴

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.get_into_nth_table(0)  # 문서 첫 번째 셀로 이동
>>> hwp.shape_copy_paste()  # 모양복사 (무엇을 붙여넣을 건지는 "붙여넣기" 시점에 결정함)
>>> hwp.TableCellBlockExtendAbs()
>>> hwp.TableCellBlockExtend()  # 셀 전체 선택
>>> hwp.shape_copy_paste(cell_fill=True)  # 글자&문단모양, 셀음영만 붙여넣기

switch_to(num)

여러 개의 hwp인스턴스가 열려 있는 경우 해당 인덱스의 문서창 인스턴스를 활성화한다.

Parameters:

Name	Type	Description	Default
num	int	전환할 문서 인스턴스 아이디(1부터 시작)	required

Returns:

Type	Description
XHwpDocument | None	문서 전환에 성공시 True, 실패시 False를 리턴

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.add_doc()
>>> hwp.add_tab()
>>> hwp.switch_to(0)

table_from_data(data, transpose=False, header0='', treat_as_char=False, header=True, index=True, cell_fill=False, header_bold=True)

dict, list 또는 csv나 xls, xlsx 및 json처럼 2차원 스프레드시트로 표현 가능한 데이터에 대해서,

정확히는 pd.DataFrame으로 변환 가능한 데이터에 대해 아래아한글 표로 변환하는 작업을 한다. 내부적으로 판다스 데이터프레임으로 변환하는 과정을 거친다.

Parameters:

Name	Type	Description	Default
data	DataFrame | dict | list | str	테이블로 변환할 데이터	required
transpose	bool	행/열 전환	False
header0	str	index=True일 경우 (1,1) 셀에 들어갈 텍스트	''
treat_as_char	bool	글자처럼 취급 여부	False
header	bool	1행을 "제목행"으로 선택할지 여부	True
header_bold	bool	1행의 텍스트에 bold를 적용할지 여부	True

Returns:

Type	Description
None	None

table_to_bottom(offset=0.0)

표 앞에 캐럿을 둔 상태 또는 캐럿이 표 안에 있는 상태에서 위 함수 실행시

표를 (페이지 기준) 하단으로 위치시킨다.

Parameters:

Name	Type	Description	Default
offset	float	페이지 하단 기준 오프셋(mm)	0.0

Returns:

Type	Description
bool	성공시 True

table_to_csv(n='', filename='result.csv', encoding='utf-8', startrow=0)

한/글 문서의 idx번째 표를 현재 폴더에 filename으로 csv포맷으로 저장한다.

filename을 지정하지 않는 경우 "./result.csv"가 기본값이다.

Returns: None을 리턴하고, 표데이터를 "./result.csv"에 저장한다.

Examples:

>>> from pyhwpx import Hwp
>>>
>>> hwp = Hwp()
>>> hwp.table_to_csv(1, "table.csv")

table_to_df(n='', cols=0, selected_range=None, start_pos=None)

(2025. 3. 3. RowSpan이랑 ColSpan을 이용해서, 중복되는 값은 그냥 모든 셀에 넣어버림

한/글 문서의 n번째 표를 판다스 데이터프레임으로 리턴하는 메서드. n을 넣지 않는 경우, 캐럿이 셀에 있다면 해당 표를 df로, 캐럿이 표 밖에 있다면 첫 번째 표를 df로 리턴한다.

Returns: 아래아한글 표 데이터를 가진 판다스 데이터프레임 인스턴스

Examples:

>>> from pyhwpx import Hwp
>>>
>>> hwp = Hwp()
>>> df = hwp.table_to_df()  # 현재 캐럿이 들어가 있는 표 전체를 df로(1행을 df의 칼럼으로)
>>> df = hwp.table_to_df(0, cols=2)  # 문서의 첫 번째 표를 df로(2번인덱스행(3행)을 칼럼명으로, 그 아래(4행부터)를 값으로)

table_to_df_q(n='', startrow=0, columns=[])

(2024. 3. 14. for문 추출 구조에서, 한 번에 추출하는 방식으로 변경->속도개선)

한/글 문서의 n번째 표를 판다스 데이터프레임으로 리턴하는 메서드. n을 넣지 않는 경우, 캐럿이 셀에 있다면 해당 표를 df로, 캐럿이 표 밖에 있다면 첫 번째 표를 df로 리턴한다. startrow는 표 제목에 일부 병합이 되어 있는 경우 df로 변환시작할 행을 특정할 때 사용된다.

Returns: 아래아한글 표 데이터를 가진 판다스 데이터프레임 인스턴스

Examples:

>>> from pyhwpx import Hwp
>>>
>>> hwp = Hwp()
>>> df = hwp.table_to_df(0)

unfill_addr_field()

현재 캐럿이 들어있는 표의 셀필드를 모두 제거하는 메서드

XHwpDocument

한글과컴퓨터 문서(HWP)의 COM 객체를 래핑한 클래스입니다.

이 클래스는 HwpDocument COM 객체와 상호작용하기 위한 속성과 메서드를 제공합니다. 문서 속성, 데이터 조작 기능, 상태 제어 등 다양한 기능을 제공하며, 한글과컴퓨터의 문서 관리 시스템을 파이썬스럽게 다룰 수 있도록 설계되었습니다.

속성

Application: 문서와 연결된 어플리케이션 객체 CLSID: 문서의 클래스 ID DocumentID: 문서의 고유 식별자 EditMode: 현재 문서의 편집 모드 Format: 문서의 형식 FullName: 문서의 전체 경로를 문자열로 반환. 저장되지 않은 문서는 빈 문자열 반환 Modified: 문서의 수정 여부를 나타냄 Path: 문서가 저장된 폴더 경로 XHwpCharacterShape: 문서의 글자모양 설정에 접근 XHwpDocumentInfo: 문서의 상세 정보에 접근 XHwpFind: 텍스트 찾기 기능에 접근 XHwpFormCheckButtons: 체크박스 양식 요소에 접근 XHwpFormComboBoxs: 콤보박스 양식 요소에 접근 XHwpFormEdits: 편집 양식 요소에 접근 XHwpFormPushButtons: 버튼 양식 요소에 접근 XHwpFormRadioButtons: 라디오버튼 양식 요소에 접근 XHwpParagraphShape: 문단 모양 설정에 접근 XHwpPrint: 문서 인쇄 제어에 접근 XHwpRange: 문서 내 범위 설정에 접근 XHwpSelection: 현재 선택된 텍스트나 개체에 접근 XHwpSendMail: 메일 보내기 기능에 접근 XHwpSummaryInfo: 문서 요약 정보에 접근

FullName property

문서의 전체경로 문자열. 저장하지 않은 빈 문서인 경우에는 빈 문자열 ''

XHwpDocuments

한글과컴퓨터 문서(HWP) COM 객체의 컬렉션을 표현하는 클래스입니다.

이 클래스는 COM 객체로 표현된 문서 컬렉션과 상호작용하기 위한 속성과 메서드를 제공합니다. 문서 컬렉션에 대한 반복, 인덱싱, 길이 조회 등의 컬렉션 유사 동작을 지원하며, 문서를 추가하고, 닫고, 특정 문서 오브젝트를 검색하는 메서드를 포함합니다.

Attributes:

Name	Type	Description
Active_XHwpDocument	XHwpDocument	컬렉션의 활성 문서
Application		COM 객체와 연결된 애플리케이션을 반환
CLSID		COM 객체의 CLSID
Count	int	컬렉션 내 문서 개수

Methods:

Name	Description
Add	bool = False) -> XHwpDocument: 컬렉션에 새 문서를 추가합니다.
Close	bool = False) -> None: 활성 문서 창을 닫습니다.
FindItem	int) -> XHwpDocument: 주어진 문서 ID에 해당하는 문서 객체를 찾아 반환합니다.

Add(isTab=False)

문서 추가

Parameters:

Name	Type	Description	Default
isTab	bool	탭으로 열 건지(True), 문서로 열 건지(False, 기본값) 결정	False

Returns:

Type	Description
'XHwpDocument'	문서 오브젝트(XHwpDocument) 리턴

Examples:

>>> from pyhwpx import Hwp
>>> hwp = Hwp()
>>> hwp.XHwpDocuments.Add(True)

Close(isDirty=False)

문서창 닫기

FindItem(lDocID)

해당 DocumentID의 문서 오브젝트가 있는지 탐색

Parameters:

Name	Type	Description	Default
lDocID	int	찾고자 하는 문서오브젝트의 ID	required

Returns:

Name	Type	Description
int	'XHwpDocument'	해당 아이디의 XHwpDocument 리턴
None	'XHwpDocument'	없는 경우 None 리턴

addr_to_tuple(cell_address)

엑셀주소를 튜플로 변환하는 헬퍼함수

엑셀 셀 주소("A1", "B2", "ASD100000" 등)를 (row, col) 튜플로 변환하는 헬퍼함수입니다. 예를 들어 addr_to_tuple("C3")을 실행하면 (3, 3)을 리턴하는 식입니다. pyhwpx 일부 메서드의 내부 연산에 사용됩니다.

Parameters:

Name	Type	Description	Default
cell_address	str	엑셀 방식의 "셀주소" 문자열	required

Returns:

Type	Description
tuple[int, int]	(row, column) 형식의 주소 튜플

Examples:

>>> from pyhwpx import addr_to_tuple
>>> print(addr_to_tuple("C3"))
(3, 3)
>>> print(addr_to_tuple("AB10"))
(10, 28)
>>> print(addr_to_tuple("AAA100000"))
(100000, 703)

check_registry_key(key_name='FilePathCheckerModule')

아래아한글의 보안모듈 FilePathCheckerModule의 레지스트리에 등록여부 체크

Parameters:

Name	Type	Description	Default
key_name	str	아래아한글 보안모듈 키 이름. 기본값은 "FilePathCheckerModule"	'FilePathCheckerModule'

Returns:

Type	Description
bool	등록되어 있는 경우 True, 미등록인 경우 False

check_tuple_of_ints(var)

변수가 튜플이고 모든 요소가 int인지 확인하는 헬퍼함수

Parameters:

Name	Type	Description	Default
var	tuple	이터러블 자료형. 일반적으로 튜플.	required

Returns:

Type	Description
bool	튜플이면서, 요소들이 모두 int인 경우 True를 리턴, 그렇지 않으면 False

com_initialized(func)

이용준님께서 기여해주셨습니다. (https://github.com/YongJun-Lee-98) 이 데코레이터는 함수 실행 전에 COM 라이브러리를 초기화하고, 실행 후에 COM 라이브러리를 해제합니다.

Python의 GC가 COM 객체를 자동으로 제거하더라도, CoUninitialize()를 호출하지 않으면 COM 라이브러리가 해당 스레드에서 완전히 해제되지 않을 수 있기 때문입니다.

excel_address_to_tuple_zero_based(address)

엑셀 셀 주소를 튜플로 변환하는 헬퍼함수

rename_duplicates_in_list(file_list)

문서 내 이미지를 파일로 저장할 때, 동일한 이름의 파일 뒤에 (2), (3).. 붙여주는 헬퍼함수

Parameters:

Name	Type	Description	Default
file_list	list[str]	문서 내 이미지 파일명 목록	required

Returns:

Type	Description
list[str]	중복된 이름이 두 개 이상 있는 경우 뒤에 "(2)", "(3)"을 붙인 새로운 문자열 리스트

tuple_to_addr(row, col)

(행번호, 칼럼번호)를 인자로 받아 엑셀 셀 주소 문자열(예: "AAA3")을 반환합니다.

hwp.goto_addr(addr) 메서드 내부에서 활용됩니다. 직접 사용하지 않습니다.

Parameters:

Name	Type	Description	Default
col	int	열(칼럼) 번호(1부터 시작)	required
row	int	행(로우) 번호(1부터 시작)	required

Returns:

Name	Type	Description
str	str	엑셀 형식의 주소 문자열(예: "A1", "VVS1004")

Examples:

>>> from pyhwpx import tuple_to_addr
>>> print(tuple_to_addr(1, 2))
B1

댓글