`entry` — 한 줄 텍스트 입력 위젯 만들기

entry — 한 줄 텍스트 입력 위젯 만들기

사용자에게 한 줄짜리 텍스트를 입력받아야 할 때 쓰는 게 entry 위젯이에요. 입력 검증, 비밀번호 마스킹, 스크롤, 선택 등 의외로 풍부한 기능을 갖추고 있어요.

출처: Tcl/Tk Manual — entry

본문

시그니처

entry pathName ?options?

entry 명령은 pathName이라는 새 창을 만들어 entry 위젯으로 만들어 줘요. 호출 시점에 pathName이라는 창이 없어야 하고, 부모는 존재해야 해요. 명령은 pathName을 돌려줘요.

entry는 한 줄 텍스트 문자열을 표시하고, 아래 설명하는 위젯 명령(주로 키 입력·마우스 동작에 바인딩됨)으로 그 문자열을 수정할 수 있게 하는 위젯이에요. 처음 만들면 문자열은 비어 있어요. 일부를 선택(selection)할 수도 있어요.

entry가 선택을 내보내고 있으면(-exportselection 옵션) 표준 X11 선택 처리 규약을 지켜요. entry 선택은 STRING 타입으로 제공돼요. entry는 입력 포커스를 다루는 표준 Tk 규칙도 지켜요. 입력 포커스를 가진 entry는 새 문자가 삽입될 위치를 가리키는 삽입 커서(insertion cursor)를 표시해요.

entry는 위젯 창에 완전히 들어가기에 너무 긴 문자열도 표시할 수 있어요. 그 경우 문자열 일부만 보이는데, 아래 명령으로 창의 보기(view)를 바꿀 수 있어요. entry는 스크롤바와 상호작용하는 표준 -xscrollcommand 메커니즘을 쓰고, 스캐닝(scanning)도 지원해요.

표준 옵션

-background or -bg, background, Background
-borderwidth or -bd, borderWidth, BorderWidth
-cursor, cursor, Cursor
-exportselection, exportSelection, ExportSelection
-font, font, Font
-foreground or -fg, foreground, Foreground
-highlightbackground, highlightBackground, HighlightBackground
-highlightcolor, highlightColor, HighlightColor
-highlightthickness, highlightThickness, HighlightThickness
-insertbackground, insertBackground, Foreground
-insertborderwidth, insertBorderWidth, BorderWidth
-insertofftime, insertOffTime, OffTime
-insertontime, insertOnTime, OnTime
-insertwidth, insertWidth, InsertWidth
-justify, justify, Justify
-relief, relief, Relief
-selectbackground, selectBackground, Foreground
-selectborderwidth, selectBorderWidth, BorderWidth
-selectforeground, selectForeground, Background
-takefocus, takeFocus, TakeFocus
-textvariable, textVariable, Variable
-xscrollcommand, xScrollCommand, ScrollCommand

위젯 전용 옵션

-disabledbackground — entry가 disabled일 때 쓸 배경색. 빈 문자열이면 일반 배경색 사용. -disabledforeground — entry가 disabled일 때 쓸 전경색. 빈 문자열이면 일반 전경색 사용. -readonlybackground — entry가 readonly일 때 쓸 배경색. 빈 문자열이면 일반 배경색 사용.

-invalidcommand or -invcmd — -validatecommand가 0을 돌려줄 때 평가할 스크립트를 지정해요. {}로 설정하면(기본값) 이 기능이 비활성화돼요. 가장 좋은 사용법은 bell로 설정하는 거예요.

-show — 이 옵션을 지정하면 entry의 실제 내용이 창에 표시되지 않아요. 대신 entry 값의 각 문자가 이 옵션 값의 첫 글자(예: "*")로 표시돼요. 비밀번호 입력에 유용해요. entry의 문자를 선택해 다른 곳으로 복사하면, 복사되는 정보는 실제 내용이 아니라 표시되는 내용이에요.

-state — entry의 세 가지 상태 중 하나를 지정해요: normal, disabled, readonly. readonly면 위젯 명령으로 값을 바꿀 수 없고, 입력 포커스가 위젯에 있어도 삽입 커서가 표시되지 않지만 내용은 여전히 선택할 수 있어요. disabled면 값을 바꿀 수 없고, 삽입 커서가 표시되지 않으며, 내용을 선택할 수도 없고, -disabledforeground·-disabledbackground 값에 따라 다른 색으로 표시될 수 있어요.

-validate — 검증이 동작할 모드를 지정해요: none, focus, focusin, focusout, key, all. 기본값은 none이에요. 검증을 원하면 원하는 모드를 명시해야 해요.

