hwp.GetFieldList() # 필드를 다룰 때 꼭 알아야 하는 메서드

응용편에서 튜토리얼을 진행하는 중에 기본 메서드를 자세하게 다루다 보면 
의식의 흐름이 툭툭 끊길 수 있어, 이런 식으로 메서드 설명을 기본편에 하나씩 써놓고
참고링크를 달아놓으려고 한다.

 

---

 

1. hwp.GetFieldList() 란?

hwp.GetFieldList()는 한/글 컨트롤 오브젝트(HwpCtrl Object)의 메서드 중 하나로

문서에 존재하는 필드(혹은 누름틀)의 목록을 구하는 메서드이다.

개인적으로 한/글 API가 참 친절하다고 느껴지는 부분은 매개변수 파트인데,

필드목록을 구하는 이 간단한 메서드에도 두 개 인자(number, option)에 각각 3개씩의 매개변수가 들어가 있어

누름틀을 상세하게 다룰 수 있다.

 

API문서 중 hwp.GetFieldList 에 대한 설명

 

---

 

2. Number 인자

Number 인자(대소문자 구분)에 들어갈 수 있는 매개변수는 0~2까지 세 개다.
생략하면 기본값인 0이 대입되며, 결과는 아래와 같다.

\x02로 구분된 필드 리스트 문자열

그런데, 동일명의 누름틀이 두 개면 어떻게 출력되는지 궁금하지 않나?
바로, 아래처럼 나온다.

동일명의 누름틀이 두 개 이상일 때, 리스트에도 중복해서 나타난다.

이 문자열을 리스트로 만들어보면?

동일한 문자열이 두 개 이상 들어있는 리스트가 되었다.

보이다시피 필드이름이 중복되어 나타나고 있다.

지금 파이썬으로 한/글파일을 다루는 최종 목적이 "필드리스트 구하기"라면 아무 문제가 없다.
그런데 보통은 필드리스트를 구한 후, 이를 통해 필드 안에 값을 채워넣는 것이 목적이기 때문에,
위 방식으로는 오류가 발생하거나, (두 번째, 세 번째 누름틀이 채워지지 않을 수 있다.)
오류를 막기 위해 번거로운 작업을 보태야 한다. 

그 때 유용한 파라미터가 Number=1(hwpFieldNumber)이다.

Number 파라미터로 1을 대입한 경우 리턴되는 값 

위처럼, 일종의 "일련번호"를 붙여 리턴해주면, 중복된 필드명이 있을 때에도 정확히 원하는 순서에 값을 넣을 수 있다.

 

이와 유사하지만 조금 다른 옵션으로 Number=2(hwpFieldCount)가 있다.
아이디인 hwpFieldCount에서 알 수 있듯, 각 필드의 갯수를 이중꼬불괄호 안에 넣어 반환해준다.

2중꼬불괄호 안에 해당 이름을 가진 필드의 갯수가 표시된다.

 

Number 인자에서 주로 사용하는 값은 보통, 0 또는 1인데, 필자는 개인적으로 1을 넣는 것을 선호하는 편이다.

예를 들어보자.

예제 : 청구서(응용편에서 현재 절찬리 포스팅중)

위 서식으로 100명분의 청구서를 PDF로 만들어야 한다고 할 때,

어떤 이는 한 쪽을 완성하고 PDF출력, 다시 다른 내용을 채우고 PDF출력, 바꿔쓰고 PDF출력~ 하는 방식.
즉, 한 쪽짜리 문서에 내용을 바꿔가며 PDF 100장을 출력하는 방식을 선호할 수 있다.

필자의 경우 다소 느려지는 것을 감안하고 100쪽짜리 문서를 만들고 저장, 누름틀에 각각 값을 채워 저장한 후
페이지별로 각각의 PDF를 출력하는 것을 선호한다. 경험상 여러가지 면에서 안정적이라고 생각해서다.

이런 식으로 작업하는 것을 선호하는 편이다. 뭐든 모아놓으면 찾기도 편하다고 느낀다.

실제로 여러분도 API매뉴얼을 틈틈이 읽다 보면,
자동화를 처리할 수 있는 비범한(혹은 신박하기까지 한) 여러 가지 방법들이 떠오를 것이다.

 

---

 

3. option 인자

option 인자는 특정 부분의 필드 목록만 가져오고 싶을 때 사용하면 된다.

option 인자(전부 소문자)에 들어갈 수 있는 매개변수는 조금 특이한데,
0, 1, 2, 4 중 일부를 더해서 파라미터를 넣어야 한다.
생략하면 기본값인 0이 대입되며, 각각의 결과는 아래와 같다.

0 : 모두 구한다.
1 : 표의 셀에 부여된 필드만 구한다.
2 : 셀이 아닌, 일반 누름틀의 리스트만 구한다.
5 : (1+4) 블록선택한 영역 중 셀에 부여된 필드 목록만 리턴한다.
6 : (2+4) 블록선택한 영역 중 누름틀 필드 목록만 리턴한다.

처음엔 생소하지만, 많이 하다 보면 그래도 생소하다...
사실 필자도 여태껏 한 번도 현업에 사용해 본 적은 없다.

만약 사용하더라도 한 가지 꼭 주의할 점은,
1~10페이지 중 2페이지만 선택한 상태에서
hwp.GetFieldList(Number=1, option=6)을 주더라도
{{n}} 안의 숫자는 0이 된다는 점을 명심하자.

{{1}}이 아니다. 2페이지의 누름틀이라도 일련번호가 {{0}}이 되는 점에 유의하자.

 

---

 

4. 마치며

MS 제품군 API를 다뤄본 분들이라면 메서드의 파라미터에 숫자가 들어가는 것이 익숙할 것이다.
아래아한글 API 메서드 대다수의 파라미터에 숫자가 들어간다.
파라미터 수가 꽤 많아서 API매뉴얼을 꼭 참고해야 하지만,
무엇보다 특이한 점은 2진수 혹은 16진수 파라미터끼리 더해야 하는 메서드가 종종 있다는 점?ㅎ
글자색 RGB값도, SetMessageBoxMode 도 그렇고..
하여튼 틈틈이 중요 메서드를 하나씩 심도있게 다뤄보고자 한다.

이번 포스팅은 여기서 마친다.