commctrl.h

Mensaje LVM_INSERTITEM

Definición

LVM_INSERTITEM
    pitem=(LPARAM)(LPLVITEM)lParam

Inserta un nuevo ítem en un control list-view. Se puede enviar este mensaje explícitamente o bien usar la macro ListView_InsertItem.

Descripción

pitem
Un puntero a una estructura LVITEM que especifica los atributos del ítem del list-view. Usar el miembro iItempara especificar el índice, basado en cero, en el que el ítem debe ser insertado. Si este valor es más grande que el número de ítems que contiene actualmente el control, el nuevo ítem se añadirá al final de la lista y se le asignará el índice correcto. Se puede examinar el valor de retorno para determinar el índice asignado al ítem.

Valor de retorno

Devuelve el índice del nuevo ítem si tiene éxito, o -1 en caso contrario.

Observaciones

No se puede usar ListView_InsertItem o LVM_INSERTITEM para insertar subítems. El miembro iSubItem de la estructura LVITEM debe ser cero. Ver LVM_SETITEM para más información sobre cómo asignar subítems.

Si el control list-view tiene el estilo LVS_EX_CHECKBOXES asignado, cualquier valor colocado en los bits 12 a 15 del miembro state de la estructura LVITEM será ignorado. Cuando se añade un ítem con este estilo activado, siempre se añadirá sin la marca de check.

SI un control list-view tiene los estilos de ventana LVS_SORTASCENDING o LVS_SORTDESCENDING, el mensaje LVM_INSERTITEM fallará si se intenta insertar un ítem que tenga el valor LPSTR_TEXTCALLBACK para el miembro pszText de su estructura LVITEM.

El mensaje LVM_INSERTITEM insertará un nuevo ítem en la posición adecuada en el orden de clasificación si se cumplen las siguientes condiciones:

  • Se está usando un de los estilos LVS_SORTXXX.
  • No se está usando el estilo LVS_OWNERDRAW.
  • El miembro pszText de la estructura apuntada por pitem no tiene asignado el valor LPSTR_TEXTCALLBACK.

Si la estructura LVITEM no contiene LVIF_GROUPID en el miembro mask, el valor del miembro iGroupId es I_GROUPIDCALLBACK por defecto.