LVITEMA 구조체(commctrl.h)

아티클
08/22/2023

목록 뷰 항목의 특성을 지정하거나 받습니다. 이 구조체는 항목 들여쓰기를 사용하도록 설정하는 새 마스크 값(LVIF_INDENT)을 지원하도록 업데이트되었습니다. 이 구조체는 LV_ITEM 구조체를 대체합니다.

구문

typedef struct tagLVITEMA {
  UINT   mask;
  int    iItem;
  int    iSubItem;
  UINT   state;
  UINT   stateMask;
  LPSTR  pszText;
  int    cchTextMax;
  int    iImage;
  LPARAM lParam;
  int    iIndent;
  int    iGroupId;
  UINT   cColumns;
  PUINT  puColumns;
  int    *piColFmt;
  int    iGroup;
} LVITEMA, *LPLVITEMA;

멤버

mask

형식: UINT

설정할 데이터가 포함된 이 구조체의 멤버 또는 요청되는 멤버를 지정하는 플래그 집합입니다. 이 멤버는 다음 플래그 중 하나 이상을 설정할 수 있습니다.

값	의미
LVIF_COLFMT	Windows Vista 이상. piColFmt 멤버가 유효하거나 설정해야 합니다. 이 플래그를 사용하는 경우 cColumns 멤버가 유효하거나 설정해야 합니다.
LVIF_COLUMNS	cColumns 멤버가 유효하거나 설정해야 합니다.
LVIF_DI_SETITEM	운영 체제는 요청된 목록 항목 정보를 저장하고 다시 요청하지 않아야 합니다. 이 플래그는 LVN_GETDISPINFO 알림 코드에서만 사용됩니다.
LVIF_GROUPID	iGroupId 멤버가 유효하거나 설정해야 합니다. LVM_INSERTITEM 메시지를 보낼 때 이 플래그가 설정되지 않은 경우 iGroupId 값은 I_GROUPIDCALLBACK 것으로 간주됩니다.
LVIF_IMAGE	iImage 멤버가 유효하거나 설정해야 합니다.
LVIF_INDENT	iIndent 멤버가 유효하거나 설정해야 합니다.
LVIF_NORECOMPUTE	컨트롤은 LVM_GETITEM 메시지를 수신하는 경우 텍스트 정보를 검색하는 LVN_GETDISPINFO 생성하지 않습니다. 대신 pszText 멤버에는 LPSTR_TEXTCALLBACK 포함됩니다.
LVIF_PARAM	lParam 멤버가 유효하거나 설정해야 합니다.
LVIF_STATE	상태 멤버가 유효하거나 설정해야 합니다.
LVIF_TEXT	pszText 멤버가 유효하거나 설정해야 합니다.

iItem

형식: int

이 구조체가 참조하는 항목의 인덱스(0부터 시작)입니다.

iSubItem

형식: int

이 구조체가 참조하는 하위 항목의 1부터 시작하는 인덱스이거나, 이 구조체가 하위 항목이 아닌 항목을 참조하는 경우 0입니다.

state

형식: UINT

항목의 상태, 상태 이미지 및 오버레이 이미지를 나타냅니다. stateMask 멤버는 이 멤버의 유효한 비트를 나타냅니다.

이 멤버의 비트 0~7에는 항목 상태 플래그가 포함됩니다. 항목 상태 값 중 하나 이상이 될 수 있습니다.

이 멤버의 비트 8~11은 1부터 시작하는 오버레이 이미지 인덱스를 지정합니다. 전체 크기 아이콘 이미지 목록과 작은 아이콘 이미지 목록 모두 오버레이 이미지를 가질 수 있습니다. 오버레이 이미지는 항목의 아이콘 이미지 위에 겹쳐집니다. 이러한 비트가 0이면 항목에 오버레이 이미지가 없습니다. 이러한 비트를 격리하려면 LVIS_OVERLAYMASK 마스크를 사용합니다. 이 멤버에서 오버레이 이미지 인덱스를 설정하려면 INDEXTOOVERLAYMASK 매크로를 사용해야 합니다. 이미지 목록의 오버레이 이미지는 ImageList_SetOverlayImage 함수로 설정됩니다.

