Struttura LVITEMA (commctrl.h)

Specifica o riceve gli attributi di un elemento della visualizzazione elenco. Questa struttura è stata aggiornata per supportare un nuovo valore della maschera (LVIF_INDENT) che abilita il rientro dell'elemento. Questa struttura sostituisce la struttura LV_ITEM.

Sintassi

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;

Membri

mask

Tipo: UINT

Set di flag che specificano quali membri di questa struttura contengono dati da impostare o quali membri vengono richiesti. Questo membro può avere uno o più dei flag seguenti impostati:

Valore	Significato
LVIF_COLFMT	Windows Vista e versioni successive. Il membro piColFmt è valido o deve essere impostato. Se viene usato questo flag, il membro cColumns è valido o deve essere impostato.
LVIF_COLUMNS	Il membro cColumns è valido o deve essere impostato.
LVIF_DI_SETITEM	Il sistema operativo deve archiviare le informazioni sull'elemento dell'elenco richiesto e non richiederle di nuovo. Questo flag viene usato solo con il codice di notifica LVN_GETDISPINFO.
LVIF_GROUPID	Il membro iGroupId è valido o deve essere impostato. Se questo flag non viene impostato quando viene inviato un messaggio di LVM_INSERTITEM, si presuppone che il valore di iGroupId sia I_GROUPIDCALLBACK.
LVIF_IMAGE	Il membro iImage è valido o deve essere impostato.
LVIF_INDENT	Il membro iIndent è valido o deve essere impostato.
LVIF_NORECOMPUTE	Il controllo non genererà LVN_GETDISPINFO per recuperare informazioni di testo se riceve un messaggio di LVM_GETITEM. Al contrario, il membro pszText conterrà LPSTR_TEXTCALLBACK.
LVIF_PARAM	Il membro lParam è valido o deve essere impostato.
LVIF_STATE	Lo stato membro è valido o deve essere impostato.
LVIF_TEXT	Il membro pszText è valido o deve essere impostato.

iItem

Tipo: int

Indice in base zero dell'elemento a cui fa riferimento questa struttura.

iSubItem

Tipo: int

Indice in base uno dell'elemento secondario a cui fa riferimento questa struttura oppure zero se questa struttura fa riferimento a un elemento anziché a un elemento secondario.

state

Tipo: UINT

Indica lo stato dell'elemento, l'immagine dello stato e l'immagine di sovrapposizione. Il membro stateMask indica i bit validi di questo membro.

I bit da 0 a 7 di questo membro contengono i flag di stato dell'elemento. Può trattarsi di uno o più valori dello stato dell'elemento .

I bit da 8 a 11 di questo membro specificano l'indice dell'immagine di sovrimpressione in base uno. Sia l'elenco di immagini a icona a dimensione intera che l'elenco di immagini a icona piccola possono avere immagini sovrapposte. L'immagine di sovrimpressione viene sovrapposta all'immagine dell'icona dell'elemento. Se questi bit sono zero, l'elemento non ha un'immagine di sovrapposizione. Per isolare questi bit, usare la maschera LVIS_OVERLAYMASK. Per impostare l'indice dell'immagine di sovrimpressione in questo membro, è necessario usare la macro INDEXTOOVERLAYMASK . Le immagini sovrapposte dell'elenco di immagini vengono impostate con la funzione ImageList_SetOverlayImage.

I bit da 12 a 15 di questo membro specificano l'indice dell'immagine di stato. L'immagine di stato viene visualizzata accanto all'icona di un elemento per indicare uno stato definito dall'applicazione. Se questi bit sono zero, l'elemento non ha un'immagine di stato. Per isolare questi bit, usare la maschera LVIS_STATEIMAGEMASK. Per impostare l'indice dell'immagine di stato, utilizzare la macro INDEXTOSTATEIMAGEMASK. L'indice dell'immagine di stato specifica l'indice dell'immagine nell'elenco di immagini di stato da disegnare. L'elenco di immagini di stato viene specificato con il messaggio di LVM_SETIMAGELIST.

stateMask

Tipo: UINT

Valore che specifica quali bit dello stato membro verranno recuperati o modificati. Ad esempio, l'impostazione di questo membro su LVIS_SELECTED causerà il recupero solo dello stato di selezione dell'elemento.

Questo membro consente di modificare uno o più stati dell'elemento senza dover prima recuperare tutti gli stati dell'elemento. Ad esempio, l'impostazione di questo membro su LVIS_SELECTED e stato su zero causerà la cancellazione dello stato di selezione dell'elemento, ma nessuno degli altri stati sarà interessato.

Per recuperare o modificare tutti gli stati, impostare questo membro su (UINT)-1.

È possibile utilizzare la macro ListView_SetItemState sia per impostare che per cancellare i bit.

pszText

Tipo: LPTSTR

Se la struttura specifica gli attributi dell'elemento, pszText è un puntatore a una stringa con terminazione Null contenente il testo dell'elemento. Quando si risponde a una notifica di LVN_GETDISPINFO, assicurarsi che questo puntatore rimanga valido fino a quando non viene ricevuta la notifica successiva.

Se la struttura riceve gli attributi dell'elemento, pszText è un puntatore a un buffer che riceve il testo dell'elemento. Si noti che anche se il controllo visualizzazione elenco consente l'archiviazione di qualsiasi stringa di lunghezza come testo dell'elemento, vengono visualizzati solo i primi 259 TCHARs.

Se il valore di pszText è LPSTR_TEXTCALLBACK, l'elemento è un elemento di callback . Se il testo del callback cambia, è necessario impostare in modo esplicito pszText su LPSTR_TEXTCALLBACK e notificare al controllo della visualizzazione elenco la modifica inviando un messaggio di LVM_SETITEM o LVM_SETITEMTEXT.