-validatecommand or -vcmd — entry로의 입력을 검증할 때 평가할 스크립트를 지정해요. {}로 설정하면(기본값) 비활성화돼요. 이 명령은 유효한 Tcl boolean 값을 돌려줘야 해요. 0(또는 그에 해당하는 boolean)을 돌려주면 새 편집을 거부하고 그 편집은 발생하지 않으며, 설정돼 있으면 -invalidcommand가 평가돼요. 1을 돌려주면 새 편집이 발생해요.

-width — entry 창의 원하는 폭을 위젯 폰트의 평균 크기 문자 수로 지정하는 정수예요. 값이 0 이하이면 위젯이 현재 텍스트를 담기에 충분한 크기를 골라요.

검증(VALIDATION)

검증은 -validatecommand 옵션에 validateCommand 스크립트를 설정하고, 그 스크립트가 -validate 옵션에 따라 평가되는 방식으로 동작해요.

  • none — 기본값. 검증이 일어나지 않아요.
  • focus — entry가 포커스를 얻거나 잃을 때 validateCommand 호출.
  • focusin — entry가 포커스를 얻을 때 호출.
  • focusout — entry가 포커스를 잃을 때 호출.
  • key — entry가 편집될 때 호출.
  • all — 위 모든 조건에서 호출.

bind 스크립트에서처럼 -validatecommand와 -invalidcommand 값에 퍼센트 치환을 쓸 수 있어요. 인식되는 치환은 다음과 같아요.

  • %d — 동작 종류: 삽입 1, 삭제 0, 포커스·강제·textvariable 검증은 -1.
  • %i — 삽입/삭제될 문자열 인덱스(없으면 -1).
  • %P — 편집이 허용된다면 entry의 값. 새 textvariable을 구성 중이면 그 textvariable의 값.
  • %s — 편집 전 entry의 현재 값.
  • %S — 삽입/삭제될 텍스트 문자열(없으면 {}).
  • %v — 현재 설정된 검증 종류.
  • %V — 콜백을 유발한 검증 종류(key, focusin, focusout, forced).
  • %W — entry 위젯의 이름.

일반적으로 -textvariable과 -validatecommand를 섞는 건 위험할 수 있어요. -validatecommand를 쓰면 전통적인 entry 동작을 방해하지 않도록 문제들이 이미 해결되어 있어요. -textvariable을 읽기 전용으로 쓰면 문제가 전혀 없어요. 위험한 경우는 -textvariable을 -validatecommand가 받아들이지 않을 값으로 설정하려 할 때로, 그러면 -validate가 none이 돼요(-invalidcommand는 유발되지 않아요). -validatecommand 평가 중 오류가 나도 같아요.

오류는 주로 -validatecommand나 -invalidcommand 스크립트를 평가하며 오류를 만나거나, -validatecommand가 유효한 Tcl boolean을 돌려주지 않을 때 발생해요. 또 -validatecommand나 -invalidcommand 안에서 entry 위젯을 편집하면 -validate 옵션이 스스로 none으로 설정돼요. 그런 편집은 검증 중이던 것을 덮어써요. 검증 중에 entry를 (예: {}로) 직접 편집하면서도 -validate를 유지하려면, 다음 명령을 -validatecommand나 -invalidcommand(entry를 편집하던 쪽)에 넣어야 해요.

after idle {%W config -validate %v}

또한 검증 중에는 관련 -textvariable을 설정하지 않는 게 권장돼요. 그렇게 하면 entry가 -textvariable과 동기화가 어긋날 수 있기 때문이에요.

위젯 명령

entry 명령은 pathName이라는 새 Tcl 명령을 만들어요.

pathName subcommand ?arg arg ...?

인덱스(INDICES)

entry의 위젯 명령 중 다수는 인덱스 하나 이상을 인자로 받아요. 인덱스는 entry 문자열의 특정 문자를 다음 방식 중 하나로 지정해요.

  • number — 숫자 인덱스. 0이 문자열의 첫 문자.
  • anchor — 선택의 앵커 포인트. select from·select adjust 위젯 명령으로 설정돼요.
  • end — entry 문자열의 마지막 문자 바로 다음 문자. entry 문자열 길이와 같은 숫자 인덱스와 동등해요.
  • insert — 삽입 커서에 인접해 바로 뒤따르는 문자.
  • sel.first — 선택의 첫 문자. 선택이 entry 창에 없으면 이 형태를 쓰는 건 오류예요.
  • sel.last — 선택의 마지막 문자 바로 다음 문자. 선택이 entry 창에 없으면 오류.
  • @number — number를 entry 창의 x좌표로 해석하고, 그 x좌표를 가로지르는 문자를 사용. 예: "@0"은 창의 맨 왼쪽 문자.