이 멤버의 비트 12~15는 상태 이미지 인덱스를 지정합니다. 상태 이미지는 애플리케이션 정의 상태를 나타내기 위해 항목의 아이콘 옆에 표시됩니다. 이러한 비트가 0이면 항목에 상태 이미지가 없습니다. 이러한 비트를 격리하려면 LVIS_STATEIMAGEMASK 마스크를 사용합니다. 상태 이미지 인덱스를 설정하려면 INDEXTOSTATEIMAGEMASK 매크로를 사용합니다. 상태 이미지 인덱스는 그려야 하는 상태 이미지 목록에서 이미지의 인덱스를 지정합니다. 상태 이미지 목록은 LVM_SETIMAGELIST 메시지와 함께 지정됩니다.

stateMask

형식: UINT

상태 멤버를 검색하거나 수정할 비트를 지정하는 값입니다. 예를 들어 이 멤버를 LVIS_SELECTED 설정하면 항목의 선택 상태만 검색됩니다.

이 멤버를 사용하면 먼저 모든 항목 상태를 검색하지 않고도 하나 이상의 항목 상태를 수정할 수 있습니다. 예를 들어 이 멤버를 LVIS_SELECTED및 상태를 0으로 설정하면 항목의 선택 상태가 지워지지만 다른 상태는 영향을 받지 않습니다.

모든 상태를 검색하거나 수정하려면 이 멤버를 (UINT)-1로 설정합니다.

매크로 ListView_SetItemState 사용하여 비트를 설정하고 지울 수 있습니다.

pszText

형식: LPTSTR

구조체가 항목 특성을 지정하는 경우 pszText 는 항목 텍스트를 포함하는 null로 끝나는 문자열에 대한 포인터입니다. LVN_GETDISPINFO 알림에 응답할 때 다음 알림이 수신될 때까지 이 포인터가 유효한지 확인합니다.

구조체가 항목 특성을 수신하는 경우 pszText 는 항목 텍스트를 수신하는 버퍼에 대한 포인터입니다. 목록 보기 컨트롤을 사용하면 모든 길이 문자열을 항목 텍스트로 저장할 수 있지만 처음 259 TCHAR만 표시됩니다.

pszText 값이 LPSTR_TEXTCALLBACK 경우 항목은 콜백 항목입니다. 콜백 텍스트가 변경되면 pszText를 명시적으로 LPSTR_TEXTCALLBACK 설정하고 LVM_SETITEM 또는 LVM_SETITEMTEXT 메시지를 보내 변경 내용을 목록 보기 컨트롤에 알려야 합니다.

목록 보기 컨트롤에 LVS_SORTASCENDING 또는 LVS_SORTDESCENDING 스타일이 있는 경우 pszText를 LPSTR_TEXTCALLBACK 설정하지 마세요.

cchTextMax

형식: int

종료 NULL을 포함하여pszText가 가리키는 버퍼의 TCHAR 수입니다.

이 멤버는 구조체가 항목 특성을 받을 때만 사용됩니다. 구조체가 항목 특성을 지정하면 무시됩니다. 예를 들어 cchTextMax 는 LVM_SETITEM 동안 무시되고 LVM_INSERTITEM. LVN_GETDISPINFO 및 기타 LVN_ 알림 중에 읽기 전용입니다.

참고cchTextMax에 종료 NULL이 포함된 cchTextMaxTCHAR를 LVN_ 알림 중에 pszText에 복사하지 마세요. 그렇지 않으면 프로그램이 실패할 수 있습니다.

iImage

형식: int

컨트롤의 이미지 목록에 있는 항목 아이콘의 인덱스입니다. 이는 크고 작은 이미지 목록 모두에 적용됩니다. 이 멤버가 I_IMAGECALLBACK 값인 경우 부모 창은 인덱스 저장을 담당합니다. 이 경우 목록 보기 컨트롤은 이미지를 표시해야 할 때 인덱스를 검색하는 LVN_GETDISPINFO 알림 코드를 부모에 보냅니다.

lParam

형식: LPARAM

