listbox — 항목 리스트 위젯 만들고 다루기

파일 목록이나 선택지처럼 여러 문자열을 세로로 나열해서 고르게 하려면 어떻게 해야 할까요? Tk의 listbox 명령은 한 줄에 하나씩 문자열 리스트를 표시하는 항목 리스트 위젯을 만듭니다. 스크롤도 되고 여러 선택 방식도 지원해서 목록 선택 UI의 기본기가 돼요.

출처: listbox (Tcl/Tk 8.6.18 매뉴얼)

본문

개요

listbox pathName ?options?

listbox 명령은 pathName 인자로 주어진 새 창을 만들고 listbox 위젯으로 만듭니다. 색, 글꼴, 텍스트, relief 같은 listbox의 측면을 구성하는 옵션을 명령줄이나 옵션 데이터베이스로 지정할 수 있어요. listbox 명령은 pathName 인자를 돌려줍니다. 호출 시점에 pathName이라는 창이 존재해서는 안 되지만, pathName의 부모는 존재해야 해요.

listbox는 한 줄에 하나씩 문자열 리스트를 표시하는 위젯입니다. 처음 만들어지면 새 listbox에는 요소가 없어요. 요소는 아래 설명하는 위젯 명령으로 추가·삭제할 수 있습니다. 또한 아래 설명대로 요소 하나 이상을 선택할 수 있어요.

listbox가 자신의 선택을 내보내고 있다면(exporting, -exportselection 옵션 참조) 선택을 처리하는 표준 X11 프로토콜을 따릅니다. listbox 선택은 STRING 유형으로 사용 가능해요. 선택의 값은 선택된 요소들의 텍스트이며, 요소 사이는 새줄로 구분됩니다.

모든 요소가 한 번에 listbox 창에 표시될 필요는 없어요. 아래 설명하는 명령으로 창의 뷰를 바꿀 수 있죠. listbox는 표준 -xscrollcommand와 -yscrollcommand 옵션으로 양방향 스크롤을 허용합니다. 아래 설명하는 스캐닝도 지원해요.

표준 옵션

-background 또는 -bg, -borderwidth 또는 -bd, -cursor, -disabledforeground, -exportselection, -font, -foreground 또는 -fg, -highlightbackground, -highlightcolor, -highlightthickness, -justify, -relief, -selectbackground, -selectborderwidth, -selectforeground, -setgrid, -takefocus, -xscrollcommand, -yscrollcommand 옵션이 표준 옵션으로 제공됩니다.

위젯 전용 옵션

-activestyle (데이터베이스 이름 activeStyle, 클래스 ActiveStyle) — 활성 요소를 그리는 방식을 지정합니다. dotbox(활성 요소 주위에 포커스 링 표시), none(활성 요소 특별 표시 없음), underline(활성 요소에 밑줄) 중 하나여야 해요. 기본값은 Windows에서 underline, 그 외에서 dotbox입니다.

-height (데이터베이스 이름 height, 클래스 Height) — 창의 원하는 높이를 줄 단위로 지정합니다. 0 이하이면 listbox의 모든 요소를 담을 만큼만 크게 만들어요.

-listvariable (데이터베이스 이름 listVariable, 클래스 Variable) — 전역 변수의 이름을 지정합니다. 변수의 값은 위젯 안에 표시될 리스트예요. 변수 값이 바뀌면 위젯이 자동으로 새 값을 반영해 갱신합니다. -listvariable에 잘못된 리스트 값을 가진 변수를 할당하려 하면 오류가 발생해요. -listvariable로 사용 중인 변수를 unset하려 하면 실패하지만 오류는 발생하지 않습니다.

-selectmode (데이터베이스 이름 selectMode, 클래스 SelectMode) — 선택을 조작하는 여러 방식 중 하나를 지정합니다. 옵션의 값은 임의일 수 있지만, 기본 바인딩은 single, browse, multiple, extended 중 하나일 것으로 기대해요. 기본값은 browse입니다.

-state (데이터베이스 이름 state, 클래스 State) — listbox의 두 상태 normal 또는 disabled 중 하나를 지정합니다. listbox가 disabled이면 항목을 삽입하거나 삭제할 수 없고, 항목은 -disabledforeground 색으로 그려지며, 선택은 수정될 수 없고 표시되지 않아요(선택 정보는 유지됩니다).