Non impostare pszText su LPSTR_TEXTCALLBACK se il controllo visualizzazione elenco ha lo stile LVS_SORTASCENDING o LVS_SORTDESCENDING.

cchTextMax

Tipo: int

Numero di di TCHARnel buffer a cui punta pszText, inclusa la terminazione NULL.

Questo membro viene utilizzato solo quando la struttura riceve gli attributi dell'elemento. Viene ignorato quando la struttura specifica gli attributi dell'elemento. Ad esempio, cchTextMax viene ignorato durante LVM_SETITEM e LVM_INSERTITEM. È di sola lettura durante LVN_GETDISPINFO e altre notifiche di LVN_.

Nota Non copiare mai più di cchTextMaxTCHARs , dove cchTextMax include l'NULL terminante, in pszText durante una notifica di LVN_; in caso contrario, il programma può non riuscire.

 

iImage

Tipo: int

Indice dell'icona dell'elemento nell'elenco di immagini del controllo. Questo vale sia per l'elenco di immagini di grandi dimensioni che per le immagini di piccole dimensioni. Se questo membro è il valore I_IMAGECALLBACK, la finestra padre è responsabile dell'archiviazione dell'indice. In questo caso, il controllo visualizzazione elenco invia all'elemento padre un codice di notifica LVN_GETDISPINFO per recuperare l'indice quando deve visualizzare l'immagine.

lParam

Tipo: LPARAM

Valore specifico dell'elemento. Se si usa il messaggio di LVM_SORTITEMS, il controllo visualizzazione elenco passa questo valore alla funzione di confronto definita dall'applicazione. È anche possibile utilizzare il messaggio di LVM_FINDITEM per cercare un elemento in un controllo visualizzazione elenco con un valore lParam specificato.

iIndent

Tipo: int

versione 4.70. Numero di larghezze dell'immagine per rientrare l'elemento. Un singolo rientro è uguale alla larghezza di un'immagine dell'elemento. Pertanto, il valore 1 rientra l'elemento in base alla larghezza di un'immagine, il valore 2 rientra per due immagini e così via. Si noti che questo campo è supportato solo per gli elementi. Se si tenta di impostare il rientro dell'elemento secondario, la funzione chiamante avrà esito negativo.

iGroupId

Tipo: int

versione 6.0 Identificatore del gruppo a cui appartiene l'elemento o uno dei valori seguenti.

Valore	Significato
I_GROUPIDCALLBACK	Il controllo listview invia all'elemento padre un codice di notifica LVN_GETDISPINFO per recuperare l'indice del gruppo.
I_GROUPIDNONE	L'elemento non appartiene a un gruppo.

cColumns

Tipo: UINT

versione 6.0 Numero di colonne di dati (elementi secondari) da visualizzare per questo elemento nella visualizzazione riquadro. Il valore massimo è 20. Se questo valore è I_COLUMNSCALLBACK, le dimensioni della matrice di colonne e della matrice stessa (puColumns) vengono ottenute inviando una notifica di LVN_GETDISPINFO.

puColumns

Tipo: PUINT

versione 6.0 puntatore a una matrice di indici di colonna, specificando le colonne visualizzate per questo elemento e l'ordine di tali colonne.

piColFmt

Tipo: int*

Windows Vista: Non implementato. Windows 7 e versioni successive: Puntatore a una matrice dei flag seguenti (da solo o in combinazione), specificando il formato di ogni elemento secondario nella visualizzazione riquadro estesa.

Valore	Significato
LVCFMT_LINE_BREAK	Forza il ritorno a capo della colonna nella parte superiore dell'elenco di colonne successivo.
LVCFMT_FILL	Riempie il resto dell'area del riquadro. Potrebbe avere un titolo.
LVCFMT_WRAP	Consente alla colonna di eseguire il wrapping all'interno dello spazio rimanente nell'elenco di colonne.
LVCFMT_NO_TITLE	Rimuove il titolo dall'elemento secondario.
LVCFMT_TILE_PLACEMENTMASK	Equivalente a una combinazione di LVCFMT_LINE_BREAK e LVCFMT_FILL.

iGroup

Tipo: int

windows Vista: indice del gruppo dell'elemento. Valido solo per i dati o il callback del proprietario (singolo elemento in più gruppi).

Osservazioni

La struttura di LVITEM viene usata con diversi messaggi, tra cui LVM_GETITEM, LVM_SETITEM, LVM_INSERTITEMe LVM_DELETEITEM.

Nella visualizzazione riquadro il nome dell'elemento viene visualizzato a destra dell'icona. È possibile specificare elementi secondari aggiuntivi (corrispondenti alle colonne nella visualizzazione dettagli) da visualizzare in righe sotto il nome dell'elemento. La matrice puColumns contiene gli indici degli elementi secondari da visualizzare. Gli indici devono essere maggiori di 0, perché l'elemento secondario 0, il nome dell'elemento, è già visualizzato. Le informazioni sulle colonne possono essere impostate anche nella struttura LVTILEINFO durante la modifica dell'elemento di elenco.

Per un esempio di codice, vedere Using List-View Controls.

Nota Comctl32.dll versione 6 non è ridistribuibile, ma è incluso in Windows o versioni successive. Per usare Comctl32.dll versione 6, specificarlo in un manifesto. Per altre informazioni sui manifesti, vedere Abilitazione degli stili di visualizzazione.

 

Nota

L'intestazione commctrl.h definisce LVITEM come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
intestazione	commctrl.h