위 모든 형태에 약어를 쓸 수 있어요(예: "e", "sel.f"). 일반적으로 범위 밖 인덱스는 가장 가까운 유효 값으로 자동 반올림돼요.

하위 명령(SUBCOMMANDS)

  • pathName bbox index — index가 주는 문자의 경계 상자를 설명하는 네 숫자 목록(픽셀)을 돌려줘요. 앞 둘은 위젯 기준 문자가 덮는 화면 영역의 좌상단 x·y 좌표, 뒤 둘은 문자의 폭·높이. 경계 상자는 창의 보이는 영역 밖 영역을 가리킬 수도 있어요.
  • pathName cget option — 설정 옵션의 현재 값.
  • pathName configure ?option? ?value option value ...? — 설정 옵션 조회/수정.
  • pathName delete first ?last? — entry 요소 하나 이상 삭제. first는 삭제할 첫 문자 인덱스, last는 삭제할 마지막 문자 바로 다음 인덱스. last를 지정하지 않으면 first+1로 기본 설정(즉 한 문자 삭제). 빈 문자열 반환.
  • pathName get — entry의 문자열 반환.
  • pathName icursor index — 삽입 커서가 index가 주는 문자 바로 앞에 표시되게 함. 빈 문자열 반환.
  • pathName index index — index에 해당하는 숫자 인덱스 반환.
  • pathName insert index string — index가 가리키는 문자 바로 앞에 string의 문자 삽입. 빈 문자열 반환.
  • pathName scan option args — entry의 스캐닝 구현. option에 따라 두 형태:
    • pathName scan mark x — x와 현재 보기를 기록. 나중에 scan dragto와 함께 사용. 보통 위젯의 마우스 버튼 누름에 연결됨. 빈 문자열 반환.
    • pathName scan dragto x — 이 명령의 x와 마지막 scan mark의 x의 차이를 계산하고, 보기를 x좌표 차이의 10배만큼 좌우로 조정. 보통 위젯의 마우스 이동 이벤트에 연결되어 entry를 창을 통해 고속으로 끄는 효과를 냄. 빈 문자열 반환.
  • pathName selection option arg — entry 내 선택 조정. option에 따라 여러 형태:
    • pathName selection adjust index — 선택 끝 중 index에 가장 가까운 쪽을 찾아 그 끝을 index로 조정(index 포함하되 넘지 않음). 선택의 다른 끝은 이후 select to의 앵커 포인트가 됨. 선택이 entry에 없으면 index와 최근 선택 앵커 포인트 사이 문자를 포함하는 새 선택 생성. 빈 문자열 반환.
    • pathName selection clear — 이 위젯에 선택이 있으면 지움. 없으면 효과 없음. 빈 문자열 반환.
    • pathName selection from index — 선택 앵커 포인트를 index가 주는 문자 바로 앞으로 설정. 선택 자체는 바꾸지 않음. 빈 문자열 반환.
    • pathName selection present — entry에 선택된 문자가 있으면 1, 없으면 0 반환.
    • pathName selection range start end — start가 인덱스하는 문자부터 end 바로 앞 문자까지 포함하는 선택 설정. end가 start와 같거나 더 이르면 entry 선택이 지워짐.
    • pathName selection to index — index가 앵커 앞이면 앵커까지(앵커 미포함) 선택, 앵커와 같으면 아무것도 안 함, 앵커 뒤면 앵커부터 index까지(미포함) 선택. 앵커는 이 위젯의 가장 최근 select from/select adjust가 정함. 선택이 위젯에 없으면 위젯에 지정된 최근 앵커로 새 선택 생성. 빈 문자열 반환.
  • pathName validate — -validate 옵션 조건과 무관하게 -validatecommand 평가를 강제. -validate를 임시로 all로 설정해 수행. 0 또는 1 반환.
  • pathName xview args — 위젯 창 내 텍스트의 수평 위치 조회/변경:
    • pathName xview — 두 요소 목록 반환. 각 요소는 0~1의 실수 분수로 창에 보이는 수평 범위를 나타냄. 예: 첫 요소 .2 둘째 .6이면 왼쪽 20%가 화면 밖, 중간 40%가 보이고, 오른쪽 40%가 화면 밖. -xscrollcommand로 스크롤바에 전달되는 값과 동일.
    • pathName xview index — index 문자가 창 왼쪽 가장자리에 오도록 보기 조정.
    • pathName xview moveto fraction — 텍스트의 fraction 지점의 문자가 왼쪽 가장자리에 오도록 보기 조정. fraction은 0~1.
    • pathName xview scroll number what — number·what에 따라 보기를 좌우 이동. number는 정수. what은 units 또는 pages(약어 가능). units면 평균 폭 문자 number개만큼, pages면 화면 number배만큼. number 음수면 왼쪽, 양수면 오른쪽.