항목과 관련된 값입니다. LVM_SORTITEMS 메시지를 사용하는 경우 list-view 컨트롤은 이 값을 애플리케이션 정의 비교 함수에 전달합니다. LVM_FINDITEM 메시지를 사용하여 지정된 lParam 값이 있는 항목에 대한 목록 보기 컨트롤을 검색할 수도 있습니다.

iIndent

형식: int

버전 4.70. 항목을 들여쓰기할 이미지 너비의 수입니다. 단일 들여쓰기 는 항목 이미지의 너비와 같습니다. 따라서 값 1은 한 이미지의 너비로 항목을 들여쓰고 값 2는 두 개의 이미지를 들여쓰는 등의 방식으로 들여쓰기합니다. 이 필드는 항목에 대해서만 지원됩니다. 하위 항목 들여쓰기를 설정하려고 하면 호출 함수가 실패합니다.

iGroupId

형식: int

버전 6.0 항목이 속한 그룹의 식별자이거나 다음 값 중 하나입니다.

값	의미
I_GROUPIDCALLBACK	listview 컨트롤은 그룹의 인덱스를 검색하는 LVN_GETDISPINFO 알림 코드를 부모에 보냅니다.
I_GROUPIDNONE	항목이 그룹에 속하지 않습니다.

cColumns

형식: UINT

버전 6.0 타일 보기에서 이 항목에 대해 표시할 데이터 열(하위 항목)의 수입니다. 최댓값은 20입니다. 이 값이 I_COLUMNSCALLBACK 경우 LVN_GETDISPINFO 알림을 보내 열 배열 및 배열 자체(puColumns)의 크기를 가져옵니다.

puColumns

형식: PUINT

버전 6.0 이 항목에 대해 표시되는 열과 해당 열의 순서를 지정하는 열 인덱스 배열에 대한 포인터입니다.

piColFmt

형식: int*

Windows Vista: 구현되지 않았습니다. Windows 7 이상: 확장 타일 보기에서 각 하위 항목의 형식을 지정하는 다음 플래그의 배열에 대한 포인터입니다(단독으로 또는 조합).

값	의미
LVCFMT_LINE_BREAK	열이 다음 열 목록의 맨 위로 래핑되도록 합니다.
LVCFMT_FILL	타일 영역의 나머지 부분을 채웁니다. 제목이 있을 수 있습니다.
LVCFMT_WRAP	열 목록의 나머지 공간 내에서 열을 래핑할 수 있습니다.
LVCFMT_NO_TITLE	하위 항목에서 제목을 제거합니다.
LVCFMT_TILE_PLACEMENTMASK	LVCFMT_LINE_BREAK 및 LVCFMT_FILL 조합에 해당합니다.

iGroup

형식: int

Windows Vista: 항목의 그룹 인덱스입니다. 소유자 데이터/콜백(여러 그룹의 단일 항목)에 대해서만 유효합니다.

설명

LVITEM 구조는 LVM_GETITEM, LVM_SETITEM, LVM_INSERTITEM 및 LVM_DELETEITEM 포함한 여러 메시지와 함께 사용됩니다.

타일 보기에서 항목 이름이 아이콘 오른쪽에 표시됩니다. 항목 이름 아래의 줄에 표시할 추가 하위 항목(세부 정보 보기의 열에 해당)을 지정할 수 있습니다. puColumns 배열에는 표시할 하위 항목의 인덱스가 포함됩니다. 항목 이름인 하위 항목 0이 이미 표시되어 있으므로 인덱스가 0보다 커야 합니다. 열 정보는 목록 항목을 수정할 때 LVTILEINFO 구조에서 설정할 수도 있습니다.

예제 코드는 List-View 컨트롤 사용을 참조하세요.

Comctl32.dll 버전 6은 재배포할 수 없지만 Windows 이상에 포함되어 있습니다. Comctl32.dll 버전 6을 사용하려면 매니페스트에 지정합니다. 매니페스트에 대한 자세한 내용은 시각적 스타일 사용을 참조하세요.

참고

commctrl.h 헤더는 UNICODE 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 LVITEM을 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
머리글	commctrl.h

다음을 통해 공유

LVITEMA 구조체(commctrl.h)

구문

멤버

설명

요구 사항

피드백

추가 리소스