-width (데이터베이스 이름 width, 클래스 Width) — 창의 원하는 너비를 문자 단위로 지정합니다. 글꼴이 균일한 너비가 아니면 문자 단위를 화면 단위로 변환할 때 "0" 문자의 너비를 사용해요. 0 이하이면 listbox의 모든 요소를 담을 만큼만 크게 만듭니다.

인덱스

listbox의 위젯 명령 대부분은 인덱스를 인자로 받습니다. 인덱스는 다음 방식 중 하나로 listbox의 특정 요소를 지정해요.

number — 요소를 숫자 인덱스로 지정합니다. 0이 listbox의 첫 요소에 해당해요.

active — 위치 커서를 가진 요소를 나타냅니다. 이 요소는 listbox가 키보드 포커스를 가질 때 -activestyle이 지정한 대로 표시되고, activate 위젯 명령으로 지정됩니다.

anchor — 선택의 앵커 지점을 나타내며, selection anchor 위젯 명령으로 설정합니다.

end — listbox의 끝을 나타냅니다. 대부분의 명령에서 이는 listbox의 마지막 요소를 가리키지만, index나 insert 같은 몇몇 명령에서는 마지막 바로 뒤 요소를 가리켜요.

@x,y — listbox 창에서 x와 y(픽셀 좌표)가 가리키는 점을 덮는 요소를 나타냅니다. 그 점을 덮는 요소가 없으면 그 점에 가장 가까운 요소가 사용돼요.

아래 위젯 명령 설명에서 index, first, last 인자는 항상 위 형태 중 하나의 텍스트 인덱스를 담습니다.

위젯 명령

listbox 명령은 이름이 pathName인 새 Tcl 명령을 만듭니다. 일반적인 형태는 다음과 같아요.

pathName option ?arg arg ...?

pathName activate index — 활성 요소를 index가 가리키는 것으로 설정합니다. index가 listbox의 요소 범위 밖이면 가장 가까운 요소가 활성화돼요. 활성 요소는 위젯이 입력 포커스를 가질 때 -activestyle이 지정한 대로 그려지고, 그 인덱스는 active 인덱스로 검색할 수 있습니다.

pathName bbox index — index로 주어진 요소의 텍스트 경계 상자를 설명하는 숫자 4개의 리스트를 돌려줍니다. 처음 두 요소는 텍스트가 덮는 화면 영역의 왼쪽 위 모서리 x, y 좌표(위젯 기준 픽셀)이고, 마지막 두 요소는 영역의 너비와 높이(픽셀)예요. index로 주어진 요소의 어떤 부분도 화면에 보이지 않거나 index가 존재하지 않는 요소를 가리키면 결과는 빈 문자열입니다. 요소가 부분적으로 보이면 결과는 보이지 않는 부분을 포함한 요소의 전체 영역을 줍니다.

pathName cget option — option으로 주어진 설정 옵션의 현재 값을 돌려줍니다.

pathName configure ?option? ?value option value ...? — 위젯의 설정 옵션을 조회하거나 수정합니다. option을 지정하지 않으면 사용 가능한 모든 옵션을 설명하는 리스트를 돌려주고, option만 지정하면 그 옵션 하나를 설명하는 리스트를 돌려줍니다. option-value 쌍을 지정하면 해당 옵션을 수정하고 빈 문자열을 돌려줘요.

pathName curselection — listbox에서 현재 선택된 모든 요소의 숫자 인덱스를 포함하는 리스트를 돌려줍니다. 선택된 요소가 없으면 빈 문자열을 돌려줘요.

pathName delete first ?last? — listbox의 요소 하나 이상을 삭제합니다. first와 last는 삭제할 범위의 첫·마지막 요소를 지정하는 인덱스예요. last를 지정하지 않으면 first로 기본값이 정해져 단일 요소가 삭제됩니다.

pathName get first ?last? — last를 생략하면 first가 가리키는 listbox 요소의 내용을 돌려주고, first가 존재하지 않는 요소를 가리키면 빈 문자열을 돌려줘요. last를 지정하면 first와 last 사이(포함)의 모든 listbox 요소를 요소로 하는 리스트를 돌려줍니다.

pathName index index — index에 해당하는 정수 인덱스 값을 돌려줍니다. index가 end이면 반환 값은 listbox의 요소 수(마지막 요소의 인덱스가 아닙니다)입니다.

