외로운코딩독학님, 안녕하세요?ㅎ

개인적으로는 위 문서를 자주 참고하지는 않고 있지만,
초반 공부할 때 위 문서들을 활용했던 방법을 간략히 알려드려보면..
우선 개인적으로는
올려주신 문서를 참고했던 빈도를 비율로 대략 따져보면
오토메이션 80%, 액션 15%, 그리고 파라미터셋 5% 정도 되지 않았나 싶습니다.

1. 오토메이션 문서

스크립트매크로 녹화를 할 수 없는 프로세스 대부분은 이 안에 들어있기도 합니다.

오토메이션 문서 중에서도 제가 가장 많이 참고했던 부분은
14~31페이지, "IHwpObject" 부분입니다.

여기서 IHwpObject는 파이썬에서

import win32com.client as win32
hwp = win32.gencache.EnsureDispatch("hwpframe.hwpobject")

로 실행할 때 그 hwp 인스턴스를 가리킵니다. hwp의 메서드를 설명해 주는 부분인 거죠.

32페이지의 IXHwpDocuments는 hwp.XHwpDocuments에 대한 설명이고,

33페이지의 IXHwpDocument는 hwp.XHwpDocuments.Item(0)에 대한 설명입니다.

위와 동일한 방식으로
IXHwpFormPushButtons는 hwp.XHwpFormPushButtons에 대한 설명,
IXHwpFormPushButton은 hwp.XHwpFormPushButtons.Item(0) [문서에 푸쉬버튼이 있는 경우]

이런 식으로 이해하시면 됩니다.

예를 들어보면

예를 들어 현재 활성화된 한/글 문서창을 백그라운드로 숨기는 방법을 문서에서 찾고 싶은데
여기저기 뒤지니까 45페이지에 Visible 속성에 대한 설명이 나와 있습니다.

Description
윈도우 보이기/보이지 않기 설정/얻음

메서드가 아닌 프로퍼티이므로 hwp.ㅁㅁㅁ.ㅇㅇㅇ.Visible = True 식의 코드로 작성할텐데
해당 프로퍼티가 IXHwpWindow에 포함되어 있다는 걸 확인했으므로
위의 예시를 통해 실행방법을 추측해보면

hwp.XHwpWindows.Item(0).Visible = True

라는 걸 알 수 있게 되는 거죠.

그리고 대부분의 메서드와 프로퍼티는 파이참 등에서 탐색이 되는 편이므로
IDE를 적극 활용하시면 좋겠습니다.

2. 액션테이블

액션오브젝트 문서는, hwp.HAction.Execute 또는 hwp.HAction.Run으로 실행 가능한 한/글 프로그램의 액션(일종의 함수) 목록입니다.

재미있는 것은, 이 액션이 크게 두 종류로 나뉜다는 것인데,
①파라미터셋이 필요한 액션과, ②파라미터셋이 필요없는 액션이 있습니다.

파라미터셋이 필요없는 메서드(통칭 Run메서드)
hwp.HAction.Run("액션") 또는 간단히 hwp.Run("액션") 명령어로 실행할 수 있습니다.

두 실행법에 차이가 있는데, HAction이 붙어있으면, 실행 성공시 True를 리턴합니다.
이런 특징 덕분에 while문의 조건으로 Run메서드를 직접 넣을 수도 있습니다.

예를 들어

표의 셀이 몇 개인지 모르지만,
표의 모든 셀을 순회하면서 "붙여넣기" 액션을 실행하고 싶다면?
아래와 같이 코드를 짜도 됩니다. (캐럿이 표의 A1셀 안에 있는 경우임)

hwp.Run("Paste")
while hwp.HAction.Run("TableRightCell"):
    hwp.Run("Paste")

한 줄에 실행되기도 하고, 메서드도 나름 직관적이어서
액션테이블에서 Run메서드만 자주 찾아서 활용했습니다.
제 블로그에 Run메서드만 따로 정리한 페이지가 있으니 참고하시기 바랍니다.
링크는 https://martinii.fun/page/hwp의-Run메서드-전체목록-및-시연화면
입니다.

3. 파라미터셋

Run액션 외의 모든 액션들은 전부 파라미터셋이 정의되고 적용되어야 합니다.

복잡한 워드프로세서 특성상, 액션별로 파라미터도 너~~무 많고, (액션도 많고)
특히 어떤 파라미터들은 문자열이나 정수로 표현하기에는 너무 복잡한데다
한/글에서는 빠릿빠릿한 최적화가 되어 있어야 하기 때문에
나름의 최적화된 구조를 만들어낸 결과가 "파라미터셋"일 거라는 추측을 해봅니다.

예를 들어

파이썬에서, 한/글 액션에 파라미터셋을 적용하는
방법 중 하나는 아래와 같습니다.
예를 들어 본문 선택구간의 글자를 빨간색으로 바꾸고 "진하게"를 적용하고 싶다면?
아래 네 줄을 실행해야 합니다.
(패턴은 대부분 아래와 같으니, 쓰시다 보면 익숙해지실 겁니다.)

pset = hwp.HParameterSet.HCharShape  # 파라미터셋 생성
hwp.HAction.GetDefault("CharShape", pset.HSet)  # 파라미터셋을 현재상태를 반영하여 초기화
pset.TextColor = hwp.RGBColor(255, 0, 0)  # 파라미터셋 변경
pset.Bold = True  # 파라미터셋 변경
hwp.HAction.Execute("CharShape", pset.HSet)  # 변경되 파라미터셋 적용