기본 바인딩

Tk는 entry에 다음 기본 동작을 주는 클래스 바인딩을 자동으로 만들어요. 아래에서 "word"는 글자·숫자·"_"의 연속, 또는 이들 외의 임의의 단일 문자를 말해요.

  • 마우스 1번 버튼 클릭 → 삽입 커서를 마우스 아래 문자 바로 앞에 놓고, 이 위젯에 입력 포커스를 주고, 위젯의 선택을 지움. 1번 버튼으로 드래그하면 삽입 커서와 마우스 아래 문자 사이를 선택.
  • 1번 버튼 더블클릭 → 마우스 아래 단어 선택, 삽입 커서를 단어 끝에 배치. 더블클릭 후 드래그하면 온전한 단어 단위로 선택.
  • 1번 버튼 트리플클릭 → entry의 전체 텍스트 선택, 삽입 커서를 줄 끝에 배치.
  • Shift 키를 누른 채 1번 버튼으로 드래그 → 선택 끝 조정(버튼을 눌렀을 때 마우스에 가장 가까운 쪽). 드래그 전 버튼을 더블클릭했다면 온전한 단어 단위로 조정.
  • Control 키를 누른 채 1번 버튼 클릭 → 선택에 영향 없이 삽입 커서만 배치.
  • 일반 출력 문자 입력 → 삽입 커서 위치에 삽입.
  • 가운데 마우스 버튼(버튼 2, TkAqua에선 버튼 3)으로 드래그 → entry의 보기 조정. 마우스 이동 없이 클릭만 하면 선택이 마우스 커서 위치에 복사됨.
  • 1번 버튼을 누른 채 마우스를 entry 좌우로 끌어내면, 화면 밖에 텍스트가 더 있으면 자동으로 스크롤해 더 보이게 함.
  • Left/Right 키 → 삽입 커서를 한 문자씩 이동. entry의 선택도 지우고 선택 앵커 설정. Shift와 함께면 선택을 새 문자까지 확장. Control-Left/Right는 단어 단위, Control-Shift-Left/Right는 단어 단위로 이동하며 선택 확장. Control-b/Control-f는 각각 Left/Right와, Meta-b/Meta-f는 각각 Control-Left/Right와 같이 동작.
  • Home 키 또는 Control-a → 삽입 커서를 entry 시작으로, 선택 지움. Shift-Home은 그 지점까지 선택 확장.
  • End 키 또는 Control-e → 삽입 커서를 entry 끝으로, 선택 지움. Shift-End는 끝까지 선택 확장.
  • Select 키·Control-Space → 선택 앵커를 삽입 커서 위치로 설정. 현재 선택엔 영향 없음. Shift-Select·Control-Shift-Space → 선택을 삽입 커서 현재 위치로 조정(이전 선택이 없으면 앵커부터 삽입 커서까지 선택).
  • Control-/ → entry 전체 텍스트 선택.
  • Control-\ → entry의 선택 지움.
  • F16 키(많은 Sun 워크스테이션에서 Copy로 표시) 또는 Meta-w → 선택(있으면)을 클립보드로 복사.
  • F20 키(Cut) 또는 Control-w → 선택을 클립보드로 복사하고 삭제. 선택이 없으면 효과 없음.
  • F18 키(Paste) 또는 Control-y → 삽입 커서 위치에 클립보드 내용 삽입.
  • Delete 키 → 선택(있으면) 삭제, 없으면 삽입 커서 오른쪽 문자 삭제.
  • BackSpace 키·Control-h → 선택(있으면) 삭제, 없으면 삽입 커서 왼쪽 문자 삭제.
  • Control-d → 삽입 커서 오른쪽 문자 삭제.
  • Meta-d → 삽입 커서 오른쪽 단어 삭제.
  • Control-k → 삽입 커서 오른쪽 모든 문자 삭제.
  • Control-t → 삽입 커서 오른쪽 두 문자의 순서 뒤집기.

-state로 entry가 disabled면, 보기는 여전히 조정할 수 있고 텍스트는 여전히 선택할 수 있지만 삽입 커서가 표시되지 않고 텍스트 수정이 일어나지 않아요. 단 -textvariable로 변수에 연결된 경우엔, -state 값과 무관하게 변수 변경이 entry에 반영돼요. 위젯별 또는 클래스 바인딩을 다시 정의해 entry 동작을 바꿀 수 있어요.

더 알아보기

ttk::entry 문서와 함께 validation(검증) 관련 동작은 bind의 퍼센트 치환 설명도 참고하세요.