pathName insert index ?element element ...? — index로 주어진 요소 바로 앞에 새 요소 0개 이상을 리스트에 삽입합니다. index를 end로 지정하면 새 요소가 리스트 끝에 추가돼요. 빈 문자열을 돌려줍니다.

pathName itemcget index option — option으로 주어진 항목 설정 옵션의 현재 값을 돌려줍니다. option은 itemconfigure 명령이 받아들이는 값 중 하나일 수 있어요.

pathName itemconfigure index ?option? ?value? ?option value ...? — listbox 항목의 설정 옵션을 조회하거나 수정합니다. 항목에 대해 현재 지원되는 옵션은 다음과 같아요.

-background color — 항목 표시 시 사용할 배경색. Tk_GetColor이 받아들이는 형태 중 하나일 수 있어요.
-foreground color — 항목 표시 시 사용할 전경색. Tk_GetColor 형태.
-selectbackground color — 항목이 선택된 동안 표시할 배경색. Tk_GetColor 형태.
-selectforeground color — 항목이 선택된 동안 표시할 전경색. Tk_GetColor 형태.

pathName nearest y — listbox 창 안의 y 좌표가 주어지면 그 y 좌표에 가장 가까운 (보이는) listbox 요소의 인덱스를 돌려줍니다.

pathName scan option args — listbox에서 스캐닝을 구현하는 데 사용됩니다. option에 따라 두 가지 형태가 있어요.

pathName scan mark x y — x, y와 현재 뷰를 listbox 창에 기록합니다. 나중의 scan dragto 명령과 함께 사용돼요. 보통 위젯에서 마우스 버튼 누름과 연결됩니다. 빈 문자열을 돌려줘요.
pathName scan dragto x y — 자기의 x, y 인자와 위젯의 마지막 scan mark 명령의 x, y 인자 사이의 차이를 계산합니다. 그다음 뷰를 좌표 차이의 10배로 조정해요. 보통 위젯의 마우스 이동 이벤트와 연결되어, 리스트를 창을 통해 고속으로 끄는 효과를 만듭니다. 반환 값은 빈 문자열이에요.

pathName see index — index로 주어진 요소가 보이도록 listbox의 뷰를 조정합니다. 요소가 이미 보이면 효과가 없고, 요소가 창의 한쪽 가장자리 근처에 있으면 그 가장자리로 요소를 가져오게 스크롤하며, 그 외에는 요소가 중앙에 오도록 스크롤해요.

pathName selection option arg — listbox 안에서 선택을 조정하는 데 사용됩니다. option에 따라 여러 형태가 있어요.

pathName selection anchor index — 선택 앵커를 index로 주어진 요소로 설정합니다. index가 존재하지 않는 요소를 가리키면 가장 가까운 요소가 사용돼요. 선택 앵커는 마우스로 선택을 끌 때 고정되는 선택의 한쪽 끝입니다. anchor 인덱스로 앵커 요소를 가리킬 수 있어요.
pathName selection clear first ?last? — first와 last 사이(포함)의 요소 중 선택된 것이 있으면 선택을 해제합니다. 이 범위 밖의 요소 선택 상태는 바뀌지 않아요.
pathName selection includes index — index가 가리키는 요소가 현재 선택돼 있으면 1, 아니면 0을 돌려줍니다.
pathName selection set first ?last? — first와 last 사이(포함)의 모든 요소를 선택합니다. 범위 밖의 요소 선택 상태는 영향을 받지 않아요.

pathName size — listbox의 총 요소 수를 나타내는 십진 문자열을 돌려줍니다.

pathName xview ?args — 위젯 창에서 정보의 수평 위치를 조회·변경하는 데 사용됩니다. 다음 형태를 가질 수 있어요.

