MFC CListBox 완전 정복, 항목 추가부터 선택 처리까지 한 번에!

🔗 CListBox란 무엇인가요?

CListBox는 MFC에서 제공하는 리스트 박스 컨트롤을 다루기 위한 클래스입니다.
사용자가 리스트 형태로 나열된 항목들 중 하나 또는 여러 개를 선택할 수 있도록 인터페이스를 제공합니다.
보통 대화 상자(Dialog)에 포함되는 형태로 사용되며, 항목을 동적으로 추가하거나 삭제하고, 사용자의 선택을 제어할 수 있어 매우 유용합니다.

이 클래스는 CWnd를 상속받으며, 내부적으로 윈도우즈 API의 ListBox 컨트롤과 연결되어 작동합니다.
즉, 우리가 자주 사용하는 AddString, DeleteString, GetCurSel 등의 멤버 함수는 실제로 윈도우 메시지를 통해 리스트박스를 제어하는 역할을 합니다.

• 📌AddString – 새로운 문자열 항목을 리스트에 추가
• 📌DeleteString – 지정한 인덱스의 항목 삭제
• 📌GetCurSel – 현재 선택된 항목 인덱스 반환
• 📌ResetContent – 모든 항목 제거
• 📌GetText – 선택된 항목의 문자열을 가져옴

기본적인 사용 방식은 리스트 박스를 리소스에 배치한 후, DDX_Control 매크로나 GetDlgItem을 통해 해당 컨트롤과 연결하여 조작하는 것입니다.
이를 통해 사용자는 프로그램 실행 중에 동적으로 리스트 항목을 추가하거나 삭제할 수 있고, 사용자의 선택을 프로그램 로직에 반영할 수 있게 됩니다.

🛠️ 항목 추가 및 삭제: AddString과 DeleteString

CListBox를 사용할 때 가장 먼저 접하게 되는 작업은 리스트에 항목을 추가하거나 삭제하는 것입니다.
이를 위해 주로 사용되는 함수가 바로 AddString과 DeleteString입니다.
두 함수 모두 직관적이며, 리스트를 동적으로 구성할 때 반드시 활용하게 되는 핵심 함수입니다.

📝 AddString으로 항목 추가하기

AddString은 리스트 박스에 새로운 문자열 항목을 추가할 때 사용됩니다.
추가된 항목은 리스트의 끝에 자동으로 삽입되며, 반환값은 해당 항목의 인덱스입니다.

// CListBox 멤버 변수: m_listBox
m_listBox.AddString(_T("새로운 항목"));

이와 같이 사용하면 “새로운 항목”이라는 문자열이 리스트에 추가되며, 사용자는 이를 선택하거나 삭제할 수 있게 됩니다.

🗑️ DeleteString으로 항목 삭제하기

DeleteString은 지정한 인덱스의 항목을 리스트에서 제거할 때 사용합니다.
인덱스는 0부터 시작하며, 유효한 범위를 벗어나면 실패하게 됩니다.

// 첫 번째 항목 삭제
m_listBox.DeleteString(0);

이와 같이 작성하면 리스트의 첫 번째 항목이 삭제됩니다.
항목 삭제 시 리스트의 인덱스가 자동으로 재정렬되므로, 삭제 후 선택 인덱스를 다시 설정해주는 것도 좋은 습관입니다.

⚙️ 현재 선택 항목 확인: GetCurSel과 GetText

CListBox는 사용자가 선택한 항목의 정보를 확인할 수 있는 기능도 제공합니다.
이때 자주 사용되는 함수가 GetCurSel과 GetText입니다.
두 함수는 리스트 박스에서 현재 선택된 항목의 인덱스와 텍스트를 가져오는 데 활용되며, 사용자 입력을 처리할 때 매우 유용합니다.

🔍 GetCurSel: 선택된 항목의 인덱스 가져오기

GetCurSel 함수는 현재 선택된 항목의 인덱스를 반환합니다.
선택된 항목이 없다면 -1을 반환하므로, 이를 통해 유효한 선택 여부를 확인할 수 있습니다.

int nIndex = m_listBox.GetCurSel();
if (nIndex != LB_ERR) {
    // 유효한 선택이 있음
}

위 코드는 사용자가 리스트에서 무언가를 선택했는지 판단하는 기본적인 구조입니다.
이후에 해당 인덱스를 바탕으로 항목의 텍스트를 얻는 작업이 이어질 수 있습니다.

💬 GetText: 선택 항목의 문자열 가져오기

