ListView_InsertItem macro (commctrl.h)

Artigo
10/24/2024

Insere um novo item em um controle de exibição de lista. Você pode usar essa macro ou enviar a mensagem LVM_INSERTITEM explicitamente.

Sintaxe

int ListView_InsertItem(
         HWND     hwnd,
   const LPLVITEM pitem
);

Parâmetros

hwnd

Tipo: HWND

Um identificador para o controle de exibição de lista.

pitem

Tipo: const LPLVITEM

Um ponteiro para uma estrutura LVITEM que especifica os atributos do item de exibição de lista. Use o membro iItem para especificar o índice baseado em zero no qual o novo item deve ser inserido. Se esse valor for maior que o número de itens contidos no momento pelo controle listview, o novo item será acrescentado ao final da lista e atribuído ao índice correto. Examine o valor retornado da macro para determinar o índice real atribuído ao item.

Valor de retorno

Tipo: int

Retorna o índice do novo item se tiver êxito ou -1 caso contrário.

Observações

Não é possível usar ListView_InsertItem ou LVM_INSERTITEM para inserir subitem. O iSubItem membro da estrutura de LVITEM deve ser zero. Consulte LVM_SETITEM para obter informações sobre como definir subitems.

Se um controle de exibição de lista tiver o conjunto de estilos de LVS_EX_CHECKBOXES, qualquer valor colocado nos bits 12 a 15 do estado membro da estrutura de LVITEM será ignorado. Quando um item é adicionado com esse conjunto de estilos, ele sempre será definido como o estado desmarcado.

Se um controle de exibição de lista tiver o estilo de janela LVS_SORTASCENDING ou LVS_SORTDESCENDING, uma mensagem LVM_INSERTITEM falhará se você tentar inserir um item que tenha LPSTR_TEXTCALLBACK como membro pszText de sua estrutura LVITEM .

A macro ListView_InsertItem inserirá o novo item na posição correta na ordem de classificação se as seguintes condições mantiverem:

Você está usando um dos estilos de LVS_SORTXXX.
Você não está usando o estilo LVS_OWNERDRAW.
O pszText membro da estrutura apontado por pitem não está definido como LPSTR_TEXTCALLBACK.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	commctrl.h

Compartilhar via