pathName xview — 요소 두 개를 포함하는 리스트를 돌려줍니다. 각 요소는 0과 1 사이의 실수 분수로, 함께 창에 보이는 수평 범위를 설명해요. 예를 들어 첫 요소가 .2, 둘째가 .6이면 listbox 텍스트의 20%가 화면 왼쪽 밖, 중간 40%가 창에 보이고, 40%가 오른쪽 밖에 있는 거예요. 이 값들은 -xscrollcommand 옵션으로 스크롤바에 전달되는 것과 같아요.
pathName xview index — index로 주어진 문자 위치가 창 왼쪽 가장자리에 표시되도록 뷰를 조정합니다. 문자 위치는 0 문자의 너비로 정의됩니다.
pathName xview moveto fraction — listbox 텍스트 총 너비의 fraction만큼이 왼쪽 화면 밖에 있도록 뷰를 조정합니다. fraction은 0과 1 사이의 분수여야 해요.
pathName xview scroll number what — number와 what에 따라 창의 뷰를 왼쪽이나 오른쪽으로 이동시킵니다. number는 정수여야 하고, what은 units 또는 pages 중 하나(또는 줄임말)여야 해요. what이 units이면 뷰가 디스플레이에서 number 문자 단위(0 문자의 너비)만큼 이동하고, pages면 number 화면만큼 이동해요. number가 음수면 더 왼쪽의 문자가 보이고, 양수면 더 오른쪽의 문자가 보입니다.

pathName yview ?args? — 위젯 창에서 텍스트의 수직 위치를 조회·변경하는 데 사용됩니다. 다음 형태를 가질 수 있어요.

pathName yview — 요소 두 개를 포함하는 리스트를 돌려줍니다. 둘 다 0과 1 사이의 실수 분수예요. 첫 요소는 창 맨 위에 있는 listbox 요소의 위치를 listbox 전체에 대해 나타내고(예: 0.5는 listbox의 중간), 두 번째 요소는 창의 마지막 요소 바로 뒤 요소의 위치를 나타냅니다. 이 값들은 -yscrollcommand 옵션으로 스크롤바에 전달되는 것과 같아요.
pathName yview index — index로 주어진 요소가 창 맨 위에 표시되도록 뷰를 조정합니다.
pathName yview moveto fraction — fraction으로 주어진 요소가 창 맨 위에 나타나도록 뷰를 조정합니다. fraction은 0과 1 사이의 분수로, 0은 첫 요소, 0.33은 1/3 지점 요소를 나타내요.
pathName yview scroll number what — number와 what에 따라 창의 뷰를 위나 아래로 조정합니다. number는 정수, what은 units 또는 pages여야 해요. units면 뷰가 number줄만큼, pages면 number 화면만큼 조정됩니다. number가 음수면 더 이전 요소가, 양수면 더 이후 요소가 보여요.

기본 바인딩

Tk는 listbox에 Motif 같은 동작을 주는 클래스 바인딩을 자동으로 만듭니다. listbox의 동작 대부분은 선택을 다루는 네 가지 방식 중 하나를 고르는 -selectmode 옵션에 의해 결정돼요.

선택 모드가 single이나 browse면 listbox에서 한 번에 최대 한 요소가 선택될 수 있어요. 두 모드 모두에서 요소의 버튼 1을 클릭하면 그 요소가 선택되고 다른 선택 항목은 해제됩니다. browse 모드에서는 버튼 1로 선택을 끌 수도 있어요. 버튼 1에서 listbox는 normal 상태라면 포커스도 가져갑니다.

선택 모드가 multiple이나 extended면 비연속 범위를 포함해 한 번에 여러 요소가 선택될 수 있어요. multiple 모드에서 요소의 버튼 1을 클릭하면 다른 요소에 영향 없이 그 요소의 선택 상태가 토글됩니다. extended 모드에서 요소의 버튼 1을 누르면 그 요소가 선택되고 나머지가 모두 해제되며, 마우스 아래 요소로 앵커가 설정됩니다. 버튼 1을 누른 채 마우스를 끌면 앵커와 마우스 아래 요소 사이(포함)의 모든 요소를 포함하도록 선택이 확장돼요.

대부분의 사람은 단일 선택에 browse 모드, 다중 선택에 extended 모드를 쓰고 싶을 거예요. 다른 모드들은 특별한 상황에서만 유용해 보입니다.

listbox에서 선택된 항목 집합이 키보드나 마우스로 사용자에 의해 갱신될 때마다 <<ListboxSelect>> 가상 이벤트가 생성됩니다. 이 가상 이벤트는 pathName selection 명령으로 선택을 조정할 때는 생성되지 않아요. listbox 선택에 대한 사용자 변경을 알기 위해서는 이 이벤트에 바인딩하는 게 가장 쉽습니다.