GetText 함수는 선택된 인덱스에 해당하는 항목의 문자열을 가져옵니다.
인자로 인덱스와 CString 변수를 받아, 해당 문자열을 해당 변수에 저장합니다.

int nIndex = m_listBox.GetCurSel();
if (nIndex != LB_ERR) {
    CString strItem;
    m_listBox.GetText(nIndex, strItem);
    AfxMessageBox(strItem);
}

위 예제처럼 GetCurSel로 인덱스를 먼저 가져오고, GetText로 해당 항목의 텍스트를 출력하는 방식이 일반적입니다.
사용자 인터페이스와 연동하여 정보를 표시하거나 로직 처리 시 꼭 필요한 부분이죠.

🔌 초기화와 전체 항목 제어: ResetContent와 GetCount

리스트 박스를 사용하다 보면 모든 항목을 한 번에 삭제하거나, 현재 항목이 몇 개인지 확인해야 하는 경우가 자주 발생합니다.
이때 유용하게 쓰이는 함수가 ResetContent와 GetCount입니다.
이 두 함수는 리스트 박스의 상태를 전반적으로 관리하는 데 필수적인 기능을 담당합니다.

🧹 ResetContent: 전체 항목 초기화

ResetContent 함수는 리스트 박스에 들어있는 모든 항목을 삭제하고, 완전히 초기 상태로 되돌립니다.
별도의 인덱스 지정 없이 모든 항목을 정리할 수 있어 리스트를 다시 구성할 때 매우 유용합니다.

// 모든 항목 삭제
m_listBox.ResetContent();

사용자가 선택했던 항목, 추가했던 항목 모두 이 한 줄로 초기화됩니다.
단, 이 작업은 되돌릴 수 없으므로, 사용자에게 확인을 받는 절차를 거치는 것도 좋은 방법입니다.

📊 GetCount: 전체 항목 수 확인

GetCount 함수는 리스트 박스에 포함된 총 항목 개수를 반환합니다.
특정 로직에서 반복문 처리나 상태 확인이 필요할 때 매우 유용하게 사용됩니다.

int nTotal = m_listBox.GetCount();
CString msg;
msg.Format(_T("총 항목 수는 %d개입니다."), nTotal);
AfxMessageBox(msg);

위 코드처럼 GetCount를 활용하면 현재 리스트에 얼마나 많은 항목이 있는지 손쉽게 확인할 수 있습니다.
이를 통해 동적 UI 제어는 물론, 조건문과 반복문에도 적극 활용할 수 있죠.

💡 실무에서 자주 쓰는 패턴 정리

CListBox는 단순한 컨트롤처럼 보이지만, 실무에서는 다양한 방식으로 활용됩니다.
입력 폼, 설정 목록, 파일 리스트, 로그 출력 등 사용처가 매우 다양하죠.
여기서는 실무에서 자주 사용하는 패턴들을 정리해보겠습니다.
이 패턴들은 단순한 기능 구현을 넘어서, 코드의 가독성과 유지 보수성을 높이는 데도 큰 도움이 됩니다.

✅ 항목 중복 방지 후 추가

같은 항목이 여러 번 추가되지 않도록 중복 여부를 먼저 검사하는 코드는 다음과 같이 구성할 수 있습니다.

CString newItem = _T("테스트");
bool isDuplicate = false;
int count = m_listBox.GetCount();

for (int i = 0; i < count; i++) {
    CString existingItem;
    m_listBox.GetText(i, existingItem);
    if (existingItem == newItem) {
        isDuplicate = true;
        break;
    }
}

if (!isDuplicate) {
    m_listBox.AddString(newItem);
}

중복 검사는 특히 사용자 입력 기반으로 리스트를 구성할 때 필수적인 과정입니다.
불필요한 데이터가 쌓이지 않도록 관리할 수 있죠.

📌 선택된 항목 자동 삭제

사용자가 선택한 항목을 버튼 클릭으로 삭제하는 방식은 다음처럼 구현할 수 있습니다.

int sel = m_listBox.GetCurSel();
if (sel != LB_ERR) {
    m_listBox.DeleteString(sel);
}

UI 상에서 리스트 항목을 클릭하고 버튼만 누르면 바로 삭제되도록 연결하면 사용자 경험이 좋아집니다.
이 방식은 폼 항목 정리, 로그 삭제 등 다양한 상황에서 유용하게 쓰입니다.

❓ 자주 묻는 질문 (FAQ)