여기서 pset이 그 파라미터셋입니다.
위 액션의 경우
액션아이디는 CharShape이고,
파라미터셋 아이디도 CharShape입니다.
(앞에 붙은 H는 접두어 같은 거라고 이해하시면 됩니다)
TextColor나 Bold는 CharShape파라미터셋의 아이템아이디입니다.

문서 탐색 순서

(위 메서드를 모른다고 가정하고)
이제 위 메서드를 완성하기 위해 문서탐색을 하는 과정을 설명드리겠습니다.

다시 말씀드리지만 이 방법 대신 스크립트 매크로를 쓰실 수 있습니다.

1. 파라미터셋 문서에서 "글자색"을 검색해본다.

"글자색"으로 문서찾기를 했더니 17페이지에 "TextColor"가 나왔습니다.

2열의 "PIT_UI4" 같은 부분은 모르고 넘어가도 괜찮지만,
아이템의 값을 이해하는 데 도움이 되기는 합니다.
PIT_는 무시하셔도 되고(시스템 호환성을 위해 한컴에서 임의로 넣은 기호상수)
UI4는 4byte Unsigned Integer (long),
즉 0 ~ 4294967295까지의 정수 데이터타입을 가리킵니다.
4열의 설명(0x00BBGGRR)을 참고해서 빨간색을 정의하면
0x000000FF==0xFF==255 가 순수한 빨강을 가리키므로
hwp.RGBColor(255, 0, 0)은 0xFF 또는 255로 대체하여 사용할 수 있습니다.

TextColor라는 아이템 아이디가 속한 파라미터셋은 CharShape입니다.

그럼 이제 액션테이블 문서를 열어서
CharShape 파라미터셋을 사용하는 액션이름이 뭔지 찾아봅시다.
(CharShape으로 검색해도 되고, "글자 모양"으로 검색해도 됩니다..)
3페이지에 나오네요.

액션아이디는 CharShape,
파라미터셋의 아이디는 CharShape인 걸 확인했으므로,
이제 아래 메서드를 완성할 수 있게 되었습니다.

pset = hwp.HParameterSet.HCharShape  # 파라미터셋 생성(접두어로 H가 붙음)
hwp.HAction.GetDefault("CharShape", pset.HSet)  # 파라미터셋 초기화
pset.TextColor = hwp.RGBColor(255, 0, 0)  # 파라미터셋 변경
hwp.HAction.Execute("CharShape", pset.HSet)  # 변경되 파라미터셋 적용

아래는 시연화면입니다.

참고로, 위의 코드는
API문서 예시코드에 나온 대로
아래 방식으로도 실행하실 수 있습니다.
(결과는 같습니다. 둘 중 편하신 방법을 쓰시면 됩니다.)

Act = hwp.CreateAction("CharShape")
Set = Act.CreateSet()  # 파라미터셋 아이디를 알아낼 필요는 없음.
Act.GetDefault(Set)
Set.SetItem("TextColor", 255)
Act.Execute(Set)

개인적으로는 전자의 방식을 선호하는데,
그 이유는 스크립트 매크로 녹화 코드와 동일하기 때문입니다.

그런데 문서를 찾는 방식을 추천드리지는 않습니다.

이렇게 문서를 통해 찾는 방법이 비효율적인 이유는
그냥 스크립트매크로 녹화하는 상태에서 글자색 빨갛게, 진하게 적용하고
녹화된 코드만 확인하면 되기 때문입니다. 변환도 간단하고요.
그리고 무엇보다, API문서에서는
hwp.RGBColor 메서드를 포함한 파라미터셋용 메서드에 대한 내용이라든지,
구체적인 파라미터값의 의미를 설명하지 않는 경우들이 많습니다. (결국 여러번 녹화해봐야 알게 됩니다.)

마치며

위와 같은 방법으로 어느 정도 문서의 기본 구조를 이해하시고 나면
스크립트매크로와 병행하여 직접 코드를 완성하시면서
차근차근 연습해보실 것을 추천드립니다.

다만, 스크립트매크로 녹화가 안 되는 몇 가지 액션이 있기는 합니다.
예를 들면 이미지 관련이라든지, 마우스를 통해 실행해야 하는 대부분의 메서드도 그런 경우죠.
이런 부분들의 해법은 어느 정도 경험이 쌓여야
자연스럽게 풀리거나, '이건 안되겠구나' 하는 감이 생기는 것 같습니다.
막힐 때마다 여기 질문 남겨주시기 바랍니다. 저도 같이 고민해보겠습니다.

또한 한글 개발자 포럼에 방문하여 질문 남기시는 것도 좋은 방법입니다.
왠만한 경우 한/글 개발자들이 직접 답변을 (보통 하루 이내로) 남겨줍니다.

하여튼 또 질문 남겨주세요^^

요즘은, 자주 쓰이는 프로세스 패턴을 클래스로 엮어서
pyhwpx라는 모듈을 만들어보기도 했습니다.
pyhwpx에 대한 포스팅도 종종 남길 예정입니다.

감사합니다.
답변이 도움이 되었으면 좋겠습니다.
행복한 하루 되세요!

인프런 커뮤니티 질문&답변

"문서"를 참조하고 활용하는 방법이 궁금합니다.

외로운코딩독학님, 안녕하세요?ㅎ

1. 오토메이션 문서

예를 들어보면

2. 액션테이블

예를 들어

3. 파라미터셋

예를 들어

문서 탐색 순서

1. 파라미터셋 문서에서 "글자색"을 검색해본다.

그런데 문서를 찾는 방식을 추천드리지는 않습니다.

마치며