위 동작에 더해, 기본 바인딩은 다음 동작을 추가로 정의합니다.

extended 모드에서 Shift 키를 누른 채 버튼 1을 누르면 선택 범위를 조정할 수 있어요. 앵커와 마우스 아래 요소 사이(포함)의 요소로 선택을 바꿉니다. 이 새 선택의 앵커가 아닌 끝은 버튼을 누른 채 끌 수도 있어요.
extended 모드에서 Control 키를 누른 채 버튼 1을 누르면 토글 작업이 시작됩니다. 앵커가 마우스 아래 요소로 설정되고 그 요소의 선택 상태가 뒤집혀요. 다른 요소의 선택 상태는 바뀌지 않습니다. 버튼 1을 누른 채 마우스를 끌면 앵커와 마우스 아래 요소 사이의 모든 요소 선택 상태가 앵커 요소와 일치하도록 설정되고, 다른 요소들은 토글 작업 시작 전 상태를 유지해요.
버튼 1을 누른 채 마우스가 listbox 창을 떠나면, 마우스 쪽에서 이전에 화면 밖이던 정보를 보이게 창이 마우스에서 멀어지는 방향으로 스크롤됩니다. 마우스가 창에 다시 들어오거나, 버튼이 놓이거나, listbox의 끝에 도달할 때까지 계속돼요.
마우스 버튼 2는 스캐닝에 사용될 수 있어요. listbox 위에서 눌러 끌면 listbox의 내용이 마우스가 움직이는 방향으로 고속으로 끌립니다.
Up 또는 Down 키를 누르면 위치 커서(활성 요소)가 한 요소씩 위나 아래로 움직입니다. 선택 모드가 browse나 extended면 새 활성 요소도 선택되고 다른 요소는 모두 해제돼요. extended 모드에서 새 활성 요소는 선택 앵커가 됩니다.
extended 모드에서 Shift-Up과 Shift-Down은 위치 커서(활성 요소)를 한 요소씩 움직이고 마우스 버튼 1로 끄는 것과 비슷하게 선택도 그 요소까지 확장합니다.
Left와 Right 키는 listbox 뷰를 0 문자의 너비만큼 왼쪽·오른쪽으로 스크롤합니다. Control-Left와 Control-Right는 창 너비만큼, Control-Prior와 Control-Next도 창 너비만큼 스크롤해요.
Prior와 Next 키는 listbox 뷰를 한 페이지(창 높이)씩 위·아래로 스크롤합니다.
Home과 End 키는 listbox를 각각 왼쪽·오른쪽 가장자리로 가로 스크롤합니다.
Control-Home은 위치 커서를 첫 요소로 설정하고, 그 요소를 선택하며, listbox의 다른 모든 것을 해제합니다.
Control-End는 위치 커서를 마지막 요소로 설정하고, 그 요소를 선택하며, 나머지 모든 것을 해제합니다.
extended 모드에서 Control-Shift-Home은 선택을 첫 요소로, Control-Shift-End는 마지막 요소로 확장합니다.
multiple 모드에서 Control-Shift-Home은 위치 커서를 첫 요소로, Control-Shift-End는 마지막 요소로 움직입니다.
space와 Select 키는 마우스 버튼 1을 그 요소 위에서 눌렀을 때처럼 위치 커서(활성 요소)에서 선택을 만듭니다.
extended 모드에서 Control-Shift-space와 Shift-Select는 Shift 키를 누른 채 버튼 1을 눌렀을 때처럼 활성 요소까지 선택을 확장합니다.
extended 모드에서 Escape 키는 가장 최근의 선택을 취소하고 선택 범위의 모든 요소를 이전 선택 상태로 복원합니다.
Control-slash는 위젯의 모든 것을 선택합니다. 단 single과 browse 모드에서는 활성 요소를 선택하고 나머지를 해제해요.
Control-backslash는 위젯의 모든 것을 해제합니다. browse 모드에서는 효과가 없어요.
F16 키(많은 Sun 워크스테이션에서 Copy로 표시) 또는 Meta-w는 선택이 있으면 위젯의 선택을 클립보드에 복사합니다.

listbox의 동작은 개별 위젯에 새 바인딩을 정의하거나 클래스 바인딩을 재정의해 바꿀 수 있어요.

더 알아보기

ttk::treeview — 테마 기반 트리·테이블 뷰 위젯